构块规格说明书：意图驱动开发中消除需求失真的核心契约

写这篇东西的起因，是我最近在一线项目复盘时看到的一组数据：前后端加测试，差不多有一半的需求，在第一版交付后都要经历至少两轮“重新对需求”的返工。返工的原因翻来覆去就那么几个——业务方说“这不是我要的”，开发说“当时需求文档里没写”，测试说“按文档测的，文档没覆盖”。那一刻我意识到，问题从来不在于大家的编码速度，而在于整个协作链条里，人的“意图”在层层转述中磨损了。

这也是IDD（意图驱动开发）这几年越来越受关注的根本原因。它不发明新框架，不绑定具体的编程语言，它只是在回答一个问题：怎样让从业务想法到代码落地的过程中，每一步都有一条可追踪、可验证的线索。而在IDD的实践里，最容易被低估、但也最值得花时间的产物，就是构块规格说明书。这篇文章，我会用完整的思路拆解它到底是什么、应该包含哪些内容、怎么写出一份真正能落地的规格，以及在真实项目中你会踩到哪些坑。

1. 代码交付反复返工，根源从来不在“手速”而在“意图传递”

1.1 三层信息失真：需求是怎么在传递中变形的

软件开发过程中的“返工成本”，绝大多数不是技术难点造成的，而是需求理解不一致造成的。我见过太多这样的协作链条：业务人员用自然语言描述一个诉求，产品经理把它翻译成业务流程图，开发负责人再把它拆解成技术方案，最终由执行开发或AI工具生成代码。每一次转译，都是一次信息的再加工，而再加工必然伴随损耗。

举个例子。业务方说“给订单列表加一个导出功能”，这句话听起来很明确，但落到不同人脑子里完全不是一回事。业务方的真实意图可能是“我要把本月所有完成订单的关键字段导成Excel，给我的财务同事做对账”。产品经理可能只理解到“订单列表页提供一个导出按钮”，开发人员考虑的是“后端接口是同步返回还是异步任务拉取”，而AI辅助编程工具如果没有更多上下文，会默认按最普通的CSV导出实现，把带格式、带汇总行、带币种换算的复杂需求全部漏掉。

这不是谁不专业的问题，而是自然语言天然带有“信息省略”的倾向。说话人默认很多背景对方知道，听话人又习惯用自己的经验脑补缺失的部分。三层转译下来，最终代码和原始意图之间可能已经隔了十万八千里。

1.2 “意图信息差”才是软件开发最大的隐性成本

我一直觉得，团队里最贵的不是服务器费用，也不是IDE授权费，而是“意图信息差”带来的隐性成本。信息差会出现在每个阶段：需求评审会上没问清楚的关键细节，会在联调阶段变成阻塞；测试用例里没覆盖到的边界，会在线上出事故；技术文档里省略掉的设计取舍，会在人员变动后变成无人区。

IDD这个思路之所以成立，是因为它把“消除信息差”这个模糊的目标，拆成了几个非常具体的动作：捕获意图、分解意图、为每个可独立交付的部分建立规格、然后才进入编码。它不是让你多写文档，而是让你在写代码之前，强制性地把脑子里的假设全部摆到台面上。

1.3 在意图和实现之间，需要一份“契约层”

如果你做过集成电路设计，一定熟悉“规格先行”的流程。芯片设计里，规格书是连接架构师和前端实现工程师的契约，一份规格含糊了，后端的布局布线再优秀也白搭。软件工程在很长时间里缺少这种“契约感”，PRD更像是记录需求的备忘录，技术设计文档更像是写给未来维护者的说明，两者都不是真正意义上的执行契约。

构块规格说明书要做的，就是填上这个空档。它不是需求文档的详细版，而是面向实现的、以可验证性为中心的规格描述。它的读者既是人，也是AI工具——只要描述足够精确，人看了知道边界在哪里，AI辅助工具看了也知道生成代码时不能被模糊描述带偏。

2. 把构块规格放进IDD流程：它到底是哪个环节的产物

2.1 我习惯把IDD流程拆成六个阶段

IDD目前没有统一共识标准，更多是实践中形成的方法论沉淀。我在多个项目里调整过流程，现在习惯把它拆成六个阶段：

