1. 项目概述为什么“代码不是资产规格才是”最近几年尤其是在深度参与几个遗留系统Brownfield的现代化改造项目后我越来越清晰地意识到一个可能颠覆我们传统认知的观点我们一直守护的“圣杯”可能错了。我们投入大量精力去重构代码、编写测试、争论命名规范和目录结构仿佛代码库本身是公司最珍贵的资产。但真相是代码正在迅速贬值而真正昂贵、真正构成核心竞争力的是那些隐藏在代码背后、却从未被系统化记录下来的东西——规格Specification或者说是系统的“意图”与“约束”。这个想法的萌芽源于一次痛苦的迁移经历。我们手头有一个运行了多年的老系统代码齐全测试覆盖率也不低CI/CD流水线健全。从技术债管理的角度看它似乎“状态良好”。但当我们需要将其核心逻辑迁移到一个新的技术栈和架构时噩梦开始了。我们花了远超预期的时间不是在写新代码而是在反复追问“这段逻辑为什么是这样”“这个奇怪的边界条件是有意为之还是当年某个Bug的临时补丁”“为什么这里要用Bcrypt而不用更现代的Argon2”答案散落在早已离职同事的记忆里、2018年的Confluence页面深处或者某个已被归档的Slack频道。代码知道“怎么做”但它对“为什么”和“不可以做什么”一无所知。这让我明白我们真正缺失的是一份独立于代码、清晰描述系统“灵魂”的规格说明书。如今随着AI编程助手和智能体AI Agents的能力爆炸式增长这个矛盾被急剧放大。生成一段能通过编译、甚至通过基础测试的代码成本正趋近于零。真正的瓶颈不再是“我们能否写出代码”而是“我们是否清楚这代码究竟该做什么以及为什么必须这样做”。AI可以轻易地为你重写一个函数但它无法告诉你这个函数背后的业务规则是源于某个已废止的行业法规还是因为与某个关键下游系统有一个隐晦的握手协议。当实现Implementation变得廉价规格Specification就成了最稀缺的资源。我们保护错了对象未来的工程实践必须从“代码优先”转向“规格优先”。2. 核心理念拆解从“代码资产论”到“规格资产论”2.1 传统“代码资产论”的局限与时代背景在过去几十年软件工程的发展中“代码即资产”的观念根深蒂固。这有其历史合理性。代码的编写、调试、测试和部署曾是一项高度专业化、耗时费力的工作。一次重写意味着数月甚至数年的投入迁移伴随着巨大的风险和成本。因此我们发展出了一整套围绕代码资产保值增值的方法论设计模式、重构、单元测试、持续集成。我们像呵护古董一样呵护代码因为它是系统功能的唯一权威载体。然而这种模式的根本缺陷在于代码是一种极其“低信噪比”的载体。它忠实地记录了“如何实现”却几乎完全丢失了“为何如此”的上下文。例如你看到一段复杂的加密逻辑代码只会展示使用了Bcrypt算法和特定的盐值长度。它不会告诉你选择Bcrypt是因为必须满足支付卡行业数据安全标准PCI DSS的特定要求而那个盐值长度是经过安全团队评估在性能与安全性之间的最佳折衷。它更不会记录团队曾评估过Scrypt但因其在当时硬件上的性能开销而被否决。这些决策逻辑和约束条件才是让这段代码有意义的“元信息”但它们却存在于代码之外脆弱地依赖于人的记忆和零散的文档。2.2 AI时代下的范式转移规格成为新的瓶颈AI代码生成工具的普及彻底改变了游戏规则。现在一个清晰的指令可以在几分钟内产出一个功能模块。开发者的角色正从“代码的撰写者”加速向“意图的定义者”和“约束的阐述者”转变。问题的核心变成了我们能否清晰、无歧义地向AI以及未来的团队成员描述我们要什么以及为什么必须是这个而不是那个在遗留系统场景中这一点尤为致命。AI可以轻松分析你的代码库并生成一个“功能等效”的新版本。但如果它不了解那些隐性的约束——比如某个看似冗余的数据库查询是为了兼容一个即将被淘汰但仍有重要客户在用的外部接口——那么新系统上线就是灾难的开始。迁移的成本从“重写代码”转移到了“挖掘和理解深埋于代码中的业务规则、历史决策和系统约束”。后者才是真正昂贵、充满不确定性的部分。因此规格Spec——这个对系统意图、约束和边界的正式描述——的价值被前所未有地凸显出来。它不再是可有可无的文档而是保障系统正确演化、特别是人机协作Human-AI Collaboration的关键资产。2.3 “规格资产”的具体内涵超越传统文档那么我所说的“规格”具体指什么它远不止是API接口文档或用户故事。它是一个结构化的知识库至少包含以下几个维度功能性意图What Why系统或模块要完成的核心任务是什么背后的业务目标或用户价值是什么这部分接近传统需求但更强调“目的”而非“功能列表”。约束与边界Constraints Boundaries这是规格的骨架。包括合规性约束如“必须使用FIPS 140-2认证的加密模块”。性能约束如“第95百分位API响应时间必须小于200毫秒”。集成约束如“必须向后兼容v1.2版本的客户端SDK因为主要合作伙伴尚未升级”。业务规则如“用户账户在连续三次登录失败后必须锁定24小时此规则由安全审计要求驱动”。决策日志Decision Log记录关键架构和技术决策包括被采纳的方案及其理由以及被否决的替代方案及其被否决的原因。这是防止团队重复踩坑的宝贵财富。信心等级Confidence Levels承认规格的不完美性。对每条信息标注信心度如Confirmed/已验证 Inferred/推断 Uncertain/存疑让读者了解信息的可靠程度。这样的规格才是伴随系统整个生命周期的、真正的“资产”。代码可以随技术迭代而重写但只要业务核心不变这些规格就具有持久的价值。3. 实践方案一种面向人与AI的双层规格格式认识到规格的重要性后我着手设计一种实用的格式来承载它。目标很明确它必须对人类友好便于阅读、讨论和编辑同时也必须对AI友好能让AI智能体高效地理解并运用其中的约束。最终我设计了一个双层格式并将其开源为Derive Spec项目。3.1 第一层人类可读层Markdown YAML Frontmatter这一层的设计原则是极简和通用。它本质上是一个带有YAML前置元数据的Markdown文件。任何能阅读Markdown的工具GitHub, VS Code, Obsidian等都能处理它确保了最低的采用门槛。--- module: “payment_processor” version: “0.1” confidence: “evolving” # 整体规格信心 --- # 支付处理模块规格 ## 概述 处理用户信用卡支付授权与捕获。核心价值是在满足合规要求的前提下提供高可用的支付服务。 ## 入口点 - process_payment(amount, card_token, user_id) - PaymentResult - 信心度: **Confirmed** (可通过代码静态分析验证) - 约束: 必须为幂等操作由上游网关重试机制驱动。 ## 关键约束 ### 安全性约束 - **PCI DSS合规**: 所有卡号数据在存储和传输中必须加密。 - 理由: 公司作为二级服务商与收单行合同要求。 - 技术体现: 使用Bcrypt成本因子12哈希卡号指纹密钥由HSM管理。 - 被否方案: 曾考虑应用层加密但因密钥轮换复杂度高而放弃。 ### 性能约束 - **P95延迟 300ms**: 从接收到外部支付网关响应。 - 理由: 用户体验指标直接影响购物车放弃率。 - 监控指标: payment_gateway_latency_seconds ### 业务逻辑约束 - **双重扣款防护**: 同一订单ID在5分钟内仅允许一次成功的支付授权。 - 理由: 防止网络超时导致前端重复提交。 - 实现提示: 依赖Redis分布式锁键格式为 lock:payment:{order_id}TTL为300秒。注意YAML部分用于机器可读的元数据而Markdown部分则用自然语言和结构化的标题来组织内容。这种结合让开发者既能快速浏览又能通过工具进行一定程度的自动化处理。3.2 第二层AI优化层编译后表示人类可读的格式对AI来说可能冗长且低效。因此Derive Spec包含一个编译器或转换器可以将第一层的规格“编译”成一种对AI Agent更友好的表示形式。这通常是一个结构化的数据格式如JSON Schema它提取关键实体和关系将“入口点”、“约束”、“理由”等元素转化为结构化的节点和边。进行令牌Token优化使用更简洁的键名和值减少大型语言模型LLM处理时的上下文长度消耗。嵌入信心度元数据让AI了解每条信息的可靠程度从而在决策时分配不同的权重。当AI智能体需要修改payment_processor模块时它不再需要通读成千上万行代码和散落的文档而是直接请求或加载这个编译后的规格。它能立刻知道“哦这里修改加密算法会违反PCI约束而且之前考虑过应用层加密但被否决了原因是密钥管理复杂。”这极大地提升了AI工作的准确性和安全性。3.3 信心度模型拥抱渐进式与不确定性一个常见的反对意见是“编写和维护规格本身就是一个巨大的负担”为此我引入了信心度模型。规格不是二元的“完成”或“未完成”状态而是一个渐进的、覆盖度与信心度共同增长的梯度模型。Confirmed已验证该信息可以直接从代码结构中推导或验证。例如工具可以静态分析出某个函数是幂等的或者某个API端点确实存在。这是信心度最高的层级。Inferred推断基于代码模式、注释或相关文档的高置信度推断。例如根据代码中特定的错误处理模式推断出某个服务必须高可用。Uncertain存疑信息来自模糊的记忆、过时的文档或需要进一步确认的讨论。这是需要人工介入审查和确认的信号。这个模型的美妙之处在于它允许团队“按需规格化”。你不需要一开始就为整个百万行代码库编写完美的规格。而是从你正在修改或理解最困难的模块开始写下你所知道的并诚实地标记信心度。随着时间推移规格的覆盖面和信心度会像测试覆盖率一样有机增长。“不确定”的标签本身就有价值它明确指出知识缺口引导协作和决策。4. 在遗留系统改造中的实战应用4.1 场景支付网关迁移假设我们需要将上述示例中的支付模块从老旧的提供商迁移到新的云支付服务。传统做法是深入代码理解所有调用、错误处理和业务逻辑然后重写。采用规格优先的方法后工作流变为知识提取与规格化首先不是直接看代码而是召集熟悉该模块的工程师、产品经理和安全专家围绕“支付处理模块的规格”进行讨论。我们将已知的约束PCI DSS、性能SLA、防重放逻辑写入Derive Spec文件并标记信心度。对于模糊的地方明确标记为“Uncertain”。缺口分析与确认那些“Uncertain”的条目就成了我们的调研清单。我们需要通过代码考古、日志分析、甚至联系原开发者来确认。例如确认“5分钟防重放锁”的具体时长是否是一个硬性业务规则还是当年的随意取值。基于规格进行迁移设计拿着这份相对完整的规格设计新系统的架构。我们可以明确地评估新的云支付服务是否满足所有约束尤其是合规性约束。AI助手也可以基于这份规格生成大致的迁移代码框架并确保不违反核心约束。验证与迭代新代码开发过程中持续对照规格进行验证。同时将新发现或变更的约束更新到规格文件中使其保持为最新的“单一可信源”。这个过程将最大的风险——对旧系统意图的误解——提前并显式地管理起来。虽然前期投入了时间编写规格但它在整个迁移周期中减少了反复、避免了重大返工总成本往往更低。4.2 工具链与集成思路要让Derive Spec这类格式落地需要简单的工具链支持规格文件生成器可以从代码注释如JSDoc、Go Doc、API定义OpenAPI/Swagger、甚至架构决策记录ADR中提取初始信息生成一个带有“Inferred”信心度的规格草稿大幅降低启动成本。IDE插件在VS Code或JetBrains系列IDE中提供语法高亮、片段Snippet自动完成、信心度标签快速插入等功能。更高级的插件可以在你阅读代码时侧边栏显示关联的规格条目。CI/CD集成在拉取请求PR流程中可以检查被修改的模块是否关联了规格文件。如果关联了可以自动将规格的变更部分呈现给评审者确保代码变更与设计意图的一致性。AI智能体接口提供标准的API或SDK让AI编程助手如GitHub Copilot、Claude Code能够查询和解析编译后的规格使其在建议代码时具备上下文感知能力。实操心得在团队内推广时不要追求大而全。从一个最痛苦、最复杂的“历史包袱”模块开始用它作为试点。当团队尝到在重构或答疑时能快速从规格中找到“为什么”的甜头后自发采用的动力会强得多。把它当作一种“知识债”的偿还工具而不是额外的文档负担。5. 常见问题与挑战5.1 规格会不会变成另一种形式的、没人维护的文档这是最关键的挑战。传统的设计文档最终腐烂是因为它们与代码生命周期脱节。Derive Spec试图通过几种机制解决与代码共位置规格文件.spec.md建议放在与对应源代码相同的目录下。修改代码时很容易看到并同步更新旁边的规格文件。低维护成本的格式Markdown是开发者最熟悉的格式之一比维护UML图或专门的文档工具要轻量得多。信心度模型允许“不完整”和“不确定”的状态存在降低了维护的心理门槛。它更像一个活的、不断修正的“思维导图”而非一份需要完美无缺的正式合同。工具辅助通过CI检查、PR提醒等轻度工具链将其纳入开发流程形成习惯。5.2 这会不会增加开发的前期开销短期看是的。为现有模块创建初始规格需要时间。但从整个软件生命周期尤其是包含维护、迁移、人员更替的周期来看这是一种投资。它节省的是未来无数个小时的“考古”时间、减少的是因误解导致的线上故障。在AI辅助编程时代这份投资回报率正在急剧升高因为清晰的规格能极大提升AI生成代码的可用性和准确性。5.3 如何保证规格的真实性和准确性无法100%保证但信心度模型提供了透明性。一个标记为“Inferred”的约束读者会带着审慎的态度看待。团队文化需要鼓励“修正规格”和“标记不确定”的行为视其为有益的贡献而非暴露无知。定期如每个季度对核心模块的规格进行“健康度检查”可以作为技术债梳理的一部分。5.4 对于全新的绿地Greenfield项目也适用吗完全适用而且可能更有效。在项目初期规格文件可以作为团队对齐设计意图的活文档。随着代码的实现不断将“Confirmed”的信息补充进去。这相当于在项目一开始就构建了系统的“知识骨架”对于后续加入的成员和未来的维护者是无价之宝。6. 未来展望规格驱动的软件工程我认为我们正处在一个范式转变的拐点。未来的软件工程尤其是面对复杂、长生命周期的企业系统时“规格”的地位将等同于甚至高于“代码”。规格即合约Spec as Contract在微服务或跨团队协作中规格文件将成为服务间、团队间正式的、可执行的合约。不仅定义API更定义行为约束和服务水平目标SLO。AI原生开发AI-Native DevelopmentAI智能体将成为开发团队中的“初级工程师”或“专家系统”。它们的主要输入和行动指南将是结构化的、机器可读的规格。人类工程师的角色将更侧重于制定策略、定义约束和进行高层次的创造性设计。自动化验证与测试生成基于形式化或半形式化的规格可以自动生成更全面的集成测试用例甚至进行属性测试Property-based Testing验证系统行为是否始终符合规格中定义的约束。动态系统理解与导航对于大型遗留系统一个覆盖全面的规格库将成为新入职开发者的最佳导航图。他们可以通过查询规格快速理解某个模块的职责、约束和历史决策而不是在代码的海洋中盲目摸索。这条路才刚刚开始像Derive Spec这样的格式只是非常初步的探索。真正的挑战在于工具链的完善、社区最佳实践的形成以及开发团队思维模式的转变。但方向是清晰的代码会来来去去而关于系统为何存在的“意图”和“约束”才是我们真正需要精心维护、代代相传的终极资产。我们保护的不再是砖块代码而是蓝图规格。在这个AI加速代码生产的新时代是时候将我们的工程智慧更多地倾注在创造清晰、稳健、可传承的蓝图之上了。
