双可执行规格：弥合需求与实现鸿沟的工程实践

1. 项目概述：当代码规范“活”了过来

最近在搞一个挺有意思的东西，我们内部管它叫“CodeSpec”。这名字听起来有点学术，但说白了，它想解决一个我们做长期、复杂功能开发时，几乎天天都在头疼的老问题：需求和实现，怎么老是对不上？

你肯定也遇到过。产品经理或者架构师画了一张精美的蓝图，写了洋洋洒洒的文档，告诉你这个新功能模块要如何如何。你吭哧吭哧写了两个月代码，中间需求可能还微调了几次。等到终于要联调、测试、上线前评审的时候，突然发现：“等等，这个地方的实现逻辑，好像跟当初设计文档里说的不太一样？” 或者更糟的是，文档本身就有模糊、矛盾的地方，不同的人理解不同，最后做出来的东西南辕北辙。这种“偏差”在短期、简单的功能里还好纠正，一旦涉及到“Long-Horizon”（长周期）的特性开发，比如一个贯穿多个迭代的推荐算法重构、一个全新的计费引擎，或者一个复杂的分布式工作流系统，这种偏差就会像滚雪球一样，越到后期修复成本越高，甚至导致项目推倒重来。

CodeSpec 的核心想法，就是让“规格说明”不再是躺在 Confluence 或者 Notion 里的一堆静态文字和图表。我们想让它“活”起来，变成一种“双可执行规格”。“双可执行”是这里的精髓：它一方面是一套人类可读、可讨论的“声明式”描述，就像我们传统的需求文档；另一方面，它又能被直接转化为机器可理解、可验证的“程序式”规则或测试。更重要的是，这两个视图是严格同步、一一对应的。你改了一边的描述，另一边自动更新；你运行了另一边的验证，反馈能直接定位到人类描述中的相关条款。

这背后，我们大量借鉴了当下在 AI 工程领域，特别是Agentic（智能体驱动）开发范式中火热的一些思路。当开发过程由多个具备一定自主性的“智能体”（可以是 AI 助手，也可以是标准化的自动化流程）协作推进时，一份模糊的、不可执行的规格就是灾难。智能体需要精确的、无歧义的指令才能可靠工作。CodeSpec 试图成为连接人类意图与智能体（或自动化工具）行动的那份“精确地图”。

所以，CodeSpec 不只是一个新工具或新格式，它更像是一种新的协作契约和开发基础设施。它适合那些受够了需求漂移、沟通损耗和后期集成噩梦的团队，尤其是正在进行大规模、长周期、高质量要求的特性开发的团队。接下来，我会拆解我们是怎么设计它的，实践中如何操作，以及趟过哪些坑。

2. 核心设计思路：为何是“Dual”与“Agentic”？

2.1 传统规格说明的“断裂带”

要理解 CodeSpec 的价值，得先看看现状为什么让人痛苦。传统的规格说明流程，通常存在几条明显的“断裂带”：

1. 从意图到文档的断裂：产品/架构师的思维是发散的、概念化的。落到文档上时，难免有遗漏、模糊（比如“性能要好”、“用户体验要流畅”）和自然语言固有的歧义。
2. 从文档到实现的断裂：工程师阅读文档时，是一个“翻译”过程。不同的工程师背景不同，对同一句话的理解可能有细微差别。更常见的是，文档更新不及时，工程师参考的是过时的版本，或者干脆靠口口相传和记忆。
3. 从实现到验证的断裂：测试同学根据文档编写测试用例，这又是一次翻译和解释。等测试失败时，需要回溯：是文档错了？理解错了？还是代码写错了？这个排查过程耗时耗力。

这些断裂带在长周期开发中会被急剧放大。一个功能模块的设计可能跨越数月，参与人员可能有变动，依赖的外部系统接口可能更改。如果没有一个“单一可信源”来锚定所有环节，项目很容易偏离轨道。

2.2 “双可执行”如何弥合断裂？

