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.mdAI 的项目入口文件在多 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 与测试报告进行最终审查人机协同仍是核心边界。十一、未来方向从规范约束到深度托管随着 AI Agent 能力增强软件研发正在从人机协作走向 AI 深度参与、人工关键兜底的深度托管模式。统一规范是这一过程中的基础设施它让人类定义规则和边界让 AI 在规则内执行编码、构建、测试和修复。未来规范体系还可能进一步与生产线、评测系统和经验记忆深度结合。规范不再只是项目文档而是持续学习的工程治理系统。它会根据真实任务反馈调整约束会根据不同场景验证适用范围也会根据 Agent 执行数据优化生成质量。对于超级应用而言控制 AI 代码熵增不是一次性工程而是长期演进过程。只有当规范、仓库、门禁和生产线形成闭环AI 原生研发才能从快速生成走向稳定交付。