• 意图捕获：收集业务目标，分辨哪些是用户真实诉求，哪些是伪需求。
• 意图分解：把大目标拆成可以独立开发、独立验证的功能单元。
• 构块建模：为每个功能单元定义边界、输入输出、依赖关系和状态变化。
• 规格编写：把构块模型写成结构化的、可验证的规格说明，这就是构块规格说明书。
• 智能实现：基于规格，由人或AI工具生成实现代码。
• 验证反馈：用规格中的验收标准反推测试用例，形成闭环。

对这个流程，我有两个心得。第一，阶段之间不要真的搞成瀑布流，规格写完进入实现后，发现边界遗漏要允许回到前序阶段补充；第二，规格编写这个阶段花的力气决定了后面两个阶段的总效率，它是杠杆率最高、也最容易被忽视的一环。

2.2 什么是一个“构块”

“构块”这个概念，可以理解为IDD对系统进行切分后产生的基本功能单元。一个构块应该满足三个特征：有明确的边界、可以被独立验证、可以被组合进更大的业务场景。它可能是单个微服务接口，可能是前端页面里的完整交互模块，也可能是一个后台定时任务。

我自己的经验是，构块的粒度在项目初期不需要追求绝对一致。判断标准很简单：如果一个功能单元的规格，你能用不超过两页纸写清楚，它的边界就是合理的；如果你发现规格越写越长，或者一个构块里塞了三四种互不相关的业务规则，那通常不是规格写得太细，而是构块拆得太粗。

2.3 规格说明书在IDD里的坐标

在IDD体系里，构块规格说明书处在“意图层”和“实现层”之间，扮演契约层的角色。意图层解决“为什么要做”，实现层解决“怎么做”，规格说明书写的是“到底做什么、做到什么程度可以被接受”。

它和PRD、架构设计文档、测试用例的差异，用一张表对照起来比较清楚：

构块规格说明书最重要的特点，是它同时面向人和机器。开发人员通过它理解需求边界，AI辅助编程工具通过它获取精确的功能描述，测试人员通过它推导验证场景。它把需求文档里那些“大概”“尽可能”“友好地提示一下”这类模糊话术，翻译成可以执行的精确描述。

3. 拆开一份构块规格说明书：每个模块解决什么实际问题

3.1 构块标识与意图声明：先逼自己回答“为什么做”

一份合格的构块规格说明书，开头必须有一段简洁的意图声明。这段声明的意义有三个：第一，防止实现过程中忘记原始目标，把功能做成自嗨式设计；第二，给后续接手的人提供决策上下文，遇到模棱两可的问题时，可以回到意图来推导取舍；第三，给变更管理提供依据，如果业务方后续提出与意图声明相悖的需求，可以第一时间识别出来。

写法上，意图声明不要写成产品经理式的目标描述，也不要写成技术方案摘要。它应该是一个可验证的业务结果声明。比如“允许运营在后台创建限时折扣活动，活动开始前可编辑，开始后仅可终止”，这句话里“可编辑”“仅可终止”就是有约束力的意图表达。每一条都要确保后续有具体规则承接。

3.2 策略与规则区：把“如果怎么样就怎么样”穷举出来

规则区是构块规格说明书的核心地带。很多规格之所以无法落地，就是因为这个区域写得像散文，比如“系统应该在用户操作异常时给出合理提示”。什么叫合理？谁来定义合理？这种描述到了实现阶段，基本等于重新开始一轮需求沟通。

我在实践中会把规则区细分成三类来描述：

• 触发规则：明确构块在什么条件下被激活，例如“当订单支付超时且订单状态为待支付时”。
• 业务约束：描述必须满足的业务限制，例如“已关闭的订单不允许再次发起支付，优惠券状态需同步回滚为可用”。
• 状态迁移规则：描述核心实体允许的状态变化，例如“订单状态机只允许：待支付→已支付、待支付→已关闭、已支付→已完成”。

规则描述有一个非常好用的句式——“当[条件]且[条件]时，系统应[动作]；否则应[动作]”，强制自己把条件和结果都写出来。规则区写得越穷举，实现阶段的“意外”就越少。

3.3 数据契约与输入输出：字段级清晰才能避免接口扯皮

以前我们经常在前后端联调时发生“这个字段为什么是空字符串而不是null”“这个时间戳到底是秒还是毫秒”之类的低级争辩。这些问题的根因，就是在编码前没有定义数据契约。

构块规格说明书里，应当为核心接口提供字段级的数据契约描述。不需要像数据库设计文档那样冗长，但需要明确：

• 输入数据的来源、类型、必填性、取值范围
• 输出数据的结构、类型、为空时的行为
• 关联数据的一致性要求（例如库存扣减与订单关闭是否要求强一致）
• 关键枚举值的定义，不允许出现实现时自己发明新值的情况

