AI Coding 知识库最佳实践：三层结构重建可维护工程

当 Claude Code、Copilot 以及各类 Agent 型工具真正进入团队日常开发之后，许多团队很快都会遇到同一个问题：工具本身越来越强，但围绕它建立起来的配置、约束和流程，却在不知不觉中变得越来越混乱。最初我们往往只是想让 AI "先跑起来"，于是很自然地把规则、注意事项、执行步骤、任务模板乃至各种经验性提醒，统统塞进一个总配置文件里；这种做法在项目早期确实高效，因为信息集中、修改方便，团队也不需要花额外成本设计结构。然而，一旦项目进入持续迭代阶段，这份原本为了提高效率而生的配置文件，往往会迅速膨胀成一块谁都知道重要、却谁都不愿认真阅读的"巨石文档"。

真正的问题，其实从来不只是"内容太多"，而是不同性质的信息被放进了同一个容器里。一部分内容属于全局约束，应该在任何任务中长期有效；另一部分内容则是特定场景触发时才需要执行的操作手册；还有一部分工作，本质上是可以拆分、委派、并行处理的独立任务。如果这三类内容长期混写在一起，AI 的行为边界就会越来越模糊，团队成员对配置体系的理解也会越来越分裂，最终形成一种典型的状态：文件还在增长，但系统已经不再具备真正的可维护性。

这篇文章想讨论的，正是如何用一种更工程化的方式重构这类 AI 协作配置。一个非常实用的思路，是把原本混杂在一起的内容拆分为三层：基础层、流程层、任务层。这并不是为了追求形式上的整齐，而是为了让规则保持稳定、让流程更易复用、让任务更容易委派，从而把 AI 从"能用的辅助工具"，逐步推进到"可维护的协作基础设施"。

图 1：以基础层、流程层、任务层为核心的三层协作结构示意。

一、为什么 AI 配置总会越写越乱？

如果回头观察很多团队的实际演进路径，会发现问题往往不是从"大而全"开始的，而是从"顺手多写一点"开始的。最初也许只是补一条编码规范，随后又加上一段部署说明，再后来为了避免遗漏，把排障流程、提测要求、发布模板、审查清单一并写进总文件。每次新增内容时，看上去都很合理，因为它们似乎都与 AI 的工作方式有关；但随着时间推移，配置文件承担的角色开始悄悄发生变化------它既像团队规范文档，又像操作手册，还兼任任务说明书和经验备忘录。到了这个阶段，问题就不再是体积，而是结构本身已经失去边界。

这类混乱通常会以几种非常典型的信号表现出来。比如，总文件越来越长，长到大家只能依赖搜索关键字定位内容；同一个流程在不同位置以不同说法重复出现，导致修改一次需要同时改动多个地方；团队新增一个能力时，成员常常争论它到底应该写成全局规则，还是写成某个场景下的模板；而随着 AI 能承担的任务越来越多，大家会逐渐发现，原本看似"集中管理"的方式，实际上正在让职责分工变得更难理解。

如果从软件设计的视角来看，这并不是什么新问题，它本质上仍然是一个典型的职责混淆问题。我们之所以容易在 AI 配置上反复踩坑，往往是因为潜意识里把这些配置当成了"说明文字"，而不是一种需要被设计、被演进、被治理的工程资产。一旦换一个角度，把它视为团队协作系统的一部分，就会很自然地意识到：既然代码需要分层，配置同样也需要分层；既然模块需要边界，AI 的规则体系同样也应该有清晰边界。

图 2：从"巨石式配置"走向"分层式组织"的对比示意。

二、三层结构的核心思路：把规则、流程与任务彻底拆开

要解决这类问题，最有效的办法并不是继续往总文件里补充目录、标签或跳转链接，而是从信息类型本身出发，重新划分配置体系的结构。一个清晰且实用的划分方式，是将其分成三层：基础层、流程层、任务层。

层级	适合承载的内容	关注重点
基础层	对所有任务长期生效的规则与约束	稳定性、通用性
流程层	在特定触发场景下调用的流程化操作	场景性、可复用性
任务层	可独立执行、可并行委派的任务单元	独立性、可组合性

如果换一种更贴近工程协作的表述，三层结构其实分别回答了三个不同的问题。

• 基础层回答的是：AI 在这个项目里始终不能越过哪些边界？
• 流程层回答的是：当某种场景发生时，AI 应该遵循怎样的标准流程？
• 任务层回答的则是：哪些工作可以被定义为一个目标清晰、输入输出明确、可以单独执行的任务单元？

