面向Skills编程：用领域知识工程驱动 Code Agent

本文是阿里妈妈效果创意中心团队在 AI Coding 领域的探索实践分享。我们围绕一个核心问题展开：如何通过构建领域知识工程体系，让 Code Agent 在复杂业务项目中真正可用。

一、两个痛点，一个方向

1. 重构中的知识断层

在25年，团队对核心工程的架构进行了一次重大升级重构。整个过程中，梳理旧业务流程占用了大部分时间。不是代码看不懂，而是反复遇到知识断层：

• 遇到不知前因后果的业务逻辑——为什么有这个分支？这个字段为什么这样处理？

• 查阅文档，要么没有，要么过时对不上

• 最终只能去找之前负责的同学，人不在，知识就断了

这种痛苦贯穿了重构项目的梳理、设计和开发的全阶段。我们意识到，必须系统性地构建和管理业务知识，不能再让同样的困境重复发生。

2. AI Coding 在复杂项目中撞墙

同年 AI Coding 彻底火爆，团队开始在日常开发中使用 Code Agent。一些问题修复、小型局部需求确实带来惊喜，Code Agent 可以很快完成。但逐渐发现，在创意中心这个庞大复杂的项目中，稍微复杂一些的需求，只靠 Code Agent 自己检索分析基本无法完成任务。

原因有三个：

• 历史逻辑噪声污染：过去几年各种业务迭代留下的废弃逻辑和噪声代码散落在流程中，严重干扰 Code Agent 对核心流程的理解

• 多线业务耦合：多条独立运转的产品线的业务逻辑交错在同一套架构链路中，且各自还在持续迭代——梳理任何一条线都必须同时理解另外两条，改动任何一处都可能影响其他产品线

• 代码量大但热代码少：项目有 20w+行代码，但日常核心变动局限在 2w 行左右，剩下 18w 行基本都是噪声

于是 Code Agent 开发模式退化成了一个低效循环：

每次需求都反复卡在前两步，多次需求之间更是在重复输入类似的背景知识和规范。

3. 两条线索的汇聚

重构的痛苦和 AI Coding 的瓶颈，根因指向同一个问题：团队的领域知识没有被系统化地记录和管理。 人读不到，Agent 也读不到。

那么，如果建立一套完整、正确的核心业务领域知识体系，既给团队沉淀经验、又给 Code Agent 提供业务上下文，是否可以同时解决这两个问题？

团队的业务相对闭环，需求开发模式相对固定，领域知识可枚举、可结构化——这给了我们一个比较理想的试验场。

二、知识体系的设计

1. 从 MCP 到 Skill：方案的演进

最初的尝试很直接：通过 MCP 方式为 Code Agent 接入团队的钉钉云文档，让 Agent 直接读取已有的业务文档。

效果不理想，两个问题：一是钉钉文档本身也有大量过时的知识，准确率上不去；二是文档内容量大且缺乏结构化组织，基本一次就撑爆上下文窗口。

25年11月，Skill 能力推出。团队在12月开始评估，发现它的渐进式加载机制天然适合领域知识的承载——元数据用于路由判断、主文件按需加载、详情文件延迟读取，完美匹配"大量知识但每次只需要一部分"的场景。于是转变方向，用 Skill 作为领域知识的载体来构建知识体系。

2. Skill 的结构

Skill 是将领域专业知识、工作流程转化为模型可理解的规范文档，用于扩展模型的边界能力。可以将它理解为特定领域的"专家手册"——不是给人读的文档，而是给 Code Agent 读的结构化领域知识。

Skill 的设计遵循渐进式披露原则，分三级加载来高效管理上下文：

这个设计的价值在于：相比把所有知识一股脑塞进 Prompt，渐进式披露让模型在合适的时机获取正确的知识，既节省 Token，又避免信息过载导致的注意力分散。

3. 三层知识架构

整套知识体系采用三层架构，对应 Code Agent 的认知路径——从全局定位到模块理解再到细节展开：

第一层：AGENTS.md + Rule（全局索引与约束）

Agent 拿到需求后的第一个文档。消耗极少的 Token，但完成最关键的决策——"我应该读哪个模块的知识"。它包含：

• 项目概述与架构分层

• 全局术语表：消除业务术语与代码命名之间的歧义

• 硬性约束：项目开发通用规范、自定义 Linter 规则

Rule 与 AGENTS.md 的分工：前者侧重通用的编程规范和软件工程原则，多个代码仓库可以共用；后者侧重当前项目的特定知识，只匹配唯一仓库。

第二层：Skill 主文件（模块核心知识）

是知识体系的核心骨架。每个业务模块对应一个 Skill，Code Agent 读完主文件后应该足以理解该模块的业务语义和代码结构，能够开始制定实现方案。主文件需要覆盖以下维度：

