架构与设计文档:AI时代的“新原始码”

过去我们经常讲所谓10倍工程师，意思大致是：同样的需求，给不同工程师可能会有10倍的差异。而在AI的加持下，这个差距可能会更大，有人生成的代码直接能用，有人生成的代码全是坑。

差别在哪？可能关键在于有没有一份高质量的架构与设计文档。

一个被重新定义的概念

先说个大家都应该要接受的观点：在 AI 编程时代，架构与设计文档不再是「给人看的说明书」，而是「给 AI 读的源代码」。

传统软件工程强调先设计后编码——需求分析、架构设计、数据库设计、接口设计等等，这些准备工作做完才应该开始写代码（事实上，很多项目这点都做不到，包括自己以前经历过的很多项目）。这个流程本身没问题。但问题在于：传统模式下，文档和代码是分离的，代码才是「真相之源」，文档只是辅助性的解释说明，容易过期、容易与实际脱节。

AI 时代，这个关系被彻底颠倒了。

💡 业界类比：高级语言通过编译器编译成二进制产物，重要的是高级语言代码，二进制产物可以随时重新生成。Spec 就像是高级语言代码，而 AI 就是编译器，代码只是「编译产物」。

这意味着你维护的核心对象变了。以前维护的是代码，文档只是辅助；现在维护的是 Spec，代码可以随时让 AI 重新生成。Spec 成为「真理之源」，代码是派生的。

Spec 到底是什么？

Spec 是对软件系统行为、接口、数据格式或业务规则的精确、无歧义、可验证的描述。在 AI Coding 中，它扮演着「宪法」的角色——明确告诉 AI：「代码必须满足哪些条件才算正确」，而不是让模型自行猜测、模仿或凭「感觉」生成。

其核心价值体现在两个层面：

规范即契约：Spec 是开发者、AI Agent 与系统之间达成的共识性「契约」，清晰界定「做什么」、「为什么做」以及「如何做」。

AI 的指令集：为大语言模型提供明确、结构化的上下文，显著减少幻觉，提升生成代码的准确性与一致性。

Spec 在 AI 工作流中的三个角色

🗺️ 角色一：Agent 推理的地图

OpenAI 有一条实践原则：「要给 Codex 的是一张地图，而不是一本 1000 页的说明书。」地图有目录、有指针，Agent 从高层概览出发，按需深入到具体节点。没有这张地图，Agent 的起点是代码——而代码只告诉它「系统现在是什么样」，不告诉它「为什么是这样」、「哪些是不应该改的」。

⚖️ 角色二：约束生效的语义基础

Linter 和结构测试可以机械地强制执行架构规则，但 Linter 检查不了语义。它不知道「某个错误码在跨服务场景下应该怎么处理」，不知道「某个接口字段在特定场景下的业务含义」。这些语义，必须被显式写下来，Agent 才能正确推理。

🧠 角色三：可继承的工程记忆

AI Coding 加速了一个已有的问题：知识随人和会话流失。大量设计决策、跨服务约定、「为什么不选另一个方案」的讨论，全部停留在一次性的 AI 对话里。Spec 把这些知识从「人脑+对话历史」转化为「仓库里版本化的结构化资产」。人可以换，AI session 可以换，但 Spec 留下来。

一套实用的 Spec 体系该怎么建？

根据实践，这套体系至少包含三个层次：

层次	内容	位置
第一层：项目级规则	代码风格、技术栈约束、安全性能红线、测试要求	项目根目录
第二层：架构与设计文档	接口契约、领域模型、验收条件（活文档，与代码同步）	product-specs / design-docs
第三层：上下文知识库（RAG）	特有业务术语、历史决策、跨团队约定	RAG 知识库

Spec 驱动的标准工作流

Phase 1：意图定义与文档生成 Step 1（人）：提供简要的意图和上下文。 Step 2（AI）：让 AI 草拟详细的技术文档。 Step 3（人）：核心环节！你必须阅读并修改这份文档，确保 AI 理解了你的真实意图。只有当你「锁定」这份文档后，才能进入下一阶段。

Phase 2：AI 编译 将上述文档喂给 AI，让它严格按照其中的步骤生成代码。

Phase 3：文档验收 如果发现代码逻辑不对，不要直接动手改代码。正确做法是回到 Spec，修改描述不清楚的地方，然后让 AI「重新编译」。

⚡ Spec 消灭的是返工，不只是提速：规范驱动方法优化的不是「写出第一版代码的速度」，而是「正确交付的总成本」。没有 Spec 时，跨服务的歧义要等到联调才暴露，边界条件要等到上线后才被发现，每次新的 AI 会话都要从零重建上下文。这些隐性成本，加起来远超写 Spec 的投入。

架构师的新能力要求

写 Spec 的过程，本质上是在回答一个追问：

系统需要什么能力？

这个能力的边界在哪里？

行为规则是什么？

失败的场景怎么处理？

这些信息怎么组织才能让 Agent 既能读懂又能执行？

这个能力——「把模糊意图转化为精确、结构化、可被 Agent 消费的定义」——正变得越来越重要。

结语：Harness 越强，Spec 越重要

Harness Engineering（通过构建结构化环境与反馈回路使 AI Agent 可靠工作的系统方法论）正在成为行业共识。但 Harness 是放大器，它放大 Agent 的执行能力，也放大输入给 Agent 的内容的影响。

Spec 写得好，Harness 把它放大为可靠的、一致的、可验证的输出。Spec 写得差或者根本没有，Harness 把 Agent 的猜测放大为高效率地产出错误。

引擎越强，导航越重要。高速公路的护栏比自行车道更必要，不是因为车更危险，而是因为速度更快、后果更严重。

在 AI 时代，它不再是文档，而是新的源代码。

写于 2026 年春

如有共鸣，欢迎转发与讨论 💬