# 模板同步边界定义

> 定义哪些文件属于"框架层"（跨项目复用），哪些属于"项目层"（项目特有）。
> 框架层变化通过 `sync-template.sh` 从 main 同步到 ai_project 模板分支。

---

## 规则

```
框架层 = 可以复用的结构和逻辑（同步）
项目层 = 某个具体项目的内容和数据（不同步）
```

---

## 文件分类

### 框架层（自动同步）

| 文件/目录 | 说明 |
|-----------|------|
| `AGENTS.md` | AI 角色定义 + 权限矩阵 + 工作流 + 命名规范 |
| `dashboard.md` | 控制面板结构（人类+Arch AI 入口） |
| `DECISIONS.md` | 决策入口结构 |
| `.ai/principles.md` | 架构设计原则 + Arch AI 上下文管理 |
| `.ai/config/*.json` | AI 配置（权限路径、职责定义、工作流） |
| `.ai/prompts/` | 提示词模板（架构、编码、测试） |
| `.ai/roles/README.md` | 角色工作台说明 |
| `.ai/roles/{arch,dev,qa}/card.md` | 角色身份卡（身份、权限、启动流程） |
| `.ai/phases/INDEX.md` | 阶段索引 + 切换规则 |
| `.ai/knowledge/patterns.md` | 可复用模式 |
| `.ai/knowledge/lessons.md` | 框架级经验教训 |
| `.ai/tasks/templates/` | Task 模板（Coder + Tester） |
| `.trae/skills/` | Skill 定义 |
| `docs/使用手册.md` | 使用手册（框架层） |
| `ENVIRONMENT.md` | 开发环境结构（框架层） |
| `sync-template.sh` | 同步脚本本身 |
| `TEMPLATE.yaml` | 模板变量配置 |
| `init.sh` | 新项目初始化脚本 |
| `SYNC.md` | 本文档 |

### 项目层（不同步）

| 文件/目录 | 说明 |
|-----------|------|
| `.ai/tasks/active/` | 活跃 task 文件（项目特定） |
| `.ai/tasks/completed/` | 已完成 task（项目特定） |
| `.ai/phases/phase-*/goal.md` | 阶段目标（项目特定） |
| `.ai/phases/phase-*/scope.md` | 阶段范围（项目特定） |
| `.ai/phases/phase-*/architecture.md` | 架构快照（项目特定） |
| `.ai/phases/phase-*/decisions.md` | 阶段决策（项目特定） |
| `.ai/phases/phase-*/completion.md` | 完成状态（项目特定） |
| `.ai/knowledge/decisions.md` | ADR 全文（项目特定） |
| `.ai/knowledge/journal/` | 每日日志（项目特定） |
| `.ai/archive/` | 归档文件 |
| `docs/01_*/ ~ docs/06_*/` | 项目文档（PRD、架构、数据模型等） |
| `docs/share/` | 对外分享内容 |
| `projects/` | 项目代码 |
| `reports/` | 测试报告 |
| `review/` | 旧 review 流程（已废弃，由 .ai/tasks/ 替代） |

---

## 使用流程

```bash
# 1. 切换到模板分支
git checkout ai_project

# 2. 运行同步脚本
bash sync-template.sh main ai_project

# 3. 检查变更 + 提交
git diff --stat
git add -A && git commit -m "sync: 框架更新 from main"
```

## 原则

1. **脚本覆盖框架层** — 直接 checkout 无需人工判断
2. **项目层隔离** — 任务、日志、代码、决策不受影响
3. **新架构适配** — dashboard.md / DECISIONS.md / .ai/tasks/ 已纳入框架层定义