# 项目架构模板

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

## 目录结构

```text
templates/
├── README.md                    # 本文件
├── AGENTS.template.md           # 入口导航模板
├── AGENT_RULES.template.md      # superpowers-first 执行规则模板
├── 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/README.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` 则跳过。
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/`
  只负责把代理导向正确的任务入口。

## 快速部署

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

```toml
# playbook.toml
[playbook]
project_root = "/path/to/project"
playbook_root = "docs/standards/playbook"
install_mode = "snapshot"

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

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

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

```bash
python <playbook_root>/scripts/playbook.py -config playbook.toml
```

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

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

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

```bash
python scripts/playbook.py -config playbook.toml
```

此时 `install_mode = "snapshot"` 会把快照写入 `<project_root>/<playbook_root>`；
后续再在目标项目内使用 `<playbook_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}}`

### 典型场景

```toml
# 场景 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 命名约定

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

- 设计只落到 `specs/`
- 计划只落到 `plans/`
- 执行状态只写回 `memory-bank/progress.md`

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

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

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

### 生命周期总览

完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。
这里仅说明职责分层：

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

### 部署后的目录结构

```text
project/
├── AGENTS.md              # 入口导航（Codex 入口）
├── AGENT_RULES.md         # superpowers-first 执行规则
├── 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` 后缀）：

其中 `templates/prompts/README.md` 部署后对应 `docs/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.py` 覆盖。
计划编排与执行细节统一指向 `docs/superpowers/`、
`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`；
这里仅说明模板职责与部署边界。

### 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 配置模板。`install_mode = "snapshot"` 安装快照时会复制这些模板：

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

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

**使用方式**：

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

[sync_standards]
langs = ["tsl", "cpp", "python"]
```

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

## 与 playbook 其他部分的关系

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

## 完整部署流程

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

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

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

---

**最后更新**：2026-05-18