CLAUDE.md 進階撰寫
CLAUDE.md 是 Claude Code 在每個對話開始時自動載入的專案級上下文，相當於給 AI 的「工程手冊」。好的 CLAUDE.md 能大幅減少重複溝通成本，讓每輪對話都從正確的起點出發。
進階結構建議：把 CLAUDE.md 分為四個區塊：① 專案概覽（技術棧、目錄職責）、② 開發流程（常用指令、測試方式）、③ 限制紅線（不可修改模組、敏感路徑）、④ 交付格式（回覆結構、驗證步驟）。
# CLAUDE.md 範例骨架
## 專案概覽
- 技術棧：Next.js 14 + TypeScript + Prisma + PostgreSQL
- 目錄職責：`app/` 路由層，`lib/` 業務邏輯，`prisma/` 資料模型
## 開發流程
```bash
pnpm dev # 本機啟動
pnpm test # 執行全部測試
pnpm typecheck # TypeScript 型別檢查
```
## 紅線限制
- **禁止修改** `lib/auth/` 下任何檔案，除非明確指示
- 所有 DB 變更必須透過 Prisma migration，不可直接寫 SQL
## 交付格式
每次回覆必須包含：變更摘要、受影響檔案清單、驗證命令與結果。
CLAUDE.md 支援 Markdown，善用標題與清單讓結構清晰。同一個 monorepo 可在子目錄放置局部 CLAUDE.md，Claude Code 會自動合併多層上下文。
Hooks 設定：pre-tool-use 與 post-tool-use
Hooks 是 Claude Code 在執行工具前後插入自訂腳本的機制，讓你在不侵入提示詞的情況下強化流程管控。常見用途包括：自動 lint、格式化、拒絕危險指令、記錄操作日誌。
Hooks 設定於 settings.json（專案層）或 ~/.claude/settings.json（使用者層）。pre-tool-use 可返回非零 exit code 來阻擋工具執行；post-tool-use 適合做後處理與通知。
// .claude/settings.json 範例
{
"hooks": {
"pre-tool-use": [
{
"matcher": "bash",
"hooks": [
{
"type": "command",
"command": "bash /project/scripts/guard-dangerous-cmd.sh \"$CLAUDE_TOOL_INPUT\""
}
]
}
],
"post-tool-use": [
{
"matcher": "write_file|edit_file",
"hooks": [
{
"type": "command",
"command": "pnpm eslint --fix $CLAUDE_TOOL_OUTPUT_PATH 2>&1 | tail -5"
}
]
}
]
}
}
- 用
pre-tool-use 阻擋含 rm -rf /、DROP TABLE 等危險模式
- 用
post-tool-use 自動觸發 lint/format，確保每次寫檔後代碼風格一致
- Hook 腳本保持輕量（<500ms），避免拖慢互動節奏
- 在 CI 環境中可用 hook 記錄完整操作日誌，方便事後審計
多 Agent 並行：Git Worktree 策略
當你需要同時進行多個獨立功能或探索多種實作方案時，可以結合 Git Worktree 與多個 Claude Code 實例達成真正的並行開發，互不干擾。
# 建立三個並行工作樹
git worktree add ../project-feat-auth feat/auth
git worktree add ../project-feat-api feat/api
git worktree add ../project-refactor refactor/db-layer
# 在各目錄分別啟動 Claude Code（不同終端機視窗）
cd ../project-feat-auth && claude
cd ../project-feat-api && claude
cd ../project-refactor && claude
每個 worktree 共享同一個 Git 物件庫，但有獨立的工作目錄與暫存區。Claude Code 在各 worktree 中是完全隔離的 session，可安全同時操作不同分支而不互相覆蓋。
並行工作時，建議在主 worktree 的 CLAUDE.md 中標示各 worktree 的職責邊界，並設定好 merge 策略（如 rebase-then-merge），避免最終整合時產生大量衝突。
MCP Server 整合
Model Context Protocol（MCP）讓 Claude Code 能呼叫外部工具服務，擴充預設工具箱。常見整合場景包括：資料庫查詢、Jira/Linear 票務、Figma 設計稿讀取、Sentry 錯誤追蹤。
# 在 settings.json 中宣告 MCP Server
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/mydb"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
- 啟動後用 /mcp 指令確認 Server 連線狀態
- 敏感憑證透過環境變數注入，不寫死於設定檔
- 只開放 Claude Code 需要的最小權限範圍（principle of least privilege）
- 自訂 MCP Server 可用 Node.js 或 Python SDK 快速實作，幾十行即可完成基本工具
自訂 Slash Commands 範例
將高頻的複合型指令封裝成 Slash Command，放入 .claude/commands/ 目錄，讓團隊成員一鍵觸發標準化流程，無需每次手打長串提示詞。
# .claude/commands/review-pr.md
---
description: 對當前 git diff 進行 Code Review，輸出結構化報告
---
請對以下 git diff 執行 Code Review：
```bash
git diff main...HEAD
```
報告格式：
1. **摘要**：本次改動目的與範圍
2. **潛在風險**：安全性、效能、相容性問題
3. **改進建議**：每條建議附上具體修改方式
4. **測試覆蓋**：指出未覆蓋的邊界條件
嚴格程度：正式 PR 標準，不放過任何命名不清或缺少錯誤處理的地方。
儲存後，在對話中輸入 /review-pr 即可觸發。Commands 支援 Markdown 與 frontmatter，可搭配 $ARGUMENTS 接收動態參數，例如 /deploy staging。
團隊共用的 Commands 放在 .claude/commands/（納入版本控制）；個人專用的放在 ~/.claude/commands/。同名時專案級優先。
大型重構分解策略
面對橫跨數十個檔案的大型重構，一次性請 Claude Code 完成往往會導致上下文爆滿、錯誤累積。正確做法是用「里程碑分解法」將重構拆成多個獨立、可驗證的子任務。
里程碑分解原則：每個子任務必須滿足三個條件 — ① 有清楚的輸入與輸出定義、② 有獨立的驗證命令、③ 失敗時可單獨回滾而不影響其他子任務。
- 第一輪：只分析現有代碼，輸出依賴圖與改動影響評估，不動任何代碼
- 第二輪：建立新的型別定義或介面，並補上對應測試
- 第三輪：逐模組遷移，每遷移一個模組就跑一次測試套件
- 第四輪：刪除舊代碼、清理廢棄 export
- 每輪結束後執行 git commit，保留可回滾的檢查點
# 分解指令範例（第一輪分析提示詞骨架）
請分析 `src/services/` 目錄下所有模組的對外依賴關係。
輸出一份 Markdown 表格，欄位為：模組名稱 | 被引用次數 | 直接依賴 | 改動風險（高/中/低）。
不要修改任何檔案，只輸出分析報告。
安全操作原則
Claude Code 擁有執行 shell 指令與寫入檔案的能力，使用前應建立明確的操作邊界，防止意外破壞生產環境或洩漏機密。
- 本機開發時使用 --no-production 或在
.env.local 指向測試資料庫
- 將
.env、*.pem、credentials.json 加入 .claudeignore，防止 AI 讀取並洩漏
- 透過
pre-tool-use Hook 阻擋所有含 --force、DROP、TRUNCATE 的指令
- 定期檢視
~/.claude/logs/ 下的操作記錄，確認無異常存取
- 在 CI 中使用 headless 模式時，以最小權限服務帳號執行，不使用個人 API Key
對於生產資料庫操作，建議額外設定一個確認 Hook：要求 Claude Code 在執行任何 DDL 語句前先輸出 dry-run 結果，由人工確認後再正式執行。
Token 節省技巧
每個 session 的 context window 有限，善用以下技巧可顯著延長有效對話輪次，降低 API 費用。
- 用 /clear 在完成一個子任務後清空上下文，避免無關歷史干擾新任務
- 用 /compact 要求 Claude Code 壓縮當前對話摘要，保留關鍵資訊同時釋放 token 空間
- 在 CLAUDE.md 中只放「高頻需要」的資訊，避免把整份技術文件塞進去
- 使用
--files 參數精準指定需要讀取的檔案，而非讓 AI 自行探索整個目錄
- 對大型檔案，在提示詞中指定行號範圍：「請看
lib/auth.ts 的第 80–120 行」
- 避免在同一個 session 中混合多個無關任務，專注單一目標
Claude Code 會自動壓縮長對話，但主動管理上下文能讓 AI 在關鍵決策點保持更高的注意力集中度，輸出品質更穩定。
CI/CD 整合：Headless Mode
Claude Code 支援 --print（非互動式）模式，可在 CI pipeline 中無人值守地執行代碼審查、自動修復或文件生成。
# GitLab CI 範例：PR 自動 Code Review
claude-review:
stage: review
image: node:20
script:
- npm install -g @anthropic-ai/claude-code
- git diff $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD > /tmp/diff.txt
- claude --print "請審查以下 diff 並輸出 Markdown 格式的 review 報告：$(cat /tmp/diff.txt)" \
> review-report.md
- cat review-report.md
artifacts:
paths: [review-report.md]
only:
- merge_requests
# GitHub Actions 範例：自動修復 lint 錯誤
- name: Auto-fix lint
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude --print "執行 pnpm lint，修復所有可自動修復的錯誤，最後跑 pnpm typecheck 確認無型別錯誤" \
--allowedTools bash,write_file,edit_file
在 CI 中務必透過 --allowedTools 限制 Claude Code 可用的工具清單，避免 AI 在自動化環境中執行非預期的副作用指令。
指令設計技巧
好的指令設計能讓 Claude Code 從第一輪就輸出可用結果，避免來回修正。以下是幾個核心技法：
黃金公式：「背景說明 + 具體目標 + 限制條件 + 輸出格式 + 驗證方式」五要素缺一不可。缺少任何一項都可能導致 AI 做出合理但不符合期待的選擇。
- 先問後做：加上「在開始實作前，先列出你的執行計畫，等我確認後再動手」，避免方向偏差
- 負面約束：明確說明「不要動 X 檔案」、「不要引入新依賴」比只說「做 Y」更有效
- 錨定範例：提供一個現有的好代碼作為風格參考，AI 會自動對齊
- 分步驟交付：「先做 A，完成後告訴我，再做 B」比「同時做 A 和 B」更可控
- 量化驗證：指定具體的成功標準，如「所有 207 個測試必須通過」而非「確保測試通過」
- 重複關鍵約束：對於最重要的限制，在指令開頭與結尾各提一次，強化 AI 的注意力
# 高品質指令範例
背景：我們正在將 Express.js API 遷移至 Hono，目前 `routes/users.ts` 已完成遷移作為參考。
目標：將 `routes/orders.ts` 按相同模式遷移至 Hono。
限制：
- 不要修改 `middleware/` 目錄下的任何檔案
- 不要引入 routes/users.ts 以外的新套件
- 保留所有現有的錯誤處理邏輯
輸出格式：直接修改 routes/orders.ts，完成後執行 `pnpm test routes/orders` 並回報結果。
驗證標準：測試全部通過，且 TypeScript 無型別錯誤。
請先列出你的遷移步驟，等我確認後再開始實作。