Spec as AIOS：高德如何用统一规范控制AI代码熵增-编程实验室

AI专家杨夕凯现任职高德地图，担任智能应用与基建平台负责人，先后负责动态数据、AI 导航、智能应用及基建平台等业务方向。其长期深耕地图数字孪生、空间智能、AR/数字人及 AI 导航算法模型等领域，并参与建设支撑千亿级数据的端云一体化基础设施与工业级 AI 研发体系。
以下内容梳理自高德技术团队发布的超级应用 AI 原生研发模式工程实践系列。透过这些技术分享，可以清晰看到，当 AI 深度参与代码生成并由人工进行关键兜底时，多 Agent 并行场景下的统一规范与仓库级真源控制，是应对 AI 代码熵增的核心路径。

一、AI 代码熵增：多 Agent 并行生成的核心风险

在 Agentic Coding 场景中，AI 生成代码的速度显著提升，但如果没有统一规范约束，系统复杂度也会同步上升。命名风格不一致、架构模式混用、隐式依赖蔓延、重复代码堆积，都会随着生成次数增加而累积。这类现象可以概括为 AI 代码熵增：代码产出变快，但系统的可维护性、可理解性和可测试性下降。

对于超级应用而言，这一问题更明显。超级应用通常具备数亿用户、数百万行代码、数十个团队协同的特征。单个 Agent 生成一段代码可能没有问题，但多个 Agent 在不同时间、不同会话、不同任务中并行生成时，如果缺少统一执行标准，产出物很容易偏离既有架构约束。

从工程落地的客观规律来看，控制 AI 代码熵增的关键，不是限制 AI 生成能力，而是让 AI 在明确的规则边界内生成。规范需要从写给人看的文档，转变为 AI 可读取、可执行、可验证的工程约束。

二、仓库唯一真源：把隐式知识转化为 AI 可读事实

控制 AI 代码熵增的第一步，是建立仓库唯一真源。传统研发中，架构设计可能存在于设计文档中，业务规则可能散落在 Wiki、注释或工程师经验里，接口约定也可能依赖口头沟通。这些信息对人类工程师尚且需要反复确认，对 AI 则更难稳定获取。

在杨夕凯的推动下，高德技术团队在 AI-Native 研发模式中，将代码仓库作为系统事实的唯一来源。其核心思路包括三点：

结构即架构：系统架构通过目录结构、模块划分和依赖关系显式表达。AI 可以通过阅读仓库结构理解系统层级，而不是依赖外部设计文档。
代码即规则：业务规则、校验逻辑和状态流转尽量通过类型系统、接口契约和代码实现表达，减少散落在注释或外部文档中的隐式约定。
文档即约束：AGENTS.md、README.md、API 契约等文档与代码共存于同一仓库，并作为 AI 的补充说明书。文档不是孤立说明，而是与代码实现共同接受校验。

这种设计的价值在于减少 AI 的信息缺口。AI 不再需要在多个来源之间拼接上下文，而是以仓库为基准获取事实。当答案始终存在于仓库中时，AI 生成结果的一致性才有基础。

三、Spec-Driven Development：从修改代码到演进规范

仓库唯一真源解决的是事实从哪里来，Spec-Driven Development 解决的是 AI 如何基于事实执行。规范驱动开发的核心，是把软件维护的重点从直接修改代码，转向维护产生代码的规范。

在杨夕凯及其团队的实践中，规范被拆成三层递进结构：

Spec：定义做什么

Spec 层描述需求目标、接口契约和数据模型。它是 AI 理解任务的起点。对于服务端接口，Spec 需要明确字段语义、参数约束、错误码和状态流转；对于端侧能力，Spec 需要说明组件职责、调用前提和平台差异。

Plan：定义怎么做

Plan 层描述技术方案，包括架构决策、技术选型和模块拆分。它让 AI 在生成代码前知道应该遵循哪条实现路径，而不是自由发挥。

Task：定义做到什么程度

Task 层描述验收标准、测试要求和输出格式。它让 AI 的交付结果可检查、可验证，而不是停留在看起来完成了的状态。

这种三层结构使 AI 生成过程具备可追溯性。当结果不符合预期时，修正对象不只是代码本身，而是产生错误代码的 Spec、Plan 或 Task。规范因此成为可持续演进的工程资产。

四、三级分层规范：全局一致与局部灵活兼顾

