本文整合 Anthropic 官方 Best Practices 與社群實戰 Tips，帶你由淺入深掌握 Claude Code。

什麼是 Claude Code？為什麼值得學？

如果你還在用「複製程式碼貼到 ChatGPT，再複製答案貼回去」的工作流程，Claude Code 會讓你大開眼界。

Claude Code 是 Anthropic 推出的命令列工具，它直接活在你的 terminal 裡，能夠讀懂你的整個 codebase、寫入檔案、執行指令、操作 git，甚至幫你開 PR。它不只是個「提示框」，而是一個能主動採取行動的 AI 代理（agentic coding assistant）。

用一句話形容：你告訴它要做什麼，它去搞定。

很多從 Cursor、GitHub Copilot 轉過來的工程師都說，用過 Claude Code 之後回不去了。原因不是它比較聰明，而是它的工作方式根本不同——它在你的環境裡工作，而不是你把東西帶去它的環境。

第一步：安裝與基本啟動

安裝 Claude Code 只需要一行：

curl -fsSL https://claude.ai/install.sh | bash

安裝後，進入你的專案目錄，直接輸入 claude 就能啟動。

四種啟動模式

建議新手先從 claude 開始，熟悉基本操作後，-c 和 -r 會成為你每天的好朋友。

Headless Mode（claude -p）

claude -p 是 Claude Code 從「個人工具」升級到「團隊基礎設施」的關鍵能力：

• 非互動式，執行完就結束，不進入對話模式
• 適合用在 CI/CD、git hooks、自動化腳本
• 可搭配 --output-format stream-json 輸出結構化 JSON，方便下游程式處理
• 可搭配 --allowedTools 限制可用工具範圍

# 最簡單的用法
claude -p "review 這個 PR 的安全性問題"

# pipe 資料進去
cat error.log | claude -p "分析這些錯誤，找出最常見的根因"

# 輸出 JSON 給下游處理
claude -p "列出所有 deprecated 的 API 呼叫" --output-format stream-json | your_script.py

# 限制工具範圍（更安全）
claude -p "把 foo.py 從 React 改成 Vue" --allowedTools Edit "Bash(git commit:*)"

第二步：學會在對話中操作

進入 Claude Code 後，它看起來像個聊天介面，但有一些特殊符號和快捷鍵讓你的效率倍增。

三個超有用的符號

@ 指定檔案：輸入 @ 後會顯示檔案列表，支援模糊搜尋，讓你精確告訴 Claude 要操作哪個檔案，不用擔心它讀錯地方。

! 直接執行 shell 指令：有時你只是想快速執行一個指令，不需要 AI 處理，直接用 ! 前綴就能執行 shell 命令。例如 !git status 或 !ls -la。

# 加入記憶：當你輸入 # 開頭的訊息，系統會詢問你要存入哪個 CLAUDE.md，讓 Claude 長期記住這段背景知識。例如「# 我們的 API 版本是 v2，請不要使用 v1 的 endpoint」，之後的每次對話它都會記得。

不可不知的快捷鍵

• ESC — 中斷當前任務。Claude 正在瘋狂編輯檔案但方向不對？按 ESC 立刻停下，不會破壞 session，可以重新下指令
• ESC ESC（按兩次） — 顯示過去發送的訊息列表，讓你選擇一個重新發送，類似「開分支」的概念，從不同的起點探索
• Shift+TAB — 切換工作模式

三種工作模式

使用 Shift+TAB 可以在三種模式間切換：

自動接受模式（auto-accept edits）：Claude 提議的修改自動核准，適合信任度高、不想每次都確認的場景。速度最快。

規劃模式（plan mode）：Claude 只做分析和規劃，不會實際動檔案。在開始寫程式之前，先用這個模式讓它產出設計方案給你審核，是架構討論的好幫手。

危險模式（--dangerously-skip-permissions）：跳過所有權限確認，讓 Claude 全速工作。官方文件特別強調這個模式要在有限制的 Docker container 裡使用，不建議在本機直接用。

第三步：設定你的專案大腦 — CLAUDE.md

CLAUDE.md 是整個 Claude Code 生態系中最重要的概念。這個檔案是 Claude 每次啟動對話時必讀的說明書，放對內容，效果立竿見影。

第一次使用時，執行 /init 指令，Claude 會自動分析你的 codebase 結構並產生一份基礎的 CLAUDE.md，再手動精修即可。

放什麼在 CLAUDE.md？

• 常用的 bash 指令（npm run build、npm run test 等）
• 核心檔案與工具函式的位置說明
• 程式碼風格規範（例如：使用 ES modules 而非 CommonJS）
• 測試方式與規則
• Git 工作流程規範（例如：branch 命名方式、merge vs. rebase）
• 開發環境特殊設定
• 任何你希望 Claude 永遠記住的事項

# 常用指令
- npm run build: 建置專案
- npm run test: 執行測試
- npm run typecheck: 型別檢查

# 程式碼風格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 盡量用解構語法引入 (import { foo } from 'bar')
- 所有 API 呼叫都走 /src/api/ 資料夾的封裝

# 工作流程
- 每次改完記得跑 typecheck
- 測試優先，盡量跑單一測試而非全套
- branch 命名格式：feature/xxx 或 fix/xxx

CLAUDE.md 的四個層級

根據官方文件，CLAUDE.md 其實有四個層級，由高到低依序套用：

CLAUDE.local.md 會自動加入 .gitignore，適合放沙箱 URL、個人測試資料等不應上傳的設定。

@import 語法

CLAUDE.md 支援用 @ 語法引入其他檔案，最多支援 5 層巢狀：

# 引入其他說明文件
請參考 @README 了解專案概覽，@package.json 查看可用指令。

# Git 工作流程
@docs/git-instructions.md

# 個人偏好（引入自 home 目錄，不會進 git）
@~/.claude/my-project-instructions.md

這讓 CLAUDE.md 保持簡潔，把細節拆到獨立文件裡分開維護。

Monorepo 建議結構

CLAUDE.md 支援多層級繼承，Claude 會自動把沿途讀到的所有 CLAUDE.md 合併進 context，這對 monorepo 非常適合：

root/
├── CLAUDE.md                ← 全專案共用：monorepo 工具（nx/turborepo）、CI 指令、跨 package 規範
│                               可用 @import 引入各 package 文件
├── docs/
│   └── git-instructions.md  ← 被 @import 引用的獨立說明
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md        ← 前端專用：React 規範、CSS-in-JS、UI 元件慣例
│   ├── backend/
│   │   └── CLAUDE.md        ← 後端專用：API 設計規範、DB migration 指令
│   └── shared/
│       └── CLAUDE.md        ← shared lib 專用：型別規範、不能有 side effect 等限制
└── CLAUDE.local.md          ← 個人設定，自動加入 .gitignore

分層邏輯：

• 根目錄 放「任何 package 都適用」的內容，例如 pnpm install、branch 命名規則、PR 流程
• 各 package 只放「這個 package 才有意義」的差異化內容

當你在 packages/frontend/ 啟動 claude，它會同時讀到根目錄與 packages/frontend/ 的 CLAUDE.md，不需要在每個 package 重複寫共用規範。

小技巧：根目錄的 CLAUDE.md 加一行職責邊界說明，例如「packages/shared 只能被其他 package 引用，不能引用 frontend 或 backend 的程式碼」，跨 package 重構時 Claude 就不會犯錯。

其他管理記憶的方式

• # 快速新增：輸入 # 內容，系統會詢問要存入哪個 CLAUDE.md
• /memory 指令：在對話中執行，會用系統編輯器開啟記憶檔案，適合一次做大量整理

第四步：上下文管理 — 最關鍵的資源

很多人用 Claude Code 用著用著開始感覺它「變笨了」，原因幾乎都是一樣的：context window 滿了。

Claude 的整個對話歷史、讀過的每個檔案、執行過的每個指令輸出，全都塞在 context window 裡。一個複雜的除錯過程，可能幾萬個 token 就燒掉了。當 context 快滿，Claude 開始「遺忘」早期的指令，犯更多錯誤。

兩個關鍵指令

/clear：清除所有當前對話的 context，重新開始。開始一個全新任務之前，養成習慣打 /clear，讓它帶著清爽的頭腦工作。

/compact：壓縮 context，可以附上提示說明要保留哪些重點。注意，壓縮後有可能遺失部分細節、導致後續表現變差，更建議的做法是直接開新的 session。

