playbook/templates

项目架构模板

本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。

目录结构

templates/
├── README.md                    # 本文件
├── AGENTS.template.md           # 路由中心模板
├── AGENT_RULES.template.md      # 执行流程模板
├── memory-bank/                 # 项目上下文模板
│   ├── project-brief.template.md
│   ├── tech-context.template.md
│   ├── system-patterns.template.md
│   ├── active-context.template.md
│   ├── progress.template.md
│   └── decisions.template.md
├── prompts/                     # 提示词库模板
│   ├── README.md
│   ├── system/
│   │   └── agent-behavior.template.md
│   ├── coding/
│   │   ├── clarify.template.md
│   │   ├── verify-change.template.md
│   │   ├── close-task.template.md
│   │   ├── update-memory.template.md
│   │   └── code-review.template.md
├── ci/                          # CI 模板
│   ├── README.md
│   └── gitea/
│       └── .gitea/
│           ├── workflows/
│           └── ci/
├── cpp/                         # C++ 配置模板
│   ├── .clang-format
│   ├── .clangd
│   └── ...
└── python/                      # Python 配置模板
    ├── .editorconfig
    ├── pyproject.toml
    └── ...

文件分类

从部署角度看，本目录的文件分成三类：

• 会同步更新的框架模板
  • AGENT_RULES.md
  • docs/prompts/system/*.md
  • docs/prompts/coding/*.md
  • AGENTS.md、CLAUDE.md（按 playbook 区块更新）
• 首次创建后由项目维护的上下文文件
  • memory-bank/*.md
  • AGENT_RULES.local.md
• 只保留在快照中参考的模板
  • ci/
  • cpp/
  • python/

补充说明：

• memory-bank/*.md 首次创建后应由项目填写；force=true 会覆盖已填写内容并先备份。
• AGENT_RULES.local.md 由 [sync_rules] 首次自动创建， 后续不再覆盖。
• docs/prompts/custom/ 和项目新增的 docs/prompts/**/* 不会被 playbook 删除。
• CLAUDE.md 如已有 playbook 区块则更新；如未引用 @AGENTS.md 则追加；如已手工引用 @AGENTS.md 则跳过。

快速部署

以下命令假设 playbook 已经部署到项目内，使用统一入口 playbook.py，配置节存在即启用：

# playbook.toml
[playbook]
project_root = "/path/to/project"

# 同步 AGENT_RULES.md（配置节存在即启用）
[sync_rules]
# force = true  # 可选，强制覆盖已存在的文件

# 同步 memory-bank/（配置节存在即启用）
[sync_memory_bank]
project_name = "MyProject"
# force = true  # 可选，强制覆盖（会先备份）

# 同步 docs/prompts/（配置节存在即启用）
[sync_prompts]
# force = true  # 可选，强制覆盖（会先备份）

python <deploy_root>/scripts/playbook.py -config playbook.toml

参数说明见 playbook.toml.example（仓库根目录）或项目内的 <deploy_root>/playbook.toml.example。

其中 <deploy_root> 默认为 docs/standards/playbook， 也可以按项目配置改成 custom/playbook 等自定义目录； 对应文档入口会变成 <deploy_root>/docs/...。

如果你当前是在 外部 clone 的 playbook 仓库 中执行，而不是在目标项目内执行快照，请使用：

python scripts/playbook.py -config playbook.toml

此时 [vendor] 会把快照写入 <project_root>/<deploy_root>； 后续再在目标项目内使用 <deploy_root>/scripts/playbook.py 做同步更新。

配置节说明

• [sync_rules]：部署 AGENT_RULES.md；必要时创建 .local.md。 选项：force、no_backup、date

• [sync_memory_bank]：部署 memory-bank/。 选项：project_name、force、no_backup、date

• [sync_prompts]：部署 docs/prompts/。 选项：force、no_backup、date

• [sync_standards]：部署 .agents/<lang>/。 选项：langs、gitattr_mode、no_backup

