// Claude Code 專案配置審計。觸發：review/優化 CLAUDE.md、skills、settings、定期清洗累積內容、新專案上線前檢查。
| name | cc-agent-audit |
| description | Claude Code 專案配置審計。觸發：review/優化 CLAUDE.md、skills、settings、定期清洗累積內容、新專案上線前檢查。 |
| version | 202604 |
| context | fork |
系統化 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 |
依序執行，每項產出 PASS / ISSUE(N) 結論。
讀取 CLAUDE.md，逐項檢查：
| 檢查項 | PASS 條件 | 常見問題 |
|---|---|---|
| 角色定義 | 寫人格不寫機制。一句話設定語氣基調 | 描述 AI 的技術機制而非個性特質 |
| 使用者期待 | 只放跟所有對話都相關的通用事項 | 任務特定指令（如寫作格式）坐在 CLAUDE.md 裡 |
| 核心原則 | 不與 .claude/rules/ 的任何檔案重複 | 原則內容 rules 已有，出現在 CLAUDE.md 造成雙重定義 |
| 結構順序 | 穩定內容在前，Lessons Learned 在最後 | 易變的 Lessons 插在中間破壞 cache 穩定性 |
| Lessons | ≤10 條，無跟 rules 重複的 | 已被共用規則涵蓋的條目沒有畢業 |
| Skill 關鍵字表（若有） | 所有引用的 skill 名稱有對應的 SKILL.md 存在 | 引用已刪除或改名的 skill |
列出所有 .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 數 = 每輪節省量。
讀取 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 風險 |
確認 .claude/rules/ 的內容與 CLAUDE.md 無矛盾：
| 檢查項 | PASS 條件 |
|---|---|
| 無相互矛盾 | rules 與 CLAUDE.md 的指令方向一致 |
| 無跨檔重複 | 同一條指令不同時出現在 rules 和 CLAUDE.md |
| @import 有效 | 若使用 @import，被引用的檔案存在 |
若有 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
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）Use when writing, reviewing, or deciding what to post on Threads. Also triggers when planning post-viral strategy or checking posting timing. Runs pre-publish checks based on Meta algorithm patents.
Use when predicting Threads post performance, analyzing post history patterns, estimating engagement ceiling for a draft, or deciding what content type to write next. Works with or without personal data — uses darkseoking benchmark as fallback.
Agent 配置設計指南 — 基於 Claude Code 6 個 built-in agent 的逆向分析。Use when: 設計新 agent、優化現有 agent prompt、決定工具/模型配置、撰寫 dispatch prompt。
AI Agent 成本工程 — 基於 Claude Code 的成本追蹤、prompt cache 最佳化、token 預算控制逆向分析。Use when: 優化 token 消耗、設計成本控制機制、分析 cache 效率、選擇模型配置。
Harness Engineering 設計模式 — 基於 Claude Code 原始碼逆向分析的 12 條可遷移原則。Use when: 設計 agent 系統架構、實作 tool orchestration、設計 context 管理策略、建構 agent loop。
System Prompt 工程 — 基於 Claude Code 914 行系統提示詞的逆向分析。Use when: 撰寫 system prompt、設計 prompt 動態組裝、最佳化 prompt cache 效率、撰寫安全指令。