• 路由判定：什么需求该读这个 Skill，什么不该读

• 业务领域知识：背景、核心概念、业务规则与不变量

• 核心代码流程：主流程概览，每个节点的职责、代码位置、输入输出

• 变更指南：修改时机判断、影响检查清单、常见变更模式与示例

第三层：引用详情文件（按需展开的细节）

更详细的业务背景、API 定义、流程细节等。只有当 Code Agent 在 Skill 主文件中判断需要更多信息时才加载。

4. 从知识补充到知识工程的演进

最初的做法比较朴素：把业务领域知识按模块写进 Skill，包括业务背景、核心概念、业务规则等。但这些知识没有与实际的项目代码流程映射结合——Skill 里写了业务规则是什么，却没有指明这些规则对应代码中的哪些流程、哪些文件、哪些函数。Code Agent 需要自行推理知识与代码的关联关系，大部分情况下能匹配上，基本可用，但准确率不够稳定——Code Agent 有时会把业务规则映射到错误的代码位置，或者遗漏关联流程。

随后我们做了一次系统性的改进，核心升级是将领域知识与实际代码流程显式映射：每个 Skill 中的业务知识不再孤立存在，而是明确标注它对应哪些代码流程、哪些关键节点、代码入口在哪里。Code Agent 不需要再猜测"这条业务规则大概和哪段代码有关"，而是直接被告知映射关系。

核心变化是从"告诉模型有什么知识"升级到"指导模型怎么用这些知识"。

结果是准确率提升到 90% 以上。

在实践过程中，这些 Skills 经历了密集的迭代打磨——前期几乎每天一版，逐步稳定到一周一版，至今仍在持续优化。知识体系不是设计完就结束的一次性工作，而是需要在真实需求中反复验证和修正的持续工程。这也引出了一个必须面对的问题：在如此高频的迭代中，如何确保知识不会腐化？

三、知识会腐化：比没有知识更危险

知识体系最大的风险不是建设成本，而是腐化。

过时的知识比没有知识更危险——Code Agent 会带着错误的确定性去执行，并快速复制。当Skill文件说业务流程是: A→B→C，而实际代码已经改成了: A→C 时，Code Agent 不会怀疑知识的正确性，它会按照错误的流程编写代码。一旦这种错误模式被引入，影响会被指数倍放大。

在项目持续迭代中，代码变更频率远高于知识更新频率。如果没有系统性的防腐机制，知识体系的准确性会快速衰减。为此我们在实践中逐步建立了四层防腐机制，覆盖开发过程中知识可能腐化或缺失的各个时机。

1. 反向校验：让 Agent 在使用知识时自己发现问题

这是最自然的一层——Code Agent 在使用知识时，天然处于一个能够交叉比对知识与代码的位置。

当 Code Agent 为了实现需求而读取 Skill 知识文件，随后又查看实际代码时，如果发现知识描述与代码现状不一致，Agent 会在输出实现方案的同时，额外生成一份校验报告，标注不一致的严重程度、具体差异和修正建议。人工确认后，直接更新对应的 Skill 文件。

知识指导 Code Agent → Agent 读实际代码 → 发现不一致 → 生成修正建议 → 人确认 → 更新知识

这个环节的价值在于：它几乎没有额外成本。Agent 本来就要读知识、读代码，交叉比对只是顺带完成的动作。而且它直接解决的是存量腐化问题——那些之前没被发现的知识偏差，在每次真实使用中被逐步暴露和修正。

2. 缺失知识沟通补充：在需求开发中生长知识

知识腐化是一类问题，知识缺失是另一类。

当需求开发过程中遇到 Skill 里没有覆盖的知识盲区时，开发者会在本次需求开发前与 Code Agent 进行反复探讨——提供所缺失的业务背景、规则、约束。这个沟通过程本身就在产生新知识。关键一步是：沟通结束后，让 Agent 总结本次对话中新增的知识内容，自行更新到对应的 Skill 模块中。

知识缺失 → 人与 Code Agent 反复沟通补充 → Agent 总结后自行更新 Skill → 知识完善

这个环节解决的是知识体系的"生长"问题。传统做法是开发完成后由人整理文档，但实际中这一步几乎不会发生——需求做完就做下一个了，谁还会回头补文档？把知识沉淀嵌入开发沟通过程本身，让它成为自然副产品而不是额外负担，才能真正持续运转。

3. Commit 前校验：堵住增量腐化的入口

前两个环节偏被动——用到时才发现问题、聊到时才补充缺失。Commit 前的校验则是一个主动的防线。