• [install_skills]：部署到 ~/.agents/skills/ 或 ~/.claude/skills/。 选项：mode、skills、agents_home、skill_link、 no_backup

• 配置节存在即启用：只写需要同步的配置节

• AGENTS.md：始终按区块更新（<!-- playbook:xxx:start/end -->），不受配置节控制

• CLAUDE.md：自动检测/创建；如已存在 playbook 区块则更新，如未引用 @AGENTS.md 则追加，否则跳过

• force：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）

• no_backup：默认 false；设为 true 时跳过备份直接覆盖

• 不删除项目文件：只更新框架提供的文件，项目新增的文件不会被删除

• 占位符替换：自动替换 {{DATE}}、{{PROJECT_NAME}}、{{PLAYBOOK_SCRIPTS}}

典型场景

# 场景 1：初次部署（全部）
[sync_rules]
[sync_memory_bank]
project_name = "MyProject"
[sync_prompts]

# 场景 2：框架升级（只更新规则）
[sync_rules]
force = true

# 场景 3：重置项目上下文
[sync_memory_bank]
project_name = "MyProject"
force = true

docs/superpowers 命名约定

为与 thirdparty superpowers 上游当前工作流对齐，建议统一使用：

• docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md： brainstorming 产出的设计稿
• docs/superpowers/plans/YYYY-MM-DD-<topic>.md： writing-plans 产出的实施计划

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

生命周期总览

需求澄清
  -> using-superpowers
  -> brainstorming
  -> docs/superpowers/specs/*.md
  -> playbook.py -record-spec
  -> writing-plans
  -> docs/superpowers/plans/*.md
  -> playbook.py -record-plan
  -> main_loop.py claim
  -> executing-plans
  -> [代码类任务] + karpathy-guidelines + .agents + AGENT_RULES
  -> main_loop.py finish
  -> update-memory / close-task

部署后的目录结构

project/
├── AGENTS.md              # 路由中心（Codex 入口）
├── AGENT_RULES.md         # 执行流程
├── AGENT_RULES.local.md   # 项目私有规则（自动创建，项目维护）
├── CLAUDE.md              # Claude Code 入口（按规则维护/追加 playbook 区块）
├── 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 消费

占位符说明

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

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

{{PROJECT_NAME}} 可通过 sync_memory_bank.project_name 自动替换； 未配置时保持原样。 {{PLAYBOOK_SCRIPTS}} 自动替换为 Playbook 脚本路径 （默认 docs/standards/playbook/scripts， 也可按项目配置改成 custom/playbook/scripts 等）。

模板说明

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 后缀）：

文件	用途	使用场景
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.py 覆盖。 计划编排与执行细节建议放在 prompts/README.md 或相关 workflow 文档中， 这里仅说明模板职责与部署边界。

AGENTS.template.md

路由中心模板，作为项目的主入口。

设计理念：

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

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

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

ci/、cpp/、python/

语言和 CI 配置模板。通过 playbook.py 的 [vendor] 复制到快照中：

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

注意：这些模板通过 [vendor] 复制到快照的 templates/ 目录，需手动从快照复制到项目根目录使用。 其中 ci/gitea/ 应按 templates/ci/README.md 的说明，整块复制 .gitea/ 目录，而不只是复制 workflows。

使用方式：

# playbook.toml - 生成包含这些模板的快照
[playbook]
project_root = "/path/to/project"

[vendor]
langs = ["tsl", "cpp", "python"]

python scripts/playbook.py -config playbook.toml
# 然后手动从 <deploy_root>/templates/ 复制所需配置到项目根目录

与 playbook 其他部分的关系

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

完整部署流程

# 1. 准备配置并执行统一入口
python <deploy_root>/scripts/playbook.py -config playbook.toml

# 2. 编辑 memory-bank/*.md 填写项目信息

# 3. 替换剩余的 {{PLACEHOLDER}} 占位符

---

最后更新：2026-05-18