3.4 异常与降级策略：只写正常路径的规格等于没写

如果把所有业务逻辑都看成一条主干道，那么异常处理就是道路两侧的护栏。没有护栏的路，遇到稍微复杂一点的天气就会出事故。

异常与降级策略是构块规格说明书里最考验写作者功力的部分，因为它要求你在编码之前就回答“如果××失败会怎样”。常见的需要覆盖的场景有：

• 第三方服务超时或不可用（例如库存扣减失败）
• 依赖数据不存在（例如用户查询的订单主单存在但明细被清理）
• 并发冲突（例如支付回调与超时关单同时发生）
• 重复调用（例如消息队列重投导致逻辑执行两次）
• 部分成功（例如批量操作中前几条成功、后几条失败）

当然，异常策略的粒度也需要根据构块的重要程度调整。一个内部管理后台的查询功能，不必为数据库不可用设计复杂的降级预案，但一个交易核心功能，就必须把每个失败场景都描述到位。规格里要敢于写“此场景不做处理”并附理由，这也是规格完整性的一部分。

3.5 验收锚点与测试映射：让“做完没有”不再靠感觉

规格说明书里写验收标准，听起来是老生常谈，但真正落实到位的很少。我见过太多规格，验收标准写的是“功能完整可用”“与需求一致，体验流畅”，这些内容对于测试人员来说等于没有信息量的废话。

我在实践里尝试过一种做法，效果比较好：把验收锚点直接与规则区里的编号一一对应。规则编号R-001对应验收锚点A-001，规则编号R-002对应验收锚点A-002，以此类推。这样一来，测试用例不再是测试人员独立发挥的产物，而是规格的结构性延伸。我甚至会让测试用例大纲在规格评审时就搭好框架，避免规格写了一套、测试测另一套的脱节现象。

3.6 “不做什么”清单：用排除法阻断需求蔓延

构块规格说明书里常见的缺项，是缺少一条“不在本构块范围内”的显式说明。很多需求蔓延，不是因为需求方一直提新需求，而是因为规格里没有明确边界，导致相关人员默认什么都可以加进来。

我推荐规格编写者花十分钟专门写一段“超出范围”事项。例如“本构块只负责优惠券的创建与编辑，不包含优惠券的核销结算”“本构块暂不处理用户手动取消订单的情况”。这段内容的价值在评审阶段就能体现出来——需求方看到自己被明确“排除”的功能，会主动确认或抗议，不管哪种反应，都比上线后才发现理解不一致要好得多。

4. 动手写一份规格：以“订单超时自动关闭并回补库存”为例

4.1 一个“简单”需求里的隐藏歧义

没有具体例子，前面说的内容还是有点空。我们来看一个非常典型的业务场景：订单支付超时自动关闭。业务方最初给到的描述很简单——“订单超过30分钟不支付就取消，取消的时候顺便把库存加回去”。

这句话听起来够简单了。真到了写规格的时候你会发现，至少有七个问题没有答案：

• 30分钟从什么时间点开始计时？从创建订单开始，还是从锁定库存开始？
• 取消前要不要给用户发提醒？还是到点直接取消？
• 如果用户在第29分钟打开支付页面，第30分01秒提交支付，此时回调成功，怎么处理？
• 如果用户在第30分钟整点提交支付，同时定时任务发现订单超时并执行了关闭，两者是并发关系，谁赢？
• 如果订单关闭成功但库存回补失败，库存记录怎么处理？人工介入吗？
• 如果一条订单关联了优惠券，订单关闭后优惠券要不要退回？退回失败怎么办？
• 定时任务延迟执行（比如系统重启）导致实际上45分钟才扫描，是否允许关闭已超时订单？

这些问题是每个真实项目都存在的隐性难点。与其等到实现阶段和测试阶段不断返工，不如在规格编写阶段就一个一个拉出来讨论。

4.2 从模糊描述到结构化规格：一份可参考的草稿

我给出一份精简但完整的构块规格草稿，它对应的就是上面这个需求。实际项目中你可以在这个框架上继续加深。

code复制构块名称：订单超时自动关闭并回补库存
意图声明：确保超过支付时限且仍处于待支付状态的订单被自动关闭，
          释放占用的库存和优惠权益，避免超卖并降低资损风险。
