/search-first — 编码前先调研（Research Before You Code）
将“在实现前搜索现有解决方案”的工作流系统化。
触发条件（Trigger）
在以下场景使用此技能（Skill）：
- 开始开发一个很可能已有现成解决方案的新功能
- 添加依赖项或集成
- 用户要求“添加 X 功能”且你正准备编写代码
- 在创建新的工具类（Utility）、辅助函数（Helper）或抽象层之前
工作流（Workflow）
┌─────────────────────────────────────────────┐
│ 1. 需求分析 (NEED ANALYSIS) │
│ 定义所需功能 │
│ 识别语言/框架约束 │
├─────────────────────────────────────────────┤
│ 2. 并行搜索 (调研智能体 researcher agent) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ 技能 │ │ Web │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. 评估 (EVALUATE) │
│ 为候选方案打分（功能、维护、 │
│ 社区、文档、许可证、依赖） │
├─────────────────────────────────────────────┤
│ 4. 决策 (DECIDE) │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ 采用 │ │ 扩展 │ │ 自研 │ │
│ │ (Adopt) │ │ (Extend)│ │ (Build) │ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. 实施 (IMPLEMENT) │
│ 安装包 / 配置 MCP / │
│ 编写最少量的自定义代码 │
└─────────────────────────────────────────────┘
决策矩阵（Decision Matrix）
| 信号 |
行动 |
| 完全匹配、维护良好、MIT/Apache 协议 |
采用 (Adopt) — 直接安装并使用 |
| 部分匹配、基础良好 |
扩展 (Extend) — 安装 + 编写轻量封装层 |
| 多个弱匹配项 |
组合 (Compose) — 结合 2-3 个小型包 |
| 未找到合适方案 |
自研 (Build) — 编写自定义代码，但基于调研结论 |
如何使用
快速模式（行内使用）
在编写工具类或添加功能前，大脑中先过一遍：
- 仓库中是否已存在？→ 先通过
rg 搜索相关的模块/测试
- 这是一个常见问题吗？→ 搜索 npm/PyPI
- 是否有相关的 MCP？→ 检查
~/.claude/settings.json 并搜索
- 是否有相关的技能（Skill）？→ 检查
~/.claude/skills/
- 是否有 GitHub 实现/模板？→ 在编写全新代码前，针对维护良好的开源软件（OSS）运行 GitHub 代码搜索
完整模式（智能体代理）
对于非平凡的功能，启动调研智能体（Researcher Agent）：
Task(subagent_type="general-purpose", prompt="
调研现有的工具，针对：[功能描述]
语言/框架：[LANG]
约束条件：[ANY]
搜索范围：npm/PyPI, MCP 服务器, Claude Code 技能, GitHub
返回结果：带建议的结构化对比报告
")
按类别搜索快捷方式
开发工具（Development Tooling）
- 代码检查（Linting）→
eslint, ruff, textlint, markdownlint
- 格式化（Formatting）→
prettier, black, gofmt
- 测试（Testing）→
jest, pytest, go test
- Pre-commit →
husky, lint-staged, pre-commit
AI/LLM 集成
- Claude SDK → 参考 Context7 获取最新文档
- 提示词管理（Prompt management）→ 检查 MCP 服务器
- 文档处理 →
unstructured, pdfplumber, mammoth
数据与 API
- HTTP 客户端 →
httpx (Python), ky/got (Node)
- 验证（Validation）→
zod (TS), pydantic (Python)
- 数据库 → 优先检查 MCP 服务器
内容与发布
- Markdown 处理 →
remark, unified, markdown-it
- 图像优化 →
sharp, imagemin
集成点（Integration Points）
与规划智能体（Planner Agent）集成
规划器应在第一阶段（架构审查 Architecture Review）之前调用调研员：
- 调研员识别可用工具
- 规划器将它们纳入实施计划
- 避免在计划中“重复造轮子”
与架构智能体（Architect Agent）集成
架构师应就以下内容咨询调研员：
与迭代检索技能（Iterative-retrieval Skill）集成
结合使用进行渐进式发现：
- 第 1 轮：广泛搜索 (npm, PyPI, MCP)
- 第 2 轮：详细评估首选候选方案
- 第 3 轮：测试与项目约束的兼容性
示例
示例 1：“添加死链检查”
需求：检查 markdown 文件中的损坏链接
搜索：npm "markdown dead link checker"
发现：textlint-rule-no-dead-link (得分: 9/10)
行动：采用 (ADOPT) — npm install textlint-rule-no-dead-link
结果：零自定义代码，经受过实战检验的解决方案
示例 2：“添加 HTTP 客户端封装层”
需求：具备重试和超时处理能力的弹性 HTTP 客户端
搜索：npm "http client retry", PyPI "httpx retry"
发现：带重试插件的 got (Node), 内置重试的 httpx (Python)
行动：采用 (ADOPT) — 直接使用带重试配置的 got/httpx
结果：零自定义代码，生产环境验证过的库
示例 3：“添加配置文件 Linter”
需求：根据 Schema 验证项目配置文件
搜索：npm "config linter schema", "json schema validator cli"
发现：ajv-cli (得分: 8/10)
行动：采用 + 扩展 (ADOPT + EXTEND) — 安装 ajv-cli，编写项目特定的 schema
结果：1 个包 + 1 个 schema 文件，无需自定义验证逻辑
反模式（Anti-Patterns）
- 直接编码：不检查是否存在现成工具就编写工具类
- 忽视 MCP：不检查 MCP 服务器是否已经提供了该功能
- 过度自定义：对库进行过重封装，导致其丧失原有优势
- 依赖膨胀：为了一个很小的功能安装庞大的包
1---
2name: search-first
3description: Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Invokes the researcher agent.
4origin: ECC
5---
6
7# /search-first — 编码前先调研（Research Before You Code）
8
9将“在实现前搜索现有解决方案”的工作流系统化。
10
11## 触发条件（Trigger）
12
13在以下场景使用此技能（Skill）：
14- 开始开发一个很可能已有现成解决方案的新功能
15- 添加依赖项或集成
16- 用户要求“添加 X 功能”且你正准备编写代码
17- 在创建新的工具类（Utility）、辅助函数（Helper）或抽象层之前
18
19## 工作流（Workflow）
20
21```
22┌─────────────────────────────────────────────┐
23│ 1. 需求分析 (NEED ANALYSIS) │
24│ 定义所需功能 │
25│ 识别语言/框架约束 │
26├─────────────────────────────────────────────┤
27│ 2. 并行搜索 (调研智能体 researcher agent) │
28│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
29│ │ npm / │ │ MCP / │ │ GitHub / │ │
30│ │ PyPI │ │ 技能 │ │ Web │ │
31│ └──────────┘ └──────────┘ └──────────┘ │
32├─────────────────────────────────────────────┤
33│ 3. 评估 (EVALUATE) │
34│ 为候选方案打分（功能、维护、 │
35│ 社区、文档、许可证、依赖） │
36├─────────────────────────────────────────────┤
37│ 4. 决策 (DECIDE) │
38│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
39│ │ 采用 │ │ 扩展 │ │ 自研 │ │
40│ │ (Adopt) │ │ (Extend)│ │ (Build) │ │
41│ └─────────┘ └──────────┘ └─────────┘ │
42├─────────────────────────────────────────────┤
43│ 5. 实施 (IMPLEMENT) │
44│ 安装包 / 配置 MCP / │
45│ 编写最少量的自定义代码 │
46└─────────────────────────────────────────────┘
47```
48
49## 决策矩阵（Decision Matrix）
50
51| 信号 | 行动 |
52|--------|--------|
53| 完全匹配、维护良好、MIT/Apache 协议 | **采用 (Adopt)** — 直接安装并使用 |
54| 部分匹配、基础良好 | **扩展 (Extend)** — 安装 + 编写轻量封装层 |
55| 多个弱匹配项 | **组合 (Compose)** — 结合 2-3 个小型包 |
56| 未找到合适方案 | **自研 (Build)** — 编写自定义代码，但基于调研结论 |
57
58## 如何使用
59
60### 快速模式（行内使用）
61
62在编写工具类或添加功能前，大脑中先过一遍：
63
640. 仓库中是否已存在？→ 先通过 `rg` 搜索相关的模块/测试
651. 这是一个常见问题吗？→ 搜索 npm/PyPI
662. 是否有相关的 MCP？→ 检查 `~/.claude/settings.json` 并搜索
673. 是否有相关的技能（Skill）？→ 检查 `~/.claude/skills/`
684. 是否有 GitHub 实现/模板？→ 在编写全新代码前，针对维护良好的开源软件（OSS）运行 GitHub 代码搜索
69
70### 完整模式（智能体代理）
71
72对于非平凡的功能，启动调研智能体（Researcher Agent）：
73
74```
75Task(subagent_type="general-purpose", prompt="
76 调研现有的工具，针对：[功能描述]
77 语言/框架：[LANG]
78 约束条件：[ANY]
79
80 搜索范围：npm/PyPI, MCP 服务器, Claude Code 技能, GitHub
81 返回结果：带建议的结构化对比报告
82")
83```
84
85## 按类别搜索快捷方式
86
87### 开发工具（Development Tooling）
88- 代码检查（Linting）→ `eslint`, `ruff`, `textlint`, `markdownlint`
89- 格式化（Formatting）→ `prettier`, `black`, `gofmt`
90- 测试（Testing）→ `jest`, `pytest`, `go test`
91- Pre-commit → `husky`, `lint-staged`, `pre-commit`
92
93### AI/LLM 集成
94- Claude SDK → 参考 Context7 获取最新文档
95- 提示词管理（Prompt management）→ 检查 MCP 服务器
96- 文档处理 → `unstructured`, `pdfplumber`, `mammoth`
97
98### 数据与 API
99- HTTP 客户端 → `httpx` (Python), `ky`/`got` (Node)
100- 验证（Validation）→ `zod` (TS), `pydantic` (Python)
101- 数据库 → 优先检查 MCP 服务器
102
103### 内容与发布
104- Markdown 处理 → `remark`, `unified`, `markdown-it`
105- 图像优化 → `sharp`, `imagemin`
106
107## 集成点（Integration Points）
108
109### 与规划智能体（Planner Agent）集成
110规划器应在第一阶段（架构审查 Architecture Review）之前调用调研员：
111- 调研员识别可用工具
112- 规划器将它们纳入实施计划
113- 避免在计划中“重复造轮子”
114
115### 与架构智能体（Architect Agent）集成
116架构师应就以下内容咨询调研员：
117- 技术栈决策
118- 集成模式发现
119- 现有参考架构
120
121### 与迭代检索技能（Iterative-retrieval Skill）集成
122结合使用进行渐进式发现：
123- 第 1 轮：广泛搜索 (npm, PyPI, MCP)
124- 第 2 轮：详细评估首选候选方案
125- 第 3 轮：测试与项目约束的兼容性
126
127## 示例
128
129### 示例 1：“添加死链检查”
130```
131需求：检查 markdown 文件中的损坏链接
132搜索：npm "markdown dead link checker"
133发现：textlint-rule-no-dead-link (得分: 9/10)
134行动：采用 (ADOPT) — npm install textlint-rule-no-dead-link
135结果：零自定义代码，经受过实战检验的解决方案
136```
137
138### 示例 2：“添加 HTTP 客户端封装层”
139```
140需求：具备重试和超时处理能力的弹性 HTTP 客户端
141搜索：npm "http client retry", PyPI "httpx retry"
142发现：带重试插件的 got (Node), 内置重试的 httpx (Python)
143行动：采用 (ADOPT) — 直接使用带重试配置的 got/httpx
144结果：零自定义代码，生产环境验证过的库
145```
146
147### 示例 3：“添加配置文件 Linter”
148```
149需求：根据 Schema 验证项目配置文件
150搜索：npm "config linter schema", "json schema validator cli"
151发现：ajv-cli (得分: 8/10)
152行动：采用 + 扩展 (ADOPT + EXTEND) — 安装 ajv-cli，编写项目特定的 schema
153结果：1 个包 + 1 个 schema 文件，无需自定义验证逻辑
154```
155
156## 反模式（Anti-Patterns）
157
158- **直接编码**：不检查是否存在现成工具就编写工具类
159- **忽视 MCP**：不检查 MCP 服务器是否已经提供了该功能
160- **过度自定义**：对库进行过重封装，导致其丧失原有优势
161- **依赖膨胀**：为了一个很小的功能安装庞大的包
xu-xiang