/search-first — 研究先于编码
系统化"在实现之前先搜索现有解决方案"的工作流程。
触发条件
在以下场景使用此技能：
- 开始一个新功能，该功能很可能已有现成解决方案
- 添加依赖项或集成
- 用户要求"添加 X 功能"，而你即将编写代码
- 在创建新的工具函数、辅助方法或抽象层之前
工作流程
┌─────────────────────────────────────────────┐
│ 0. 工具可用性预检 │
│ 在依赖搜索渠道之前先检查其可用性； │
│ 诚实报告跳过的渠道 │
├─────────────────────────────────────────────┤
│ 1. 需求分析 │
│ 定义所需功能 │
│ 确定语言/框架约束 │
├─────────────────────────────────────────────┤
│ 2. 并行搜索（研究者代理） │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ Skills │ │ Web │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. 评估 │
│ 对候选方案评分（功能、维护状况、 │
│ 社区活跃度、文档、许可证、依赖项） │
├─────────────────────────────────────────────┤
│ 4. 决策 │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ 直接采用 │ │ 扩展/包装 │ │ 自定义构建│ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. 实现 │
│ 安装包 / 配置 MCP / │
│ 编写最少量的自定义代码 │
└─────────────────────────────────────────────┘
决策矩阵
| 信号 | 行动 |
|---|---|
| 完全匹配，维护良好，MIT/Apache 许可证 | 直接采用 — 安装并直接使用 |
| 部分匹配，基础良好 | 扩展 — 安装并编写薄包装层 |
| 多个弱匹配 | 组合 — 组合 2-3 个小包 |
| 未找到合适的方案 | 构建 — 编写自定义代码，但在研究基础上进行 |
使用方式
步骤 0：工具可用性预检
这是代理指导，不是可执行的设置脚本。仅检查与当前任务和项目相关的渠道。
| 渠道 | 检查内容 | 如果缺失 |
|---|---|---|
| 仓库搜索 | rg --files 和有针对性的 rg 查询 | 声明仅检查了可见文件 |
| 包注册表 | npm --version、python -m pip --version 或项目包管理器 | 使用网络/文档搜索，不声称具有注册表覆盖 |
| GitHub CLI | gh auth status | 仅使用公共网络或本地 git 历史 |
| MCP/文档工具 | 可用工具列表或本地 MCP 配置 | 回退到官方文档/网络搜索 |
| 技能目录 | 在适用处 ls ~/.claude/skills ~/.codex/skills | 说明没有可用的本地技能目录 |
快速模式（内联）
在编写工具函数或添加功能之前，在脑海中快速过一遍：
- 这已经在仓库中存在了吗？→ 首先通过
rg搜索相关模块/测试 - 这是一个常见问题吗？→ 搜索 npm/PyPI
- 是否有对应的 MCP？→ 检查
~/.claude/settings.json并搜索 - 是否有对应的技能？→ 检查
~/.claude/skills/ - 是否有 GitHub 实现/模板？→ 在编写全新代码前运行 GitHub 代码搜索，查找维护良好的开源项目
完整模式（代理）
对于非平凡的功能，启动研究者代理：
Agent(subagent_type="general-purpose", prompt="
研究用于以下功能的现有工具： [描述]
语言/框架： [语言]
约束： [任何约束]
搜索： npm/PyPI, MCP 服务器, Claude Code 技能, GitHub
返回： 结构化比较及推荐
")
旧版 Claude Code 文档可能称此为 Task(...)；请使用当前活动工具集暴露的 agent/subagent 工具名称。
按类别分类的搜索快捷方式
开发工具
- 语法检查 →
eslint、ruff、textlint、markdownlint - 代码格式化 →
prettier、black、gofmt - 测试 →
jest、pytest、go test - 预提交 →
husky、lint-staged、pre-commit
AI/LLM 集成
- Claude SDK → 使用 Context7 获取最新文档
- 提示词管理 → 检查 MCP 服务器
- 文档处理 →
unstructured、pdfplumber、mammoth
数据和 API
- HTTP 客户端 →
httpx(Python)、ky/undici(Node) - 验证 →
zod(TypeScript)、pydantic(Python) - 数据库 → 优先检查 MCP 服务器
内容和发布
- Markdown 处理 →
remark、unified、markdown-it - 图片优化 →
sharp、imagemin
集成点
与规划代理集成
规划代理应在第一阶段（架构审查）之前调用研究者代理：
- 研究者识别可用工具
- 规划代理将其纳入实现计划
- 避免在计划中"重复造轮子"
与架构代理集成
架构代理应咨询研究者代理以进行：
- 技术栈决策
- 集成模式发现
- 现有参考架构
与迭代检索技能集成
组合用于渐进式发现：
- 周期 1：广泛搜索（npm、PyPI、MCP）
- 周期 2：详细评估顶级候选方案
- 周期 3：测试与项目约束的兼容性
示例
示例 1："添加死链检查"
需求：检查 Markdown 文件中的失效链接
搜索：npm "markdown dead link checker"
发现：textlint-rule-no-dead-link (评分：9/10)
行动：直接采用 — npm install textlint-rule-no-dead-link
结果：零自定义代码，久经考验的解决方案
示例 2："添加 HTTP 客户端包装"
需求：具有重试和超时处理的弹性 HTTP 客户端
搜索：npm "http client retry"、PyPI "httpx retry"
发现：got (Node) 带有重试插件、httpx (Python) 带有内建重试
行动：直接采用 — 使用带重试配置的 got/httpx
结果：零自定义代码，生产级验证的库
示例 3："添加配置文件检查工具"
需求：根据模式验证项目配置文件
搜索：npm "config linter schema"、"json schema validator cli"
发现：ajv-cli (评分：8/10)
行动：直接采用 + 扩展 — 安装 ajv-cli，编写项目特定的模式
结果：1 个包 + 1 个模式文件，零自定义验证逻辑
反模式
- 直接跳到编码：不检查是否存在现成方案，直接编写工具函数
- 忽略 MCP：不检查 MCP 服务器是否已提供该功能
- 静默跳过：当搜索渠道不可用时，报告"未找到任何内容"
- 过度定制：过度包装一个库，使其失去原有优势
- 依赖膨胀：为一个小功能安装一个庞大的包