265 lines
9.5 KiB
Markdown
265 lines
9.5 KiB
Markdown
# 项目架构模板
|
||
|
||
本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
templates/
|
||
├── README.md # 本文件
|
||
├── AGENTS.template.md # 路由中心模板
|
||
├── AGENT_RULES.template.md # 执行流程模板
|
||
├── memory-bank/ # 项目上下文模板
|
||
│ ├── project-brief.template.md
|
||
│ ├── tech-stack.template.md
|
||
│ ├── architecture.template.md
|
||
│ ├── progress.template.md
|
||
│ └── decisions.template.md
|
||
├── prompts/ # 提示词库模板
|
||
│ ├── README.md
|
||
│ ├── system/
|
||
│ │ └── agent-behavior.template.md
|
||
│ └── coding/
|
||
│ ├── clarify.template.md
|
||
│ └── verify.template.md
|
||
├── ci/ # CI 模板
|
||
│ └── gitea/
|
||
│ └── .gitea/workflows/
|
||
├── cpp/ # C++ 配置模板
|
||
│ ├── .clang-format
|
||
│ ├── .clangd
|
||
│ └── ...
|
||
└── python/ # Python 配置模板
|
||
├── .editorconfig
|
||
├── pyproject.toml
|
||
└── ...
|
||
```
|
||
|
||
## 快速部署
|
||
|
||
使用统一入口 `playbook.py`，配置节存在即启用：
|
||
|
||
```toml
|
||
# 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 # 可选，强制覆盖（会先备份）
|
||
```
|
||
|
||
```bash
|
||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||
```
|
||
|
||
参数说明见 `playbook.toml.example`（仓库根目录）或 vendoring 后的 `docs/standards/playbook/playbook.toml.example`。
|
||
|
||
### 配置节说明
|
||
|
||
| 配置节 | 部署内容 | 选项 |
|
||
| -------------------- | -------------- | ----------------------- |
|
||
| `[sync_rules]` | AGENT_RULES.md | `force` |
|
||
| `[sync_memory_bank]` | memory-bank/ | `project_name`, `force` |
|
||
| `[sync_prompts]` | docs/prompts/ | `force` |
|
||
|
||
- **配置节存在即启用**：只写需要同步的配置节
|
||
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
|
||
- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（memory-bank/ 和 prompts/ 会先备份）
|
||
- **占位符替换**：自动替换 `{{DATE}}`、`{{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
|
||
```
|
||
|
||
### 部署后的目录结构
|
||
|
||
```text
|
||
project/
|
||
├── AGENTS.md # 路由中心（主入口）
|
||
├── AGENT_RULES.md # 执行流程
|
||
├── AGENT_RULES.local.md # 项目私有规则（可选，手动维护）
|
||
├── memory-bank/ # 项目上下文
|
||
│ ├── project-brief.md
|
||
│ ├── tech-stack.md
|
||
│ ├── architecture.md
|
||
│ ├── progress.md
|
||
│ └── decisions.md
|
||
└── docs/prompts/ # 提示词库
|
||
├── README.md
|
||
├── system/agent-behavior.md
|
||
└── coding/
|
||
├── clarify.md
|
||
└── verify.md
|
||
```
|
||
|
||
## 占位符说明
|
||
|
||
模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
|
||
|
||
| 占位符 | 说明 | 自动替换 |
|
||
| ------------------------- | ------------ | -------- |
|
||
| `{{DATE}}` | 日期 | ✅ 是 |
|
||
| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 |
|
||
| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 |
|
||
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 |
|
||
| `{{MAIN_LANGUAGE}}` | 主语言 | ✅ 可选 |
|
||
| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 |
|
||
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
|
||
|
||
`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样。
|
||
`{{MAIN_LANGUAGE}}` 可通过 `sync_standards.langs[0]` 自动替换；未配置时默认 `tsl`。
|
||
`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）。
|
||
|
||
## 模板说明
|
||
|
||
### memory-bank/
|
||
|
||
项目上下文文档，用于让 AI 快速理解项目：
|
||
|
||
| 文件 | 用途 |
|
||
| --------------------------- | -------------------- |
|
||
| `project-brief.template.md` | 项目定位、边界、约束 |
|
||
| `tech-stack.template.md` | 技术栈、工具链、环境 |
|
||
| `architecture.template.md` | 架构设计、模块职责 |
|
||
| `progress.template.md` | 开发进度追踪 |
|
||
| `decisions.template.md` | 架构决策记录（ADR） |
|
||
|
||
### prompts/
|
||
|
||
工作流程模板：
|
||
|
||
| 文件 | 用途 |
|
||
| ----------------------------------- | ------------ |
|
||
| `system/agent-behavior.template.md` | AI 行为规范 |
|
||
| `coding/clarify.template.md` | 需求澄清模板 |
|
||
| `coding/verify.template.md` | 验证检查清单 |
|
||
|
||
### AGENT_RULES.template.md
|
||
|
||
执行流程规范，定义 AI 的工作循环和约束。
|
||
如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
|
||
且不会被 `playbook.py` 覆盖。
|
||
主循环会根据 `memory-bank/progress.md` 的 Plan 状态与 `docs/plans/` 文件名日期，
|
||
自动选择最新未完成的 Plan，并要求通过 `scripts/plan_progress.py` 写入进度。
|
||
|
||
### 示例：不跑测试的计划提示词
|
||
|
||
当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：
|
||
|
||
```text
|
||
你是 Codex。先使用 $brainstorming。
|
||
目标：修改 <模块/功能>，细节如下：<你的需求>
|
||
约束：
|
||
- 不跑任何测试（test/ci），但允许做可通过的局部验证（格式化/静态检查/人工 diff）。
|
||
- Plan 不能包含任何必然失败或未确认的任务；所有依赖必须在 brainstorming 阶段确认清楚。
|
||
- 采用 writing-plans 的固定头部格式，且在 `---` 之后追加 `## Plan Meta`：
|
||
- Plan Group: <X>
|
||
- Parent Plan: <docs/plans/...-design.md>
|
||
- Verification Scope: local
|
||
- Verification Gate: must-pass
|
||
|
||
流程：
|
||
1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`。
|
||
2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。
|
||
3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。
|
||
4) 执行计划并更新 `memory-bank/progress.md`。
|
||
```
|
||
|
||
### 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/` 目录，需手动从快照复制到项目根目录使用。
|
||
|
||
**使用方式**：
|
||
|
||
```toml
|
||
# playbook.toml - 生成包含这些模板的快照
|
||
[playbook]
|
||
project_root = "/path/to/project"
|
||
|
||
[vendor]
|
||
langs = ["tsl", "cpp", "python"]
|
||
```
|
||
|
||
```bash
|
||
python scripts/playbook.py -config playbook.toml
|
||
# 然后手动从 docs/standards/playbook/templates/ 复制所需配置到项目根目录
|
||
```
|
||
|
||
## 与 playbook 其他部分的关系
|
||
|
||
```text
|
||
playbook/
|
||
├── rulesets/ # 语言级硬规则 → 部署到 .agents/
|
||
├── codex/skills/ # 按需加载的技能
|
||
├── docs/ # 权威静态文档
|
||
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
|
||
└── scripts/
|
||
├── playbook.py # 统一入口：vendor/sync_rules/sync_memory_bank/sync_prompts/sync_standards/...
|
||
└── plan_progress.py # Plan 选择与进度记录
|
||
```
|
||
|
||
## 完整部署流程
|
||
|
||
```bash
|
||
# 1. 准备配置并执行统一入口
|
||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||
|
||
# 2. 编辑 memory-bank/*.md 填写项目信息
|
||
|
||
# 3. 替换剩余的 {{PLACEHOLDER}} 占位符
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新**：2026-01-26
|