search-first

name	search-first
description	编码前先研究的工作流。在编写自定义代码之前搜索现有工具、库和模式。调用研究员智能体。
origin	ECC

/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 或项目包管理器	使用 web/文档搜索，避免声称注册表覆盖
GitHub CLI	gh auth status	仅使用公开 web 或本地 git 历史
MCP/文档工具	可用工具列表或本地 MCP 配置	回退到官方文档/web 搜索
技能目录	ls ~/.claude/skills ~/.codex/skills（如适用）	说明没有本地技能目录可用

快速模式（内联）

在编写工具函数或添加功能之前，在脑中快速过一遍：

0. 仓库中是否已存在？→ 先用 rg 搜索相关模块/测试
1. 这是常见问题吗？→ 搜索 npm/PyPI
2. 是否有 MCP 支持这个？→ 检查 ~/.claude/settings.json 并搜索
3. 是否有技能支持这个？→ 检查 ~/.claude/skills/
4. 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 获取最新文档
• Prompt 管理 → 检查 MCP 服务器
• 文档处理 → unstructured、pdfplumber、mammoth

数据和 API

• HTTP 客户端 → httpx（Python）、ky/undici（Node）
• 验证 → zod（TS）、pydantic（Python）
• 数据库 → 先检查 MCP 服务器

内容和发布

• Markdown 处理 → remark、unified、markdown-it
• 图片优化 → sharp、imagemin

集成点

与规划器智能体

规划器应在阶段 1（架构审查）之前调用研究员：

• 研究员识别可用工具
• 规划器将它们纳入实现计划
• 避免在计划中"重新发明轮子"

与架构师智能体

架构师应向研究员咨询：

• 技术栈决策
• 集成模式发现
• 现有参考架构

与迭代检索技能

组合使用以进行渐进式发现：

• 周期 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 服务器是否已提供该能力
• 静默跳过：在搜索渠道不可用时报告"未找到"
• 过度定制：过度封装库使其失去优势
• 依赖膨胀：为一个小功能安装巨大的包