Claude Code 最佳實踐

• 為了讓命令能安全執行而不需要您逐一核准，新的終端機和 VS Code 工作階段會以自動模式啟動，由分類器在任何有風險的操作執行前先進行審查。
• 為了讓您的主要對話保持專注，同時讓獨立的工作平行進行，Claude 會將工作委派給 subagent，並且只在必要時才回報。
• 為了讓長時間的工作階段能持續進行而不需要您管理，對話會在上下文視窗填滿之前自動壓縮。

• 只存在於某個人腦中的部署流程
• 絕對不能被讀取的檔案
• 任何工作必須通過才能算完成的檢查
• 您必須控制在範圍內的預算

• Claude 打造出的東西與您想像的不同，或者它必須在每個工作階段開始時重新發現同一件事實。它缺少了無法透過閱讀儲存庫取得的資訊。請參閱告訴 Claude 它看不到的資訊。
• Claude 說它完成了，但其實並未完全完成，通常是因為它沒有辦法檢查自己的工作。請參閱給 Claude 一個可執行的檢查。
• Claude 做了在這個儲存庫中絕對不能發生的事，或跳過了必須執行的步驟。單靠提示詞無法保證這兩者。請參閱強制執行不容例外的規則。
• Claude 做對了，但花費的時間、token 或權限提示超出了這項任務應有的成本。請參閱變更預設值。

確定性與非確定性指令

1. 非確定性：您撰寫指令，由 Claude（模型）讀取。這可以是您的提示詞、CLAUDE.md 或 skill。接著由模型決定如何處理這些資訊。它通常會遵循您的命令，而且目前的模型很擅長在沒有太多上下文的情況下理解您的意圖，但無法保證它會遵循您的指令。它仍然可能決定不做某些事，或做其他的事。
2. 確定性：您設定指令，由 Claude Code（執行框架）必須執行。這可以是 hook、拒絕規則或受管設定。無論模型決定做什麼，Claude Code 每次都會套用它。

• 絕對不要編輯 src/gen/ 中產生的用戶端
• 建立檔案後一律執行授權標頭指令碼

告訴 Claude 它看不到的資訊

• 您的團隊在會議中做出的決定
• 只存在於某個人腦中的部署流程
• 整合測試需要的環境變數

1. 它能透過閱讀程式碼找到這個資訊嗎？
2. 它實際上會去找嗎？

撰寫具體的提示詞

• 檔案：輸入 @ 和路徑，即可在訊息中包含檔案內容。
• 影像：將設計或錯誤的螢幕擷取畫面貼到提示詞中。
• 命令輸出：從您的 shell 用 cat error.log | claude -p "what's going on here" 以管道傳入。

build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout

先與 Claude 腦力激盪

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

保持 CLAUDE.md 簡短

• 如何在這個儲存庫中確認工作：確切的測試、型別檢查和 lint 命令，以及如何執行單一測試檔案
• 程式碼容易誤導的地方：到處都是但新程式碼不能仿效的舊模式，或看起來未使用但其實在用的目錄
• 不在儲存庫中的決定：團隊最終採用哪個錯誤輔助函式、部署如何運作、什麼需要遷移審查
• 任何您已經修正過兩次的事情

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

• /init 會根據您的程式碼庫產生一個初始版本。之後的工作主要是刪除行數。記憶指南建議保持在 200 行以下。
• /doctor 會針對 Claude 已經能從程式碼推斷出的內容建議刪除。
• /doctor prompt-audit 會標記為舊模型撰寫的指令、指向已不存在之檔案的指令，或彼此矛盾的指令。

將規則限定在程式碼庫的某個部分

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

將團隊流程放在 skill 中

---
name: release
description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
disable-model-invocation: true
---
1. Make sure you're on main with a clean tree. If not, stop and ask.
2. Run `pnpm changeset version` and commit the result.
3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.

連接 Claude 需要的工具

claude mcp add --transport http notion https://mcp.notion.com/mcp

給 Claude 一個可執行的檢查

• 一個測試檔案
• 建置的退出碼
• Linter
• 將輸出與固定測試資料進行差異比對的指令碼
• 與設計稿並排的瀏覽器螢幕擷取畫面

• 在提示詞中：run the auth tests after, and keep going until they pass。由 Claude 自行決定何時滿意。這適用於任何任務，今天就能用，不需要任何設定。
• 作為目標：/goal all tests in tests/auth pass and lint is clean 會設定一個條件，由另一個模型在每個回合後根據對話進行檢查，Claude 會持續工作直到條件達成。您在工作階段中自己很少需要這個。它對長時間的背景執行很重要，因為 Claude 有時會在仍有未完成項目時以進度摘要結束回合，而目標會把它送回去繼續工作。
• 作為 Stop hook：Stop hook 會在 Claude 嘗試結束回合時執行您的指令碼，如果指令碼以退出碼 2 結束，就會讓 Claude 回去繼續工作。這是由 Claude Code（執行框架）強制執行的，因此在型別檢查通過或達到封鎖上限之前，回合不會結束。下方有範例。
• 由沒有撰寫程式碼的人審查：在終端機中，/code-review 會在一個從未看過您對話的全新 subagent 中審查差異。它不會受到產生程式碼時的推理所影響。

