# 项目架构模板

本目录包含项目架构与工作流入口模板，以及按需采用的语言配置模板。正式工程主链采用
Matt Pocock workflow 与 ticket-native 主循环。

## 与 Playbook 其他部分的关系

```text
playbook/
├── rulesets/        # 语言级规则模板 -> 通过 sync_standards 部署到 .agents/
├── skills/          # 按需安装的工作流与知识技能
├── docs/            # 权威静态文档
├── templates/       # 本目录：项目架构与工作流入口模板
└── scripts/
    └── playbook.py  # 统一部署入口
```

`templates/` 负责生成或更新 `AGENTS.md`、`AGENT_RULES.md` 和 `memory-bank/` 等项目
入口与知识文件；`memory-bank/` 不承载新流程机器状态。完整部署方式见
[主 README 的“在其他项目中使用本 Playbook”章节](../README.md#在其他项目中使用本-playbook)。

## 目录

```text
templates/
├── AGENTS.template.md           # 项目主入口与导航模板
├── AGENT_RULES.template.md      # Matt Pocock ticket-native 执行规则模板
├── memory-bank/                 # 稳定项目知识模板（3 个），不是机器状态源
├── cpp/                         # C++ 工具链模板
└── python/                      # Python 工具链模板
```

完整主链只在 `AGENT_RULES.template.md` 定义。

## 模板分类

从部署和维护职责看，本目录中的模板分为三类。

### 1. 入口导航

- `AGENTS.md`、`CLAUDE.md` 通过 Playbook 标记区块维护
- 更新标记区块时保留区块外的项目内容
- 已有的人工入口和项目补充说明继续由项目维护

### 2. 初始化后由项目维护

- `AGENT_RULES.md`：项目采用的完整工程流程与执行规则
- `AGENT_RULES.local.md`：项目私有规则，Playbook 不覆盖
- `memory-bank/`：稳定项目定位、技术上下文和当前系统模式，不承载机器状态

Playbook 只处理框架提供的同名文件。项目新增的 `memory-bank/*` 不会被删除。

### 3. 参考模板

这些模板保留在快照中，按项目需要手动采用：

- `cpp/`：C++、CMake 和 Conan 工具链模板
- `python/`：Python 工具链配置模板

## 模板说明

### memory-bank/

`memory-bank/` 保存 grilling、设计和实现都需要的稳定项目知识。它不记录 owner、
heartbeat、ticket 或集成状态；机器状态只以 `.scratch/` 和 `main_loop.py` 为准。

| 文件                          | 用途                                           |
| ----------------------------- | ---------------------------------------------- |
| `project-brief.template.md`   | 项目定位、边界、约束和成功定义                 |
| `tech-context.template.md`    | 技术栈、仓库入口、工具链、平台差异和验证命令   |
| `system-patterns.template.md` | 稳定模块边界、数据流、不变量、扩展路径和禁止项 |

### AGENT_RULES.template.md

部署为项目的 `AGENT_RULES.md`，是 Matt Pocock 工程主链、ticket 调度、worktree、
验证和集成协议的唯一流程权威。项目私有规则写入 `AGENT_RULES.local.md`；该文件由
项目维护，Playbook 不覆盖。

### AGENTS.template.md

部署为项目的 `AGENTS.md`，只提供语言规则、核心规则和工程上下文导航。
标记区块的更新约束见下文“AGENTS 模板标记”。

## 部署

```toml
[sync_rules]

[sync_memory_bank]
project_name = "MyProject"

[sync_standards]
langs = ["python"]

[install_skills]
mode = "all"
```

部署后首次使用正式流程时运行 `setup-matt-pocock-skills`，并为本地主循环选择
local markdown tracker。

## 正式开发流程

```text
setup-matt-pocock-skills
  -> grill-with-docs
  -> to-spec
  -> to-tickets
  -> main_loop.py enqueue
  -> main_loop.py claim
  -> 本地 ticket 执行协议（tdd）
  -> commit
  -> code-review
  -> main_loop.py finish
  -> main_loop.py integrate
```

产物和职责：

- `.scratch/<feature>/spec.md`：feature spec
- `.scratch/<feature>/issues/*.md`：ticket DAG 与执行状态
- `.scratch/queue.md`：feature 开发和集成顺序
- `CONTEXT.md`：稳定领域词汇
- `docs/adr/`：长期架构决策
- `docs/agents/*.md`：tracker 与领域文档配置

明确串行时可用 in-place，不创建 worktree；计划多个 session 并发时，第一个 claim
就指定 worktree。并发 sessions 必须共享同一文件系统与 Git common directory；
`main_loop.py` 不支持跨机器、独立 clone 或远程 tracker adapter。Matt skills 可单独
使用远程 issue tracker，但不能把远程状态接入本主循环。完整隔离、恢复和证据协议见
`AGENT_RULES.template.md`。

## AGENTS 模板标记

- `<!-- playbook:framework:start/end -->`：完整框架区块
- `<!-- playbook:agents:start/end -->`：语言规则入口
- `<!-- playbook:templates:start/end -->`：项目流程入口

`playbook:agents` 必须嵌在 `playbook:framework` 内。框架区块替换时，
`preserve_agents_subblock()` 依赖该嵌套保留项目按 `langs` 生成的语言入口。

## 占位符

模板同时包含部署工具自动替换的占位符和需要项目手工填写的内容：

| 占位符                    | 说明                   | 自动替换                     |
| ------------------------- | ---------------------- | ---------------------------- |
| `{{DATE}}`                | 同步日期               | 是                           |
| `{{PROJECT_NAME}}`        | 可选项目名             | 配置 `project_name` 时替换   |
| `{{PLAYBOOK_ROOT}}`       | 项目内 Playbook 根目录 | 是                           |
| `{{PLAYBOOK_SCRIPTS}}`    | 项目内脚本目录         | 是                           |
| `{{PROJECT_GOAL}}`        | 项目目标               | 否，项目手工填写             |
| `{{PROJECT_DESCRIPTION}}` | 项目描述               | 否，项目手工填写             |
| 其他 `{{...}}`            | 模板中的项目特定内容   | 否，项目手工填写或删除所在行 |

`{{PROJECT_NAME}}` 由 `[sync_memory_bank].project_name` 提供；未配置时保持原样。
其他人工占位符不会由 `playbook.py` 推导。

## `playbook.py` 部署后结构

```text
project/
├── AGENTS.md                    # 任一 sync_* 节启用时创建或按区块更新
├── AGENT_RULES.md               # [sync_rules]
├── AGENT_RULES.local.md         # 首次成功写入规则时创建，后续由项目维护
├── CLAUDE.md                    # 默认位置；也可使用 .claude/CLAUDE.md
├── .agents/                     # [sync_standards]
├── .gitattributes               # [sync_standards] 按配置同步
└── memory-bank/                 # [sync_memory_bank] 部署三个稳定知识文件
```

`[install_skills]` 安装到 `agents_home/skills/`，通常不在项目目录内。`mode = "list"`
要求用户逐项列出 skills 及其依赖；`mode = "all"` 安装全部 skills。

## 正式流程运行后按需产生的结构

```text
project/
├── CONTEXT.md                     # setup 后按需创建的稳定领域词汇
├── .scratch/
│   ├── queue.md                   # main_loop.py 维护的 feature 顺序
│   └── <feature>/
│       ├── spec.md                # to-spec 产物
│       └── issues/                # to-tickets 产物与机器状态
└── docs/
    ├── agents/                    # setup 生成的 tracker/domain 配置
    └── adr/                       # grilling 过程中按需沉淀的长期决策
```

---

**最后更新**：2026-08-07