一旦这三个问题被分开回答，配置体系的可维护性就会大幅提高，因为你不再试图用同一种文本结构去承载完全不同的内容。换句话说，真正应该被管理的不是"文档数量"，而是变化频率、调用方式与粒度是否一致。只要这三者不一致，就不应该被放在同一个层级里。

三、基础层：把身份、边界和硬约束写进 AGENT.md / rules.md

基础层最像 Agent 的"底座人格"。它不负责说"这次任务具体怎么做"，而是负责规定"无论做什么，都不能越线"。

在真实 Agent 系统里，这一层最适合落在：

• AGENT.md：执行规则、行为指令、禁令、协作方式
• rules.md：项目级约束、编码规范、输出规范、审查原则

这一层适合写什么？

• 允许和禁止使用哪些工具
• 哪些操作必须先读文件、先验证、先征求确认
• 代码规范、命名规则、安全边界
• 输出语言、答复风格、提交要求
• 对外部系统、敏感数据、内网操作的限制

一个 AGENT.md 示例

# 执行规则

1. 修改任何文件前必须先读取上下文。
2. 禁止在未确认的情况下执行破坏性操作。
3. 涉及密钥、凭证、权限控制时，优先使用官方工具链。
4. 需要调用浏览器时，禁止使用脆弱的 UI 自动化。

# 行为要求

- 回复默认使用中文
- 优先给出可执行结论
- 修改代码后要说明影响范围

一个 rules.md 示例

# 项目规则

- 文件命名使用 kebab-case
- 禁止在生产代码中保留 debug 输出
- 数据库迁移必须单独评审
- 安全相关改动必须人工复核

基础层最容易出现的误区，是被不断追加那些本不属于它的内容。很多团队会在总规则文件里逐渐写进"如何发版""如何排查线上问题""如何撰写周报""如何回滚版本"等步骤性内容，理由通常是"这些也很常用"。问题在于，常用不等于全局有效 。一旦把"如何部署""如何排障""如何生成周报"也塞进 AGENT.md 或 rules.md，基础层就会失去稳定性。基础层应该短、硬、稳；它定义的是底线，不是步骤。

四、流程层：把可复用流程沉淀成 Skill

与基础层不同，流程层并不要求内容始终生效，它承载的是那些在特定场景下才需要被调用的标准流程。也就是说，它不是定义边界，而是定义动作；不是告诉 AI 什么永远不能做，而是告诉 AI 在某个任务意图出现时，应该依次完成哪些步骤。

在现代 Agent 生态里，这一层最适合映射到 Skill。原因很直接：Skill 天然适合承载"触发条件明确、步骤可复用、可能要调脚本或 MCP 工具"的流程性能力。

Skill 往往会封装这些东西：

• 场景描述与触发条件
• 前提条件与完成标准
• 多步执行逻辑
• 复用脚本
• MCP 工具调用方式
• 相关资源或模板

所以，它们有一个共同特征：每个任务一旦触发，就应该按照相对稳定的步骤执行。流程层不是普通说明文档，而更像"可调用的标准作业模块"。

一个好的流程层实现，通常要写清四件事：

1. 它在什么情况下被触发
2. 执行前需要满足哪些前提
3. 执行过程由哪些步骤组成
4. 最终怎样才算完成。

这四个问题非常关键，因为它们共同构成了流程的可执行边界。如果只写一段模糊描述，例如"进行部署"或"帮我排查问题"，那么 AI 在不同上下文下很可能会做出不同理解，最终导致执行质量高度依赖即时提示词，而无法真正形成稳定流程。

一个 Skill 定义示例

---
name: deploy-service
description: 用于服务部署场景，负责检查、发布和验证
---

## 触发条件
- 用户要求部署、上线、发版

## 前提条件
- 测试通过
- 变更已审批

## 执行步骤
1. 读取变更说明
2. 运行部署前检查
3. 调用发布工具部署到 staging
4. 验证核心链路
5. 部署 production
6. 发送完成通知

## 使用工具
- deploy MCP
- test script
- notify script

如果这个 Skill 需要脚本支撑，可以继续挂接复用脚本：

# skills/deploy/check_release.py

def precheck(ctx):
    assert ctx["tests_passed"] is True
    assert ctx["approved"] is True
    return "ok"

如果这个 Skill 依赖 MCP 工具，本质上也是流程层的一部分：

{
  "tool": "deploy_service",
  "params": {
    "env": "staging",
    "service": "api-gateway"
  }
}

为什么 Skill 很适合流程层？

因为它正好处在"全局规则"和"单次任务"之间：

• 比 AGENT.md 更具体
• 比单次 Prompt 更稳定
• 可以复用脚本和工具
• 可以在多个任务中重复调用
• 流程层最常见的错误
• 把 Skill 写成另一个"大杂烩"。