在代码提交前，自动分析本次代码 diff 是否命中知识更新的触发规则。命中后，Agent 自动分析变更对知识体系的影响，生成结构化的更新建议——精确到哪个业务模块、哪个核心流程的知识需要同步修改。Review 无问题后，自动更新到对应的 Skill 模块。

触发 Commit 提交 → 提交前强制进入知识 Diff-Check → 不一致则自更新 → 知识与业务代码保持一致

这个环节是 Commit 前的必经环节。这样做的好处是将知识更新与代码变更绑定在同一个工作流中——代码改了，知识的检查和更新就在当下完成，不会被拖延到"下次有空再说"。

4. 基线全量巡检：兜底防线

即使有了前三层，仍然会有遗漏逐渐积累。每次合并到基线发布结束时，执行全量健康巡检：扫描所有代码锚点的有效性、比对知识中的接口定义与实际路由、比对数据模型描述与最新表结构、统计知识覆盖度和新鲜度。

合并 master 基线后 → 全量巡检对比 → Code Agent 给出更新报告 → 人 Review 后 Agent 自更新

这个环节解决的是"漏网之鱼"问题。前三层各有盲区：反向校验只覆盖被使用到的模块、沟通补充只覆盖当前需求涉及的知识、Commit 校验可能因触发规则不够全面而遗漏。全量巡检作为兜底，确保知识体系的最终一致。

5. 四层机制的协作关系

四个环节并非简单堆叠，而是各有分工：

四、为什么没有选择 SDD

2025年 SDD（Spec-Driven Development，规范驱动开发）随着 AI Coding 一起爆火。团队最初也尝试过这条路，但很快发现它不适合我们的日常开发节奏。

原因很直接：团队日常需求大部分都是中小型需求，一个两三百来行的代码改动，SDD 模式下生成的 spec 文档却有五六百行——规范比代码还多。开发者的精力从"写代码"变成了"维护每个需求的spec"。

更深层的问题是：既然都要投入精力维护文档，为什么不把这份精力花在维护一套最核心的领域业务知识上？整个业务、整个工程都是围绕这套领域知识运转的，代码无非是领域知识的另一层展现。只要把领域知识锚定到实际代码流程，中间的映射理解完全可以交给 Code Agent。

当然，SDD 有它的价值和适用场景。团队也使用 SDD 从零AI Coding编写了一个 4000+ 行的业务项目，效果不错——从 0 到 1 的项目，没有存量代码的历史包袱，spec 可以从头写起，不存在与现有代码脱节的问题。同时，SDD 先规划再执行的思想本身也是当前最主流的 AI Coding 工作方式。

我们的选择是：不为每个需求写一次性的 spec，而是维护一套持续演进的领域知识体系。 前者随用随弃，后者越用越厚。对于一个持续迭代的复杂业务项目，知识的复利效应远大于 spec 的即时价值。

五、展望

模型和 Code Agent 能力是下限，仓库知识的质量和覆盖度是上限。我们能做的，是持续抬高这个上限。

接下来的趋势必然是端到端 AI Coding：业务需求理解 → 技术方案设计 → 功能开发 → 自动化测试。

但并不打算构建一个端到端的自动化平台。判断是：软件工程的完整开发流程，大概率会被Qoder、Claude Code 这些 Code Agent 原生集成。自建平台的意义不大，生命周期也有限。

我们选择做的是：为 Code Agent 提供它所需的一切。

• 持续跟进使用 Code Agent 的最新能力

• 持续维护和更新领域知识体系

• 构建Agent友好的项目仓库

• 构建自闭环反馈链路：集成自动化测试、监控体系、日志系统

这个选择背后的逻辑是：Code Agent 的通用能力在快速进化，我们的核心壁垒不在通用平台，而在领域知识的深度和准确性。把精力投入到知识工程上，回报更持久。

六、实践建议

对于想在自己业务上尝试类似模式的团队，几点建议：

1. 先评估业务适配度。业务越闭环、开发模式越固定、领域知识越可枚举，这套模式的投入产出比越高。

2. 从一个模块开始，不要全面铺开。选近期有需求迭代的模块，写完 Skill 后用真实需求验证效果，再决定是否扩展。

3. 防腐机制比知识本身更重要。知识体系建起来不难，难的是在持续迭代中不腐化。优先建立反向校验和 Commit 前校验，让知识更新成为开发流程的自然组成部分。

4. Skill 编写的两条经验：

• 触发设计采用倒金字塔结构：元数据描述要全面，主文件按步骤细分，引用详情细化到最小逻辑单元。

• 统一流程命名：每段最小划分的业务逻辑确定唯一的流程名词，同一个业务动作在不同 Skill 文件中必须使用相同称呼，避免模型在跨模块推理时产生混淆。

  
  

阿里妈妈工程技术部2027届实习招聘火热进行中！