Shared Playbook

這個目錄作為 AI 協作與工程規範的共用模板，各專案以 git submodule 方式引用到 playbook/ 路徑。 定位上分成兩層：

• core：跨專案共用的規則、角色、workflow、模板
• overlay：依專案裁切的技術棧與團隊政策

作為 submodule 引用到專案

每個專案以 playbook/ 為固定路徑引用本 repo。

一次性 setup（新專案）

# 1. 加入 playbook submodule
git submodule add <playbook-repo-url> playbook
git commit -m "chore: add playbook submodule"

# 2. 跑 setup script（可重複執行）
bash playbook/setup.sh

Script 會：建立 CLAUDE.md（指向 @playbook/CLAUDE.md）、symlink AGENTS.md / GEMINI.md 指向 CLAUDE.md（嘗試讓 Copilot CLI / Gemini CLI 讀到同一份規則，未做完整 cross-CLI smoke test；實測主要在 Claude Code）、為 playbook/symlink/agents/ 下每個 subagent 建立 .claude/agents/<name>.md 獨立 symlink、為 playbook/symlink/hooks/ 下每個 hook 建立 .claude/hooks/<name>.sh 獨立 symlink、整檔寫入 .claude/settings.json 的 hooks wiring。

首次啟動提醒：第一次在此專案跑 claude，Claude Code 會偵測到 CLAUDE.md 裡的 @playbook/CLAUDE.md 外部 import，彈出 approval dialog 列出即將載入的檔案，必須選 approve。若誤拒，import 會永久 disabled 且對話框不會再跳出（整個 playbook 失效）。恢復方式依 Claude Code 當時版本而定；參考 guides/diagnosing-output.md 或 Claude Code 官方文件的「memory / imports」段落。刪除 .claude/ 與 root CLAUDE.md 重跑 setup 未必能清除 Claude Code 端的 import 同意狀態。