依據您的規格進行審查

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

使用 Stop hook 強制執行檢查

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

強制執行不容例外的規則

使用 hook 強制執行步驟

• Shell 命令（一般情況）
• 對 HTTP 端點發送 POST
• 對您某個 MCP 伺服器的工具呼叫
• prompt 或 agent hook，讓模型來決定

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }
        ]
      }
    ]
  }
}

使用權限規則和沙箱限制存取

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

• Read 規則確實會攔截 cat .env，因為 Claude Code 能辨識常見的檔案讀取命令。
• 它不會攔截開啟該檔案的指令碼。
• 針對某個網域的 WebFetch 拒絕規則，對於以 curl 存取同一網域毫無作用，除非沙箱已開啟。

選擇規則適用的對象

• .claude/settings.local.json 和 ~/.claude/settings.json 只屬於您自己。當您對某個命令選擇 Yes, and don’t ask again 時，Claude Code 會將該規則儲存到本機檔案。
• .claude/settings.json 及其中的 hook 屬於儲存庫。提交之後，它們會適用於在該儲存庫中工作的每個人。其中的拒絕規則會立即生效。其中的 allow 規則會等到每個人接受該資料夾的信任對話框後才生效，而工作區信任也決定了其中的 hook 何時開始在他們的電腦上執行。
• 受管設定屬於組織。它們來自管理主控台、MDM 或 managed-settings.json 檔案，任何個人設定檔都無法覆寫它們，這使得它們成為安全團隊政策的唯一存放處。如果您是負責設定它們的人，請參閱為您的組織設定 Claude Code。

變更預設值

• 互動式終端機和 VS Code 工作階段以自動模式啟動。
• 在大多數方案和供應商上，它會執行中等 effort 的 Claude Opus 5.5。
• 當它認為有理由時，會將工作委派給 subagent。
• 它會在對話增長時進行壓縮。

變更權限模式

• 手動模式：您要親自核准每一次編輯和每一個非唯讀的命令。很安全，但到了第十個提示後，您就會開始不讀內容就核准，而且在您離開鍵盤時，一切都不會進展。
• bypassPermissions：核准所有不在您的拒絕和詢問規則涵蓋範圍內的操作，這只在可拋棄的容器中才合理。

• curl | bash
• 正式環境部署和遷移
• 強制推送覆蓋他人的工作
• 將敏感資料傳送到外部端點
• 看起來是由 Claude 讀取的內容而非由您驅動的動作

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and every repo under it",
      "Trusted internal domains: *.internal.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
    ]
  }
}

變更模型和 effort

• 當做對與否取決於容易被忽略的情況時，用 /effort high 或 /effort xhigh 調高它。例如您沒寫過的程式碼中的錯誤、不穩定的測試，或是 Claude 必須找出舊結構所有讀取者的 schema 變更。這樣 Claude 會在回答之前檢查更多邊界情況並驗證更多工作，額外的時間和 token 就花在這裡。
• 當您正在快速來回互動且無論如何都會審查每個結果時，用 /effort low 調低它：腦力激盪、初步草稿、跨幾個檔案的重新命名。Claude 會更快給您一個起點，而既然您在每一步都會引導，額外的深思熟慮除了讓您等待更久之外，不會有太大改變。
• 將 max 留給您希望 Claude 在沒有您的情況下努力解決的困難問題，例如尋找安全漏洞。在一般任務上它容易想太多，所以您會付出更多，得到的答案卻可能不比 high 更好。
• 當只有下一則訊息需要時，例如在原本例行的工作中穿插一個棘手的問題，請在該提示詞中加入 ultrathink，而不是變更設定。

了解 subagent 的成本

• 大範圍的程式碼庫搜尋會交給內建的 Explore agent。
• 在分叉模式開啟時（預設），支線任務會被分叉出去。
• 它啟動的 subagent 預設在背景執行，因此您的主要對話可以持續進行。

• 同時執行獨立的工作片段，讓整個任務更快完成
• 將冗長的輸出（例如完整的測試執行或大範圍搜尋）排除在主要對話之外，否則它會在整個工作階段剩餘時間中一直跟著
• 取得一個沒看過程式碼撰寫過程的審查者
• 給予某項任務比主要工作階段更少的工具，例如只能讀取但不能編輯的審查者

