358 lines
13 KiB
Markdown
358 lines
13 KiB
Markdown
# 项目架构模板
|
||
|
||
本目录包含以 `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
|