Area 1 · Claude Code 配置實務

1.1 配置機制選擇 — 先問「強制還是建議」

五個機制解五種不同問題。第一個判斷永遠是：這條規則能不能容忍被違反？

這條 guidance…
│
├─ 絕不能被違反（compliance / 金流 / 破壞性操作）？
│    ├─ 是「擋某個工具呼叫」 → settings permissions（deny/ask 規則）
│    └─ 要「檢查內容再決定/轉換」 → hooks（PreToolUse 擋、PostToolUse 轉換）
│
└─ 是建議/慣例（違反了頂多品質差）？
     ├─ 全專案、每個 session 都該知道 → CLAUDE.md
     ├─ 只有某類檔案適用          → .claude/rules/ + paths glob（省 context）
     └─ 多步驟流程、偶爾才用       → Skill（被呼叫才載入）

1.2 Permission modes — 六個，背行為差異

1.3 Settings 層級與規則評估

優先序（高 → 低）                     permission rules 例外
Managed（企業，誰都蓋不掉）           ├ 不是覆蓋，是 merge
  ↓ CLI 參數                          ├ 任一層的 deny 永遠贏
  ↓ .claude/settings.local.json（個人）├ 高層 allow 蓋不掉低層 deny
  ↓ .claude/settings.json（team 共用） └ 評估順序固定：
  ↓ ~/.claude/settings.json（user）        deny → ask → allow（先中先贏）

• 先中先贏、與具體程度無關：deny Bash(git push *) + allow Bash(git push origin dev) → 照樣 deny（deny 先評估）。
• deny 裡放裸工具名（Bash）= 整個工具從 context 移除；Bash(rm *) = 保留工具、擋特定呼叫。
• Hook 與規則的位階：hook 的 block 優先於 allow 規則；但 settings 的 deny 連 hook 的 allow 都蓋掉。一句話：deny > hook > allow。
• MCP 整合（50% 那條）：project .mcp.json 進 repo team 共用｜~/.claude.json 個人；secrets 走 ${ENV_VAR} 展開絕不進 commit；server 連線時 tools 一次全部 discover。

路徑規則的錨點 — 單斜線不是絕對路徑

先記這句反直覺的：權限規則裡的 /Users/alice/file 不是絕對路徑。

單斜線開頭的路徑是半截的——Claude Code 會自動幫你補上前面那一段。補什麼，看這條規則寫在哪個檔案。所以同一行字，換個檔案放就管到不同地方：

