القائمة
對 playbook 進行多模型交叉審計與重構，確保符合官方最佳實踐
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | playbook-audit |
| description | 對 playbook 進行多模型交叉審計與重構，確保符合官方最佳實踐 |
| disable-model-invocation | true |
對 playbook 的 prompt 組裝系統進行結構化審計，透過多模型交叉驗證找出缺陷，分波修正。
執行對象：$ARGUMENTS（若未指定，預設審計整個 playbook）
進 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 |
同時派出 Codex 和 Gemini 做獨立審查，自己也做一份，三方比對。
同時發送、背景執行、不等結果：
cc-gemini-plugin:gemini-agent）：全 codebase 掃描。強項：跨檔一致性、術語統一、規模議題（哪些檔過長、哪些規則重複）codex:codex-rescue）：獨立 diagnosis pass。強項：挑戰「宣稱 vs 實際」落差、找出被忽略的機制盲點（例：宣稱自動載入但無 @ import）分派 prompt 時附上 Phase 0 的預檢結果，讓 agent 知道已機械化查過的項目，專注深層分析。
要求每個審計者檢查以下維度：
@ import 正確使用）@ import；宣稱的優先序是否被遵守）@ import、.claude/agents/、.claude/skills/、.claude/rules/）三方結果到齊後，製作比對表：
| 議題 | Claude | Codex | Gemini | 共識 |
|:-----|:------:|:-----:|:------:|:-----|
| ... | ✅/⚠️/❌ | ✅/⚠️/❌ | ✅/⚠️/❌ | 行動決策 |
判斷原則：
將審計發現按「對使用者的影響」排序，分三波執行。
| 波次 | 標準 | 時機 |
|---|---|---|
| 第一波 | 高風險：死引用、機制落差、破壞性殘留、使用者踩坑 | 立即 |
| 第二波 | 中風險：層級重分、術語統一、官方格式對齊 | 本週 |
| 第三波 | 缺失項目：onboarding、降級指引、文件補齊 | 下週 |
修正方案有分歧時的判斷原則：
每波執行後驗證，再進入下一波。
! 標記（例：refactor!: 刪除 X）每波完成後檢查：
/tmp 建測試目錄跑 bash playbook/setup.sh取得官方最新文件，逐項比對。
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」，避免抽象總結。
| 維度 | 檢查什麼 | 官方具體規範 |
|---|---|---|
| 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 忽略規則 |
找到落差後，同樣用三方交叉驗證確認修正方向。特別注意：
.claude/skills/ 只在編輯該子目錄檔案時自動載入；claude --add-dir 載 skills 不載 subagents.claude/ 不會自動被專案根讀：消費端必須 symlink最後清理檔案結構。
確保只有兩個入口：
README.md：給人讀，包含快速入門CLAUDE.md：給 agent 讀，包含組裝規則兩者不互相引用（README 可提 CLAUDE.md 的存在與用途，但不載入其內容）。
AGENTS.md 和 GEMINI.md 是 CLAUDE.md 的 symlink。修改 CLAUDE.md 會自動反映，不要單獨編輯。需要改入口規則只動 CLAUDE.md。
playbook/.claude/：playbook maintainer 自用（playbook-audit skill、settings.local.json）。消費端不需接playbook/symlink/：消費端專用（subagents 給消費端 symlink 用）任何新增的 .claude/ 內容要先判斷屬於哪一邊，避免混淆。
Phase 0 的 python grep 再跑一次，確認無死引用。手動檢查入口檔之間無循環。
在 /tmp 建空目錄，symlink playbook 進去，跑 bash playbook/setup.sh，驗證：
全部修正完成後，已經分波 commit。最後做：
git log --oneline 確認本輪所有 commit 訊息清楚、Breaking 有 ! 標記