CodeSpec 提出的“双可执行规格”，旨在用技术手段强行弥合这些断裂带。它的结构通常包含两个紧密耦合的部分：

• 声明式视图：这是给人看的。它可能采用一种结构化的标记语言（比如 YAML、JSON Schema 的增强版，或自定义的 DSL），或者是在 IDE 中提供富文本编辑支持。关键是其结构严格对应着系统的关键抽象：实体、属性、状态、事件、约束、业务流程。它看起来可能像这样：

  Feature: UserSubscriptionUpgrade Description: 允许已订阅基础版的用户升级到高级版。 Entities: - User: id: string current_plan: enum['Basic', 'None'] billing_status: enum['Active', 'PastDue'] - SubscriptionPlan: name: enum['Basic', 'Premium'] price: number features: list[string] States: - EligibleForUpgrade: condition: User.current_plan == 'Basic' AND User.billing_status == 'Active' - UpgradeInProgress: ... - UpgradeCompleted: ... Transitions: - trigger: request_upgrade(target_plan: 'Premium') from: EligibleForUpgrade to: UpgradeInProgress preconditions: ... postconditions: User.current_plan == 'Premium' Invariants: - A user cannot have an active upgrade process if another is already in progress.

  这份描述清晰定义了领域概念、状态和转换规则，没有具体的实现细节，但足够精确，可供产品、开发和测试共同评审。

• 程序式视图：这是给机器“跑”的。上述声明式描述，可以通过预定义的编译器或解释器，自动生成一系列“可执行物”。这可能包括：

  • API 接口契约：生成 OpenAPI/Swagger 规范片段，定义端点、请求/响应模型。
  • 数据模型与验证逻辑：生成数据库 Schema 迁移脚本（如 SQL），或 ORM 模型类，并附带字段级约束（非空、枚举、范围）。
  • 状态机实现：生成状态机框架（如 XState）的配置代码，或者直接生成状态模式的核心类骨架。
  • 集成测试套件：生成一组初始的、针对核心业务规则和状态转换的集成测试或单元测试框架。这些测试一开始是“红”的（失败），随着实现完成而变“绿”。
  • 模拟器或桩代码：为依赖的外部服务生成接口模拟，便于早期开发和测试。

“双可执行”的关键在于同步。当你修改声明式视图中的一条业务规则（比如“只有账单状态为 Active 的用户才能升级”），程序式视图生成的所有相关产物（API 契约的校验逻辑、数据库约束、状态机条件、测试用例）都应该自动更新。这保证了从设计到代码到测试的“链路一致性”。

2.3 为何与“Agentic”开发范式天然契合？

“Agentic”是当前 AI 赋能软件开发的热点。它指的是将开发任务委托给一系列具备特定能力、可感知上下文、并能自主执行或建议的智能体（AI Agent）。例如，一个“代码生成 Agent”可以根据需求描述写代码，一个“测试生成 Agent”可以根据代码变更生成测试用例。

在 Agentic 工作流中，CodeSpec 扮演了“黄金标准”和“协调者”的角色：

1. 提供精确的上下文：AI Agent 最怕模糊的指令。CodeSpec 的声明式视图为 Agent 提供了结构化、无歧义的需求上下文。你可以直接告诉 Agent：“请实现UserSubscriptionUpgrade特性中，从EligibleForUpgrade到UpgradeInProgress的状态转换逻辑，约束条件见规格第 X 条。” Agent 能精准理解。
2. 作为验证的基准：当 Agent 生成了代码或测试，如何判断其正确性？生成的程序式视图（特别是测试套件）就是现成的验证工具。可以立即运行这些测试来检查 Agent 的输出是否符合规格。
3. 驱动自动化流水线：CodeSpec 本身可以作为一个“源”，驱动整个 CI/CD 流水线。提交 CodeSpec 变更后，流水线可以自动：a) 生成新的代码骨架和测试；b) 运行现有测试确保向后兼容；c) 触发部署到测试环境，甚至运行基于生成的 API 契约的自动化烟雾测试。