流程层最常见的错误

把 Skill 写成另一个"大杂烩"。

如果一个 Skill 同时负责排障、修复、回归、发公告、同步日报，它迟早会重新膨胀。流程层应该围绕一个清晰目标组织，而不是把所有动作都塞进一个 Skill。

五、任务层：把这一次任务的信息动态喂给 Agent

如果说流程层更多是在回答"这件事应该怎么做"，那么任务层回答的则是"这件事应该由谁来做，以及能否独立完成"。当一个工作已经具备明确的输入、可预期的输出，并且不需要依赖过长的上下文链路时，它往往就很适合被拆分成独立任务，交由单独的 Agent 处理。

在实际工程中，这类任务并不少见。比如，

• 审查某个 PR 的命名问题
• 扫描某个模块的安全风险
• 为一组函数补全文档
• 根据原始资料生成一篇博客初稿
• 对多个方案分别做调研总结

这些任务的共同点在于，它们通常拥有相对稳定的目标边界，并且可以在较少依赖其他任务状态的前提下独立运行。也正因为如此，任务层最适合承载那些可以拆分成独立单元、能够复用并支持并行处理的能力。把这类工作从统一流程中抽离出来，交给独立 Agent 处理，会带来几个非常明显的收益。

• 首先，它天然更适合并行执行，多个任务可以同时推进，而不必被一条长流程串行阻塞；

• 其次，它的复用性更高，例如一个专门做代码审查的 Agent，可以同时被发布流程、提交前检查流程或质量巡检流程所调用，而不需要在多个地方重复粘贴同样的规则；

• 再次，它有助于控制职责边界，因为一个 Agent 只围绕单一目标设计，其输出格式和执行逻辑也更容易标准化；最后，它更利于后续演进，你可以单独优化某个 Agent，而不必连带修改整个流程体系。

这里有一个尤其值得强调的原则：任务层应尽可能保持无状态。 一旦某个 Agent 的效果严重依赖隐式记忆、长期上下文或内部状态累积，它就会迅速变得难以并行、难以复现、难以调试。理想情况下，任务层更像一个输入明确、输出明确的执行器，而不是一个不断吸附上下文、能力边界越来越模糊的黑盒。只有保持这种"轻、窄、清晰"的设计，任务层才能真正成为可组合的能力单元，而不是新的复杂度来源。

为什么这层不能提前固化进 Skill？

因为任务层强调的是"这一次"的目标、范围和上下文。比如同样是写文档：

• 这次面向谁
• 用什么语言
• 输出成什么格式
• 只看哪些输入
• 不要做哪些扩展

这些信息都可能随任务变化。如果把它们写死进 Skill，Skill 会失去复用性；如果写进 AGENT.md，又会污染全局规则。

任务层最关键的不是写长，而是写清楚

一个合格的任务派发，至少要写清四点：

1. 目标
2. 输入
3. 边界
4. 输出格式

如果这些不清楚，Agent 很容易开始"自由发挥"。

在 Agent 生态里，任务层通常随着用户输入动态生成，然后被喂给某个 Agent 或 Subagent。这一层最常见的技术形态包括：

• Subagent Prompt
• create_task / 派发任务指令
• 动态注入的上下文、目标、输出格式
• 当前任务专属的限制条件

这类内容的特点是：一次性强、上下文敏感、粒度细。

一个 Subagent 派发示例

你是一个代码审查子代理。

任务目标：检查这次 PR 中的命名问题和调试代码残留。
输入材料：Git diff、项目规则摘录。
只关注：命名规范、debug 输出、显式 TODO。
不要做：不要评价架构优劣，不要扩展到未修改文件。
输出格式：
- file:line
- 问题
- 原因
- 建议修改

一个动态 create_task 风格示例

{
  "agent": "doc-writer",
  "goal": "根据这份接口变更说明生成发布文档初稿",
  "context": {
    "language": "zh-CN",
    "audience": "internal engineers",
    "source_files": ["api_diff.md", "release_notes.txt"]
  },
  "output": {
    "format": "markdown",
    "sections": ["变更摘要", "兼容性影响", "升级建议"]
  }
}

图 3：流程统一编排、多个任务并行委派的协作方式示意。

六、到底该放哪一层？一个比"经验判断"更可靠的方法

在实践中，团队最常遇到的困难并不是"不知道三层结构是什么"，而是明明知道这套方法，面对一段具体内容时依然会犹豫：它究竟应该写在基础层、流程层，还是任务层？如果这个判断完全依赖个人经验，那么体系很快又会重新走向失控。因此，更可靠的做法，是建立一个简单但清晰的判断顺序。