边界范围：本构块只覆盖“待支付订单自动关闭”的业务链路。
          不包含用户手动取消、售后关闭、风控拦截关闭等场景。
触发规则：
  R-001  订单创建成功并锁定库存后，支付截止时间=订单创建时间+支付时限。
  R-002  支付时限默认30分钟，支持系统参数热更新。
  R-003  支付成功回调到达后，订单离开待支付状态，自动关闭流程不再生效。
主流程：
  F-001  定时扫描订单表，筛选满足“订单状态=待支付 且 当前时间>支付截止时间”
         的订单。
  F-002  将满足条件的每条订单标记为“关闭中”，防止并发任务重复处理。
  F-003  调用库存服务，归还该订单占用的库存数量，记录回补流水号。
  F-004  调用优惠服务，归还该订单使用的优惠券，记录退回流水号。
  F-005  将订单状态最终迁移为“已关闭”，原因为“支付超时”。
业务规则：
  B-001  仅允许订单状态为“待支付”的单据执行超时关闭迁移。
         若支付成功回调已先将状态变更为“已支付”，本链路必须放弃关闭。
  B-002  同一订单在分布式环境下同时触发超时关闭与支付回调时，
         必须只允许一个流程成功胜出。实现层面建议引入状态乐观锁。
  B-003  库存回补操作需具有幂等性，同一流水号重复执行不产生重复回补。
  B-004  优惠券退回需保留原使用记录，字段关联原订单号，
         方便退款场景或审计对账时追溯。
异常策略：
  E-001  若库存服务调用失败，订单保持“关闭中”状态并进入重试队列。
         重试超过3次后，标记为“补偿失败”，触发告警并通知人工处理。
  E-002  若订单关闭成功但优惠券退回失败，不影响订单最终关闭结果，
         但需记录明确的补偿状态，确保对账时可发现异常。
  E-003  定时扫描任务支持进程重启后的恢复扫描。
         扫描范围依据支付截止时间，不依赖内存中的计时任务。
数据契约：
  D-001  支付截止时间字段使用UTC时间戳，单位毫秒。
  D-002  订单状态枚举允许值：待支付、已支付、已关闭、已完成，不允许新增值。
  D-003  库存回补结果需回写关联标识：回补流水号、回补时间、操作人(系统)。
验收锚点：
  A-001  给定待支付订单且已超过支付截止时间，执行扫描后订单状态应变为已关闭，
         库存占用数精确减少，回补流水记录完整。
  A-002  给定已支付订单且支付时间大于截止时间（边缘并发），
         订单状态应保持已支付，不得被关闭。
  A-003  同一订单重复触发两次关闭逻辑，库存只允许回补一次。
  A-004  库存服务持续不可用时，订单不得处于既非待支付又非已关闭的悬挂态，
         必须有明确的中间状态和告警信息。
超出范围：
  - 不包含订单支付流程的完整实现。
  - 不包含超时前向用户发送提醒消息的功能。
  - 不包含超时规则的金额分层策略（如大额订单延长支付时限）。

你可以看到，这份草稿并不长，但每一个规则都拒绝含糊。尤其是B-002这条，它直接决定了实现人员做技术选型时要不要引入乐观锁机制；如果规格里不写清楚，开发按普通顺序逻辑实现，线上并发场景一定会出问题。

4.3 规格评审时重点追问什么

规格草稿完成后，我建议组织一次专门的规格评审。评审不需要代码走查，核心是业务方、开发、测试站在一起，把规格里的每条规则逐条过一遍。我通常会在评审时要求团队就以下四个问题展开追问：

• 每条规则的措辞是否只有一种解释？
• 规格中的状态迁移是否覆盖了所有非法路径？
• 异常策略描述是否符合故障发生时的真实预期？
• 验收锚点是否能在集成测试环境里被稳定验证？

很多规格文本写出来的时候感觉逻辑严密，一追问就会发现自己遗漏了关键场景。比如上面草稿的E-003，如果没有写清楚扫描采用“扫描数据库”而不是“内存任务”，实现人员很可能会把超时定时器放在应用内存里，导致重启后丢失大量本应关闭的订单。规格评审就是要把这层风险挡在编码之前。

4.4 让规格真正驱动实现而非锁死实现

这里必须说明一个重要的边界：构块规格说明书定义的是“做什么”和“做到什么程度”，它不应越权规定“具体用什么代码技术实现”。我在草稿里提到“实现层面建议引入状态乐观锁”，这是为了实现B-002这个业务需求而给出的技术方向提示，但绝不能写成“必须使用Redisson分布式锁并配置waitTime为3秒”这种过度具体的技术指令。

