/search-first — 研究先於編碼
將「在實作前先搜尋既有解決方案」的工作流程系統化。
觸發時機
在以下情況使用此技能：
- 開始一個很可能已有現有解決方案的新功能時
- 加入一個依賴項或整合時
- 使用者要求「加入 X 功能」而你正準備開始寫程式碼時
- 在建立新的工具函式、輔助函式或抽象層之前
工作流程
┌─────────────────────────────────────────────┐
│ 0. 工具可用性預檢 │
│ 在依賴搜尋管道前先檢查其可用性； │
│ 誠實回報跳過的管道 │
├─────────────────────────────────────────────┤
│ 1. 需求分析 │
│ 定義所需的功能 │
│ 識別語言/框架限制 │
├─────────────────────────────────────────────┤
│ 2. 平行搜尋 (研究代理) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ 技能 │ │ 網路 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 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(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：「加入設定檔檢查器」
需求：根據 schema 驗證專案設定檔
搜尋：npm "config linter schema", "json schema validator cli"
找到：ajv-cli (分數：8/10)
行動：直接採用 + 擴展 — 安裝 ajv-cli，撰寫專案專屬 schema
結果：1 個套件 + 1 個 schema 檔案，無自訂驗證邏輯
反模式
- 直接跳入程式碼：未檢查是否存在即撰寫工具函式
- 忽略 MCP：未檢查 MCP 伺服器是否已提供該能力
- 靜默跳過：當搜尋管道不可用時回報「找不到任何內容」
- 過度客製化：過度包裝函式庫，使其失去原有優勢
- 依賴膨脹：為了一個小功能安裝一個龐大的套件