playbook/templates

项目架构模板

本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 代理工作环境。

与 Playbook 其他部分的关系

playbook/
├── rulesets/        # 语言级硬规则 → 部署到 .agents/
├── skills/          # 按需加载的技能
├── docs/            # 权威静态文档
├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/
    └── playbook.py    # 统一入口

部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。

目录结构

templates/
├── AGENTS.template.md           # 入口导航模板
├── AGENT_RULES.template.md      # superpowers 执行规则模板
├── memory-bank/                 # 项目上下文模板（6 个）
├── prompts/                     # 任务入口模板（6 个 + README）
├── ci/                          # CI 配置模板
├── cpp/                         # C++ 工具链模板
└── python/                      # Python 工具链模板

模板分类

从部署和维护角度，模板分为三类：

1. 框架模板（会自动更新）

这些文件由 playbook 框架维护，每次同步时可能更新：

• AGENT_RULES.md
• AGENTS.md、CLAUDE.md（按 playbook 区块更新）
• docs/prompts/README.md
• docs/prompts/system/*.md
• docs/prompts/coding/*.md

2. 项目上下文（首次创建后由项目维护）

这些文件首次创建后应由项目填写，force=true 会覆盖已填写内容并先备份：

• memory-bank/*.md
• AGENT_RULES.local.md（首次自动创建，后续不再覆盖）

3. 参考模板（需手动复制）

这些模板保留在快照中供参考，需手动复制到项目根目录：

• ci/：Gitea Actions 工作流
• cpp/：C++ 工具链配置
• python/：Python 工具链配置

补充说明：

• docs/prompts/custom/ 和项目新增的 docs/prompts/**/* 不会被 playbook 删除
• CLAUDE.md 如已有 playbook 区块则更新；如未引用 @AGENTS.md 则追加；如已手工引用则跳过
• 流程约束统一收敛到 AGENT_RULES.md；docs/prompts/ 只负责把代理导向正确的任务入口

部署方式

使用 playbook.py 统一入口部署，通过配置节控制同步内容：

# playbook.toml
[sync_rules]           # 同步 AGENT_RULES.md
[sync_memory_bank]     # 同步 memory-bank/
[sync_prompts]         # 同步 docs/prompts/

详细配置说明见主 README.md 和 playbook.toml.example。

模板说明

memory-bank/

项目上下文文档，用于让 AI 快速理解项目：

文件	用途
project-brief.template.md	项目定位、边界、约束
tech-context.template.md	技术上下文、工具链、入口
system-patterns.template.md	系统模式、边界、不变量
active-context.template.md	当前目标、最近变更、下一步
progress.template.md	人类摘要 + Plan 状态块
decisions.template.md	架构决策记录（ADR）

prompts/

任务入口模板，部署后去掉 .template 后缀。prompts/README.md 作为任务入口索引。

文件	用途	使用场景
system/agent-behavior.template.md	入口路由模板	选择执行路径
coding/clarify.template.md	需求澄清模板	需求不明确时
coding/verify-change.template.md	变更验证模板	声称完成前验证
coding/close-task.template.md	本轮收尾模板	一轮工作结束时
coding/update-memory.template.md	回写记忆模板	上下文变化后回写
coding/code-review.template.md	代码评审入口	执行 MR/PR 代码评审

AGENT_RULES.template.md

执行规则模板，定义 AI 的工作循环和约束。如需项目私有规则，建议维护 AGENT_RULES.local.md；该文件通常由 [sync_rules] 首次自动创建，其优先级高于 AGENT_RULES.md，且后续不会被 playbook 覆盖。

计划编排与执行细节统一指向 docs/superpowers/、playbook.py -record-spec/-record-plan 与 main_loop.py claim/finish。

AGENTS.template.md

入口导航模板，作为项目的主入口（Codex 入口）。

设计理念：

• 最小化内容：只包含导航链接，不包含详细规则
• 结构化导航：分为核心规则、项目上下文、任务入口三个板块

playbook 标记（用于自动更新）：

• <!-- playbook:agents:start/end -->：语言规则链接，由 [sync_standards] 管理
• <!-- playbook:templates:start/end -->：路由链接，AGENTS.md 始终按区块更新
• <!-- playbook:framework:start/end -->：完整框架，AGENTS.md 始终按区块更新

superpowers 工作流约定

docs/superpowers/ 统一承载设计稿和实施计划：

• 设计稿：specs/YYYY-MM-DD-<topic>-design.md（brainstorming 产出）
• 实施计划：plans/YYYY-MM-DD-<topic>.md（writing-plans 产出）
• 执行状态：回写到 memory-bank/progress.md

其中 plans/ 为主执行入口；specs/ 只作为设计背景和上游文档。

生命周期：

• docs/prompts/：任务入口层，只负责把代理导向正确入口
• docs/superpowers/specs/：设计稿
• docs/superpowers/plans/：实施计划与主执行输入
• memory-bank/progress.md：执行状态留痕

完整主链只在 AGENT_RULES.template.md 定义。

语言配置模板（ci/、cpp/、python/）

语言和 CI 配置模板，install_mode = "snapshot" 安装快照时会复制这些模板：

• ci/gitea/：Gitea Actions 工作流与辅助脚本，部署到快照 templates/ci/
• cpp/：.clang-format、.clangd、CMakeLists.txt 等文件，部署到快照 templates/cpp/
• python/：pyproject.toml、.editorconfig 等文件，部署到快照 templates/python/

使用方式：这些模板保留在快照中供参考，需手动复制到项目根目录使用。其中 ci/gitea/ 应按 templates/ci/README.md 的说明，整块复制 .gitea/ 目录。

技术细节

占位符说明

模板中使用 {{PLACEHOLDER}} 格式的占位符，需要替换为实际值：

占位符	说明	自动替换
{{DATE}}	日期	✅ 是
{{PROJECT_NAME}}	项目名称	✅ 可选
{{PLAYBOOK_ROOT}}	Playbook 根	✅ 是
{{PLAYBOOK_SCRIPTS}}	脚本路径	✅ 是
{{PROJECT_GOAL}}	项目目标	❌ 手动
{{PROJECT_DESCRIPTION}}	项目描述	❌ 手动
其他 {{...}}	项目特定内容	❌ 手动

• {{PROJECT_NAME}} 可通过 sync_memory_bank.project_name 自动替换；未配置时保持原样
• {{PLAYBOOK_ROOT}} 自动替换为项目内 Playbook 根目录（默认 docs/standards/playbook）
• {{PLAYBOOK_SCRIPTS}} 自动替换为 Playbook 脚本路径（默认 docs/standards/playbook/scripts）

部署后的目录结构

project/
├── AGENTS.md              # 入口导航（Codex 入口）
├── AGENT_RULES.md         # superpowers 执行规则
├── AGENT_RULES.local.md   # 项目私有规则（自动创建，项目维护）
├── CLAUDE.md              # Claude Code 入口
├── memory-bank/           # 项目上下文
│   ├── project-brief.md
│   ├── tech-context.md
│   ├── system-patterns.md
│   ├── active-context.md
│   ├── progress.md
│   └── decisions.md
└── docs/
    ├── prompts/           # 任务入口层
    │   ├── README.md
    │   ├── system/agent-behavior.md
    │   └── coding/
    │       ├── clarify.md
    │       ├── verify-change.md
    │       ├── close-task.md
    │       ├── update-memory.md
    │       └── code-review.md
    └── superpowers/
        ├── specs/         # brainstorming 产物
        └── plans/         # writing-plans / main_loop 消费

---

最后更新：2026-06-17