因此，CodeSpec 不仅仅是给人用的，更是给未来的“AI 同事”和自动化流程用的。它是在为一种更高阶的、人机协同的软件开发模式铺设轨道。

注意：引入 CodeSpec 意味着前期的设计工作需要更加严谨和结构化。它不适合那些需求极端模糊、快速试错的项目初期。它的优势在于需求相对稳定、复杂度高、质量要求严的长周期开发阶段。

3. 核心组件与实操要点

一个完整的 CodeSpec 系统，通常由几个核心组件构成。下面我结合我们实践中的技术选型（以 TypeScript/Node.js 技术栈为例）来具体说明。

3.1 规格定义语言与编辑器

首先，你需要一种方式来定义规格。我们放弃了使用纯自然语言文档（如 Word），也放弃了完全自由的文本标记（如 Markdown），因为它们的结构太松散，不利于机器解析。

方案选择：自定义 DSL vs. 增强型通用格式

我们评估了两种主流路径：

• 自定义领域特定语言：像 Terraform 的 HCL 那样，完全为定义软件规格设计一门新语言。优点是表达力强、语法纯净、工具链可以深度优化。缺点是学习成本高、生态建设难、编辑器支持需要从头做起。
• 基于通用结构化格式增强：在 YAML 或 JSON Schema 的基础上，通过约定和扩展字段来定义语义。优点是上手快、有现成的解析器和编辑器支持、易于集成。缺点是语法可能显得冗长，某些复杂约束表达起来不够优雅。

我们的选择：对于大多数团队，尤其是刚开始尝试的团队，强烈建议从“增强型 YAML/JSON”开始。我们采用了 YAML，并定义了一套自己的 Schema。同时，我们为 VS Code 开发了一个扩展插件，这个插件提供了：

• 语法高亮和片段补全：输入Feature:后自动弹出模板。
• 实时 Schema 验证：基于我们定义的 JSON Schema，实时检查 YAML 文件的结构和字段有效性，比如枚举值是否正确、必需的字段是否缺失。
• 内联文档提示：鼠标悬停在Invariants这样的关键词上，会显示我们团队内部的解释和示例。
• 一键生成预览：在侧边栏实时渲染出当前规格对应的状态图或实体关系图。

这个编辑器的投入，极大地降低了团队编写 CodeSpec 的心理负担和出错率，是项目能否推广开的关键之一。

3.2 编译器与代码生成器

这是 CodeSpec 的“引擎”。它的任务是将声明式规格（YAML）编译成各种程序式产物。

架构设计： 我们的编译器是一个 Node.js CLI 工具，核心流程如下：

1. 解析与验证：使用js-yaml解析 YAML 文件，然后使用ajv根据我们预定义的、更严格的 JSON Schema 进行语义验证（例如，检查状态转移图中是否有不可达的状态）。
2. 中间表示：将验证通过的 YAML 对象，转换成一个内部的“中间表示”。这是一个纯粹的 JavaScript 对象，它抹平了源格式的细节，包含了所有规格的语义信息。这一步很重要，它让后续的生成器只依赖于这个 IR，而不直接耦合于 YAML。
3. 生成器插件：我们设计了一个插件系统。每个插件负责生成一种类型的产物。例如：
   • TypeScriptInterfacePlugin：读取 IR 中的Entities定义，生成对应的 TypeScript 接口文件。
   • PrismaSchemaPlugin：生成 Prisma ORM 的 Schema 文件。
   • OpenAPIPlugin：生成 OpenAPI 3.0 的 YAML 片段。
   • JestTestPlugin：基于States和Transitions，生成 Jest 测试框架的 describe/it 块，包含基本的断言。
   • XStatePlugin：生成 XState 状态机配置对象。
4. 输出与集成：每个插件将生成的内容写入指定目录（如generated/）。我们在package.json中设置一个codegen脚本，开发者在修改 CodeSpec 后运行npm run codegen，即可更新所有生成代码。