同一行規則：Edit(/src/**)

寫在專案的 .claude/settings.json
  自動補上  /Users/you/myapp
  你寫的                    /src/**
  實際管到  /Users/you/myapp/src/**       ✅ 正是你要的

寫在 ~/.claude/settings.json
  自動補上  /Users/you/.claude
  你寫的                      /src/**
  實際管到  /Users/you/.claude/src/**     ❌ 這資料夾根本不存在

四種寫法（斜線越多，起點越靠前）
  src/**     → 目前工作目錄
  /src/**    → 半截路徑，自動補前綴（補什麼看寫在哪個檔）
  //src/**   → 完整路徑，放哪個檔都等於 /src/**
  ~/src/**   → 家目錄底下

.claude/settings.json（project）  → <專案根>/path
.claude/settings.local.json       → <啟動 Claude 的 cwd>/path
~/.claude/settings.json（user）   → ~/.claude/path      ← 最容易中招
--settings <file>                 → <該檔所在目錄>/path
CLI 旗標 / /permissions           → <啟動 cwd>/path

1.4 CI / Headless CLI 旗標

claude -p "Review yesterday's merged changes" \
  --output-format json --json-schema ./findings-schema.json \
  --permission-mode dontAsk \
  --allowedTools "Read" "Grep" "Glob" "Bash(git log *)" "Bash(git diff *)" \
  --max-turns 30 --max-budget-usd 5.00

1.5 Hooks — 位置決定能力

user prompt ──▶ [UserPromptSubmit]* ──▶ Claude 決定呼叫工具
                                            │
                              [PreToolUse]* ─┤ exit 2 = 擋下（工具不執行）
                                            ▼
                                        工具執行
                                            │
                              [PostToolUse] ─┤ 只能轉換結果/補 context
                                            ▼   （動作已發生，擋不了）
                                     結果進 agent context
Claude 想結束 ──▶ [Stop / SubagentStop]* ── exit 2 = 不准停、繼續做
context 快滿 ──▶ [PreCompact]*            （* = 可 block 的事件）

• Exit code：0 成功｜2 blocking（只對 pre-action 事件有效）｜其他非零 = non-blocking error。
• 設定位置：settings.json 的 hooks 欄位（各層級皆可）；Skill/Agent frontmatter 也能掛 scoped hooks。

npm run clean      # package.json 裡是 "clean": "rimraf dist"
make clean         # Makefile 裡是 rm -rf build/
python cleanup.py  # 第 40 行 os.remove("Atlas/Dots/x.md")

階段一：Claude Code 決定要不要送出這個指令  ← deny 規則 / hook（看字串，懂語意）
階段二：OS 執行這個行程                     ← sandbox（看實際碰的檔案，不懂語意）

1.6 CI Review 配置與測試生成

Review 配置三件套（那條 0% 的 objective 原文就是這三件）

1. 載入 project 標準：CI instance 是全新 context，要餵 CLAUDE.md 三類內容——專案慣例（命名/架構/測試標準）、accepted patterns（刻意設計，如 barrel files、re-export），與排除準則（哪些類別不要報，如 generated code、vendored 依賴）。三者作為每次 review 都載入的 persistent context，否則它拿通用標準審你的刻意設計，false positive 淹沒真 finding。
2. 限制工具：review 只需要讀 → --allowedTools 只給 Read/Grep/Glob（+ 唯讀 git）。不給 Edit/Write = review agent 不可能改壞東西。
3. 結構化輸出：--output-format json + --json-schema，讓 bot 能 parse 成 PR comments / gate 條件。

測試生成品質三件套

1. 給既有測試檔當 context —— 學專案的測試風格與結構，而不是憑通用習慣生成。
2. 定義 fixture 慣例 —— 測試資料怎麼建、放哪、怎麼共用。
3. 給區分準則：behavioral test（測邊界行為、錯誤路徑）vs trivial assertion（assert getter 回傳值）。沒有準則，模型會大量生成後者衝覆蓋率。

// trivial —— 存 Alice、取出 Alice，中間什麼都沒發生
it('returns the name', () => {
  expect(new User('Alice').getName()).toBe('Alice')
})

// behavioral —— 每一條對應一個真的會發生的災難
it('折扣不會讓價格變負數', () =>
  expect(calc.apply({ price: 100, discount: 150 })).toBe(0))

it('API timeout 時回傳 cached 值而不是丟例外', async () =>
  await expect(client.fetchRates()).resolves.toEqual(CACHED_RATES))

it('空清單不會炸，回傳空結果', () =>
  expect(summarize([])).toEqual({ total: 0, items: [] }))

1.7 Iterative refinement 三機制

1. Concrete input/output examples：具體「輸入 → 期望輸出」範例 > prose 描述（prose 被不一致解讀 → 格式漂移）。
2. Targeted feedback on specific failures：指著具體失敗點回饋（「第 3 段表格欄位順序錯」），不是「再改好一點」。
3. Batched issue descriptions：相關問題打包一次給（consolidated evaluation）——一條一條擠牙膏會來回震盪、每輪重新理解 context。

討論題（40 分鐘 session 用 — 先自己想，再來挑戰我）

1. deny Bash(git push *)（user 層）+ allow Bash(git push origin main)（project 層）+ 一個 PreToolUse hook 回 allow——最後 git push origin main 會怎樣？為什麼？
2. 「CLAUDE.md 寫了不准刪檔，agent 還是刪了」——列出三種真正能擋住的做法，各自的適用差異？
3. CI 上想跑 review 又怕 fork 的 PR 挾帶惡意 project settings——哪兩個旗標組合起來處理？
4. dontAsk 和 bypassPermissions 都「不會卡 prompt」，什麼情境下選錯會出大事？
5. 為什麼 --max-turns 預設無上限這個事實在考題裡重要？