• 如果某個 subagent 的工作很簡單，例如收集匯入某個模組的檔案或檢查文件中的連結，請在其定義中設定 model: haiku。這類工作不需要較大的模型，而 Haiku 每次請求的成本低得多。
• 要求回傳簡短的摘要，這樣二十個結果就不會塞滿您的上下文。
• 查看 /usage，了解每種 subagent 類型佔您用量的比例，藉此判斷哪些是值得其成本的。
• 為 .claude/agents/ 中的自訂 subagent 只提供 tools: Read, Grep, Glob。如此它就成為一個無法編輯任何內容的審查者，而這項限制是由 Claude Code 強制執行的，而不是在提示詞中請求的。

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

降低成本和上下文

• 在不相關的任務之間使用 /clear。它不需要任何成本，而且意味著下一項任務不必持續為前一項任務的歷史付費。/clear oauth-migration 會為您要離開的工作階段命名，讓您之後可以回來。
• 帶著重點使用 /compact，例如 /compact keep the API changes and the test commands。在長時間的工作階段中，/compact 本身就是一個大型請求，因為它要讀取整個對話才能進行摘要，快取過期後更是如此。
• 留意背景工作：/loop、目標在每個回合後的檢查，以及 Claude 自己的 subagent，都會在您沒有輸入時持續發送請求。

引導工作階段

• Esc 會讓 Claude 在動作途中停下，並保留到那一刻為止的所有內容，讓您可以重新導向而不會失去工作成果。
• /rewind，或在空白提示下按兩次 Esc，會開啟倒帶選單，您可以在那裡將程式碼、對話或兩者都回復到先前的提示詞。這使得先嘗試較大膽的做法、不成功再倒帶變得低風險。同一個選單也可以在部分對話已經過時時將其摘要。
• /clear 會重新開始。如果您已經修正同一件事兩次而它仍然是錯的，第三次修正大多只是增加到一個已經包含兩次失敗嘗試的對話中，而 Claude 必須一直重新讀取這些內容。/clear 加上一個納入您所學內容的新提示詞，幾乎每次都效果更好。

讓 Claude 在您不在時執行

1. 它知道完成是什麼樣子嗎？一個目標條件、一份規格檔案，或一個它必須讓其通過的失敗測試。
2. 它能檢查自己的工作嗎？測試套件、Stop hook、某種審查步驟。
3. 它被允許觸及什麼？權限規則、dontAsk、沙箱、worktree、它唯一可以推送的分支。
4. 什麼會讓它停下？--max-turns、--max-budget-usd、支出上限。
5. 結果會送到哪裡，由誰簽核？一個 PR、一則留言或一份摘要，然後由一個人核准合併、部署，或任何其他無法撤回的動作。

從指令碼執行 Claude

• --bare 會略過 hook、skill、外掛、MCP 伺服器和 CLAUDE.md 檔案（包括儲存庫的以及電腦的），讓執行無論在哪裡執行都做同樣的事。它也完全不會動到您的 claude.ai 登入：身分驗證來自 ANTHROPIC_API_KEY、您以 --settings 傳入的檔案中的 apiKeyHelper，或您雲端供應商的憑證。
• --append-system-prompt、--mcp-config 和 --settings 會明確傳入執行確實需要的東西。您以 --settings 傳入的 hook 在 --bare 下不會執行，因此需要這些 hook 的執行請不要使用 --bare。
• --allowedTools 會預先核准它的工具，而 --permission-mode dontAsk 會拒絕其他任何原本會觸發提示的操作。
• --output-format json 會給您一個可供剖析的單一結果物件，而搭配 --verbose 的 stream-json 會在事件發生時即時串流。

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

依排程或事件啟動執行

/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push

平行執行工作階段

.env
.env.local
config/dev-credentials.json

• 當您結束一個未命名的 worktree 工作階段時，如果其中沒有任何內容，Claude Code 會移除該 worktree。對於已命名的工作階段或有變更的工作階段，它會詢問要怎麼做。
• Subagent 的 worktree 會在 subagent 完成且沒有變更時消失。
• 確實被遺留下來的 subagent 和背景工作階段 worktree，會在存在時間超過 cleanupPeriodDays 且不含任何工作時被清除。

可以停止做的事

相關資源

• Claude Code 如何運作：迴圈、工具，以及啟動時載入的內容
• 探索上下文視窗：工作階段中佔用空間的內容及其載入時機
• 擴充 Claude Code：在 skill、hook、MCP、subagent 和外掛之間做選擇
• 選擇權限模式和設定權限
• 有效管理成本
• 以程式方式執行 Claude Code和使用雲端排程任務自動化工作
• 給團隊主管和管理員：為您的組織設定 Claude Code