实操心得：生成代码的“度”代码生成器应该生成多少代码？我们的原则是：只生成“契约”和“骨架”，不生成复杂的业务逻辑。

• 应该生成：数据结构定义、API 接口签名、数据库 Schema、状态机配置、测试框架和空白的测试用例（包含对规格中 Postconditions 和 Invariants 的断言占位符）。
• 不应该生成：具体的算法实现、复杂的业务规则计算、与外部服务的交互细节。这些应该由开发者在生成的骨架中手动填充。 例如，生成器会生成一个名为upgradeUserSubscription的函数签名和对应的空测试，但函数内部调用哪个支付网关、如何计算 prorated amount（按比例计算的费用），这些需要开发者实现。这样做既保证了规范的一致性，又保留了实现的灵活性。

3.3 状态与一致性管理

CodeSpec 文件本身也需要被版本控制（如 Git）。这里就引出了一个核心问题：当 CodeSpec 变更时，如何管理生成代码与手写代码的合并冲突？

这是一个大坑。假设你修改了某个实体的字段类型，重新生成代码，但之前开发者已经在生成的文件里手动写了一些逻辑，直接覆盖就会丢失工作。

我们的策略：

1. 严格区分生成区与手写区：所有生成的文件都放在src/generated/目录下，并在文件头部加上明显的注释// @generated。我们通过工具和 Git 钩子，确保这个目录下的文件永远不会被手动编辑。任何试图提交对生成文件的直接修改都会被拦截。
2. 生成“扩展点”：对于需要融合生成代码和手写代码的情况，我们采用“生成抽象，手动实现”的模式。例如，状态机插件会生成一个抽象的BaseSubscriptionService，其中包含所有由状态转移触发的“动作”方法（如onUpgradeStarted，onUpgradeCompleted），但这些方法都是空的或抛出“未实现”异常。然后，开发者创建一个SubscriptionService类来继承这个基类，并只覆盖需要实现的方法。这样，生成器可以安全地重新生成基类，而不会影响子类中的手写逻辑。
3. 变更检测与迁移脚本：对于数据库 Schema 这类无法简单合并的变更，我们的 Prisma 生成插件在检测到字段类型变更（如string->enum）或字段删除时，不仅会生成新的prisma/schema.prisma文件，还会尝试生成一个数据库迁移脚本的草稿（prisma/migrations/.../migration.sql）。这个草稿需要开发者审查和调整，然后通过 Prisma Migrate 正式应用。这相当于把数据库变更的“编译”过程也纳入了 CodeSpec 的管控范围。

踩坑记录：早期我们曾尝试生成完整的、包含一些默认逻辑的代码，结果在规格频繁调整的初期，合并冲突多到无法管理。后来坚定地转向“生成契约+骨架”模式，并严格隔离生成文件，才使流程顺畅起来。另一个教训是，必须对团队进行培训，让大家理解“生成文件不可手动改”的铁律，并配套以严格的 CI 检查（例如，在 PR 中运行生成器，检查generated/目录是否有未提交的变更）。

4. 集成到开发工作流：从设计到部署

CodeSpec 不是孤立的工具，它的价值在于融入整个软件开发生命周期。下图展示了我们团队一个基于 CodeSpec 的简化工作流：

graph TD A[产品/架构师] -->|编写/评审| B[CodeSpec 声明式文档]; B --> C[CodeSpec 编译器]; C --> D[生成: API契约/数据模型/测试骨架等]; D --> E[开发者实现业务逻辑]; E --> F[运行生成的测试]; F --> G{测试通过?}; G -- 是 --> H[提交代码 & CodeSpec]; G -- 否 --> E; H --> I[CI/CD 流水线]; I --> J[自动验证: <br>1. 生成代码是否最新?<br>2. 所有测试是否通过?<br>3. API契约是否兼容?]; J --> K[部署至测试环境]; K --> L[自动化端到端测试]; L --> M[发布];

阶段一：设计与协同