官方建議：在長對話工作後、切換到新任務前，定期使用 /clear。有些工程師甚至把「每次開始新任務就 /clear」當成強制習慣。

第五步：善用 Think 模式深度推理

Claude Code 支援幾個特殊關鍵字，讓它進入不同深度的思考模式：

使用方式很直覺，直接在 prompt 裡說「請 think hard，設計這個資料庫 schema」或「ultrathink，分析這個 bug 的根本原因」即可。

重要提醒：更深的思考消耗更多 token，建議根據問題複雜度選擇。簡單任務用 think 就夠，複雜架構設計或難以追蹤的 bug 才用 ultrathink。

中文指令「想一想」、「深度思考」也可以被識別，但優先用英文以確保穩定性。

第六步：掌握高效工作流

有了基礎工具知識後，來看幾個 Anthropic 官方推薦的實戰工作流。

工作流一：探索 → 規劃 → 實作 → Commit

這是最通用的工作流，適合大多數功能開發場景：

1. 探索：告訴 Claude 讀相關的檔案、圖表或 URL，但明確說「還不要寫程式」。這個階段讓它建立完整的 context。
2. 規劃：請 Claude 制定實作計畫（可以用 think hard 讓它想得更仔細）。計畫確認後，請它寫成 Markdown 文件或 GitHub issue 存檔。
3. 實作：拿著確認好的計畫，請它動手寫程式。
4. Commit：請 Claude 寫 commit message 並 commit，需要的話也可以請它開 PR。

前兩步是關鍵。很多工程師跳過規劃直接叫它寫，結果方向跑偏，浪費更多時間。

工作流二：TDD 測試驅動開發

這是 Anthropic 內部最愛的工作流，AI 時代的 TDD 威力加倍：

1. 請 Claude 根據預期的輸入輸出寫測試，明確說要做 TDD，不要先做 mock 實作
2. 請它跑測試，確認測試確實失敗
3. 對測試滿意後，請它 commit 測試
4. 請 Claude 寫讓測試通過的實作，不允許修改測試，讓它自己跑測試、修改、再跑，直到全部通過
5. 確認後 commit 實作

提供清晰的「完成標準」是讓 Claude 表現最好的方式，而測試就是最好的完成標準。

工作流三：截圖視覺迭代（UI 開發最愛）

1. 給 Claude 一個設計稿圖片（拖放或貼上截圖）
2. 請它實作 UI
3. 透過 Puppeteer MCP 讓它截圖比對
4. 請它根據差異迭代修正
5. 滿意後 commit

Claude 在有視覺目標時表現特別好。第一版可能不完美，但給它 2-3 輪迭代後通常相當接近設計稿。

第七步：進階技巧 — 讓 Claude 更強大

擴充工具能力：MCP

MCP（Model Context Protocol）是讓 Claude Code 連接外部服務的標準協議。常用的有：

• Puppeteer：讓 Claude 能操控瀏覽器、截圖
• GitHub MCP：更深度整合 GitHub 操作
• 資料庫 MCP：直接查詢你的資料庫

在專案目錄加入 .mcp.json 設定檔，整個團隊都能共用這些工具。

自訂 Slash 指令

把重複的工作流程做成 slash 指令，存在 .claude/commands/ 資料夾裡。例如建立 fix-github-issue.md：

請分析並修復 GitHub issue：$ARGUMENTS

步驟：
1. 用 gh issue view 取得 issue 詳細內容
2. 理解問題描述
3. 搜尋 codebase 找出相關檔案
4. 實作必要的修改
5. 撰寫並執行測試驗證修復
6. 確認通過 lint 和 type check
7. 建立描述性的 commit message
8. Push 並開 PR

之後只要輸入 /project:fix-github-issue 1234 就能一鍵處理 issue #1234。個人常用指令則存到 ~/.claude/commands/ 讓所有專案都能用。

允許清單（Permissions）

用 /permissions 指令把常用操作加入允許清單，例如 Edit（允許編輯檔案）和 Bash(git commit:*)（允許 git commit），不用每次都確認，工作流程更流暢。

第八步：多 Claude 並行 — 終極生產力

當你熟悉了單 Claude 工作流後，可以嘗試更強大的多 Agent 模式。

雙 Claude 互審

用第一個 Claude 寫程式，另開一個 terminal 或用 /clear 重置，讓第二個 Claude 審查程式碼。不同的 context 往往能發現不同的問題，效果類似真實的 code review。

Git Worktrees 平行作業

這是 Anthropic 工程師內部的常用技巧：用 git worktree add 建立多個獨立的工作目錄，每個目錄開一個 Claude，同時處理不同任務：

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

cd ../project-feature-a && claude  # Claude A 做 feature A
cd ../project-feature-b && claude  # Claude B 做 feature B

# 完成後清理
git worktree remove ../project-feature-a
git worktree remove ../project-feature-b

兩個任務互不干擾，你只需要輪流去確認進度和核准操作。

給新手的建議清單

操作習慣

• 每次開始新任務前先 /clear，保持 context 乾淨
• 養成用 ESC 中斷而非 Ctrl+C（後者會直接退出整個程式）
• 用 @ 精確指定檔案，不要讓它猜
• 重要決策和設定用 # 記錄到 CLAUDE.md，或用 /memory 做整理

下指令的原則

• 具體比模糊好。「幫我加測試」遠不如「為 foo.py 新增一個測試 case，覆蓋使用者未登入的邊界情況，不要用 mock」
• 先規劃再實作，省下來的時間遠比多打一次指令值得
• 根據問題複雜度選擇 think 層級，不要每次都 ultrathink

品質把關

• Claude 寫的程式你負責 review，最終責任在你
• 有測試和 CI 的環境下信任它更多，沒有就要多留意
• 對話越長越要注意 context 品質，適時 /clear 比用 /compact 更可靠

結語

Claude Code 的學習曲線不在於功能複雜，而在於思維方式的轉換：從「AI 幫我補全程式碼」轉向「AI 是我的協作工程師，我負責方向，它負責執行」。

一開始可能會覺得要打很多字、要設定很多東西。但一旦你的 CLAUDE.md 建立起來，slash 指令設定好，權限調整完，你會發現整個開發體驗有質的飛躍。

從今天開始，打開 terminal，進入你的專案，輸入 claude，然後問它：「你對這個 codebase 有什麼問題嗎？」——你們的旅程就此開始。

參考資料：Anthropic 官方 Claude Code Best Practices、Anthropic 官方 Memory 文件、Cash Wu 的 Claude Code Tips

本文整合 Anthropic 官方 Best Practices 與社群實戰 Tips，帶你由淺入深掌握 Claude Code。

什麼是 Claude Code？為什麼值得學？

如果你還在用「複製程式碼貼到 ChatGPT，再複製答案貼回去」的工作流程，Claude Code 會讓你大開眼界。

Claude Code 是 Anthropic 推出的命令列工具，它直接活在你的 terminal 裡，能夠讀懂你的整個 codebase、寫入檔案、執行指令、操作 git，甚至幫你開 PR。它不只是個「提示框」，而是一個能主動採取行動的 AI 代理（agentic coding assistant）。

用一句話形容：你告訴它要做什麼，它去搞定。

很多從 Cursor、GitHub Copilot 轉過來的工程師都說，用過 Claude Code 之後回不去了。原因不是它比較聰明，而是它的工作方式根本不同——它在你的環境裡工作，而不是你把東西帶去它的環境。

第一步：安裝與基本啟動

安裝 Claude Code 只需要一行：

curl -fsSL https://claude.ai/install.sh | bash

安裝後，進入你的專案目錄，直接輸入 claude 就能啟動。

四種啟動模式

建議新手先從 claude 開始，熟悉基本操作後，-c 和 -r 會成為你每天的好朋友。

Headless Mode（claude -p）

claude -p 是 Claude Code 從「個人工具」升級到「團隊基礎設施」的關鍵能力：

• 非互動式，執行完就結束，不進入對話模式
• 適合用在 CI/CD、git hooks、自動化腳本
• 可搭配 --output-format stream-json 輸出結構化 JSON，方便下游程式處理
• 可搭配 --allowedTools 限制可用工具範圍

# 最簡單的用法
claude -p "review 這個 PR 的安全性問題"

# pipe 資料進去
cat error.log | claude -p "分析這些錯誤，找出最常見的根因"

