playbook/templates/README.md

# 项目架构模板

本目录包含项目架构的模板文件，用于快速初始化新项目的 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
│   │   └── review.template.md
│   └── meta/
│       └── prompt-generator.template.md
├── ci/                          # CI 模板
│   └── gitea/
│       └── .gitea/workflows/
├── cpp/                         # C++ 配置模板
│   ├── .clang-format
│   ├── .clangd
│   └── ...
└── python/                      # Python 配置模板
    ├── .editorconfig
    ├── pyproject.toml
    └── ...
```

## 文件分类

从部署角度，文件分为四类：

| 类型 | 说明 | 部署行为 |
|------|------|----------|
| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 |
| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 |
| **项目私有** | 项目手动创建 | 不部署 |
| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 |

### 框架模板（A类）

```
AGENT_RULES.md
AGENTS.md（区块更新）
docs/prompts/system/*.md     # 框架提供
docs/prompts/coding/*.md     # 框架提供
docs/prompts/meta/*.md       # 框架提供
```

### 项目上下文（B类）

```
memory-bank/
├── project-brief.md
├── tech-stack.md
├── architecture.md
├── progress.md
└── decisions.md
```

> ⚠️ B类文件首次创建后应由项目填写。`force=true` 会覆盖已填写内容（自动备份）。

### 项目私有（C类，不部署）

```
AGENT_RULES.local.md         # 项目私有规则
docs/plans/                  # 项目实施计划
docs/prompts/custom/         # 项目自定义提示词
docs/prompts/**/*            # 项目新增的文件不会被删除
```

### 参考资料（D类，不部署到项目根）

```
# 留在 docs/standards/playbook/templates/ 中参考
ci/                      # CI 配置
cpp/                     # C++ 配置
python/                  # Python 配置
```

## 快速部署

使用统一入口 `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 时覆盖框架文件（会先备份）
- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
- **占位符替换**：自动替换 `{{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
    │   └── review.md
    └── meta/prompt-generator.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/

工作流程模板（部署后去掉 `.template` 后缀）：

| 文件                                | 用途           | 使用场景               |
| ----------------------------------- | -------------- | ---------------------- |
| `system/agent-behavior.template.md` | 工作模式参考   | 切换探索/开发/调试模式 |
| `coding/clarify.template.md`        | 需求澄清模板   | 需求不明确时           |
| `coding/review.template.md`         | 复盘总结模板   | Plan 完成后复盘        |
| `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词     |

### AGENT_RULES.template.md

执行流程规范，定义 AI 的工作循环和约束。
如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
且不会被 `playbook.py` 覆盖。
主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单，
自动选择第一个 pending 的 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