playbook-audit

name	playbook-audit
description	對 playbook 進行多模型交叉審計與重構，確保符合官方最佳實踐
disable-model-invocation	true

Playbook 審計與重構

對 playbook 的 prompt 組裝系統進行結構化審計，透過多模型交叉驗證找出缺陷，分波修正。

執行對象：$ARGUMENTS（若未指定，預設審計整個 playbook）

---

Phase 0：預檢（不用 LLM 先掃一輪）

進 Phase 1 之前先跑機械化檢查，能自動發現的問題不浪費 agent 算力：

# 死引用：文中提到的檔案是否存在
python3 -c "
import os, re
from pathlib import Path
for f in Path('.').rglob('*.md'):
    if '.git' in f.parts: continue
    for m in re.finditer(r'\`([a-z][a-z_-]*/[a-z0-9_/-]+\.md)\`', f.read_text()):
        ref = m.group(1)
        if not Path(ref).exists() and not ref.startswith('playbook/'):
            print(f'{f}: ref {ref} not found')
"

# Claim vs reality：CLAUDE.md 宣稱自動載入 / inline / 必載 但沒用 @ import
grep -lE "自動(載入|inline)|必載|強制載入" CLAUDE.md && grep "^@" CLAUDE.md

# 行數合規
for f in roles/*.md skills/*.md stacks/*.md policies/*.md templates/*.md; do
  lines=$(wc -l < "$f")
  [[ $lines -gt 100 ]] && echo "$f: $lines (exceeds 100)"
done
wc -l CLAUDE.md | awk '$1 > 200 {print $2": "$1" (exceeds 200)"}'

已知易踩的 gotcha pattern：

Pattern	症狀	檢查方式
批次替換空格殘留	sed s/A/B/ 後 B + 原本 A 後面的空格 + 中文	grep 上方
死引用	刪除檔案後仍有 \path/to/deleted.md``	python 上方
假自動載入	CLAUDE.md 說「自動載入 X」但無 @X	上方 grep
路徑混淆	@playbook/CLAUDE.md（import 指令） vs `playbook/CLAUDE.md`（文字引用）	視覺檢查
Breaking 無標記	刪除 / 遷移檔案但 commit message 無 !	git log --oneline
.claude 子目錄誤認自動載入	submodule 下 playbook/.claude/ 實際不會自動載	驗證 consumer setup

---

Phase 1：多模型交叉審計

同時派出 Codex 和 Gemini 做獨立審查，自己也做一份，三方比對。

1.1 派出審計任務

同時發送、背景執行、不等結果：

• Gemini（cc-gemini-plugin:gemini-agent）：全 codebase 掃描。強項：跨檔一致性、術語統一、規模議題（哪些檔過長、哪些規則重複）
• Codex（codex:codex-rescue）：獨立 diagnosis pass。強項：挑戰「宣稱 vs 實際」落差、找出被忽略的機制盲點（例：宣稱自動載入但無 @ import）
• 自己：同步進行分析。強項：結構性問題、路徑引用、已知 gotcha 核對

分派 prompt 時附上 Phase 0 的預檢結果，讓 agent 知道已機械化查過的項目，專注深層分析。

1.2 審計維度

要求每個審計者檢查以下維度：

1. 架構風險：層間邊界是否清晰、優先順序是否合理（且內部無矛盾）、組合是否可驗證
2. 自我一致性：playbook 是否遵守自己定義的規則（delta-only、行數上限、術語統一、@ import 正確使用）
3. 機制落差：文件宣稱的機制是否真的生效（例：「自動載入」「每次必載」是否用了 @ import；宣稱的優先序是否被遵守）
4. 原生機制對應：playbook 的邏輯分層（core / overlay）是否映射到 Claude Code 原生 discovery（@ import、.claude/agents/、.claude/skills/、.claude/rules/）
5. 維護負擔：易過期內容（版本號、工具清單、URL）、過長檔案、重複資訊
6. 消費端影響：消費端 setup 流程是否仍可跑、升級 playbook 會破壞哪些引用、Breaking Change 是否標記
7. 一致性問題：跨檔案引用是否存在、術語統一、互斥清單完整
8. 缺失項目：成本控制、安全護欄、失敗模式 / plugin 降級、onboarding、多模型指引
9. 過度約束：LLM 常識、policy 層級錯置、stack 混入工作流程

1.3 三方比對

三方結果到齊後，製作比對表：

| 議題 | Claude | Codex | Gemini | 共識 |
|:-----|:------:|:-----:|:------:|:-----|
| ... | ✅/⚠️/❌ | ✅/⚠️/❌ | ✅/⚠️/❌ | 行動決策 |

判斷原則：

• 三方一致：直接採納
• 二比一：採多數意見，但檢查少數方的理由是否有獨特洞見（通常 Codex 找機制落差、Gemini 找一致性、自己找結構）
• 三方分歧：查官方文件或原始碼確認，不猜測

---

Phase 2：分波修正計畫

將審計發現按「對使用者的影響」排序，分三波執行。

2.1 整合為三波

波次	標準	時機
第一波	高風險：死引用、機制落差、破壞性殘留、使用者踩坑	立即
第二波	中風險：層級重分、術語統一、官方格式對齊	本週
第三波	缺失項目：onboarding、降級指引、文件補齊	下週

2.2 分歧裁決

修正方案有分歧時的判斷原則：

• 偏務實的方案優先（避免過度工程化）
• 減少檔案數的方案優先（每個新檔案都是維護負擔）
• 向官方最佳實踐靠攏的方案優先
• 使用者的明確要求（CLAUDE.md 保守 / 激進等）優先於 agent 建議

---

Phase 3：逐波執行

每波執行後驗證，再進入下一波。

3.1 執行

• 依修正計畫逐項執行
• 新建檔案前確認能否合併到現有檔案
• 刪除 / 重命名檔案時更新所有引用（用 Phase 0 的 grep 驗證）
• Breaking 變更的 commit 用 ! 標記（例：refactor!: 刪除 X）
• 每波完成後 commit

3.2 波間驗證

每波完成後檢查：

• 引用完整性：Phase 0 的 grep 再跑一次，無死引用
• 無循環參考：入口檔之間不互相指來指去
• 行數合規：元件檔 ≤ 100 行、CLAUDE.md ≤ 200 行、SKILL.md ≤ 500 行（官方建議）
• 消費端可跑：在 /tmp 建測試目錄跑 bash playbook/setup.sh

---

Phase 4：官方最佳實踐比對

取得官方最新文件，逐項比對。

4.1 取得官方文件

WebFetch: https://code.claude.com/docs/en/best-practices
WebFetch: https://code.claude.com/docs/en/memory
WebFetch: https://code.claude.com/docs/en/sub-agents
WebFetch: https://code.claude.com/docs/en/skills
WebFetch: https://code.claude.com/docs/en/settings
WebFetch: https://code.claude.com/docs/en/hooks

可平行 WebFetch，每份請 agent 整理「具體 do's and don'ts」、「format requirements」、「common mistakes」，避免抽象總結。

4.2 比對維度與官方上限

維度	檢查什麼	官方具體規範
CLAUDE.md	長度、內容類型	上限 200 行；只放 LLM 無法自推的內容
SKILL.md	長度、supporting files	建議 < 500 行；長內容拆成 reference.md 等同目錄檔
Subagent frontmatter	name / description / tools / model	tools: Read, Grep, Bash（逗號分隔 string）；model 頂層
@path import	相對路徑、遞迴深度	相對 檔案本身，不是 CWD；最多 5 層遞迴
Skills 路徑	位置與命名	.claude/skills/<name>/SKILL.md；子目錄 .claude/skills/ 會在編輯該子目錄檔案時被 auto-discover
Hooks vs CLAUDE.md	強制 vs 建議	需確定性行為用 hook；建議性用 CLAUDE.md
驗證	是否強調	官方列為「the single highest-leverage thing」
上下文管理	token 成本、/clear 使用	CLAUDE.md 變肥 → Claude 忽略規則

4.3 落差修正

找到落差後，同樣用三方交叉驗證確認修正方向。特別注意：

• subagent 只能用 Claude 系列模型；跨模型協作用 plugin
• tools 格式：逗號分隔 string 或 YAML list 皆可
• Skills auto-discovery 的邊界：nested .claude/skills/ 只在編輯該子目錄檔案時自動載入；claude --add-dir 載 skills 不載 subagents
• Submodule .claude/ 不會自動被專案根讀：消費端必須 symlink

---

Phase 5：結構收斂

最後清理檔案結構。

5.1 入口檔案

確保只有兩個入口：

• README.md：給人讀，包含快速入門
• CLAUDE.md：給 agent 讀，包含組裝規則

兩者不互相引用（README 可提 CLAUDE.md 的存在與用途，但不載入其內容）。

5.1.1 AGENTS.md 與 GEMINI.md

AGENTS.md 和 GEMINI.md 是 CLAUDE.md 的 symlink。修改 CLAUDE.md 會自動反映，不要單獨編輯。需要改入口規則只動 CLAUDE.md。

5.1.2 消費端 vs maintainer 內容分離

• playbook/.claude/：playbook maintainer 自用（playbook-audit skill、settings.local.json）。消費端不需接
• playbook/symlink/：消費端專用（subagents 給消費端 symlink 用）

任何新增的 .claude/ 內容要先判斷屬於哪一邊，避免混淆。

5.2 參考方向檢查

Phase 0 的 python grep 再跑一次，確認無死引用。手動檢查入口檔之間無循環。

5.3 消費端 setup 實測

在 /tmp 建空目錄，symlink playbook 進去，跑 bash playbook/setup.sh，驗證：

• Fresh setup 全部成功
• 重跑仍通過（idempotency）
• 模擬 playbook 改名 / 刪除 agent 情境，清理邏輯正確
• 使用者的自訂真實檔未被破壞

5.4 最終 commit

全部修正完成後，已經分波 commit。最後做：

• git log --oneline 確認本輪所有 commit 訊息清楚、Breaking 有 ! 標記
• 若有單波內臨時的 fixup commit，考慮 squash（但不強制）
• 不建立額外的 summary commit（git log 已說話）