search-first

/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（適用時）	說明沒有可用的本地技能目錄

快速模式（行內）

在撰寫工具函式或加入功能之前，在腦中快速跑一遍：

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(...)；請使用目前執行環境提供的代理/子代理工具名稱。

依類別搜尋捷徑

開發工具

• Linting → eslint、ruff、textlint、markdownlint
• 格式化 → prettier、black、gofmt
• 測試 → jest、pytest、go test
• Pre-commit → 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

整合點

與規劃代理

規劃代理應在研究員代理之前（第一階段：架構審查）呼叫：

• 研究員找出可用工具
• 規劃代理將其納入實作計畫
• 避免在計畫中「重新發明輪子」

與架構代理

架構代理應諮詢研究員代理以取得：

• 技術棧決策
• 整合模式探索
• 現有參考架構

與迭代檢索技能

結合使用以進行漸進式探索：

• 第一輪：廣泛搜尋（npm、PyPI、MCP）
• 第二輪：詳細評估頂尖候選方案
• 第三輪：測試與專案限制的相容性

範例

範例 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：「加入設定檔 linter」

需求：根據 schema 驗證專案設定檔
搜尋：npm "config linter schema"、"json schema validator cli"
找到：ajv-cli（評分：8/10）
行動：直接採用 + 擴充 — 安裝 ajv-cli，撰寫專屬 schema
結果：1 個套件 + 1 個 schema 檔案，無自訂驗證邏輯

反模式

• 直接跳入程式碼：未檢查是否存在現有工具就撰寫工具函式
• 忽略 MCP：未檢查 MCP 伺服器是否已提供該功能
• 默默跳過：當搜尋管道不可用時仍回報「找不到」
• 過度自訂：包裝函式庫到失去其優點
• 相依性膨脹：為了一個小功能安裝龐大的套件