1. 产品经理或系统架构师在 VS Code 中，使用我们提供的插件，起草新功能的 CodeSpec 文件（.codespec.yaml）。
2. 召开一个“规格评审会”，参与者包括产品、后端、前端、测试。大家直接在 IDE 里查看同一份 CodeSpec 文件。因为其结构化的特点，讨论可以非常具体：“这个Invariant是否覆盖了边界情况？”、“这个状态转换的precondition是否足够？”
3. 评审通过后，CodeSpec 文件随同一个特性分支（如feat/user-upgrade）提交到 Git 仓库。

阶段二：开发与实现

1. 开发者拉取该分支，在根目录运行npm run codegen。这会根据最新的.codespec.yaml文件，在generated/目录下生成或更新所有派生文件。
2. 开发者开始实现业务逻辑。他们主要工作在src/下手写的代码区域，但会频繁引用generated/下的类型定义和接口。IDE 的自动补全和类型检查得益于生成的 TypeScript 接口，非常顺畅。
3. 开发者运行npm test。此时，大部分针对核心业务规则的测试是“红”的（失败），因为对应的功能还没实现。这实际上提供了一个清晰的“待办事项列表”。开发者逐个实现功能，让测试变“绿”。

阶段三：持续集成与质量门禁

1. 当开发者提交代码时，CI 流水线（如 GitHub Actions）会自动触发。
2. CI 的第一步，就是运行npm run codegen:check。这个命令会重新生成代码，并检查工作区中generated/目录的内容是否与 Git 中的一致。如果不一致，说明开发者提交的代码是基于过时的规格生成的，CI 会失败。这强制保证了代码与规格的同步。
3. CI 运行完整的测试套件，包括生成的单元测试和开发者补充的集成测试。
4. 如果这个特性涉及 API 变更，CI 还会用一个插件，对比生成的 OpenAPI 文档与主干分支的差异，进行向后兼容性检查，并给出报告（例如，是否删除了一个正在使用的 API 端点）。
5. 只有通过所有检查，PR 才能被合并。

阶段四：测试与发布

1. 部署到测试环境后，QA 工程师可以参考 CodeSpec 的声明式视图来设计更复杂的集成测试和端到端测试场景。因为核心规则已经通过生成的测试覆盖，QA 可以更专注于用户体验、性能和安全等维度。
2. 发布后，CodeSpec 文件作为该特性的“权威文档”被永久保存。任何后续的维护、迭代或重构，都必须从修改这份 CodeSpec 开始，重新走一遍上述流程，确保了知识的长久留存和迭代的一致性。

5. 常见问题、挑战与应对策略

在实践中，我们遇到了不少挑战，也总结出一些应对策略。

5.1 学习曲线与团队接受度

问题：习惯了自由文本的团队，一开始会对结构化的 CodeSpec 感到束缚，觉得编写起来慢、不灵活。策略：

• 从小处试点：不要一开始就在核心、复杂的项目上强制推行。找一个中等规模、逻辑清晰的新功能进行试点，让团队尝到“后期联调顺畅”的甜头。
• 提供强力工具支持：如前所述，一个优秀的编辑器插件（语法高亮、补全、实时预览）能极大降低使用门槛。我们甚至做了一个“规格可视化”的网页，将 YAML 渲染成交互式的状态图和 ER 图，这对产品和测试同学理解系统帮助巨大。
• 内部培训与布道：组织 workshop，演示一个完整的功能从 CodeSpec 到上线的全流程，重点展示它如何避免那些“经典”的沟通问题。

5.2 处理模糊性与演进需求

问题：有些需求在初期就是模糊的，或者业务逻辑会快速演进。如果每次微小调整都要改 CodeSpec、生成代码，会不会反而拖慢速度？策略：

