# 项目治理与演进规则

> 本文定义 **{{project_name}}** 的文档维护与质量演进机制。
> 目标是：长期迭代中保持轻量、信息可追溯、质量持续提升。

---

## 1. 四层生命周期

```
会话周期（每次） → 模块周期（每功能） → 里程碑周期（每版本） → 演进周期（每季度）
```

| 周期 | 触发条件 | 动作 | 耗时 |
|------|----------|------|------|
| **会话** | 每次 AI 对话开始/结束 | 读/写 STATUS.md | 2 分钟 |
| **模块** | STATUS「当前焦点」完成 | 收尾清理 + DECISIONS/PITFALLS 更新 | 5 分钟 |
| **里程碑** | ROADMAP 里程碑标记完成 | 文档健康检查 | 15 分钟 |
| **演进** | 季度 review 或痛点触发 | 结构优化 + 废弃清理 | 30 分钟 |

---

## 2. 会话周期

### 开始
1. 读 `docs/STATUS.md`「当前焦点」
2. 确认任务在 ROADMAP 当前里程碑内

### 结束
1. 更新 STATUS：最近完成 / 缺口 / 下一焦点
2. 重要取舍 → DECISIONS.md 新 ADR
3. 踩坑 → PITFALLS.md 新条目

---

## 3. 模块周期（收尾清理）

功能模块完成时：
- [ ] 无 `console.log` / `dbg!()` / 注释掉的旧实现
- [ ] STATUS 已更新
- [ ] 有新的工程约定 → 更新 quick-ref.md 或 DEVELOPMENT-STANDARDS.md
- [ ] 有新的踩坑 → PITFALLS.md
- [ ] 关键路径测试通过

---

## 4. 里程碑周期（文档健康检查）

ROADMAP 里程碑完成时，执行一轮文档体检：

### 4.1 死引用检查

查找指向已删除文件的链接，修复或删除所有断链。

### 4.2 膨胀检查

任何 `.md` 超过 **500 行** → 评估是否应拆分：
- ≤ 300 行：理想，AI 一次读完
- 301–500 行：可接受，按章节跳读
- > 500 行：产生拆分讨论

### 4.3 过时内容清理

- 标记的「已废弃」ADR 超过 3 个月可归档到 `docs/archive/`
- 不再适用的踩坑条目标记「已过时」

---

## 5. 演进周期（季度 review）

每季度或遇到以下信号时触发：

| 信号 | 动作 |
|------|------|
| 文档间出现明显矛盾 | 检查 DECISIONS 是否与 PRD 冲突 |
| 同类问题反复出现在 PITFALLS | 评估是否需要架构修正（写 ADR） |
| 新成员入职后 AI 协作混乱 | 检查 AGENTS.md 是否足够清晰 |
| 文档目录层级 > 3 层 | 评估是否过度设计，考虑扁平化 |

### 演进动作

1. **删除过时文件**（归档到 `archive/` 或直接删除）
2. **合并重复内容**（两处说同一件事 → 保留一处 + 交叉引用）
3. **升级版本号**（DEVELOPMENT-STANDARDS 大改时升级 `v2.0`）
4. **更新 QUICKREF**（确保 30 秒入口始终准确）

---

## 6. 文档质量原则

| 原则 | 说明 |
|------|------|
| **读比写重要** | 为下一个读的人优化（可能是 3 个月后的你或新 AI） |
| **单点真相** | 同一事实只出现在一个地方；其他地方用链接引用 |
| **表格优先** | 对比、规范、清单用表格；长段落只用于说明「为什么」 |
| **可控长度** | 每个文档有明确的边界——不让 AGENTS 膨胀成 README |
| **自动生成优于手动维护** | 能从代码/配置生成的不要手写（如 API 文档、变更日志） |

---

## 7. 文档模板（新项目初始化清单）

项目启动时，按以下顺序建立文档：

```
✅ 1. AGENTS.md           — AI 协作者入口（本文档体系中的「根」）
✅ 2. QUICKREF.md         — 30 秒速查
✅ 3. docs/BRAND.md       — 品牌规范（项目名、定位、命名规则）
✅ 4. docs/PRD.md         — 产品需求（做什么、不做什么、AC 验收）
✅ 5. docs/STATUS.md      — 当前进度（每个会话后更新）
✅ 6. docs/ROADMAP.md     — 里程碑与阶段
✅ 7. docs/ARCHITECTURE.md— 技术架构与分层
✅ 8. docs/LOCAL-SETUP.md — 本地开发环境搭建
✅ 9. docs/quick-ref.md   — 编码速查（具体语法/模式）
⬜ 10. docs/DECISIONS.md  — 第一个技术决策产生时创建
⬜ 11. docs/PITFALLS.md   — 第一个坑踩到时创建
```

> 前 9 份文档建议在**第一次 AI 会话**中就建好骨架。10、11 按需添加。