majiayu000 Claude Code 專案配置審計
系統化 review 一個 Claude Code 專案或 agent 的配置品質，確保 prompt 精簡、結構清晰、資訊零損失。
核心原則：搬移而非刪除
優化配置時，一律採用「搬移」而非「刪除」：
| 操作 | 錯誤做法 | 正確做法 |
|---|---|---|
| 畢業一條 Lesson | 從 CLAUDE.md 刪除 | 搬到共用 rules 或 skill references/ |
| 精簡 description | 移除細節文字 | 先把細節移入 SKILL.md 正文，再縮短 description |
| 刪除一條使用者期待 | 直接刪除 | 搬到對應的 skill |
| 合併重複原則 | 刪較弱的那個 | 保留主版本，標記次版本為 @import 或 reference |
審計保證：優化後，所有資訊仍存在於系統的某處，品質不降級。
三層分離原則
解決「description 要豐富觸發 vs. token 要最小」的矛盾：
Layer 1: description（每輪注入 system-reminder）= 觸發條件 ONLY，≤2 句
Layer 2: SKILL.md 正文（按需載入）= 能力範圍、工作流程、品質標準
Layer 3: references/（深度載入）= 知識庫、案例、歷史教訓
每層的職責不互相跨越。詳見 references/three-layer-principle.md。
前置載入（按需）
| Skill | 何時需要 |
|---|---|
cc-prompt-craft |
審查 CLAUDE.md 文本品質、cache 結構 |
cc-agent-design |
審查工具配置、模型選擇、dispatch prompt |
cc-cost-engineering |
審查 token 消耗、cache 效率、model 成本矩陣 |
cc-harness-patterns |
審查 deferred loading、cache 穩定性 |
agentskill-expertise |
審查 skill 設計哲學、Metadata-driven Triggering |
5 項檢查
依序執行，每項產出 PASS / ISSUE(N) 結論。
Check 1：CLAUDE.md 文本品質
讀取 CLAUDE.md，逐項檢查：
| 檢查項 | PASS 條件 | 常見問題 |
|---|---|---|
| 角色定義 | 寫人格不寫機制。一句話設定語氣基調 | 描述 AI 的技術機制而非個性特質 |
| 使用者期待 | 只放跟所有對話都相關的通用事項 | 任務特定指令（如寫作格式）坐在 CLAUDE.md 裡 |
| 核心原則 | 不與 .claude/rules/ 的任何檔案重複 |
原則內容 rules 已有，出現在 CLAUDE.md 造成雙重定義 |
| 結構順序 | 穩定內容在前，Lessons Learned 在最後 | 易變的 Lessons 插在中間破壞 cache 穩定性 |
| Lessons | ≤10 條，無跟 rules 重複的 | 已被共用規則涵蓋的條目沒有畢業 |
| Skill 關鍵字表（若有） | 所有引用的 skill 名稱有對應的 SKILL.md 存在 | 引用已刪除或改名的 skill |
Check 2：Skill Description 品質
列出所有 .claude/skills/*/SKILL.md，逐個檢查 frontmatter：
| 檢查項 | PASS 條件 | 常見問題 |
|---|---|---|
| 有 frontmatter | --- 包圍的 YAML block 存在 |
缺少 frontmatter，Claude Code 無法顯示於 system-reminder |
| description 長度 | ≤2 句話 | 觸發情境、更新時機、能力列表全塞進 description |
| 觸發條件 | 包含「觸發：」或「Use when:」 | 只寫功能描述，沒說什麼時候用 |
| 無冗餘內容 | 能力範圍、更新政策不在 description 裡 | 這些屬於 SKILL.md 正文，不該佔 system-reminder token |
| 格式統一 | 統一用一種觸發格式 | 有的中文「觸發時機」有的英文「Use when」混用 |
估算 token 節省：skill 數量 × 每個 skill 平均精簡 token 數 = 每輪節省量。
Check 3：Settings 配置
讀取 settings.local.json 或 settings.json，檢查：
| 檢查項 | PASS 條件 | 常見問題 |
|---|---|---|
| 工具最小化 | allow list 只有這個 agent 真的需要的工具 | 一次性加了全套工具，實際用不到 |
| 無冗餘權限 | wildcard（*）存在時無個別條目 |
mcp__tool__* 同時列了 7 條個別權限 |
| deny rules | 執行 bash 的 agent 有 deny rules | 無 deny 導致 agent 可執行危險指令 |
| model 適配 | model 匹配任務複雜度（見 cc-cost-engineering 矩陣） | 簡單反思任務用 opus，浪費費用 |
| MCP server 數量 | .mcp.json 的 server 數量合理，無不使用的 server |
MCP server 的工具 schema 每輪注入 prompt，多餘 server 增加 token + cache break 風險 |
Check 4：Rules 對齊
確認 .claude/rules/ 的內容與 CLAUDE.md 無矛盾：
| 檢查項 | PASS 條件 |
|---|---|
| 無相互矛盾 | rules 與 CLAUDE.md 的指令方向一致 |
| 無跨檔重複 | 同一條指令不同時出現在 rules 和 CLAUDE.md |
| @import 有效 | 若使用 @import，被引用的檔案存在 |
Check 5：跨檔一致性
若有 persona/soul.md，檢查與 CLAUDE.md 的一致性：
| 檢查項 | PASS 條件 | 常見問題 |
|---|---|---|
| 角色定義對齊 | CLAUDE.md 角色定義 ⊆ soul.md Who I Am | CLAUDE.md 寫「AI 助手」但 soul.md 寫有個性的角色名 |
| 原則不矛盾 | CLAUDE.md 核心原則不與 soul.md Work Principles 衝突 | 同一條原則兩邊措辭或方向不同 |
| 使用者期待不重複 | CLAUDE.md 使用者期待不與 soul.md Quirks/How I Sound 重複 | 「emoji 節制」同時出現在兩處 |
若無 persona/soul.md，此 check 標記 N/A。
執行模式
| 模式 | 觸發方式 | 行為 |
|---|---|---|
| review | "review X 的配置" / "audit this project" | 唯讀，產出報告，不改任何檔案 |
| fix | "整理 X 的配置" / "optimize this project" | 產出報告 + 列出所有預計改動，等確認後才執行 |
| batch | "review 所有 agent" | 逐個 agent/專案產出獨立報告 |
輸出格式
# 配置審計報告：{project/agent name}
## Summary
- CLAUDE.md: PASS / ISSUE(N)
- Skills: PASS / ISSUE(N)
- Settings: PASS / ISSUE(N)
- Rules: PASS / ISSUE(N)
- Consistency: PASS / ISSUE(N) / N/A
## Issues
### [ISSUE-1] {檢查項}
- Current: ...
- Problem: ...
- Suggested fix: ... （含具體 before/after）
- Migration: 被移除的內容搬到哪裡
### [ISSUE-2] ...
## Token Impact
- Skill descriptions: ~{N} tokens/turn saved
- CLAUDE.md: ~{N} tokens saved
- Rules consolidation: {N} fewer system-reminder injections
安全規範
- review 模式是嚴格唯讀，不寫入任何檔案
- fix 模式必須先列出所有計畫變更（diff 格式），等待使用者確認後才執行
- Lessons 永不自動刪除——只標記為「畢業候選」，由使用者決定
- Description 精簡必須先確認細節已移入 SKILL.md 正文，才縮短 description
依賴的知識來源
cc-prompt-craft：prompt 結構、cache 優化、17 種設計模式cc-agent-design：工具最小化、模型選擇、dispatch promptcc-cost-engineering：token 成本、cache 中斷原因、model 成本矩陣cc-harness-patterns：deferred loading、cache 穩定性agentskill-expertise：skill 設計哲學（Metadata-driven、Description-Driven Triggering）