# 輸出 JSON 給下游處理
claude -p "列出所有 deprecated 的 API 呼叫" --output-format stream-json | your_script.py

# 限制工具範圍（更安全）
claude -p "把 foo.py 從 React 改成 Vue" --allowedTools Edit "Bash(git commit:*)"

第二步：學會在對話中操作

進入 Claude Code 後，它看起來像個聊天介面，但有一些特殊符號和快捷鍵讓你的效率倍增。

三個超有用的符號

@ 指定檔案：輸入 @ 後會顯示檔案列表，支援模糊搜尋，讓你精確告訴 Claude 要操作哪個檔案，不用擔心它讀錯地方。

! 直接執行 shell 指令：有時你只是想快速執行一個指令，不需要 AI 處理，直接用 ! 前綴就能執行 shell 命令。例如 !git status 或 !ls -la。

# 加入記憶：當你輸入 # 開頭的訊息，系統會詢問你要存入哪個 CLAUDE.md，讓 Claude 長期記住這段背景知識。例如「# 我們的 API 版本是 v2，請不要使用 v1 的 endpoint」，之後的每次對話它都會記得。

不可不知的快捷鍵

• ESC — 中斷當前任務。Claude 正在瘋狂編輯檔案但方向不對？按 ESC 立刻停下，不會破壞 session，可以重新下指令
• ESC ESC（按兩次） — 顯示過去發送的訊息列表，讓你選擇一個重新發送，類似「開分支」的概念，從不同的起點探索
• Shift+TAB — 切換工作模式

三種工作模式

使用 Shift+TAB 可以在三種模式間切換：

自動接受模式（auto-accept edits）：Claude 提議的修改自動核准，適合信任度高、不想每次都確認的場景。速度最快。

規劃模式（plan mode）：Claude 只做分析和規劃，不會實際動檔案。在開始寫程式之前，先用這個模式讓它產出設計方案給你審核，是架構討論的好幫手。

危險模式（--dangerously-skip-permissions）：跳過所有權限確認，讓 Claude 全速工作。官方文件特別強調這個模式要在有限制的 Docker container 裡使用，不建議在本機直接用。

第三步：設定你的專案大腦 — CLAUDE.md

CLAUDE.md 是整個 Claude Code 生態系中最重要的概念。這個檔案是 Claude 每次啟動對話時必讀的說明書，放對內容，效果立竿見影。

第一次使用時，執行 /init 指令，Claude 會自動分析你的 codebase 結構並產生一份基礎的 CLAUDE.md，再手動精修即可。

放什麼在 CLAUDE.md？

• 常用的 bash 指令（npm run build、npm run test 等）
• 核心檔案與工具函式的位置說明
• 程式碼風格規範（例如：使用 ES modules 而非 CommonJS）
• 測試方式與規則
• Git 工作流程規範（例如：branch 命名方式、merge vs. rebase）
• 開發環境特殊設定
• 任何你希望 Claude 永遠記住的事項

# 常用指令
- npm run build: 建置專案
- npm run test: 執行測試
- npm run typecheck: 型別檢查

# 程式碼風格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 盡量用解構語法引入 (import { foo } from 'bar')
- 所有 API 呼叫都走 /src/api/ 資料夾的封裝

# 工作流程
- 每次改完記得跑 typecheck
- 測試優先，盡量跑單一測試而非全套
- branch 命名格式：feature/xxx 或 fix/xxx

CLAUDE.md 的四個層級

根據官方文件，CLAUDE.md 其實有四個層級，由高到低依序套用：

CLAUDE.local.md 會自動加入 .gitignore，適合放沙箱 URL、個人測試資料等不應上傳的設定。

@import 語法

CLAUDE.md 支援用 @ 語法引入其他檔案，最多支援 5 層巢狀：

# 引入其他說明文件
請參考 @README 了解專案概覽，@package.json 查看可用指令。

# Git 工作流程
@docs/git-instructions.md

# 個人偏好（引入自 home 目錄，不會進 git）
@~/.claude/my-project-instructions.md

這讓 CLAUDE.md 保持簡潔，把細節拆到獨立文件裡分開維護。

Monorepo 建議結構

CLAUDE.md 支援多層級繼承，Claude 會自動把沿途讀到的所有 CLAUDE.md 合併進 context，這對 monorepo 非常適合：

root/
├── CLAUDE.md                ← 全專案共用：monorepo 工具（nx/turborepo）、CI 指令、跨 package 規範
│                               可用 @import 引入各 package 文件
├── docs/
│   └── git-instructions.md  ← 被 @import 引用的獨立說明
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md        ← 前端專用：React 規範、CSS-in-JS、UI 元件慣例
│   ├── backend/
│   │   └── CLAUDE.md        ← 後端專用：API 設計規範、DB migration 指令
│   └── shared/
│       └── CLAUDE.md        ← shared lib 專用：型別規範、不能有 side effect 等限制
└── CLAUDE.local.md          ← 個人設定，自動加入 .gitignore

分層邏輯：

• 根目錄 放「任何 package 都適用」的內容，例如 pnpm install、branch 命名規則、PR 流程
• 各 package 只放「這個 package 才有意義」的差異化內容

當你在 packages/frontend/ 啟動 claude，它會同時讀到根目錄與 packages/frontend/ 的 CLAUDE.md，不需要在每個 package 重複寫共用規範。

小技巧：根目錄的 CLAUDE.md 加一行職責邊界說明，例如「packages/shared 只能被其他 package 引用，不能引用 frontend 或 backend 的程式碼」，跨 package 重構時 Claude 就不會犯錯。

其他管理記憶的方式

• # 快速新增：輸入 # 內容，系統會詢問要存入哪個 CLAUDE.md
• /memory 指令：在對話中執行，會用系統編輯器開啟記憶檔案，適合一次做大量整理

第四步：上下文管理 — 最關鍵的資源

很多人用 Claude Code 用著用著開始感覺它「變笨了」，原因幾乎都是一樣的：context window 滿了。

Claude 的整個對話歷史、讀過的每個檔案、執行過的每個指令輸出，全都塞在 context window 裡。一個複雜的除錯過程，可能幾萬個 token 就燒掉了。當 context 快滿，Claude 開始「遺忘」早期的指令，犯更多錯誤。

兩個關鍵指令

/clear：清除所有當前對話的 context，重新開始。開始一個全新任務之前，養成習慣打 /clear，讓它帶著清爽的頭腦工作。

/compact：壓縮 context，可以附上提示說明要保留哪些重點。注意，壓縮後有可能遺失部分細節、導致後續表現變差，更建議的做法是直接開新的 session。

官方建議：在長對話工作後、切換到新任務前，定期使用 /clear。有些工程師甚至把「每次開始新任務就 /clear」當成強制習慣。

第五步：善用 Think 模式深度推理

Claude Code 支援幾個特殊關鍵字，讓它進入不同深度的思考模式：

使用方式很直覺，直接在 prompt 裡說「請 think hard，設計這個資料庫 schema」或「ultrathink，分析這個 bug 的根本原因」即可。

重要提醒：更深的思考消耗更多 token，建議根據問題複雜度選擇。簡單任務用 think 就夠，複雜架構設計或難以追蹤的 bug 才用 ultrathink。

中文指令「想一想」、「深度思考」也可以被識別，但優先用英文以確保穩定性。

第六步：掌握高效工作流

有了基礎工具知識後，來看幾個 Anthropic 官方推薦的實戰工作流。

工作流一：探索 → 規劃 → 實作 → Commit

這是最通用的工作流，適合大多數功能開發場景：

1. 探索：告訴 Claude 讀相關的檔案、圖表或 URL，但明確說「還不要寫程式」。這個階段讓它建立完整的 context。
2. 規劃：請 Claude 制定實作計畫（可以用 think hard 讓它想得更仔細）。計畫確認後，請它寫成 Markdown 文件或 GitHub issue 存檔。
3. 實作：拿著確認好的計畫，請它動手寫程式。
4. Commit：請 Claude 寫 commit message 並 commit，需要的話也可以請它開 PR。

前兩步是關鍵。很多工程師跳過規劃直接叫它寫，結果方向跑偏，浪費更多時間。

工作流二：TDD 測試驅動開發

這是 Anthropic 內部最愛的工作流，AI 時代的 TDD 威力加倍：