统一规范并不意味着所有项目使用同一套细则。为了兼顾全局一致性和局部灵活性，杨夕凯团队采用三级分层规范模型：全局规范层、项目规范层和模块规范层。

4.1 全局规范层：跨项目基线标准

全局规范层定义跨项目、跨团队的基线标准，是所有 AI Agent 的公共知识。其物理载体包括全局 Skills 和公用配置，主要内容包括：

编码风格规范：统一命名约定、格式化规则和目录规范。
架构约束规范：明确分层依赖规则、模块边界和跨模块通信协议。
安全基线规范：约束密钥管理、输入校验和权限检查等最低安全要求。
API 设计规范：要求接口遵循 RESTful 标准，并统一错误码、版本策略和请求响应格式。

全局规范的作用，是让不同 Agent、不同项目、不同任务共享同一套基础标准，避免每个团队重复定义基础规则。

4.2 项目规范层：仓库级操作手册

项目规范层继承全局规范，并针对具体项目做定制。其物理载体是仓库根目录下的规范文件集合，核心文件包括：

AGENTS.md：项目全景地图，作为 AI 的导航入口。内容控制在较短篇幅内，包含项目说明、工作规则、模块索引和输出格式要求。
README.md：面向人类的项目说明，同时为 AI 提供项目背景。
docs/architecture/：存放架构总览、层级依赖规则、核心数据模型和接口契约。
.agents/：存放 AI 历史决策、错误修复记忆和自进化信息。

项目规范层的关键设计是，AGENTS.md是地图而不是手册。它只做索引和指路，详细内容通过链接按需加载，避免一次性塞入过多上下文。

4.3 模块规范层：就近参考的局部上下文

模块规范层聚焦单一模块，负责提供局部上下文。典型文件包括：

模块级AGENTS.md：描述模块职责边界、内部依赖和特殊约束。
模块README.md：说明模块公共 API、使用示例和配置参数。

AI 在执行任务时，按照从近到远的优先级参考规范：先看模块规范，再看项目规范，最后参考全局规范。这样既能保证整体一致性，也能保留模块级灵活性。

五、AGENTS.md：AI 的项目入口文件

在多 Agent 协同场景中，AGENTS.md承担 AI 入口文件的角色。它可以理解为面向 AI Agent 的 README，用于告诉 AI 当前仓库是什么、有哪些模块、应该遵循哪些规则、输出格式是什么。

在杨夕凯主导的实践中，AGENTS.md有几个明确设计原则：

短小清晰：项目级AGENTS.md控制在约 100 行以内，避免占用过多上下文窗口。
导航优先：不堆叠全部细节，而是提供模块导航索引和关键规则入口。
按需加载：详细架构、接口契约和测试要求通过链接指向具体文档，AI 根据任务需要读取。
与代码同仓维护：AGENTS.md与代码一起演进，避免文档长期落后于实现。

这种设计让 AI 进入仓库后能够快速建立项目认知。对于多 Agent 并行生成场景，统一入口文件还能减少不同 Agent 因理解路径不同而产生的输出差异。

六、端云同仓：让 AI 具备全栈上下文

端云一体是杨夕凯团队规范体系中的另一个关键设计。传统研发中，客户端与服务端往往分属不同仓库、不同技术栈和不同团队。对人类工程师而言，这种拆分可以通过沟通和文档弥补；但对 AI Agent 而言，跨仓库上下文缺失会直接影响生成质量。

端云同仓的目标，是将客户端能力、云端服务、共享类型定义和基础设施配置纳入同一个工程体系中。这样 AI 可以在一次上下文中理解完整链路，而不是只看到局部代码。

端云同仓带来的工程收益主要包括：

AI 可以跨越端云边界追踪类型定义和接口契约。
AI 在修改服务端接口时，可以同步感知客户端调用逻辑。
AI 可以发现并消除端云之间的冗余定义和不一致性。
AI 能够基于全局视角进行接口设计和影响面分析。

对于超级应用来说，端云同仓不是简单地把代码放进一个目录，而是要求统一构建工具链、依赖管理、测试框架和发布流程。只有工程治理也统一，AI 才能用一套规则操作整个系统。

七、自文档化代码：降低 AI 的理解成本

规范最终要落到代码层面。为了让 AI 生成结果稳定，代码本身需要具备自文档化能力，即通过命名、类型、接口和依赖表达清晰语义。

