/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(...)；請使用目前執行環境所提供的代理/子代理工具名稱。
依類別分類的搜尋捷徑
開發工具
- 程式碼檢查 →
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（架構審查）之前呼叫研究者：
- 研究者找出可用的工具
- 規劃者將這些工具納入實作計畫
- 避免在計畫中「重新發明輪子」
與架構師代理整合
架構師應諮詢研究者以進行：
- 技術棧決策
- 整合模式探索
- 尋找現有的參考架構
與迭代檢索技能整合
結合使用以進行漸進式探索：
- 週期 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 伺服器是否已提供該功能
- 沉默跳過：搜尋通道不可用時，仍回報「找不到任何東西」
- 過度自訂：將一個函式庫包裝得過於沉重，以至於失去其優勢
- 相依套件膨脹：為了一個小功能安裝一個龐大的套件