claude-code/README.md

# Claude Code 工具箱

用 Claude Code 從零到一打造產品的完整工作環境。包含 23 個 AI Agent、45 個指令、66 個技能知識庫。

---

## 目錄

- [前置需求](#前置需求)
- [快速開始](#快速開始)
- [專案結構](#專案結構)
- [指令總覽](#指令總覽)
- [從零到一：打造產品的完整流程](#從零到一打造產品的完整流程)
- [常用工作流程](#常用工作流程)
- [如何追加與擴充](#如何追加與擴充)
- [MCP Server 說明](#mcp-server-說明)
- [FAQ](#faq)

---

## 前置需求

| 工具 | 用途 | 安裝方式 |
|------|------|----------|
| **Claude Code CLI** | 核心 AI 助手 | `npm install -g @anthropic-ai/claude-code` |
| **Node.js ≥ 18** | 執行 MCP server 與腳本 | [nodejs.org](https://nodejs.org) 或 `brew install node` |
| **Git** | 版本控制 | `brew install git`（macOS 通常已內建） |

以下為**選用**，依你的開發語言安裝：

| 工具 | 用途 |
|------|------|
| Go | 使用 `/go-build`、`/go-review`、`/go-test` 指令 |
| Python 3 | 使用 `/python-review` 指令 |
| PM2 | 使用 `/pm2` 服務管理指令（`npm install -g pm2`） |

## 快速開始

```bash
# 1. 複製這個工具箱到你的專案
cp -r claude/ 你的專案/claude/

# 2. 安裝所有依賴（MCP server 等）
make install

# 3. 進入你的專案，啟動 Claude Code
cd 你的專案
claude

# 4. 在 Claude Code 裡輸入斜線指令開始工作
#    輸入 / 會看到所有可用指令
```

> **提示**：第一次使用請先跑 `make install`，它會幫你裝好所有 MCP server 需要的 npm 套件。

---

## 專案結構

```
.claude/
├── CLAUDE.md              # 總開發規範（Claude 自動讀取）
├── agents/                # 23 個 AI Agent 定義
│   ├── architect.md       #   架構師
│   ├── planner.md         #   規劃師
│   ├── code-reviewer.md   #   程式碼審查
│   ├── tdd-guide.md       #   TDD 引導
│   ├── security-reviewer.md #  安全審查
│   ├── fin-*.md           #   金融分析系列（5 個）
│   └── pm-*.md            #   產品經理系列（4 個）
├── commands/              # 45 個斜線指令
│   ├── plan.md            #   /plan — 規劃
│   ├── tdd.md             #   /tdd — 測試驅動開發
│   ├── code-review.md     #   /code-review — 程式碼審查
│   ├── fin-*.md           #   /fin-* — 金融分析系列
│   ├── pm-*.md            #   /pm-* — 產品經理系列
│   └── ...                #   更多指令見下方總覽
├── skills/                # 66 個技能知識庫（Claude 自動參考）
│   ├── golang-clean-arch/ #   Go Clean Architecture
│   ├── tdd-workflow/      #   TDD 工作流程
│   └── ...                #   各語言/框架的最佳實踐
├── rules/                 # 各語言的編碼規範
│   ├── common/            #   通用規範
│   ├── golang/            #   Go 規範
│   ├── python/            #   Python 規範
│   ├── typescript/        #   TypeScript 規範
│   └── swift/             #   Swift 規範
└── mcp-configs/           # MCP Server 設定範本
    └── mcp-servers.json   #   可用的 MCP server 清單
```

> **Skills 不會出現在 `/` 選單裡**，它們是背景知識，Claude 會在需要時自動參考。

---

## 指令總覽

在 Claude Code 裡輸入 `/` 就能看到所有指令。以下依用途分類：

### 🏗️ 規劃與架構

| 指令 | 說明 |
|------|------|
| `/plan` | 重述需求 → 風險評估 → 分步計劃。**不會動程式碼**，等你確認才開始 |
| `/orchestrate` | 串接多個 Agent 執行複雜任務（feature / bugfix / refactor / security） |

### 💻 開發與測試

| 指令 | 說明 |
|------|------|
| `/tdd` | 測試驅動開發：先寫測試 → 實作 → 重構 → 確保 80%+ 覆蓋率 |
| `/build-fix` | 逐一修復建置/型別錯誤，一次一個，最小改動 |
| `/code-review` | 全面程式碼審查（安全、品質、效能） |
| `/verify` | 一鍵驗證：建置 → 型別 → Lint → 測試 → 安全掃描 |
| `/test-coverage` | 分析覆蓋率缺口，自動補測試到 80%+ |
| `/refactor-clean` | 安全移除死碼，每步都跑測試驗證 |
| `/e2e` | 用 Playwright 產生並執行端對端測試 |

### 🐹 Go 專用

| 指令 | 說明 |
|------|------|
| `/go-build` | 修復 Go 建置錯誤、go vet 警告 |
| `/go-review` | Go 程式碼審查（慣用寫法、並發安全、錯誤處理） |
| `/go-test` | Go TDD 工作流程（table-driven tests） |

### 🐍 Python 專用

| 指令 | 說明 |
|------|------|
| `/python-review` | Python 審查（PEP 8、型別提示、安全、慣用寫法） |


### 💰 金融分析系列

| 指令 | 說明 |
|------|------|
| `/fin-full` | 完整金融分析（市場研究 → 估值 → 客戶 → 建模 → 戰略，輸出 7 份報告） |
| `/fin-research` | 市場規模估算 + 競爭格局 + SWOT/波特五力 |
| `/fin-valuation` | DCF 估值 + 可比公司分析 + 目標價推導 |
| `/fin-customer` | 客戶 Persona + 細分矩陣 + 旅程地圖 |
| `/fin-model` | 定價策略 + 單位經濟 + 3 年財務預測 |
| `/fin-strategy` | GTM 策略 + 90 天行動計劃 + CEO 摘要 |
| `/fin-screen` | 量化選股篩選（基本面/技術面/籌碼面） |

### 📋 產品經理系列

| 指令 | 說明 |
|------|------|
| `/pm` | 完整 PM 流程 → 輸出結構化 PRD |
| `/pm-research` | 只做市場規模與競品研究 |
| `/pm-user` | 只做用戶痛點挖掘 |
| `/pm-plan` | 功能排序 + 旅程設計 + Roadmap |
| `/pm-edit` | 修改/深化現有 PRD |

### 🤖 多模型協作

| 指令 | 說明 |
|------|------|
| `/multi-workflow` | 完整多模型協作流程（Research → Plan → Execute → Review） |
| `/multi-plan` | 多模型協作規劃 |
| `/multi-execute` | 多模型協作執行 |
| `/multi-frontend` | 前端開發（Gemini 主導） |
| `/multi-backend` | 後端開發（Codex 主導） |

### 🧠 學習與進化

| 指令 | 說明 |
|------|------|
| `/learn` | 從當前 session 提取可重用模式 |
| `/learn-eval` | 提取模式 + 品質自評 + 決定存放位置 |
| `/skill-create` | 分析 git 歷史，自動產生 SKILL.md |
| `/evolve` | 將學到的 instinct 聚合成 skill/agent |
| `/instinct-status` | 查看所有已學習的 instinct |
| `/instinct-import` | 匯入 instinct |
| `/instinct-export` | 匯出 instinct |

### 🔧 工具與維護

| 指令 | 說明 |
|------|------|
| `/update-codemaps` | 產生/更新架構文件（token 精簡版） |
| `/update-docs` | 從原始碼同步文件 |
| `/sessions` | 管理 session 歷史（列表/載入/別名） |
| `/checkpoint` | 建立工作流程檢查點 |
| `/setup-pm` | 設定偏好的套件管理器 |
| `/pm2` | 自動偵測專案並產生 PM2 服務管理指令 |

---

## 從零到一：打造產品的完整流程

以下是用這套工具箱從一個想法變成可運行產品的完整步驟：

### 第一步：市場研究（你還只有一個模糊的想法）

```
你：/fin-research 我想做一個幫自由工作者管理發票的 SaaS
```

Claude 會產出市場規模估算、競爭格局分析、SWOT 分析。

### 第二步：用戶研究（確認真的有人需要）

```
你：/pm-user 自由工作者在發票管理上的痛點
```

Claude 會從公開管道挖掘真實用戶聲音，產出痛點清單。

### 第三步：產品規劃（決定要做什麼）

```
你：/pm 我想做一個幫自由工作者管理發票的 SaaS，
    目標台灣市場，3 個月 MVP，一人開發
```

Claude 會跑完整 PM 流程，產出結構化的 PRD（產品需求文件）。

### 第四步：架構規劃（決定怎麼做）

```
你：/plan 根據剛才的 PRD，規劃技術架構和實作步驟
```

planner agent 會產出分階段的實作計劃，**等你確認才動手**。

### 第五步：開始開發（寫程式）

```
你：/tdd 實作用戶註冊功能
```

Claude 會用 TDD 流程：先寫測試 → 實作 → 重構 → 確保覆蓋率。

### 第六步：程式碼審查

```
你：/code-review
```

全面審查安全性、程式碼品質、效能問題。

### 第七步：驗證一切正常

```
你：/verify
```

一鍵跑完建置、型別檢查、Lint、測試、安全掃描。

### 完整流程圖

```
想法 → /fin-research（市場研究）
     → /pm-user（用戶研究）
     → /pm（產品規劃 → PRD）
     → /plan（技術規劃）
     → /tdd（開發）
     → /code-review（審查）
     → /verify（驗證）
     → 部署 🚀
```

> 不一定要跑完所有步驟。如果你已經很清楚要做什麼，可以直接從 `/plan` 開始。

---

## 常用工作流程

### 日常開發

```bash
/plan 新增 XXX 功能          # 先規劃
/tdd 實作 XXX               # TDD 開發
/code-review                 # 審查
/verify                      # 驗證
```

### 修 Bug

```bash
/orchestrate bugfix "描述問題"  # 自動串接 planner → tdd → reviewer
```

### 重構

```bash
/refactor-clean              # 先清死碼
/orchestrate refactor "重構快取層"  # 架構師 → 審查 → TDD
```

### Go 專案

```bash
/go-test 實作 user 模組      # Go TDD（自動套用 Clean Architecture）
/go-review                   # Go 程式碼審查
/go-build                    # 修建置錯誤
```

---

## 如何追加與擴充

### 新增指令（Command）

在 `.claude/commands/` 建立 `.md` 檔，檔名就是指令名（`my-cmd.md` → `/my-cmd`）：

```markdown
---
description: 這段會顯示在 / 選單裡
---

# 指令名稱

你希望 Claude 做什麼的詳細說明...
```

> ⚠️ **不支援子目錄**，用前綴分組：`fin-`、`pm-`、`go-` 等。

### 新增 Agent

在 `.claude/agents/` 建立 `.md` 檔：

```markdown
---
name: my-agent
description: Agent 的職責描述
tools: ["Read", "Write", "Bash"]
model: sonnet
---

你是一個專精於 XXX 的專家...
```

### 新增 Skill（知識庫）

在 `.claude/skills/` 建立**目錄**，裡面放 `SKILL.md`：

```bash
mkdir -p claude/skills/my-skill
# 然後編輯 claude/skills/my-skill/SKILL.md
```

> Skills 支援子目錄，Claude 會自動發現。不會出現在 `/` 選單。

### 追加的最佳實踐

1. **命名一致**：用前綴分組（`fin-`、`pm-`、`go-`）
2. **先寫 Command，再考慮 Agent**：大多數需求用 Command 就夠了
3. **Skill 放通用知識**：架構規範、設計模式
4. **Rule 放強制規範**：編碼風格、安全要求
5. **用 `/learn` 自動提取**：做完事後跑 `/learn`，讓 Claude 自己提煉模式

---

## MCP Server 說明

MCP（Model Context Protocol）Server 讓 Claude 能連接外部服務。

### 安裝

```bash
make install          # 安裝所有免費 MCP
make mcp-github       # 或單獨安裝
```

### 啟用

安裝後，將需要的 server 設定從 `.claude/mcp-configs/mcp-servers.json` 複製到 `~/.claude.json` 的 `mcpServers` 區段。

### 可用清單

| Server | 用途 | 需要 API Key |
|--------|------|:---:|
| context7 | 即時查詢最新技術文件 | ❌ |
| github | GitHub PR/Issue 操作 | ✅ |
| memory | 跨 session 持久記憶 | ❌ |
| sequential-thinking | 鏈式推理 | ❌ |
| magic | Magic UI 元件 | ❌ |
| filesystem | 檔案系統操作 | ❌ |
| firecrawl | 網頁爬取 | ✅ |
| supabase | 資料庫操作 | ✅ |
| vercel | 部署（HTTP，免安裝） | ✅ |
| cloudflare-* | 文件/Workers/監控（HTTP，免安裝） | ❌ |
| clickhouse | 分析查詢（HTTP，免安裝） | ✅ |

> 建議同時啟用不超過 10 個，以免佔用太多 context window。

---

## FAQ

**Q：指令太多記不住？**
輸入 `/` 就會看到所有指令。最常用：`/plan`、`/tdd`、`/code-review`、`/verify`。

**Q：Skills 和 Commands 差在哪？**
Commands 是你主動輸入 `/xxx` 觸發的動作；Skills 是背景知識，Claude 需要時自動參考。

**Q：Agent 和 Command 差在哪？**
Agent 定義角色（身份、能力）；Command 定義動作（流程），可能呼叫多個 Agent。

**Q：我只寫 Go，不需要其他語言的東西？**
不相關的指令不會影響你。專注用 `/go-*` 系列 + 通用的 `/plan`、`/tdd`、`/verify`。

**Q：怎麼讓 Claude 記住我的偏好？**
編輯 `.claude/CLAUDE.md`，Claude 每次啟動都會自動讀取。

**Q：中文版（.claude-zh）是什麼？**
`.claude-zh/` 是 `.claude/` 的繁體中文翻譯版。想用中文版就把它改名為 `.claude/`（先備份原版）。