不會被覆蓋的檔案：既有 CLAUDE.md（若非 symlink 也非指向 playbook 者會被跳過並提醒）、任何已存在的真實檔（非 symlink）如 AGENTS.md / GEMINI.md / .claude/agents/*。

會被整檔接管的檔案：.claude/settings.json（hooks wiring 的 source of truth 在 setup.sh 內；已有內容會被覆寫並提示）。專案自訂設定請放 .claude/settings.local.json，Claude Code 會原生合併，不會被 playbook 動到。

注意 scope 合併語意：Claude Code 對 array 類欄位（permissions.allow / permissions.deny / hooks 等）是跨 scope 合併去重而非覆寫，所以使用者個人 settings（~/.claude/settings.json）與 .claude/settings.local.json 裡的 array 條目仍會與 playbook 的項目疊加；scalar 欄位（model、autoMode 等）才是後者取代前者。

Hooks 行為 override 走 repo 內 .claude/playbook-hooks.conf（純資料格式，團隊共用）。細節見 guides/hooks-cookbook.md。

playbook/symlink/ 是消費端專用目錄，包含跨專案共用的 subagents。playbook/.claude/ 則是 playbook 自己維護用的（playbook-audit skill 等），消費端不需接。

playbook 的全域規則、語氣、組裝規則自動生效；role / stack / skill / policy 由 LLM 依任務按需載入，不預先宣告。若專案有與 playbook 預設不同的規則，再加一段「專案覆寫」（詳見 templates/project-claude-md.md）。

手動版本（若不想用 script）

只處理 aliases 與 subagents。若要完整等價（含 hooks 與 settings.json wiring），還是跑 bash playbook/setup.sh。

echo "@playbook/CLAUDE.md" > CLAUDE.md
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md GEMINI.md
mkdir -p .claude/agents .claude/hooks
for f in playbook/symlink/agents/*.md; do
    ln -s "../../$f" ".claude/agents/$(basename "$f")"
done
for f in playbook/symlink/hooks/*.sh; do
    [[ "$(basename "$f")" == "tests.sh" ]] && continue
    ln -s "../../$f" ".claude/hooks/$(basename "$f")"
done
# hooks wiring 需要寫入 .claude/settings.json，手動版本不處理，請跑 setup.sh

為什麼逐檔而非目錄 symlink：這樣 playbook 重命名或刪除 subagent / hook 時，setup.sh 可只清指向 playbook 的舊 symlink，保留消費端自訂的。

平台限制：symlink 步驟目前僅支援 macOS / Linux。Windows 開發者需額外處理（mklink 或 git config core.symlinks true），此 playbook 尚未提供官方指引。

clone 既有專案

git clone --recursive <project-repo-url>
# 或 clone 後補拉
git submodule update --init --recursive

更新 playbook 到最新版

cd playbook && git pull origin main && cd ..
bash playbook/setup.sh        # 重跑以更新 subagent / hook symlink 與 settings.json wiring
git add playbook .claude CLAUDE.md AGENTS.md GEMINI.md && git commit -m "chore: bump playbook"

重跑 setup.sh 是必要步驟：playbook 新增/移除 subagent 或 hook、改動 hooks wiring 時，只 git pull 不會反映到消費端的 symlink 與 .claude/settings.json。重跑完建議重開 Claude session，讓 harness 重新掃描設定。

原則：playbook 升級由專案主動拉、pin commit、走 code review；不自動同步，避免上游改動打壞下游。

路徑慣例

• 本 playbook 內部互相引用（例：stacks/backend-dotnet.md 提到 policies/architecture-defaults.md）一律相對 playbook 根
• 專案載入 playbook 後，LLM 要讀 playbook 內檔案時自動加上 playbook/ 前綴（例：playbook/policies/architecture-defaults.md）
• @playbook/CLAUDE.md 這類 @ 開頭語法是 Claude Code 的 inline 載入指令，與純文字路徑引用不同

@ import 解析規則（Claude Code 官方）

• 相對於引入者所在檔案，不是 CWD。消費端 CLAUDE.md 的 @playbook/CLAUDE.md 相對於專案根；playbook/CLAUDE.md 內的 @policies/agent-security.md 相對於 playbook 根（解析為 playbook/policies/agent-security.md）
• 最大遞迴深度：5 層。本 playbook 當前只用 2 層（project/CLAUDE.md → playbook/CLAUDE.md → policies/agent-security.md），預留充足空間
• 消費端 CLAUDE.md 不要 用 @ 預載 role / stack / skill / policy — 會讓每次對話都付固定 token 成本，破壞 playbook 的「按需載入」模型（詳見 guides/prompt-best-practices.md）

快速入門

最小組合

CLAUDE.md               ← Agent 入口文件（每次對話自動載入）
roles/developer.md      ← 通用開發角色

先用這兩個檔案跑一個真實任務，看到效果再往下加。

驗證範例：載入最小組合後，輸入「幫我 review 這段程式碼：function add(a, b) { return a - b; }」。預期 agent 會以 developer 角色指出邏輯錯誤、建議修正方向、並標示驗證方式。若回覆符合 CLAUDE.md 的格式（結論 → 說明 → 風險），代表組裝正確。

按需疊加

想做什麼	加什麼	範例
換角色	roles/ 裡的其他角色	做 API → roles/backend.md
加流程	skills/ 裡的技能	做 Code Review → skills/code-review.md
固定產出格式	templates/ 裡的模板	要 RCA 報告 → templates/incident-rca.md
套技術棧限制	stacks/ 裡的 overlay	.NET 專案 → stacks/backend-dotnet.md
套團隊政策	policies/ 裡的 overlay	微服務架構 → policies/architecture-defaults.md

不需要一次全載。每次對話只帶 1 個 role + 1–3 個 skill，夠用就好。

內容

• CLAUDE.md — Agent 入口文件（全域規則、組裝規則、語氣；每次對話自動載入）
• AGENTS.md / GEMINI.md — CLAUDE.md 的 symlink，嘗試讓其他 CLI 讀到同一份規則（未做完整 cross-CLI smoke test）
• roles/ skills/ templates/ policies/ stacks/ — 可組合的 prompt 元件
• symlink/agents/ — 暴露給消費端的 subagent 定義（security-reviewer、code-reviewer、qa-checker、migration-reviewer）
• symlink/hooks/ — 暴露給消費端的 PreToolUse/PostToolUse hooks（secret-guard、dangerous-bash、migration-warn、auto-format、pre-commit-test）
• .claude/ — playbook 自己維護用（playbook-audit skill 等），消費端不需接入；詳見 .claude/README.md

Core（預設保留）

CLAUDE.md · roles/ · skills/ · templates/

Overlay（依專案裁切）

stacks/ · policies/

若專案不符合既有 stack / policy，應改寫或新增 overlay，而不是硬套進 core prompt。

組裝與工作流

組裝順序、載入原則、衝突規則與範例見 CLAUDE.md。

若任務較複雜，建議遵循：spec / discovery → plan → implement → verify → review / handoff

指南

• 新手上路：onboarding.md
• Prompt 撰寫與維護：prompt-best-practices.md
• Harness 設定：harness-setup.md
• Hooks 設定與範例：hooks-cookbook.md
• OpenSpec 整合：openspec-integration.md
• 產出不符預期時的診斷：diagnosing-output.md
• 成本與 token 控制：cost-control.md
• 多模型協作：multi-model.md
• 完整元件列表與範例：assembly-reference.md

選配工具

本 playbook 不內建變更管理工具。若需要 spec / proposal / tasks 等結構化工件，可自行安裝 Fission-AI/OpenSpec 為 global plugin 使用，工作流與本 playbook 互補不衝突。