• 区分“稳固核心”与“可变细节”：CodeSpec 应聚焦于相对稳定的核心领域概念、实体、关键业务规则和状态。对于UI交互细节、算法参数、文案等易变部分，不应放入 CodeSpec，而是通过配置表或特性开关管理。
• 拥抱迭代：CodeSpec 本身也是代码，应该小步快跑地迭代。鼓励团队频繁地、增量地更新规格，而不是攒一个大变更。CI 的检查机制能确保每次小变更都不会破坏现有功能。
• “占位符”与“TODO”：对于尚未明确的部分，可以在 CodeSpec 中使用明确的标记，如decision_pending: true或注释TODO: 与支付团队确认退款规则。生成器看到这些标记，可以生成相应的提示或空结构，而不是阻塞流程。

5.3 与现有代码库和流程的集成

问题：如何在已经运行了多年、有大量遗留代码的项目中引入 CodeSpec？策略：

• “由外向内”侵蚀：不要试图一次性为整个系统编写 CodeSpec。从下一个全新的、边界清晰的模块或特性开始。让新模块完全遵循 CodeSpec 流程，与老模块通过定义良好的接口（这些接口本身可以用 CodeSpec 来定义）通信。
• “逆向工程”现有核心模块：对于最关键、最复杂的遗留模块，可以尝试为其“补写”CodeSpec。这个过程本身就是一个极佳的代码理解和文档化过程。补写的 CodeSpec 不一定用于生成代码，但可以作为该模块的权威行为描述，指导未来的重构。
• 工具链的渐进接入：可以先引入 CodeSpec 的“文档和验证”部分，即只编写 YAML，并用它来生成测试用例，用于验证现有代码的行为是否符合预期。暂不进行代码生成。等团队适应后，再逐步引入代码生成。

5.4 性能与复杂度管理

问题：当系统非常庞大，一个 CodeSpec 文件可能变得极其冗长，难以维护。策略：

• 模块化与引用：支持 CodeSpec 文件的模块化。可以定义一个common.codespec.yaml存放共享的实体（如User，Account）。其他特性规格文件可以通过$ref的方式引用这些共享定义。编译器需要支持这种引用解析。
• 关注点分离：将不同层面的规格分开。例如，用domain.codespec.yaml定义领域模型和业务规则，用api.codespec.yaml定义接口，用workflow.codespec.yaml定义长流程。它们之间可以相互引用。
• 工具优化：对于大型项目，编译和生成代码的时间可能变长。需要对编译器进行性能优化，并支持增量编译（只处理发生变更的文件）。

5.5 对“Agentic”未来的准备

问题：如何让 CodeSpec 更好地适配 AI 智能体协作？策略：

• 提供结构化的上下文导出：除了人类可读的 YAML，可以设计一个更精简、更适合 AI Agent 理解的 JSON 格式，包含任务、实体、约束的清晰脉络。
• 定义“Agent 可执行指令”：在 CodeSpec 中，可以增加一个特殊的agent_tasks部分，用更接近自然语言但结构化的方式描述你希望 AI 助手完成的具体任务。例如：

  agent_tasks: - id: implement_upgrade_logic target: src/services/subscription/upgrade.ts instruction: | 请实现 `BaseSubscriptionService` 中的 `onUpgradeStarted` 方法。 需要：1. 调用支付服务创建升级订单；2. 记录审计日志；3. 发送通知邮件。 相关实体和接口定义请参考本规格文件。

• 将 CodeSpec 作为 Agent 的“事实来源”：在构建内部 AI 开发助手时，可以训练它或提示它，在回答任何关于系统行为的问题时，优先查询并引用最新的 CodeSpec 文件，确保建议与既定规格一致。

引入 CodeSpec 和双可执行规格的理念，确实需要前期的投入和习惯的改变。它有点像在软件开发中引入“强类型”系统：一开始可能会觉得繁琐，但一旦适应，它带来的在大型项目、长周期开发中的安全性、可维护性和协作效率的提升是巨大的。它尤其为未来人机协同的“Agentic”开发模式打下了坚实的基础。如果你所在的团队正在被复杂系统的需求一致性问题所困扰，不妨从一个试点项目开始，尝试一下这条路径。