1. 請 Claude 根據預期的輸入輸出寫測試，明確說要做 TDD，不要先做 mock 實作
2. 請它跑測試，確認測試確實失敗
3. 對測試滿意後，請它 commit 測試
4. 請 Claude 寫讓測試通過的實作，不允許修改測試，讓它自己跑測試、修改、再跑，直到全部通過
5. 確認後 commit 實作

提供清晰的「完成標準」是讓 Claude 表現最好的方式，而測試就是最好的完成標準。

工作流三：截圖視覺迭代（UI 開發最愛）

1. 給 Claude 一個設計稿圖片（拖放或貼上截圖）
2. 請它實作 UI
3. 透過 Puppeteer MCP 讓它截圖比對
4. 請它根據差異迭代修正
5. 滿意後 commit

Claude 在有視覺目標時表現特別好。第一版可能不完美，但給它 2-3 輪迭代後通常相當接近設計稿。

第七步：進階技巧 — 讓 Claude 更強大

擴充工具能力：MCP

MCP（Model Context Protocol）是讓 Claude Code 連接外部服務的標準協議。常用的有：

• Puppeteer：讓 Claude 能操控瀏覽器、截圖
• GitHub MCP：更深度整合 GitHub 操作
• 資料庫 MCP：直接查詢你的資料庫

在專案目錄加入 .mcp.json 設定檔，整個團隊都能共用這些工具。

自訂 Slash 指令

把重複的工作流程做成 slash 指令，存在 .claude/commands/ 資料夾裡。例如建立 fix-github-issue.md：

請分析並修復 GitHub issue：$ARGUMENTS

步驟：
1. 用 gh issue view 取得 issue 詳細內容
2. 理解問題描述
3. 搜尋 codebase 找出相關檔案
4. 實作必要的修改
5. 撰寫並執行測試驗證修復
6. 確認通過 lint 和 type check
7. 建立描述性的 commit message
8. Push 並開 PR

之後只要輸入 /project:fix-github-issue 1234 就能一鍵處理 issue #1234。個人常用指令則存到 ~/.claude/commands/ 讓所有專案都能用。

允許清單（Permissions）

用 /permissions 指令把常用操作加入允許清單，例如 Edit（允許編輯檔案）和 Bash(git commit:*)（允許 git commit），不用每次都確認，工作流程更流暢。

第八步：多 Claude 並行 — 終極生產力

當你熟悉了單 Claude 工作流後，可以嘗試更強大的多 Agent 模式。

雙 Claude 互審

用第一個 Claude 寫程式，另開一個 terminal 或用 /clear 重置，讓第二個 Claude 審查程式碼。不同的 context 往往能發現不同的問題，效果類似真實的 code review。

Git Worktrees 平行作業

這是 Anthropic 工程師內部的常用技巧：用 git worktree add 建立多個獨立的工作目錄，每個目錄開一個 Claude，同時處理不同任務：

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

cd ../project-feature-a && claude  # Claude A 做 feature A
cd ../project-feature-b && claude  # Claude B 做 feature B

# 完成後清理
git worktree remove ../project-feature-a
git worktree remove ../project-feature-b

兩個任務互不干擾，你只需要輪流去確認進度和核准操作。

給新手的建議清單

操作習慣

• 每次開始新任務前先 /clear，保持 context 乾淨
• 養成用 ESC 中斷而非 Ctrl+C（後者會直接退出整個程式）
• 用 @ 精確指定檔案，不要讓它猜
• 重要決策和設定用 # 記錄到 CLAUDE.md，或用 /memory 做整理

下指令的原則

• 具體比模糊好。「幫我加測試」遠不如「為 foo.py 新增一個測試 case，覆蓋使用者未登入的邊界情況，不要用 mock」
• 先規劃再實作，省下來的時間遠比多打一次指令值得
• 根據問題複雜度選擇 think 層級，不要每次都 ultrathink

品質把關

• Claude 寫的程式你負責 review，最終責任在你
• 有測試和 CI 的環境下信任它更多，沒有就要多留意
• 對話越長越要注意 context 品質，適時 /clear 比用 /compact 更可靠

結語

Claude Code 的學習曲線不在於功能複雜，而在於思維方式的轉換：從「AI 幫我補全程式碼」轉向「AI 是我的協作工程師，我負責方向，它負責執行」。

一開始可能會覺得要打很多字、要設定很多東西。但一旦你的 CLAUDE.md 建立起來，slash 指令設定好，權限調整完，你會發現整個開發體驗有質的飛躍。

從今天開始，打開 terminal，進入你的專案，輸入 claude，然後問它：「你對這個 codebase 有什麼問題嗎？」——你們的旅程就此開始。

一、 動機與痛點：為什麼你需要介入 AI 的生命週期？

在預設狀態下，Claude Code 雖然強大，但它是「被動」且「無狀態」的，這導致了開發者常遇到以下痛點：

1. 記憶重置 (Session Amnesia)：

   • 痛點：每次重啟終端機，AI 就像失憶一樣。

   • 解法：你需要一個機制，在 SessionStart 時自動把「上一集的劇情（Session Log）」灌輸給它。

2. 程式碼品質不一 (Inconsistent Quality)：

   • 痛點：AI 寫出的 Go 程式碼可能忘了 gofmt，或者留下了 fmt.Println 除錯訊息。

   • 解法：你需要一個「糾察隊」，在 PostToolUse（工具用完後）自動執行格式化與檢查。

3. 危險操作 (Safety Risks)：

   • 痛點：AI 有時會過度自信，想直接 git push 到主分支。

   • 解法：你需要在 PreToolUse（工具執行前）設下攔截點，強制顯示警告。

4. 上下文丟失 (Context Drift)：

   • 痛點：對話太長時，重要資訊被壓縮丟棄。

   • 解法：利用 PreCompact 在壓縮發生前，將關鍵狀態寫入硬碟。

二、 核心機制：生命週期圖解 (The Lifecycle)

要掌握 Hooks，必須理解這張生命週期圖。這不僅是流程，更是我們可以「插入程式碼」的機會點：

我們可以將其劃分為三個戰略區域：

1. 啟動與結束區 (Session Management)

• SessionStart：這是「載入記憶」的時刻。你的腳本 session-start.js 在這裡執行，負責掃描 .claude/sessions/ 下的 .tmp 檔案，告訴 AI 上次工作到哪裡。

• SessionEnd：這是「存檔」的時刻。session-end.js 會將當前的狀態快照保存下來，供下次使用。

2. 代理循環區 (The Agentic Loop) - 自動化的核心

這是圖中橙色虛線框起來的部分，也是 AI 實際工作的地方。

• PreToolUse (攔截層)：在 AI 真正執行 Bash 或 Edit 之前。這是防止錯誤的最佳時機（例如阻擋 git push）。

• PostToolUse (修正層)：在 AI 修改完檔案後。你的腳本可以在這裡自動執行 gofmt，或是檢查有沒有遺留的 fmt.Print。

3. 維護區 (Maintenance)

• PreCompact：當 Token 即將爆滿時，系統會觸發壓縮。利用 pre-compact.js 記錄這一事件，防止重要資訊在壓縮中「無聲消失」。

三、 配置結構與語法

Hooks 配置在 .claude/settings.local.json 中：

{
  "hooks": {
    "HookEvent": [
      {
        "matcher": "條件表達式",
        "hooks": [
          {
            "type": "command",
            "command": "要執行的指令"
          }
        ]
      }
    ]
  }
}

Matcher 語法

• "*" - 匹配所有情況

• tool == "Bash" - 匹配特定工具

• tool == "Edit" && tool_input.file_path matches "\\.go$" - 組合條件

• !(tool_input.file_path matches "README\\.md") - 排除條件

四、 實戰配置解析：你的腳本做了什麼？

結合 Go 專案範例，這套配置實現了以下具體功能：

1. 智慧型記憶掛載 (SessionStart)

你的配置不再只是依賴單一的 CLAUDE.md，而是引入了時間序列的 Session Log。