首先要问的是：这条内容是否应该在所有任务中长期有效？ 如果答案是肯定的，那么它大概率属于基础层。例如命名规范、安全底线、提交纪律、目录组织原则等，它们并不依赖特定任务意图，只要项目还在，这些约束就应持续存在。

如果答案是否定的，那么第二个问题是：它是否属于某种场景触发时需要执行的一整套固定流程？ 如果是，那么它更适合进入流程层。例如部署、排障、回滚、博客发布、版本检查，这些都不是时时刻刻执行的动作，但每次一旦触发，就需要遵循相对明确的步骤。

如果它既不是全局规则，也不是一整套场景流程，那么最后再问：它是否可以被定义为一个独立任务，并且可以单独委派甚至并行执行？ 如果可以，那么它通常就应该进入任务层。像审查、扫描、生成、提取、汇总这类工作，往往都具备这样的特征。

这个判断顺序的价值，在于它帮助团队把"写在哪里"从感性经验变成了可讨论、可对齐的判断标准。当大家不再围绕目录结构争论，而是围绕内容属性本身作判断时，配置体系的稳定性就会明显提高。反过来说，如果一段内容无论放到哪一层都显得别扭，那么问题往往不在结构，而在这段内容本身的职责定义就不清楚；这时候真正应该做的，不是硬塞进某个目录，而是先把需求重新拆清楚。

如果把三层映射到真实 Agent 工程，目录大致可以这样设计：

agent-system/
├── AGENT.md
├── rules.md
├── skills/
│   ├── deploy-service/
│   │   ├── SKILL.md
│   │   └── check_release.py
│   ├── incident-response/
│   │   └── SKILL.md
│   └── write-blog/
│       └── SKILL.md
└── tasks/
    ├── review_pr.json
    └── write_release_note.json

对应关系很清楚：

1）基础层

放在：

• AGENT.md
• rules.md

负责：

• 身份设定
• 执行规则
• 行为边界
• 长期有效的项目约束

2）流程层

放在：

• skills/**/SKILL.md
• Skill 依赖的脚本
• Skill 调用的 MCP 工具

负责：

• 复用流程
• 工具编排
• 多步执行
• 场景化能力沉淀

3）任务层

放在：

• 子代理 Prompt

• 动态派发 JSON

• 本次任务的上下文块

  负责：

• 当前任务目标

• 输入材料

• 输出格式

• 临时限制条件

这个结构的好处很直接：

• 改规则，不会污染 Skill
• 改 Skill，不会影响全局人格
• 改任务派发，不需要重写底层流程

七、三个常见的反模式

即便团队已经接受了分层思路，在落地过程中仍然很容易再次滑回旧模式。这里尤其值得警惕三种反模式，因为它们几乎是所有配置体系重新失控的起点。

1. 把一切都继续堆进 AGENT.md

AGENT.md 应该定义底线，不应该承包所有流程。

这是最常见也最具迷惑性的做法。表面上看，它似乎能保持"集中管理"，但实际上却让总文件同时承担规则手册、流程文档和任务说明三种完全不同的职责。短期内你会觉得方便，长期却会发现没有任何人真正能完整维护这份文件。总文件一旦突破可读范围，就不再是基础设施，而只是一块不断增长的信息堆积物。

2. 把一次性任务细节写死进 Skill

Skill 应该可复用。如果某个 Skill 里充满"本次任务专用要求"，那它其实写成了任务层。

流程层的职责是描述流程，而不是把每一个独立任务都直接写死在流程文档中。如果一个流程内部包含大量彼此独立的执行逻辑，那么它最终会变得臃肿、脆弱且难以复用。更合理的方式，是在流程中明确"何时委派任务"，而不是把任务本身的全部实现揉进流程描述里。前者让流程保持清晰，后者则只会制造新的耦合。

3. 让 Agent 承担过多上下文和状态

单次任务 Prompt 越依赖历史状态，越难并行、越难复现、越难调试。

任务层之所以适合并行，前提正是它足够轻量、足够独立。一旦 Agent 变成一个高度依赖历史上下文、长期状态和隐式记忆的复杂角色，它就会失去可并发、可复现、可测试的优势，最终又变成另一个难以治理的系统中心。很多团队误以为"让 Agent 更聪明"就是不断给它叠加记忆和职责，但从工程角度看，这往往意味着你正在把一个原本可控的任务单元，重新做成难以维护的黑盒。

八、分层之后，团队到底能得到什么？

如果只是从概念层面理解三层结构，它看起来像一种"更优雅的整理方式"；但真正落地之后，它带来的收益其实远不止文档好看这么简单。更准确地说，它会在协作成本、认知负担、复用效率和 AI 行为稳定性上，持续释放价值。