好的规格给实现人员留出合理的方案选择空间。同一份规格，团队用Java还是Go实现都没有问题，用数据库乐观锁还是分布式锁都没有问题，只要最终能满足规则区的约束，测试能够通过验收锚点，就是合格的落地。规格越聚焦业务行为和可验证结果，它的生命力越长。

5. 一份构块规格写得好不好，用这套检查表打分

5.1 从“模糊到不可感知”到“精确到可验证”

多年实践下来，我自己总结了一套快速判断规格质量的检查表，每次评审时都会带着过一遍。

第一，每一句话描述的行为都能被验证。如果一句话无法推导出验证方法，这句话就不该出现在规格里。例如“系统应保证用户体验流畅”，这就不是合格描述；“在百兆网络环境下，页面首屏加载时间不超过3秒”，就是可以验证的表述。

第二，每个业务术语全篇只保留一个含义。如果文稿里一会儿叫“取消订单”，一会儿叫“关单”，一会儿叫“订单关闭”，读者就会怀疑它们是不是同一个概念。遇到这种情况必须在开头术语表里强制统一。

第三，每个规则条目都有对应编号，并且能追溯到验收锚点。规则编号与验收编号的映射关系，是最有效的防脱节机制。

第四，边界状态和异常路径占全文的篇幅不小于正常路径的三分之一。如果异常路径寥寥几行，几乎说明写规格的人没有认真推演失败场景。

第五，看完规格后，实现者能回答“我能开始写代码了吗”并且真的可以动手。如果读者看完还得跑去找业务方确认某个细节，规格的完备性就不及格。

5.2 区分优秀规格和平庸规格的三个关键差异

把两份规格放在一起对比，你能很快看出差异。

平庸规格写的是“支持订单查询”，优秀规格写的是“查询条件支持订单号精确查询、手机号模糊查询、下单时间范围查询，三个条件为AND关系，未传条件时返回参数错误提示”。

平庸规格写的是“发生错误时提示用户”，优秀规格写的是“当上游库存服务返回业务码INSUFFICIENT_STOCK时，前端在提交按钮下方展示‘库存不足’文案，并保持用户已填写的收货地址和备注不变”。

平庸规格通篇描述预期行为，优秀规格还会额外写明“当前版本不做的事”。排除法比列举法更能约束范围。

这三个差异的底层逻辑是一致的——优秀的规格文本是一台“消歧机器”，每句话都在降低不确定性，而平庸的规格文本只是一份“愿望清单”。以这个标准看，规格写作其实是从模糊到精确的思维训练，文档本身是副产品。

5.3 参考检查表：评审时逐项打勾

为了不让你在评审时漫无目的地翻阅，我把常用问题做成了一张可执行清单：

• [ ] 是否有意图声明？能否在一分钟内说出本构块的存在价值？
• [ ] 是否列出超出范围事项？有没有把不做的内容显式说明？
• [ ] 触发规则是否完整列出？是否覆盖所有进入本构块的入口？
• [ ] 状态迁移是否覆盖所有“当前状态+动作=目标状态”的组合？
• [ ] 数据契约是否明确到字段级？必填、类型、枚举是否有歧义？
• [ ] 异常策略是否至少覆盖服务不可用、数据缺失、重复调用、并发冲突四类场景？
• [ ] 验收锚点是否能映射到具体测试用例？是否包含边界值和异常路径？
• [ ] 全文是否存在“稍微”“快速”“合理”“友好”等不可验证的形容词？
• [ ] 是否保留了实现人员的技术选型空间？有没有因过度设计而锁死技术方案？

如果你的规格对每个问号都能给出明确答案，那这份规格大概率已经能承担契约层的职责。反之，任何一个问号背后悬而未决，它都会在项目推进的某个节点引爆。

6. 我踩过的那些坑：规格写不好，实现阶段会加倍奉还

6.1 把规格写成“需求加方案混淆体”

我第一次完整实践IDD时，很容易把构块规格说明书写成一个怪物：前半部分是需求复述，后半部分是代码架构设计。结果业务方看前半部分说没什么新东西，开发团队看后半部分说方案不可行要改设计。两边都觉得这份文档价值有限，规格评审会变成了方案争论会。