• 行為：腳本會檢查 go.mod 確認這是 Go 專案，並自動尋找最近修改過的 sessions/*.tmp 檔案。

• 優勢：AI 一啟動就知道專案類型（Go Module）以及上次具體的工作內容，實現「無縫熱啟動」。

配置範例：

{
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/session-start.js"
        }
      ]
    }
  ]
}

session-start.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');

  // 檢查是否有最近的 session 記錄
  if (fs.existsSync(sessionsDir)) {
    const files = fs.readdirSync(sessionsDir)
      .filter(f => f.endsWith('.tmp'))
      .sort().reverse();

    if (files.length > 0) {
      console.error(`[SessionStart] Found ${files.length} recent session(s)`);
      console.error(`[SessionStart] Latest: ${files[0]}`);
    }
  }

  // Go 專案檢測
  if (fs.existsSync('go.mod')) {
    const content = fs.readFileSync('go.mod', 'utf8');
    const match = content.match(/^module\s+(.+)$/m);
    if (match) {
      console.error(`[SessionStart] Go project: ${match[1]}`);
    }
  }

  process.exit(0);
}

main();

2. 強制性程式碼規範 (PostToolUse)

這是這套配置最精彩的部分—— 自動修正 (Auto-Correction)。

• 行為：當監測到 Edit 工具修改了 .go 檔案後，Hooks 會自動觸發：

    gofmt -w "file_path"
  

  同時，若發現檔案內含有 fmt.Print，會透過 console.error 警告開發者。

• 優勢：即使 AI 生成的程式碼格式混亂，寫入硬碟的那一刻也會被強制修正為標準格式。這大幅減少了 code review 的負擔。

配置範例：

{
  "PostToolUse": [
    {
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.go$\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const{execSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){try{execSync('gofmt -w \\\"'+p+'\\\"',{stdio:['pipe','pipe','pipe']})}catch(e){console.error('[Hook] gofmt failed: '+e.message)}}console.log(d)})\""
        }
      ]
    },
    {
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.go$\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){const c=fs.readFileSync(p,'utf8');if(/fmt\\\\.Print(ln|f)?\\\\(/.test(c)){console.error('[Hook] WARNING: fmt.Print found in '+p);console.error('[Hook] Consider using proper logging instead')}}console.log(d)})\""
        }
      ]
    },
    {
      "matcher": "tool == \"Bash\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const cmd=i.tool_input?.command||'';if(/gh pr create/.test(cmd)){const out=i.tool_output?.output||'';const m=out.match(/https:\\\\/\\\\/github.com\\\\/[^/]+\\\\/[^/]+\\\\/pull\\\\/\\\\d+/);if(m){console.error('[Hook] PR created: '+m[0])}}console.log(d)})\""
        }
      ]
    }
  ]
}

3. 危險操作防護網 (PreToolUse)

• 行為：當 AI 試圖執行 git push 時，Hooks 會攔截並輸出：

  [Hook] Review changes before push... Consider: git diff HEAD~1

• 優勢：增加了一道「冷靜期」，防止 AI 在未經人工確認的情況下將錯誤程式碼推送到遠端倉庫。

配置範例：

{
  "PreToolUse": [
    {
      "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"console.error('[Hook] Review changes before push...');console.error('[Hook] Consider: git diff HEAD~1, git log --oneline -5')\""
        }
      ]
    },
    {
      "matcher": "tool == \"Write\" && tool_input.file_path matches \"\\\\.(md|txt)$\" && !(tool_input.file_path matches \"README\\\\.md|CLAUDE\\\\.md\")",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"console.error('[Hook] WARNING: Creating documentation file');console.error('[Hook] Consider using CONTEXT.md for session notes')\""
        }
      ]
    }
  ]
}

4. 提交前最後檢查 (Stop)

配置範例：

{
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const{execSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{execSync('git rev-parse --git-dir',{stdio:'pipe'})}catch{console.log(d);process.exit(0)}try{const files=execSync('git diff --name-only HEAD',{encoding:'utf8',stdio:['pipe','pipe','pipe']}).split('\\\\n').filter(f=>/\\\\.go$/.test(f)&&fs.existsSync(f));let hasDebug=false;for(const f of files){const content=fs.readFileSync(f,'utf8');if(/fmt\\\\.Print(ln|f)?\\\\(/.test(content)){console.error('[Hook] WARNING: fmt.Print found in '+f);hasDebug=true}}if(hasDebug)console.error('[Hook] Remove debug prints before committing')}catch(e){}console.log(d)})\""
        }
      ]
    }
  ]
}

5. Session 結束存檔 (SessionEnd)

配置範例：

{
  "SessionEnd": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/session-end.js"
        }
      ]
    }
  ]
}

session-end.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');
  const today = new Date().toISOString().split('T')[0];
  const sessionFile = path.join(sessionsDir, `${today}-session.tmp`);

  if (!fs.existsSync(sessionsDir)) {
    fs.mkdirSync(sessionsDir, { recursive: true });
  }

  const time = new Date().toTimeString().slice(0, 5);

  if (fs.existsSync(sessionFile)) {
    let content = fs.readFileSync(sessionFile, 'utf8');
    content = content.replace(/\*\*Last Updated:\*\*.*/, `**Last Updated:** ${time}`);
    fs.writeFileSync(sessionFile, content);
    console.error(`[SessionEnd] Updated session: ${today}-session.tmp`);
  } else {
    const template = `# Session: ${today}
**Started:** ${time}
**Last Updated:** ${time}

## Completed
- [ ]

## In Progress
- [ ]

## Notes for Next Session
-
`;
    fs.writeFileSync(sessionFile, template);
    console.error(`[SessionEnd] Created session: ${today}-session.tmp`);
  }

  process.exit(0);
}

main();

6. 壓縮前狀態保存 (PreCompact)

配置範例：

{
  "PreCompact": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/pre-compact.js"
        }
      ]
    }
  ]
}

pre-compact.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');
  const logFile = path.join(sessionsDir, 'compaction-log.txt');

  if (!fs.existsSync(sessionsDir)) {
    fs.mkdirSync(sessionsDir, { recursive: true });
  }

  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
  fs.appendFileSync(logFile, `[${timestamp}] Context compaction triggered\n`);

  console.error('[PreCompact] State preserved before compaction');
  process.exit(0);
}

main();

五、 目錄結構

建議的專案 hooks 結構：

.claude/
├── settings.local.json    # Hooks 配置
├── scripts/
│   ├── hooks/
│   │   ├── session-start.js
│   │   ├── session-end.js
│   │   └── pre-compact.js
│   └── lib/
│       └── utils.js       # 共用工具函式
└── skills/                # Claude Code skills

六、 為什麼 Claude Code 仰賴這些設定？

Claude Code 本質上是一個 「事件驅動的執行環境 (Event-Driven Execution Environment)」。

1. 彌補 LLM 的缺陷：LLM 擅長生成，但不擅長「守紀律」和「記狀態」。Hooks 透過確定性的程式碼（Node.js/Shell）來彌補機率性的 AI 模型。

2. 標準輸入/輸出的管道設計： 注意到腳本中使用了 process.stdin 和 process.stdout 嗎？

    process.stdin.on('data', c => d += c); // 接收 Claude 的數據
    console.log(d); // 必須把數據傳下去，否則流程會斷掉
   

   這設計讓 Hooks 成為類似 Linux Pipe 的過濾器，可以在不打斷 AI 思路的前提下，對資料進行「偷看」、「修改」或「阻擋」。

七、 注意事項

1. Hook 必須輸出 stdin 資料：對於需要處理輸入的 hooks，必須在最後輸出 console.log(d) 將原始資料傳遞下去

2. 使用 stderr 顯示訊息：console.error() 用於顯示給使用者的訊息，console.log() 用於傳遞資料

3. 避免阻塞：Hook 腳本應快速執行，避免耗時操作

4. 錯誤處理：即使發生錯誤也應 process.exit(0)，避免阻斷 Claude Code 流程

5. 路徑處理：使用絕對路徑或相對於專案根目錄的路徑

八、 配置後帶來的行為變革

一旦部署這套 .claude/settings.local.json，你的開發體驗將發生如下質變：

總結

這套配置將 記憶持久化概念 進一步細化為針對 Go 語言特性的自動化工作流。它不僅解決了「失憶」問題，更透過 gofmt 和安全檢查，讓 AI 成為了一個「守紀律」的初級工程師，而不僅僅是一個聊天機器人。

參考資源

• Claude Code Hooks 官方文件

1. 為什麼需要這個組件？

簡單來說，deltatocumulativeprocessor 的工作就是把 Delta (增量) 指標轉成 Cumulative (累積) 指標。

聽起來很簡單？但這是一個 Stateful (有狀態) 的操作。這意味著 Processor 必須在記憶體裡「記住」所有 Time Series 當前的數值。一旦流量大起來，這裡就是記憶體洩漏或是數據遺失的高風險區。

