【AI编程】使用笔记：AI编程项目文档体系与框架
____tz_zs （2026-08-06）
最核心的原则是：
工作要求写成规则，当前系统写成现状与契约，方案取舍写成决策记录，历史背景和经验写成上下文，临时进度写成任务状态。
这五类信息的用途、有效期和权威性不同，不应全部堆进一个"项目记忆"文件。
1. AI 工作规则
回答"AI 应该怎样工作"，内容应短、明确、可执行。
例如：
- 修改前先读取目标模块的 readme。
- 不从单个数据样例推导当前数据库 Schema。
- 修改 API、配置或状态机时，同步检查技术契约文档。
- 不擅自回退已经接受的设计决策。
通用工作规则通常在仓库级维护一次，不需要每个模块复制一份。
2. 当前系统现状与技术契约
回答"系统现在是什么、怎样运行"。
包括：
- 模块职责、边界和依赖方向。
- 主流程、数据流和失败恢复方式。
- API、配置、数据库 Schema 和状态机。
- 当前技术栈、运行环境和兼容性要求。
- 关键代码入口和验证方式。
这是描述当前行为的主体文档。设计决策记录解释"为什么这样设计"，不能替代当前架构和技术契约。
3. 设计决策记录
回答"为什么选择这个方案"。可以使用 ADR（Architecture Decision Record）格式。
每条决策只保留可复核摘要：
- 当时要解决的问题和约束。
- 最终选择。
- 真正评估过的备选方案。
- 收益、代价和后续影响。
- 是否替代了旧决策。
不要保存完整聊天记录、内部推理过程或与最终决策无关的讨论。
设计决策不只包括架构，还可以包括数据口径、兼容方案、失败策略和迁移方式。
4. 项目背景与经验
回答"有哪些信息无法只从当前代码中看出来"。
包括：
- 项目的真实用途和业务背景。
- 外部系统、组织约束和历史原因。
- 会稳定影响实现方式的偏好与约定。
- 已知技术债务、重要故障经验和风险。
这里保存的是辅助理解的信息，不应复制完整架构、Schema 或 ADR。已经被测试、校验或代码防护固化的经验，可以只保留链接或在维护时删除。
5. 当前任务状态
回答"这次任务做到哪里，下一步是什么"。它是短期接力信息，不是长期历史。
适合记录：
- 当前目标和完成条件。
- 已完成的检查点。
- 当前阻塞和未验证风险。
- 已执行的验证。
- 下一步操作。
普通会话结束不等于任务结束。只有任务需要跨会话暂停时才保留状态；任务完成后，应将长期有效内容迁移到对应文档，再清理过程记录。