/search-first —— 先研究，再编码
系统化地执行“在实现之前搜索现有解决方案”的工作流程。
触发条件
在以下情况使用此技能：
- 开始一个可能存在现有解决方案的新功能
- 添加依赖或集成
- 用户要求“添加 X 功能”，而你正准备编写代码
- 在创建新的工具函数、助手或抽象层之前
工作流程
┌─────────────────────────────────────────────┐
│ 0. 工具可用性预检 │
│ 在依赖搜索渠道之前检查其可用性； │
│ 如实报告跳过的渠道 │
├─────────────────────────────────────────────┤
│ 1. 需求分析 │
│ 定义所需功能 │
│ 识别语言/框架约束 │
├─────────────────────────────────────────────┤
│ 2. 并行搜索（研究员智能体） │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ 技能 │ │ 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(...)；请使用当前活动工具集暴露的智能体/子智能体工具名称。
按类别分类的搜索快捷方式
开发工具
- 代码检查 →
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(TS)、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 服务器是否已提供所需能力
- 静默跳过：当搜索渠道不可用时，却报告“未找到任何内容”
- 过度定制：包装库过重，以至于失去了它带来的好处
- 依赖膨胀：为一个小功能安装一个庞大的包