2. 核心架構：它是如何撐住高併發的？

為了不讓這個 Processor 成為效能瓶頸，此 Processor 的設計核心在於「高效的狀態管理」與「嚴格的時間序驗證」。為了在高併發下維持準確性，它採用了細粒度的鎖定策略與強型別的狀態存儲。

2.1 關鍵資料結構 (Key Data Structures)

核心邏輯位於 processor/deltatocumulativeprocessor，主要由以下結構支撐：

A. 唯一識別 identity.Stream

Processor 怎麼知道哪些數據屬於同一個 Time Series？它依賴 identity.Stream。這不光是看 Metric Name，它會把 Name、Unit、Type 甚至所有的 Label (Attribute Hash) 組合起來當作唯一的 Key。所以，只要 Label 變了，對它來說就是一個全新的 Stream。

• Metric Signature: Name, Unit, Type, Monotonicity, Temporality.

• Attributes Hash: 所有 DataPoint 屬性 (Labels) 的雜湊值。 這確保了即使是同一個 Metric Name，不同的 Label 組合也會被視為獨立的 Stream。

B. 狀態儲存 state

在儲存方面，它用了 maps.Parallel (底層是 xsync.MapOf)。為了避開 Golang interface 轉換的開銷並確保型別安全，它很「搞剛」地把 Number (Sum/Gauge)、Histogram 和 ExponentialHistogram 拆成三個獨立的 Map 來存。：

• nums: 存儲 NumberDataPoint (Sum/Gauge)

• hist: 存儲 HistogramDataPoint

• expo: 存儲 ExponentialHistogramDataPoint

C. 鎖的策略、併發控制 mutex[T]

這是效能的關鍵點。Processor 沒有使用全域鎖 (Global Lock)。 如果每次處理數據都要鎖住整個 Map，那吞吐量肯定上不去。它為每一個獨立的 Stream 分配了一個專屬的 mutex。這意味著，除非多個請求同時更新「同一個 Metric 的同一個 Label 組合」，否則大家的更新操作是完全平行、互不卡頓的。

2.2 數據流經的旅程 (ConsumeMetrics)

當一筆 Metrics 進入 Processor 時，數據流經以下嚴格步驟：

1. 過濾 (Filter):

   • 檢查 AggregationTemporality。只有 Delta 類型的指標會被處理；Cumulative 指標直接透傳 (Pass-through)。

2. 識別與查找 (Identify & Lookup):

   • 計算 DataPoint 的 identity.Stream。

   • 嘗試從 state Map 中撈取現有累積值。

   • 注意：如果是新 Stream 且總數超過 max_streams，它會直接標記 error="limit" 然後丟棄。這在除錯時很容易被忽略。

3. 聚合運算 (delta.Aggregate):

   • 在 Stream 級別的鎖保護下執行。

   • 邏輯: New_Cumulative = Old_Cumulative + New_Delta。

4. 時間序驗證 (Validation): 在聚合前，必須通過兩項關鍵檢查 (位於 internal/delta/delta.go)：

   • 亂序檢測 (ErrOutOfOrder):

     • 條件: New.Time <= Stored.Time

     • 結果: 丟棄數據。這通常發生在發送端重試或網路亂序時。

   • 重啟檢測 (ErrOlderStart):

     • 條件: New.Start < Stored.Start

     • 結果: 丟棄數據。這代表來源進程可能已重啟，發送了屬於「上一代」的數據，或是時間戳生成有誤。

5. 寫回與標記:

   • 將計算出的 Cumulative 值寫回原始 DataPoint。

   • 將 Temporality 修改為 Cumulative。

   • 更新 stale map 中的最後活躍時間 (Last Seen)。

2.3 垃圾回收機制 (GC)

為了避免記憶體爆炸（例如 Pod 重啟頻繁導致 Stream 無限增長），這裡有一個背景 Goroutine，每分鐘會巡一次。只要發現某個 Stream 超過 max_stale 沒更新，就會把它從記憶體中清掉。

• 邏輯: 遍歷 stale Map。如果 now - last_seen > max_stale，則從記憶體中刪除該 Stream 的所有狀態。

3. 設定檔該怎麼調？ (Configuration)

只有兩個參數，但都很致命：

processors:
    deltatocumulative:
       # Stream 多久沒動靜就清掉？預設 5m。
        # 坑點：設太短會導致狀態頻繁重置（數據斷層）；設太長記憶體會爆
        max_stale: 5m

        # 允許追蹤的最大 Stream 數量 (預設為 Max Int)
        # 影響: 這是保護 Collector 不被 High Cardinality 數據撐爆的最後防線。
        # 這是防線。一旦爆了，超出的數據會被「無情丟棄」。
        max_streams: 9223372036854775807

4. 監控指標詳解 (Observability)

Processor 透過 internal/telemetry 暴露了自我監控指標 (Self-monitoring Metrics)，這是排查數據丟失問題的首要依據。當你懷疑數據掉了，請先看這些自我監控指標 (internal/telemetry)：

4.1 核心指標列表

• deltatocumulative_datapoints：這是最重要的 Counter。
  • 看 error="limit"：是不是 max_streams 設太小了？
  • 看 error="delta.ErrOutOfOrder"：發送端是不是時間戳亂跳？
• deltatocumulative_streams_tracked：目前記憶體裡到底存了多少 Stream。

5. 線上鬼故事：常見問題剖析

案例一：狀態丟失與 streams_tracked 的鋸齒狀波動

現象： 監控圖表顯示 streams_tracked 呈現週期性的鋸齒狀下跌，或者劇烈震盪。同時下游看到的數值可能突然歸零或重置。

原因： 這通常與 GC 機制 (stale check) 有關。

1. 間歇性流量: 如果某個指標每 6 分鐘才送一次，而 max_stale 設為 5 分鐘。Processor 會在第 5 分鐘刪除狀態。第 6 分鐘數據進來時，被視為全新的 Stream，累積值從 0 (或當前 Delta) 開始計算，導致狀態丟失。

2. GC 運作: 背景 Goroutine 每分鐘一次的清理動作，會導致 streams_tracked 出現階梯式下降。

解法：

• 確保 max_stale 顯著大於 metrics 的 scrape interval 或 push interval (建議至少 2-3 倍)。

案例二：消失的數據與 Pipeline 順序之謎

現象：Batch Processor 報告發送了 2.6k 點，但 exporter 報告只發送了 2.0k 點。中間的 0.6k 憑空消失，且沒有任何 Error Log。

源碼級原因： 這是 deltatocumulative 的 max_streams 限制與 Pipeline 順序共同作用的結果。

// processor.go 片段
if maps.Exceeded(last, loaded) {
    attrs.Set(telemetry.Error("limit"))
    return drop // 靜默丟棄，只會標記 error label
}

如果 Pipeline 配置為 [batch, deltatocumulative]：

1. Batch: 收到數據，計數器 batch_send_size +2.6k。

2. DeltaToCumulative: 發現 Stream 總數超標，靜默丟棄 0.6k 數據點 (僅增加 deltatocumulative_datapoints{error="limit"})。

3. Exporter: 收到剩餘的 2.0k，計數器 sent_metric_points +2.0k。

解法：

1. 調整順序: 改為 [deltatocumulative, batch]。讓過濾發生在打包之前。

2. 監控 Drop: 設置告警監控 sum(rate(otelcol_deltatocumulative_datapoints{error="limit"}[2m])) > 0。

案例三：亂序數據 (Out of Order)

現象： 數據偶爾丟失，deltatocumulative_datapoints 出現 error="out_of_order"。

原因 (internal/delta/delta.go)：

case dp.Timestamp() <= state.Timestamp():
    return ErrOutOfOrder{...}

Processor 為了保證累積值的單調遞增，對時間戳要求非常嚴格 (New.Time > Stored.Time)。如果發送端 (如 Prometheus Remote Write 或某些 SDK) 因重試邏輯發送了重複或舊的時間戳，Processor 會為了保護累積值的單調性而拒絕該數據。

解法： 檢查發送端的 Retry 策略或時鐘同步狀態。

6. 本地重現 (PoC)

為了驗證那個「Pipeline 順序導致數據消失」的鬼故事，我用 Docker Compose 搞了個實驗。 (詳細配置略，核心概念是用 60 個 telemetrygen 實例去衝撞 max_streams: 50 的限制)

