# 项目架构模板

本目录包含项目架构与工作流入口模板，以及按需采用的语言配置模板。正式工程主链采用
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      # 任务入口与按需 skill 路由模板
├── gitignore.template           # .scratch 持久状态与本机运行时忽略规则
├── memory-bank/                 # 稳定项目知识模板（3 个），不是机器状态源
├── cpp/                         # C++ 工具链模板
└── python/                      # Python 工具链模板
```

`AGENT_RULES.template.md` 只定义常驻边界和 Skill 入口；任务路由、完整主链与本地 Markdown
ticket 协议只在第一方 `skills/cook-it-through/` 定义，并在工程任务中按需加载。

## 模板分类

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

### 1. 入口导航

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

### 2. 流程由 Playbook 维护，补充由项目维护

- `AGENT_RULES.md`：`<!-- playbook:rules:start/end -->` 区块内的工程流程由 Playbook
  维护，重新同步时刷新；项目自己的补充写在区块外，同步不会动它
- `AGENT_RULES.local.md`：项目私有规则，Playbook 不覆盖
- `.gitignore`：Playbook 维护专属标记区块，仅忽略 `.scratch` 下的本机运行时产物
- `memory-bank/`：稳定项目定位、技术上下文和当前系统模式，不承载机器状态

Playbook 只处理框架提供的同名文件。项目新增的 `memory-bank/*` 不会被删除。
没有标记区块的旧 `AGENT_RULES.md` 保持原样，不会被静默改写。

### 3. 参考模板

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

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

## 模板说明

### memory-bank/

`memory-bank/` 保存 grilling、设计和实现都需要的稳定项目知识。它不记录 owner、
heartbeat、ticket 或集成状态；`.scratch/` 是唯一机器状态源，状态格式、转换语义和执行入口
由第一方 `cook-it-through` Skill 权威定义。

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

### AGENT_RULES.template.md

部署为项目的 `AGENT_RULES.md`，只常驻指令优先级、项目边界和 Skill 加载入口。
`<!-- playbook:rules:start/end -->` 区块内的
内容由 Playbook 维护并在重新同步时刷新，项目补充写在区块外。项目私有规则写入
`AGENT_RULES.local.md`；该文件由项目维护，Playbook 不覆盖。

完整工程流程由 `cook-it-through` skill 按需定义；rules 只保留加载触发条件，不复制其协议。

### AGENTS.template.md

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

## 部署

```toml
[sync_rules]

[sync_memory_bank]
project_name = "MyProject"

[sync_standards]
langs = ["python"]

[install_skills]
mode = "all"
```

本示例启用了 `[sync_rules]`，因此安装集合必须包含 `cook-it-through`：
`[install_skills].mode = "list"` 时显式列出，`mode = "all"` 时不得通过 `exclude` 排除。
只有不部署官方 `AGENT_RULES.md` 且不使用正式工程主链的安装场景，才可以排除该 skill。
同一配置违反该约束时，部署器会在写入任何同步文件前拒绝执行。
部署后首次使用正式流程时运行 `setup-matt-pocock-skills`，并为本地主循环选择 local Markdown
tracker；工程工作流与主循环协议只查该 skill。

## 正式开发流程

新 feature 或设计变更走这条链；任务分级和是否升级到主链的判据只查 `cook-it-through`。

```text
setup-matt-pocock-skills
  -> grill-with-docs
  -> to-spec
  -> 按 cook-it-through 的本地 ticket 生命周期继续
```

从 `to-tickets` 到 final workflow state 的格式、命令、产物职责、隔离、恢复、证据和集成顺序
只查 `cook-it-through`；本 README 不维护第二份流程定义。

## AGENTS 模板标记

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

`playbook:agents` 必须嵌在 `playbook:framework` 内。框架区块替换时，
该嵌套关系用于保留项目按 `langs` 生成的语言入口。

## 占位符

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

| 占位符                    | 说明                   | 自动替换                     |
| ------------------------- | ---------------------- | ---------------------------- |
| `{{DATE}}`                | 同步日期               | 是                           |
| `{{PROJECT_NAME}}`        | 可选项目名             | 配置 `project_name` 时替换   |
| `{{PLAYBOOK_ROOT}}`       | 项目内 Playbook 根目录 | 是                           |
| `{{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         # 首次成功写入规则时创建，后续由项目维护
├── .gitignore                   # [sync_rules] 更新 Playbook .scratch 标记区块
├── 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。两种模式都可用
`exclude = ["skill-name"]` 从本次安装集合排除同名 skill；该选项不会卸载已有目录。
同时启用 `[sync_rules]` 时，必须遵守上文对 `cook-it-through` 的保留约束。
`cook-it-through` 会随 skill 一起安装并包含其内部执行引擎，不依赖 snapshot 根目录下的脚本路径。

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

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