后来我意识到，混写的问题在于混淆了两个问题：“这个功能要实现什么业务规则”和“这个系统内部应该怎么架构”。规格说明书应该专注前者，纵使要给出实现建议，也应该以“为满足某条业务规则，建议考虑……”的句式呈现，而不是直接把技术方案定为默认结论。把业务规则和技术方案分离，评审效率会高很多，因为讨论业务时不会夹带技术偏好，讨论技术时也不用担心推翻业务结论。

6.2 只写正常路径，异常路径草草带过

这个问题在经验较少的规格写作者身上尤其明显。人的思维惯性是顺向的，写一个流程时天然会沿着“正常情况下一步一步往下走”的路径思考。但软件系统运行在真实世界里，三分之一的请求会遇到某种异常，这些异常恰恰占据了排查和返工时间的大头。

我现在写规格有一个强制动作：写完主流程后，逐行审查每一条正常步骤，然后问自己“如果这一步执行了50%的时候出现问题，会发生什么”。库存扣减成功后订单关闭前宕机了，怎么办？订单关闭成功后发送通知失败，需要回滚订单状态吗？把这些问题全部过一遍，规格才称得上具备工程完整性。

6.3 术语不统一，微妙的“语义漂移”比想象的更常见

有一次项目里，需求文档写的是“取消订单”，开发讨论时说的是“关单”，测试用例里写的是“订单失效”，而数据库里的状态值叫CANCELLED。大家心里其实都清楚指的是同一个东西，但在排查某个工单时，由于没有明确的术语对应关系，每个人在自己的语境里转换来转换去，浪费了大量时间。

从那以后，我要求每份构块规格说明书必须有一个“术语表”模块。凡是出现超过两次的专有名词，全部集中定义，代码层、存储层、业务层的叫法不一致时也要做显式映射。这个动作看起来微不足道，它却能把跨角色沟通成本成倍降低。

6.4 粒度把握失准：太粗变成废话，太细变成代码注释

规格粒度是新手和高手的核心分水岭。粒度太粗，每隔几条描述就要停下来问“这里具体怎么处理”，它就没有起到契约作用；粒度太细，把实现层面的函数调用和临时变量都写进去，规格会在第一次代码重构后作废，没有人愿意维护一套和代码完全重复的文档。

怎么判断粒度是否合适？我的经验是：规格中的任何描述，只有当它影响“业务结果是否正确”或“边界行为是否可接受”时，才值得写。如果纯属实现人员可以自行决定的内容，例如用什么集合类型、要不要建索引，规格就要学会沉默。好的规格不会替代代码，也不会被代码替代，它描述的是实现必须遵守的外部可观察行为。

6.5 验收标准写成口号，测试用例只能靠猜

“功能正常”“和需求一致”这类验收话术，在所有不合格的规格书写里出现频率最高。它们的问题不是错误，而是缺乏信息量。验收锚点必须采用“给定某前置条件，执行某操作，断言某可观测结果”的结构。比如前面案例里的“给定待支付订单且已超过支付截止时间，执行扫描后订单状态应变为已关闭”，这种写法直接对应一条集成测试用例。

如果规格中的每条验收锚点都能让测试人员直接引用，测试设计的返工就会减少一大半。这也是构块规格说明书区别于其他文档最有价值的地方——它是唯一能让业务规则与自动化测试直接建立追溯关系的载体。

6.6 不维护旧规格，让契约沦为一次性废纸

规格写完、功能上线，不等于规格的生命周期结束。需求变更会频繁发生，不更新规格的团队很快就会陷入文档与现实脱节的混乱。对此我没有完美的解决方案，但有一个可执行的做法：把所有构块规格放在代码仓库里，和对应模块的代码保持同一次提交或把关单。任何代码变更涉及业务行为时，必须同步更新规格中受影响的规则区。

这会让代码评审多一层看板，团队会在Diff里同时看到“代码变更”和“规格变更”，这种做法可以从机制上保证规格不会成为一次性废纸，它会一直处于与代码实际行为同步的状态，维持作为契约的信用。

我在实际项目中摸索出的体会是：构块规格说明书真正的价值峰值，其实发生在写作过程中——它强迫你把所有模糊的“想当然”都变成明确的“决定”。如果你所在团队正在为需求反复返工头痛，不必一开始就追求全流程体系化。挑一个近期要做的小构块，用本文提到的模块框架写一版规格，开一场规格评审，再让团队照它实现一次。只要跑通一轮，你就能直观感受到，用文字先完成一轮思维推演，远比多写几千行代码再推翻要划算得多。