6.1 環境架構

┌─────────────────┐     ┌─────────────────────────────────────┐     ┌────────────┐
│  telemetrygen   │────▶│         OTel Collector              │────▶│ Prometheus │
│  (60 instances) │     │  ┌─────────────────────────────┐    │     │  :9090     │
│  app-01 ~ 60    │     │  │ Pipeline:                   │    │     └────────────┘
└─────────────────┘     │  │ receiver → cumulativetodelta│    │
                        │  │          → batch            │    │
                        │  │          → deltatocumulative│    │
                        │  │          → exporter         │    │
                        │  │                             │    │
                        │  │ max_streams: 50 (< 60)      │    │
                        │  └─────────────────────────────┘    │
                        └─────────────────────────────────────┘

設計理念：

• 60 個 telemetrygen 實例，每個發送不同的 service.name (app-01 ~ app-60)

• max_streams 設為 50，刻意製造 Stream 超限

• Pipeline 順序為 [cumulativetodelta, batch, deltatocumulative]，重現「先 batch 後過濾」的問題

6.2 檔案結構

poc-lab/
├── docker-compose.yaml   # Docker Compose 配置
├── otel-config.yaml      # OTel Collector 配置
└── prometheus.yaml       # Prometheus scrape 配置

6.3 配置檔案

otel-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  # 將 telemetrygen 產生的 Cumulative 轉成 Delta
  cumulativetodelta:

  batch:
    send_batch_size: 100
    timeout: 1s

  deltatocumulative:
    max_stale: 1m
    # 【關鍵設定】設定極低的上限，強迫發生 Drop
    max_streams: 50

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: "poc_app"

  debug:
    verbosity: normal

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: "0.0.0.0"
                port: 8888

  pipelines:
    metrics:
      receivers: [otlp]
      # 【關鍵錯誤順序】重現問題
      processors: [cumulativetodelta, batch, deltatocumulative]
      exporters: [prometheus, debug]

prometheus.yaml

global:
  scrape_interval: 5s
  evaluation_interval: 5s

scrape_configs:
  # Job 1: 監控 Collector 本身
  - job_name: 'otel-collector-internal'
    static_configs:
      - targets: ['otel-collector:8888']

  # Job 2: 監控實際輸出的數據
  - job_name: 'app-metrics'
    static_configs:
      - targets: ['otel-collector:8889']

docker-compose.yaml (精簡版)

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.142.0
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-config.yaml:/etc/otel-collector-config.yaml:ro
    ports:
      - "4317:4317"
      - "8888:8888"   # Collector Internal Metrics
      - "8889:8889"   # Prometheus Exporter
    networks:
      - otel-network

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yaml:/etc/prometheus/prometheus.yml:ro
    ports:
      - "9090:9090"
    depends_on:
      - otel-collector
    networks:
      - otel-network

  # 使用 YAML anchor 定義 60 個 telemetrygen 實例
  telemetrygen-01: &telemetrygen-base
    image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest
    command: ["metrics", "--otlp-insecure", "--otlp-endpoint=otel-collector:4317",
              "--rate=5", "--duration=1000h", "--metric-type=Sum", "--service=app-01"]
    depends_on: [otel-collector]
    networks: [otel-network]

  telemetrygen-02: { <<: *telemetrygen-base, command: [..., "--service=app-02"] }
  # ... (app-03 ~ app-60)

networks:
  otel-network:
    driver: bridge

6.4 運行與驗證

步驟 1: 啟動環境

cd poc-lab
docker compose up -d

步驟 2: 等待數據累積 (約 30-60 秒)

docker compose ps  # 確認所有容器運行中

步驟 3: 驗證查詢