首先，最直观的变化是总规则文件会明显瘦身。原本那些并不属于全局规则的流程和任务描述被迁移出去之后，基础层终于只保留真正长期有效的内容，这不仅提升了可读性，也提升了团队对它的信任度。一个简洁清晰的总规则文件，远比一份什么都有、却没有边界的大全文档更有价值。

其次，团队协作成本会下降。过去大家常常要反复讨论"这段内容应该写哪里""为什么这里和那里写得不一样""新增能力要不要再加一条总规则"，而分层方法提供了一套相对稳定的判断标准，使这类讨论从模糊争执转变为结构化判断。换句话说，分层并不只是整理文件，更是在降低团队围绕 AI 配置的沟通摩擦。

再次，重复维护的概率会显著降低。流程类知识集中在流程层，独立能力集中在任务层，全局约束则留在基础层，各类内容不再因为找不到合适归属而被复制到多个地方。随着重复减少，配置体系的演进速度也会更健康，因为你终于可以在一个位置修改规则、在另一个位置调整流程、在第三个位置优化任务，而不必担心牵一发而动全身。

最后，也是最容易被低估的一点，是 AI 的行为会变得更稳定。很多人以为 AI 输出不一致只是模型能力问题，但实际上，结构混乱的配置本身就会制造大量歧义。当规则、流程与任务边界被明确区分后，AI 在不同场景中会更容易建立稳定的决策路径：哪些约束必须始终遵守，哪些流程只在特定触发条件下执行，哪些工作可以直接委派给独立 Agent。稳定性并不只来自模型，更来自清晰的系统设计。

九、如果你准备落地这套方法，可以怎么开始？

对于已经积累了一段时间 AI 配置的团队来说，最好的切入点通常不是"一次性彻底重构"，而是通过几个低风险、高收益的动作逐步完成迁移。

第一步，先对现有配置做一次系统清点。把当前项目中所有与 AI 协作相关的规则文件、流程模板、任务说明、提示词文档全部列出来，重点观察哪些内容已经混杂在一起，哪些地方存在重复、冲突和模糊归属。很多团队只有在真正把这些资产摆到一起时，才会意识到混乱的程度远超预期。

第二步，按照三层结构重新归类内容。这个阶段不需要追求一步到位，而是优先把那些性质最明确的内容迁移出来：长期不变的约束收敛到基础层，具备触发条件的流程沉淀到流程层，输入输出清晰、可独立执行的能力抽到任务层。只要这一步完成了，整个体系的轮廓通常就已经开始变清楚。

第三步，优先处理当前最混乱、最膨胀的那一部分。对大多数团队而言，这往往就是那个不断加长的总规则文件。与其试图同时优化所有目录，不如先让基础层重新恢复"只承载全局规则"的职责；一旦这件事做对，后续很多拆分工作都会变得顺理成章。

第四步，为流程明确触发条件和完成标准。不要只写"发布博客"或"执行部署"这种任务标题，而要清楚说明什么样的用户意图会触发该流程，以及流程完成后应该满足哪些结果标准。这样做不仅能提升 AI 的执行稳定性，也能让团队成员在调用这些流程时更容易形成一致预期。

第五步，为任务层定义清晰的输入与输出。不要只说"做代码审查"，而要说明输入是什么、输出格式是什么、边界是什么、哪些问题由 Agent 判断、哪些问题必须交还人来决策。只有当任务的输入输出被说清楚，Agent 才真正具备工程上的可组合性，而不只是"看起来能用"。

十、结语：从"能用"走向"可维护"，关键在于分层

把 AI 协作配置拆分为基础层、流程层、任务层，本质上并不是在做复杂化设计，恰恰相反，它是在用最朴素的工程原则，为一个不断增长的系统重新建立秩序：让真正稳定的规则保持稳定，让场景化流程能够复用，让独立任务可以被委派和并行处理。

如果用 Agent 生态里的具体技术来映射三层结构，结论其实很清楚：

• 基础层 = AGENT.md + rules.md：定义身份、规则和硬约束
• 流程层 = Skill：封装可复用流程、脚本、MCP 工具和多步编排
• 任务层 = 动态任务派发：用 Subagent Prompt、create_task 指令和即时上下文定义这一次任务

把这三层分开之后，系统会更稳定，团队也更容易扩展。

从"把所有东西写在一起"走向"按职责分层组织"，看似只是文档结构的变化，但它往往正是 AI 协作体系从可用迈向可维护、从临时工具升级为工程基础设施的关键分水岭。