---
name: search-first
description: 「先研究後編碼」工作流。在撰寫自定義程式碼前，優先搜尋現有的工具、函式庫與模式。會調用研究員 (Researcher) Agent。
---

# /search-first — 先研究，再動手

系統化地落實「在開始實作前，優先搜尋現有解決方案」的工作流。

## 觸發時機

在以下情境時使用此技能：
- 開始一項新的功能開發，且該功能極大機率已有現成方案。
- 準備添加新的依賴項或整合。
- 使用者要求「增加 X 功能」，而你正準備開始撰寫程式碼時。
- 在建立新的工具函式 (Utility)、輔助程式 (Helper) 或抽象層之前。

## 工作流程

```
┌─────────────────────────────────────────────┐
│  1. 需求分析 (Need Analysis)                 │
│     定義所需的功能細節                         │
│     識別語言或框架的限制條件                   │
├─────────────────────────────────────────────┤
│  2. 並行搜尋 (Parallel Search)               │
│     ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│     │  npm /   │ │  MCP /   │ │  GitHub / │  │
│     │  PyPI    │ │  Skills  │ │  Web      │  │
│     └──────────┘ └──────────┘ └──────────┘  │
├─────────────────────────────────────────────┤
│  3. 方案評估 (Evaluate)                      │
│     針對候選方案評分（功能、維護狀況、社群、     │
│     文件、授權證明、依賴量）                   │
├─────────────────────────────────────────────┤
│  4. 做成決策 (Decide)                        │
│     ┌─────────┐  ┌──────────┐  ┌─────────┐  │
│     │ 直接採用 │  │ 擴展/封裝 │  │ 自行建構 │  │
│     │ (Adopt) │  │ (Wrap)   │  │ (Build) │  │
│     └─────────┘  └──────────┘  └─────────┘  │
├─────────────────────────────────────────────┤
│  5. 執行路徑 (Implement)                     │
│     安裝套件 / 配置 MCP / 撰寫最小自研程式碼     │
└─────────────────────────────────────────────┘
```

## 決策矩陣

| 訊號特徵 | 採取行動 |
|--------|--------|
| 完全符合需求、維護良好、具備 MIT/Apache 等友善授權 | **直接採用 (Adopt)** — 安裝並直接使用 |
| 部分符合需求、基礎紮實 | **擴展 (Extend)** — 安裝後撰寫一層薄薄的封裝 (Wrapper) |
| 有多個小型的弱符合項 | **組合 (Compose)** — 結合 2 至 3 個小型套件 |
| 找不到任何適合的方案 | **自行建構 (Build)** — 根據研究心得撰寫自定義程式碼 |

## 如何使用

### 快速模式 (思維核對)

在撰寫工具函式或增加功能前，先在腦中跑過一遍：
1. 這是一般性的常見問題嗎？ → 搜尋 npm / PyPI。
2. 是否已有對應的 MCP？ → 檢查 `~/.claude/settings.json` 並搜尋。
3. 是否已有相關技能 (Skill)？ → 檢查 `~/.claude/skills/`。
4. GitHub 上是否有模板？ → 在 GitHub 搜尋。

### 完整模式 (Agent 執行)

針對非瑣碎的功能需求，啟動研究員 (Researcher) Agent：

```
Task(subagent_type="general-purpose", prompt="
  研究現有工具以實現：[功能描述]
  程式語言/框架：[語言]
  限制條件：[任何特殊限制]

  搜尋目標：npm/PyPI, MCP servers, Claude Code skills, GitHub
  結果要求：結構化對比表並給出具體建議
")
```

## 各類別搜尋快捷參考

### 開發工具類
- 代碼檢查 (Linting) → `eslint`, `ruff`, `textlint`, `markdownlint`
- 代碼格式化 (Formatting) → `prettier`, `black`, `gofmt`
- 測試工具 → `jest`, `pytest`, `go test`
- Pre-commit → `husky`, `lint-staged`, `pre-commit`

### AI/LLM 整合類
- Claude SDK → 參考 Context7 獲取最新文件
- 提示詞管理 → 優先檢查 MCP servers
- 文件處理 → `unstructured`, `pdfplumber`, `mammoth`

### 數據與 API 類
- HTTP 客戶端 → `httpx` (Python), `ky` / `got` (Node)
- 資料驗證 → `zod` (TS), `pydantic` (Python)
- 資料庫操作 → 優先檢查是否有可用的 MCP server

## 整合要點

### 與規劃者 (Planner) 整合
規劃者應在「階段 1（架構審查）」之前調用研究員：
- 研究員識别可用工具。
- 規劃者將工具納入實作計劃。
- 避免在計畫中「重新發明輪子」。

### 與反覆擷取技能 (Iterative-retrieval) 整合
結合以進行漸進式探索：
- 循環 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 的重試配置
成效：零自研程式碼，使用被生產環境證明過的庫
```

## 應避免的反模式

- **直接開工**：在未確認是否有現成方案前，直接開始撰寫工具。
- **無視 MCP**：沒檢查 MCP server 是否已經提供了該能力。
- **過度封裝**：對函式庫進行極其厚重的封裝，導致失去其原本優勢。
- **依賴臃腫**：為了實現一個微小功能而安裝一個巨大的重型套件。