打開 Prometheus UI (http://localhost:9090) 或使用 curl：

查詢 1: Streams 追蹤數量 (應該達到上限 50)

otelcol_deltatocumulative_streams_tracked

查詢 2: 數據點處理結果 (按 error 分類)

otelcol_deltatocumulative_datapoints_total

查詢 3: 比較 Batch vs Exporter

# Batch 處理量
otelcol_processor_batch_batch_send_size_sum

# Exporter 發送量
otelcol_exporter_sent_metric_points_total

6.5 驗證結果 - 問題重現 (錯誤順序)

使用錯誤的 Pipeline 順序 [cumulativetodelta, batch, deltatocumulative] 運行後：

數據點處理詳情：

關鍵發現：

• 發送端: 60 個 telemetrygen 實例

• 限制: max_streams = 50

• 被完全丟棄的實例: 10 個 (60 - 50)

• Batch (13,000) ≠ Exporter (11,000)：差異 2,000 個數據點「憑空消失」

• 丟棄僅標記 error="limit"，無 Error Log，難以察覺

6.6 修正驗證 - 正確順序

修改 otel-config.yaml 中的 processors 順序：

# 修正前 (問題配置)
processors: [cumulativetodelta, batch, deltatocumulative]

# 修正後 (正確配置)
processors: [cumulativetodelta, deltatocumulative, batch]

修正後驗證結果：

數據點處理詳情：

6.7 修正前後對比

實驗結論：

修正前: Batch (13,000) ≠ Exporter (11,000)  ← 數據「消失」，難以排查
修正後: Batch (14,950) = Exporter (14,950)  ← 指標一致，問題可追溯

1. Pipeline 順序修正有效 - Batch 和 Exporter 的數值現在完全一致

2. 丟棄仍然發生 (error="limit")，但這是預期行為，因為來源數 (60) > max_streams (50)

3. 監控指標正確反映實際狀態 - 運維人員可直接從 error="limit" 指標看到丟棄量

6.8 清理環境

docker compose down

7. 番外篇：為什麼 PHP 開發者最需要它？

7.1 為什麼是 PHP？ (The "Share-Nothing" Architecture)

你可能會問，為什麼我們需要这么麻煩的轉 Delta？

對於 Java、Go 這種 Long-running process 來說，維護一個全域計數器（Cumulative）是輕而易舉的事。它們在記憶體中有一個全域的計數器，可以一直累加數值：

• 00:01: 累計 10 次

• 00:02: 累計 15 次 (累加了 5 次)

• 00:03: 累計 20 次 (又累加了 5 次)

這就是 Cumulative (累積) 模式，也是 Prometheus 等後端系統最喜歡的格式。

但是，PHP 通常運行在 PHP-FPM 或 CGI 模式下。其生命週期是「一個請求一個進程」 (Per-request process)：

1. 收到請求 -> 啟動 (或重用) PHP worker。
2. 執行腳本 -> 處理指標 (Metrics)。
3. 請求結束 -> 記憶體釋放/重置。

PHP (在 FPM 模式下) 是 Share-Nothing 架構。一個請求進來，Process 啟動，處理完，記憶體釋放。 PHP 進程沒辦法簡單地告訴下一個進程：「嘿，我剛剛處理了 1 個，現在總數是 100 喔。」(除非你用 Redis or SharedMemory等外部儲存)。

因此，PHP 最自然的做法是只回報「這一次請求發生了什麼」：

• 請求 A: 我處理了 1 個 DB 查詢 (Delta) -> 結束

• 請求 B: 我處理了 1 個 DB 查詢 (Delta) -> 結束

  所以 PHP 最自然的行為是：「這次請求我處理了 1 個 DB Query (Delta)」，這就是 Delta (增量) 模式。 至於加總的工作？就交給 OTel Collector 的 deltatocumulative processor 來扛吧。這就是它存在的最大意義。

7.2 Delta to Cumulative Processor 的角色

當您的後端資料庫（如 Prometheus）只接受 Cumulative 資料，但您的應用程式（如 PHP 或 Serverless Functions）只能提供 Delta 資料時，就會發生格式不相容。

這時候就需要 deltatocumulative processor 擔任「狀態管理者」 (Stateful Intermediary) 的角色：

1. 接收 (Receive): 它接收來自 PHP 的無數個小 Delta (例如：+1, +1, +1)。
2. 記憶 (Remember): 它在 Collector 的記憶體中維護一個對應的 Stream，並幫忙做加法運算 (State Management)。
3. 轉換 (Convert): 它算出累積值 (例如：目前總共是 3)，並將其轉換為 Cumulative 格式。
4. 輸出 (Export): 發送給 Prometheus。

雖然 Serverless (如 AWS Lambda) 或 CLI 工具也有類似需求，但 PHP的廣泛使用以及其標準的運行模式，使其成為這個 Processor 最常見的使用案例。

8. 結論與最佳實踐

1. Pipeline 順序至關重要：請務必把 deltatocumulative 放在 batch 之前。

2. 監控不能少：一定要針對 error="limit" 和 error="out_of_order" 設告警。

3. 容量規劃: 根據預期的 Stream 數量合理設置 max_streams

4. Stale 設定: max_stale 應大於最大的 push/scrape interval (建議 2-3 倍)

在閱讀這篇之前能先稍微理解Go Module以及Go install的用法。

官方Blog Organizing a Go module這篇文章內把Go專案的內容大致分成Package和Command或者兩個的組合。 Package 就是我們熟知的library, Command 則是executable能編譯出來執行的go檔案。

演化路程如下圖

如果是純library專案給人家import到別人的go project內使用的, 那package這條路線就是我們能參考。 像這個go-linq，該專案都是library。go-redis也是這類型的專案。

如果是需要安裝到主機上變成執行檔的，那command這條路線能參考。 像protoc-gen-go。

Basic package

下面的目錄結構長相是go module和package code都在專案的根目錄中。

project-root-directory/
  go.mod
  modname.go
  modname_test.go

上面的 modname.go 是package code，modname_test.go 則是與modname.go相關的測試程式。

如果把這包程式碼上傳到Github repo上，例如 github.com/someuser/modname，那麼 go.mod 裡指定該module的路徑也會是 github.com/someuser/modname，這點之後有機會在介紹go module的細節。

module github.com/someuser/modname

然後因為package code在根目錄，所以沒意外這package code一開始的package name會是 modname

package modname

這樣別人就能透過 go get github.com/someuser/modname 來取得這公開的package。

也可以該package的程式碼能切分開來在多個檔案中，只要這些檔案都在同一層的目錄中。

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth.go
  auth_test.go
  hash.go
  hash_test.go

這些檔案除了在同一層目錄中，同時它們的package name也都是modname。

Basic command

如果是要可以執行的程式，那最基本的專案結構會長的像

project-root-directory/
  go.mod
  auth.go
  auth_test.go
  client.go
  main.go

其中 main.go 會包含 func main，這應該沒什麼問題，雖然檔名也能叫 modname.go，只是main.go比較是慣例命名。 這目錄中所有的檔案其pakcage name也會是 main，畢竟go同一層目錄的package name必須一樣否則編譯會出錯。

同上該專案被上傳到 github.com/someuser/modname

module github.com/someuser/modname

那麼我們就能夠透過 go install 來下載並安裝

go install github.com/someuser/modname@latest

只是通常這種可執行的專案沒那麼單純，我們會有一些程式碼不希望發布上git後被別人的專案給go get來使用那些package。這時就出現 interanl 資料夾了。

Internal package

Go在1.4時加入了internal package的機制。 internal package除了不能讓外面的用戶直接import之外，代表著對其他module來說，該internal package對它們來說是不可見的，所以能做一層隔離，interanl package內程式的修改對外部是沒影響的

同時也只能被同一個階層以下的所有package來存取，所以絕大部分internal package都被放在根目錄，就是希望讓根目錄中所有package都能去導入 internal package。

project-root-directory/
  go.mod
  main.go
  package1/
    internal/
      interal.go
    package1.go
  package2/
    internal/
      interal.go
    package2.go
  interanl/
    version/
      version.go
    internal.go

這樣的定義下，package1的interanl只有package1這層以下的能導入，package2的interanl也是，連main都無法導入到這兩個interanl package。 但是main可以導入根目錄下的internal package。 package1能夠導入根目錄下的interanl package。

如果硬要import，則編譯時會出現編譯錯誤 use of internal package xxxx/internal not allowed

至於如果package1剛好要導入root internal package, 都要給導入internal package一個別名, 才能正常使用；除非引用的是internal package的下一層package。 如導入上面目錄結構的 internal/version, 就沒問題。 如果是剛好想要導入internal package的internal.go的部份就要給上alias別名。

Package or command with supporting packages

有了internal package的認識後，就能將interanl package理解成supporting package，就是我們內部會引用到，但不希望被外部專案給直接引用的package。這時候Go官方就會建議我們放到 internal 目錄中。

project-root-directory/
  internal/
    auth/
      auth.go
      auth_test.go
    hash/
      hash.go
      hash_test.go
  go.mod
  modname.go
  modname_test.go

在這樣目的下，我們就能設計modname.go，能導入auth package和hash package。 modname.go能這樣導入

import "github.com/someuser/modname/internal/auth"

但外部只能導入modname package來使用。

Multiple packages

一個專案可以有多個能被導入的package，且每個package都會有自己的目錄結構來進行組織。

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
    token/
      token.go
      token_test.go
  hash/
    hash.go
  internal/
    trace/
      trace.go

這樣子的結構意味著，別人可以導入

github.com/someuser/modname
github.com/someuser/modname/auth
github.com/someuser/modname/hash

也能導入auth package的下一層token package

github.com/someuser/modname/auth/token

外部專案就是不能導入

github.com/someuser/modname/internal/trace

在這專案結構設計上，剛好interanl package放在根目錄中，就是為了能讓專案內的package給導入使用。 例如專案內的package就能導入trace package使用

github.com/someuser/modname/internal/trace

Multiple commands

一個專案能包含多個可執行的程序。像是例子中的prog1/main.go和prog2/main.go

project-root-directory/
  go.mod
  internal/
    ... shared internal packages
  prog1/
    main.go
  prog2/
    main.go

所以使用者可以透過go install來直接安裝使用

$ go install github.com/someuser/modname/prog1@latest
$ go install github.com/someuser/modname/prog2@latest

但是為了好區別可執行command的目錄名稱，通常會建議放入一個名為 cmd 的目錄內，這樣子會很好區分出哪些是可以被導入的package哪些則是可以被執行的command。這些都是建議，並非必要。

Packages and commands in the same repository

如果一個專案同時提供可以被導入的package和能夠被安裝執行的command，通常會像這樣的結構。

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
  internal/
    ... internal packages
  cmd/
    prog1/
      main.go
    prog2/
      main.go

這樣子的結構意味著，別人可以導入

github.com/someuser/modname
github.com/someuser/modname/auth

能透過go install來安裝cmd/prog1和cmd/prog2

$ go install github.com/someuser/modname/cmd/prog1@latest
$ go install github.com/someuser/modname/cmd/prog2@latest

以Prometheus這專案為例子

github.com/prometheus/prometheus/
  cmd/
    prometheus/
      main.go
    promtool/
      main.go
  internal/
  model/
  plugins/
  rules/
  scrape/
  scripts/
  storage/
    interface.go

Prometheus提供了prometheus能安裝啟動，還提供了promtool這工具，能讓我們安裝來對prometheus進行檢查還有檢查各種prometheus設定文件等作用。

又因為prometheus本身只提供local storage功能, 所以在stoage package內有定義了interace來給其他storage service來導入開發用。 像是Grafana Lab旗下的Mimir，內部就導入很多Prometheus專案內的package。

但你不會看到Mimir去導入prometheus/internal底下的package，因為這些只能被prometheus專案內部所導入。

總結

官方這篇文章主要針對專案根目錄，internal目錄做說明，cmd目錄則是建議。 如果我們的專案需要提供一堆package供別專案導入時，有人也是會建議集中放到 pkg 目錄中，讓根目錄乾淨點，但也只是建議。

對我來說目錄結構反應的也是設計時的一個邊界，怎樣探索出邊界，不是按照這篇Project布局來被強迫設計就這樣塞入，該repo的issue也在討論這份也不是標準Go專案布局。

更多的我想還是回歸場景與需求的設計，像是DDD中提到的subdomain與bounded context, 就是基於業務層面的設計布局，在基於這樣業務布局進行專案結構的布局設計，這樣能讓專案設計貼近於業務設計，減低認知與轉化負擔。

令一個層面是關於release，如果該專案內有些package對於其他專案項目有用處，為了方便管理發佈與版本控制，官方是建議拆分成獨立的專案進行管理。只有跟我們這包系統有緊密生命週期相關的package和command才集中在一個專案內，方便開發和部署。

參考資料

Go doc Organizing a Go module

Go doc go1.4 Internal packages

Go 项目目录该怎么组织？官方终于出指南了！