AGE App Template：贯穿 AI 开发全流程使用图

这张图把“什么时候写什么文档、在哪里设置什么机制、由什么触发、如何进入代码实现、如何回写长期记忆”串成一条闭环。核心原则：文档不是额外负担，而是 AI 的长期上下文、约束入口和合并依据。

输入与澄清需求/设计/架构收敛计划与审查实现与验证合并门禁/长期记忆

0. 初始化阶段：模板复制后必须先设置的“项目吸引子”

目标：先让 AI 知道项目事实、自治边界、代码地图和真实验证命令

① 基础上下文

这些文件决定 AI 每次进仓库后先相信什么、先读什么、不能越过什么边界。

AGENTS.md
START-HERE-after-copy.md
docs/context/project-context.md
docs/context/ai-autonomy-policy.md
docs/context/codebase-map.md
docs/backlog/README.md

② 验证基线

不能只写“请测试一下”。必须写真实可执行命令，否则 AI 很容易自我验证。

known-good-baselines.md
docs/testing/README.md
scripts/run-known-good-baseline.sh（建议补充）
package.json / pom.xml / Makefile / CI workflow

③ 合并门禁

如果没有门禁，模板会退化成“大家自觉维护 MD”。建议从低成本规则开始。

PR 模板 docs 必填检查验证命令检查 Owner Doc 变更提示复杂改动必须有 plan

1. 主流程：从需求输入到代码合并，再到长期记忆沉淀

建议规则：一个需求 = 一个分支 = 代码 + 文档 + 验证 + 日志同 PR 合并

需求输入

业务方、会议、聊天、截图、临时想法，先保留原始信息。

更新文档

docs/input/xxx-raw.md

触发机制

新需求进入
业务口头信息转文字
AI 先做摘要，不直接实现

澄清讨论

不确定、不一致、有分歧的内容，先不要污染正式需求。

更新文档

docs/discussions/xxx.md

触发机制

发现歧义
需求与现有设计冲突
AI 生成问题清单

需求收敛

把可实现的目标、边界、验收标准沉淀成 AI 可执行需求。

更新文档

docs/requirements/REQ-xxx.md

门禁机制

必须有验收标准
必须说明不做什么
必须标明影响范围

设计/架构判断

不是所有需求都要改架构；只有边界变化时才更新 Owner Doc。

按需更新

docs/design/xxx.md

docs/architecture/xxx.md

触发机制

API / DB / 权限变化
跨模块依赖变化
状态机/业务流程变化

制定计划

复杂需求先写 plan，不能让 AI 直接“凭感觉改代码”。

更新文档

docs/plans/PLAN-xxx.md

触发机制

跨 3 个以上文件
涉及数据/权限/接口
需要迁移或兼容

实现与验证

AI 根据 active requirement + active owner doc + plan 修改代码并运行验证。

更新内容

src/...

tests/...

docs/testing/xxx.md

触发机制

plan audit 通过
执行真实测试命令
失败则回写问题

关闭审查与沉淀

代码不是终点，必须把实际变化、经验、基线写回长期记忆。

更新文档

docs/logs/xxx.md

docs/bugs/xxx.md（如有）

known-good-baselines.md

门禁机制

closure audit
PR 模板勾选
CI / Reviewer 合并

2. AI 每次开始开发前的读取顺序

避免 AI 只读当前聊天，必须让它从仓库恢复上下文

AI Session 启动读取链路

第一层	AGENTS.md：项目级规则、禁止事项、默认流程、验证要求。
第二层	docs/context/project-context.md：业务背景、产品目标、稳定术语。
第三层	docs/context/ai-autonomy-policy.md：AI 可以自主做什么，哪些必须先问人。
第四层	docs/context/codebase-map.md：代码结构、模块边界、常见入口。
第五层	active requirement + active owner doc + active plan：本次任务的直接依据。

复杂度分流规则

极小改动	文案、局部样式、明显 bug，小于 1~2 个文件，可直接处理，但仍要记录验证。
中等改动	涉及多个文件、接口或业务分支，必须先写 docs/plans/。
高风险改动	数据库、权限、支付、调度、核心状态机，必须更新 owner doc，并经过人工/AI plan audit。
修 bug	必须补 docs/bugs/，并说明对应测试覆盖，避免同类问题复发。
架构变化	必须更新 docs/architecture/ 与 codebase-map，否则下一轮 AI 会读到旧世界。

3. 应该设置的机制：从“自觉维护”升级到“工程约束”

先做低成本自动化，再逐步升级为文档-代码联动

机制 A：文档必填检查

触发：PR 打开 / 更新

检查：需求文档是否存在、验收标准是否为空、验证命令是否填写。

工具：PR 模板 + docs lint + 简单脚本。

机制 B：复杂改动必须有 Plan

触发：变更文件数量 / 关键目录变化

检查：涉及 src、db、api、auth、workflow 等关键目录时，必须有 docs/plans。

目标：防止 AI 直接大范围改代码。

机制 C：Owner Doc 变更提示

触发：接口/模型/数据库/权限变化

检查：是否同步更新 docs/design 或 docs/architecture。

目标：防止代码变了，长期文档还是旧的。

机制 D：验证基线执行

触发：PR / main 合并前

检查：known-good-baselines.md 中的命令是否能跑通。

目标：防止“AI 说已验证”但实际没验证。

机制 E：Closure Audit

触发：AI 声称完成 / PR ready

检查：代码、文档、测试、日志、bug 记录是否闭环。

目标：防止 demo 化完成。

机制 F：Codebase Map 更新

触发：目录结构/模块入口变化

检查：docs/context/codebase-map.md 是否反映最新模块边界。

目标：让下一轮 AI 快速定位代码。

机制 G：Bug Lesson 固化

触发：bugfix PR

检查：是否有 docs/bugs 记录，是否补测试覆盖。

目标：把错误变成下次 AI 的约束。

机制 H：Session Log

触发：每次重要 AI 任务结束

检查：docs/logs 记录本次做了什么、没做什么、验证结果。

目标：支持多 session 接力。

4. 文档更新矩阵：什么变化应该更新哪份文档

可直接作为团队 PR Review 清单

触发事件	必须更新	建议更新	检查机制	风险
新需求进入	必须 docs/input/	docs/discussions/	需求入口记录	原始上下文丢失，后续只能靠口头解释
需求已明确	必须 docs/requirements/	docs/backlog/README.md	验收标准检查	AI 不知道完成标准，容易过度发挥
业务流程变化	必须 docs/design/	docs/requirements/ 反链	Owner Doc 检查	业务规则散落在代码里
API / DB / 权限 / 模块边界变化	必须 docs/architecture/	docs/context/codebase-map.md	关键目录变更检查	下一轮 AI 读取旧架构，越改越偏
复杂实现开始前	必须 docs/plans/	plan audit 记录	复杂度门禁	AI 大范围改动不可控
代码实现完成	必须 docs/logs/	docs/testing/	Closure audit	多 session 无法接力，不知道实际做了什么
发现或修复 bug	必须 docs/bugs/	known-good-baselines.md	bugfix PR 检查	同类错误反复出现
验证命令变化	必须 known-good-baselines.md	docs/testing/README.md	CI 执行基线	AI 引用过期测试命令，产生假验证