DESIGN.md（AI 可执行版）
文件定位：本次需求 / 变更的唯一实现依据（Single Source of Truth） 主要受众：AI 编程工具 + 人类 Reviewer 核心目标：将人类的设计意图，翻译为无歧义、可校验、可执行的实现说明。
0. 设计使用声明（必读）
- 本文档描述的是：“这一次要怎么改”，而不是项目长期设计
- AI 只能依据本文档 + GEMINI.md 进行实现
-
本文档中未明确说明的行为：
- ❌ 不允许 AI 自行假设
- ❌ 不允许凭经验补全
如果存在缺失或歧义，AI 必须停止并提出澄清问题。
1. 需求背景与目标（Why）
1.1 背景说明
-
触发原因：
<业务需求 / 缺陷 / 事故 / 优化动因>
-
相关背景（简述）：
<为什么现在要做>
1.2 目标与成功标准
-
本次变更要达到的目标：
<目标 1><目标 2>
-
成功判定标准（可验证）：
<条件 1><条件 2>
2. 需求范围与非目标（Scope）
2.1 本次包含的内容
<明确要做的点，条目化>
2.2 本次不包含的内容（非常重要）
用于主动压制 AI 发散。
-
不做：
<例如：重构某模块><例如：性能整体优化>
3. 现状分析（As-Is）
让 AI 理解“现在是什么样”。
3.1 当前行为描述
-
相关模块 / 类：
<模块 / 类名>
-
当前关键逻辑流程：
<步骤 1><步骤 2>
3.2 当前存在的问题
<问题 1><问题 2>
4. 目标方案概述（To-Be）
高层方案说明，不写代码。
-
方案核心思路：
<一句话或几句话>
-
涉及模块变化：
- 新增：
<模块> - 修改：
<模块>
- 新增：
5. 详细设计（AI 执行核心）
本章是 AI 最重要的输入，必须具体、确定、可逐条校验。
5.1 接口与入参 / 出参定义
-
接口 / 方法签名：
<方法名>
-
输入参数：
| 参数 | 类型 | 说明 | 是否可空 | | – | – | – | —- |
-
输出结果： | 字段 | 类型 | 说明 | |—-|—-|—-|—-|
5.2 核心处理流程（顺序不可省略）
必须按顺序描述，不允许 AI 自行调整步骤顺序。
<步骤 1：校验><步骤 2：核心逻辑><步骤 3：状态变更><步骤 4：持久化 / 调用外部系统>
5.3 条件分支与边界情况（必须穷举）
AI 最容易出错的地方。
-
当
<条件 A>时：- 行为：
<明确说明>
- 行为：
-
当
<条件 B>时：- 行为：
<明确说明>
- 行为：
5.4 异常与错误处理
-
可预期异常：
<异常类型>→<处理方式>
-
不可预期异常：
- 是否兜底：
是 / 否 - 兜底策略：
<说明>
- 是否兜底：
5.5 数据与状态变更说明
-
涉及的数据表 / 存储：
<表名>：<读 / 写 / 更新>
-
状态变化规则：
<状态 A>→<状态 B>（条件）
6. 兼容性与历史影响分析
历史项目的关键章节，不能省略。
-
是否影响已有行为：
是 / 否 -
影响范围：
<模块 / 场景>
-
向后兼容策略：
<说明>
7. 风险点与防控措施
-
已知风险点：
<风险>→<规避方式>
-
AI 实现时特别容易出错的点：
<提示>
8. 验证与测试要点（可执行）
用于判断 “是否实现完成”。
-
正常路径用例：
<用例说明>
-
异常 / 边界用例：
<用例说明>
9. 与其他文档的关系
- GEMINI.md：定义 不可违反的工程与行为约束
- PROJECT_PROFILE.md：提供 项目背景与历史语义
如本文档与 GEMINI.md 冲突，以 GEMINI.md 为准。
10. AI 执行确认清单（强制）
在开始编码前，AI 必须逐条确认：
- 已完整阅读 GEMINI.md
- 已完整阅读 PROJECT_PROFILE.md
- 本文档中不存在未澄清的歧义
- 本次实现不涉及任何未声明的重构或扩展
若任一项无法确认，必须先提出问题，而不是生成代码。
总结
这是整套体系里最关键、也是最容易被低估的一份文档。
我下面不重复模板内容，而是重点解释三件事：
它和普通设计文档的本质差异、你在真实项目中该如何“写给 AI 看”、以及它在你整个方法论中的位置。
一、这份 DESIGN.md 和传统设计文档的本质区别
一句话总结：
这是“可被 AI 逐条执行的设计”，而不是“给人讨论的设计”。
因此它在设计上刻意做了三件事：
1. 强制消灭“合理但未说明”的空间
-
所有关键行为都要：
- 有顺序
- 有条件
- 有边界
-
未写 = 不允许 AI 自行补全
这直接命中你之前说的核心问题： 人类语言是压缩的，机器需要解压后的指令。
2. 把“非目标”当成一等公民
第 2 章（Scope）在 AI 场景下非常关键：
- 明确“不做什么”
- 明确“这次不碰哪些模块”
- 明确“不是一次顺手重构”
这是压制 AI 发散最有效、也最工程化的手段。
3. 把“边界情况”和“异常”前置
你会发现：
- 条件分支
- 异常处理
- 状态迁移
都被要求显式穷举，这不是为了“严谨”，而是因为：
AI 在 happy path 上几乎不出错，在边界上极容易“自作主张”。
二、你在真实项目中，如何“写好”这份 DESIGN.md
给你一个非常实用的判断标准：
如果一个段落，你觉得“有经验的老同事一看就懂”，那对 AI 来说几乎一定不够。
推荐写作顺序（非常重要）
不是从第 1 章开始写，而是：
-
先写 §5 详细设计
- 接口
- 流程
- 分支
- 再补 §6 兼容性
- 再补 §2 非目标
- 最后才写 §1 背景
这样可以避免背景写得很丰满，但执行层模糊。
三、DESIGN.md 在你整个体系中的“锚点”作用
你现在的三份文档，其实形成了一个非常清晰的三角结构：
| 文档 | 本质作用 |
|---|---|
| GEMINI.md | 约束 AI 的“行为边界” |
| PROJECT_PROFILE.md | 约束 AI 的“理解边界” |
| DESIGN.md（AI 可执行版） | 约束 AI 的“实现自由度” |
也正因为有 DESIGN.md，你才能做到：
- 人负责决策
- AI 负责执行
- Review 聚焦在“是否按设计实现”，而不是“你是不是又脑补了什么”
四、一个你已经隐约走在前面的方向（点明一下）
你现在这套方法，本质上已经是：
Specification-driven + Constraint-driven 的 AI 编程模式
这非常接近未来两三年主流的：
- Agent 编程
- 多模型协作
- 自动实现 / 自动验证
而 DESIGN.md 正是那个可以被多轮 agent 消费的稳定接口。
