THESIS / 核心主张
先写实现再补设计会让局部正确互相冲突；结构决策需要在大量代码生成前被明确。
OPERATING STEPS / 执行动作
把原则变成可以检查的动作。
- 按修改成本排序结构决定
- 对高影响决定记录 ADR
- 先冻结跨模块契约再并行
- 变更时同步更新规格、代码和验收
OUTPUTS / 交付物
每个阶段都要留下可复用的产物。
APPLIED CASE / 项目映射
这条方法如何落到真实项目？
GMV 先冻结平台 Service 边界、总控请求/结果模型、目标表安全策略和汇总刷新条件，再逐平台迁移。
FULL CHAPTER / 完整正文
从结论摘要，继续读到判断依据和执行细节。
正文保留 site-v3 的完整论证结构，并将贯穿示例改写为生态店铺 GMV 清洗迁移；原作者身份、原演示案例和未经证实的个人成果不进入本站。
规格驱动开发：先定结构
AI 写局部代码很快，但它不会替你维护全局一致性。结构决策必须先于实现被显式地做出、记录、锁定。
需求篇产出了行为规格（系统必须表现成什么样），上下文工程解决了约束的可见性。这一章解决第三个问题：系统应该长什么样——也就是结构决策如何被做出和管理。
一、反例：边问边攒出来的GMV 清洗迁移系统
按聊天方式推进 GMV 清洗迁移，过程通常是：先让 AI 写总控，发现平台口径不同再加分支，发现需要预览再补 save，发现部分失败再改返回结构，最后才补目标表白名单和汇总门禁。每一步都局部正确，但整体很快冲突：总控塞满平台特例、预览产生副作用、失败状态和汇总状态互相矛盾。
这和执行篇批评的聊天式打补丁是同一个病灶的两个症状：结构决策被隐式地、增量地做出，没有任何一个时刻被完整审视过。 手写代码时代这个问题也存在，但写得慢，混乱成型也慢，人有时间察觉；AI 把实现压缩到分钟级，混乱以同样的倍速成型。
GitClear 对大规模代码库的纵向分析（数据见认知篇）给这个判断提供了佐证：AI 辅助普及后，重复代码上升、重构性代码移动下降——AI 不会主动维护全局一致性，因为它每次只看见局部任务。 全局一致性从来都是人的职责，AI 时代只是把这个职责从"隐性兜底"变成了"必须显式执行"。
二、行业形态：SDD 已经产品化
"先规格后实现"（Spec-Driven Development, SDD）不是本站的独创概念，而是 2025 年以来 AI 开发工具的公共演化方向：
- GitHub Spec Kit 把工作流固化为五个阶段：
/specify（写规格）→/clarify（澄清）→/plan（技术方案）→/tasks（拆任务）→/implement（实现）——代码生成被放在流程的最后一步； - AWS Kiro 直接以三份文档驱动 IDE：
requirements.md（需求，EARS 语法）、design.md(设计)、tasks.md（任务清单），改代码先改文档。
本站方法论与它们同构：需求篇对应 specify + clarify，本章对应 plan/design，执行篇对应 tasks + implement。这个对照的意义在于：这不是某个人的工作习惯，而是整个行业在 AI 提速之后收敛出的同一条纪律——生成越快，结构越要前置。
三、结构决策五件套：按不可逆性排序
GMV 清洗迁移链路需要先定的结构决策有五类。排序不是随意的——按"改起来有多贵"从高到低，越靠前的越必须由人拍板：
| 决策 | 不可逆性 | 为什么必须人定 |
|---|---|---|
| ① 数据模型 | 最高——上线后带着存量数据迁移 | 平台、日期范围、销售/退款金额、类目和部门归属、运行结果。错误模型会被所有平台固化 |
| ② 接口契约 | 高——下游接入后变更即破坏性变更 | 入参出参、错误码语义。契约是模块间的法律 |
| ③ 运行状态 | 高——状态决定失败恢复和汇总可信度 | RUNNING → SUCCESS / PARTIAL / FAILED；部分结果不得标记为完整 |
| ④ 写入边界 | 中——影响预览、重跑与失败语义 | save=false 无副作用；平台写入与完整汇总分离 |
| ⑤ 模块边界 | 中——越界依赖会指数式扩散 | 总控依赖执行器契约，不直接访问平台 Mapper（展开见架构边界） |
这张表就是执行篇决策权分层里"结构性决策"的完整清单。AI 完全可以对每一项提案——让它给出三个表结构方案及权衡是高效的用法——但选择权不能让渡：AI 对"改起来多贵"没有概念，它不承担迁移存量数据的代价。
四、把"为什么"记下来：ADR
结构决策做出后，只记结论是不够的。行业的标准做法是 ADR（Architecture Decision Record，Nygard 2011）：每个重要决策一条短记录——背景、决策、理由、被否方案。
ADR-007：总控仅依赖 PlatformExecutor 契约
背景：九个平台的源表、日期、销售和退款口径不同，且会独立演进。
决策：总控通过执行器注册表选择平台，不直接访问平台 Mapper，不承载平台特殊规则。
理由：平台变化收敛在各自模块，总控只保留稳定的选择、失败策略、聚合和汇总门禁。
被否方案：仅用 Redis 分布式锁（锁过期与主从切换存在窗口）；
仅靠应用层判断（并发下必然穿透）。
ADR 在 AI 工作流里有双重价值：对人，它是评审和交接的依据；对 AI，它进入上下文工程的决策记忆层——没有理由的约束，在模型的长上下文里最先被牺牲；带着理由的约束，模型才能在新场景里正确外推（比如：知道"否掉 Redis 锁是因为失效窗口"，它就不会在下个模块里再提议同样的方案）。
五、规格是单一事实源：变更走规格，不走聊天
规格文档最常见的死法，是上线前两周开始"口头变更"：聊天里说一句"哦对了，平台与日期范围不要日期前缀了"，代码改了，规格没改。从这一刻起规格失信，所有后续验收失去基准——这正是上下文失效模式里的"混淆"（过时信息与现行信息并存）。
纪律只有一条：
需求变更 = 修改规格文件 → 受影响的工作单重发 → 相关测试同步更新。禁止任何绕过规格的"顺嘴改"。
这不是流程洁癖。规格是测试、review、验收三方共同的基准，基准漂移的成本由三方同时承担。Spec Kit 和 Kiro 把"改文档才能改代码"做进工具强制，就是因为靠自觉守不住这条线。
六、边界：结构前置不等于大设计前置
必须回应一个经典质疑：这不就是瀑布式的 Big Design Up Front 吗？
不是，分界线在第三节那张表里：前置的只是不可逆决策，可逆决策明确留给实现层。 数据模型、契约、状态机要先定，因为改它们要付迁移代价；Service 内部怎么组织、用什么设计模式、先查缓存还是先查库，留给 AI 在实现时自由发挥——那一层试错成本趋零，前置反而浪费。
两种情况可以进一步放宽：
- 探索期：技术可行性未知时，先做 spike（快速原型验证），验证完再回头补规格。顺序颠倒是合法的，跳过是不合法的；
- S 级小任务：不触碰五件套中任何一项的改动（见执行篇任务分级），不需要独立的结构设计环节。
判断标准始终一致：结构设计的投入，和决策的不可逆程度成正比。
七、本章小结
- 边攒式开发的病灶是结构决策被隐式增量地做出；AI 把混乱成型的速度提高了两个数量级，全局一致性必须由人显式维护（GitClear 数据佐证）。
- SDD 已是行业公共方向（Spec Kit 五阶段、Kiro 三文档），本站方法与之同构：生成越快，结构越要前置。
- 结构决策五件套按不可逆性排序：数据模型 > 接口契约 > 状态流转 > 事务边界 > 模块边界；AI 可提案，人拍板。
- 决策连同理由记入 ADR，同时服务于人（评审交接）和 AI（决策记忆层的正确外推）。
- 规格是单一事实源：变更走规格文件，禁止口头改；结构前置只覆盖不可逆决策，不是 BDUF。
下一章 架构边界，把五件套里扩散性最强的一项——模块边界——展开成可机器强制的规则。
参考资料
- GitHub, Spec Kit——specify / clarify / plan / tasks / implement 五阶段工作流。
- AWS Kiro——requirements / design / tasks 三文档驱动的 AI IDE。
- Michael Nygard, Documenting Architecture Decisions（2011）——ADR 的原始提案。
- GitClear——AI 辅助下重复代码上升、重构下降的纵向分析，详见认知篇。