211 lines
8.4 KiB
Markdown
211 lines
8.4 KiB
Markdown
# 项目架构模板
|
||
|
||
本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 代理工作环境。
|
||
|
||
## 与 Playbook 其他部分的关系
|
||
|
||
```text
|
||
playbook/
|
||
├── rulesets/ # 语言级硬规则 → 部署到 .agents/
|
||
├── skills/ # 按需加载的技能
|
||
├── docs/ # 权威静态文档
|
||
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
|
||
└── scripts/
|
||
└── playbook.py # 统一入口
|
||
```
|
||
|
||
部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
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` 统一入口部署，通过配置节控制同步内容：
|
||
|
||
```toml
|
||
# 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`）
|
||
|
||
### 部署后的目录结构
|
||
|
||
```text
|
||
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
|