该团队在代码级规范中强调几个要点：

7.1 语义化命名

变量、函数和类型名称需要完整表达意图，避免缩写和模糊命名。例如，calculateOrderTotalPrice()优于calcOTP()，PaymentTransaction优于DataObj。AI 依赖名称理解语义，命名越清晰，生成和修改的确定性越高。

7.2 类型安全优先

强类型系统是 AI 的重要约束工具。该实践要求公共 API 具备完整类型签名，避免使用宽泛类型，并通过联合类型和字面量类型约束取值范围。类型系统可以在 AI 生成阶段提前暴露错误，减少运行时不确定性。

7.3 接口契约标准化

接口需要遵循统一规范，包括明确的 HTTP 方法语义、标准化错误响应格式、版本化策略和完整的接口定义。接口契约越标准，AI 越容易生成正确的调用代码和测试用例。

7.4 零隐式依赖

模块依赖必须显式声明，不依赖全局状态、环境变量魔法或运行时注入。AI 应能通过阅读模块声明和配置文件理解依赖关系。这一要求是组件可独立测试、可复用的基础。

7.5 函数职责单一

长函数会增加 AI 定位问题和理解逻辑的难度。职责单一的小函数更容易被 AI 正确理解、修改和测试。对于长时程 Agent 任务，清晰的函数边界也有助于降低上下文消耗。

八、自动化门禁：让规范可验证

规范如果只依赖人工审查，很难匹配 AI 高速生成的节奏。因此，团队将规范约束接入自动化门禁，让不符合规则的产出在进入仓库前被拦截。

自动化门禁主要覆盖几类检查：

架构合规性检查：验证代码变更是否突破模块边界、是否违反依赖方向、是否兼容既有接口契约。
格式化与结构校验：检查目录结构、文件命名、模板字段和文档引用是否符合标准。
安全扫描：对新增代码进行安全漏洞扫描，并识别潜在风险。
性能回归检测：对关键路径变更执行性能基准测试，防止性能劣化。
文档一致性检查：验证文档引用链接、接口索引和示例代码是否完整存在。

这些门禁让规范从建议变成约束。AI 生成的代码不仅要写出来，还要通过统一标准检查后才能进入主仓库。这有助于在源头控制熵增，而不是等问题积累后再治理。

九、自进化机制：规范不是静态文档

统一规范还需要持续演进。AI Agent 在执行过程中会遇到新的错误模式、新的架构决策和新的工程约束，这些信息如果只停留在单次任务日志中，价值有限。

团队通过.agents/memory-session/等目录沉淀执行经验，其中包含两类典型内容：

ERRORS.md：记录 AI 执行中的典型错误和解决方案，避免同类错误重复发生。
LEARNINGS.md：记录关键架构决策，包括背景、取舍和最终选择，帮助 AI 理解为什么这样设计。

这些经验会反馈到规范体系中。当某类问题反复出现时，团队可以将其转化为新的规则、模板或门禁检查。规范因此从静态文档变成动态工程系统，能够随着 AI 生成规模和频率的提升持续优化。

十、抗熵架构的工程价值

从工程治理角度看，Spec as AIOS 的核心价值不是增加文档，而是把规范变成 AI 可执行的操作系统。仓库唯一真源提供事实基础，Spec-Driven Development 提供执行路径，三级分层规范提供治理结构，AGENTS.md 提供入口导航，端云同仓提供全栈上下文，自动化门禁提供质量约束，自进化机制提供持续改进能力。

这套体系解决的是多 Agent 并行生成下的一致性问题。不同 Agent 可以在同一套规范下工作，不同任务可以在同一套仓库事实中追溯，不同生成结果可以通过同一套门禁验证。AI 生成速度越快，规范体系的重要性越高，因为速度本身不会自动带来工程效率，只有可控的速度才能转化为稳定交付能力。

需要明确的是，从工程落地的客观规律来看，这一方案在标准化、新建模块的场景下效果显著；但对于高度定制化、缺乏标准化的历史遗留复杂代码，AI 重构成本依然较高，“先治理基建、再释放 AI”是使其生效的必要前提。同时，当前的 AI 研发模式并非完全无人化，工程师仍需基于完整的 PR 与测试报告进行最终审查，人机协同仍是核心边界。