【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. 当前任务状态

回答“这次任务做到哪里，下一步是什么”。它是短期接力信息，不是长期历史。

适合记录：

• 当前目标和完成条件。
• 已完成的检查点。
• 当前阻塞和未验证风险。
• 已执行的验证。
• 下一步操作。

普通会话结束不等于任务结束。只有任务需要跨会话暂停时才保留状态；任务完成后，应将长期有效内容迁移到对应文档，再清理过程记录。