如何构建专属 Agent Team — 实战方法论

从 UAR Agent Team（44→33 文件，10,444→8,343 行）的构建与精简中提炼的通用方法论。
适用于任何需要 AI agent 深度参与的领域项目。

---

前置判断：你需要 Agent Team 吗？

不是所有项目都需要 agent team。先过三个条件：

条件	不满足时的替代方案
项目有 领域专属知识（LLM 不自带的）	写几条 CLAUDE.md 规则就够
项目有 多个协作角色（不同视角的产出）	单个 agent prompt 就够
项目是 持续迭代的（不是一次性任务）	写一次性 prompt 就够

三个都满足 → 值得投入建 agent team。
只满足一两个 → 用 CLAUDE.md + 少量 SKILL.md 就够。

---

Phase 1：领域建模 — 识别"只有你知道的"

核心问题：什么知识是 LLM 不自带的？

做减法，不做加法。不要想"我需要教 agent 什么"，而是问"如果不告诉 agent，它会搞错什么"。

四象限分类法

                   项目专属
                      ↑
         ┌────────────┼────────────┐
         │  ② 必写     │  ① 核心    │
 低变化率 │  架构约束    │  业务规则   │ 高变化率
         │  术语定义    │  状态机     │
         │             │  实体模型   │
         ├────────────┼────────────┤
         │  ④ 不写     │  ③ 写锚点  │
         │  设计模式    │  枚举值     │
         │  框架用法    │  方法签名   │
         └────────────┼────────────┘
                      ↓
                   通用知识

象限	策略	示例
① 核心	详细写入 SKILL.md，持续维护	你项目的状态机、业务流程、实体关系
② 必写	写入后基本不变，低维护成本	架构分层规则、领域术语、角色定义
③ 写锚点	只写语义 + @source 指向代码，不缓存精确值	枚举 code 值、接口方法签名
④ 不写	LLM 本身就知道，写了浪费 context	RICE 框架、SOLID 原则、设计模式

检验方法：把你准备写的内容直接问 LLM，如果它不看文件就能给出 80% 正确的答案 → 不写。

识别领域知识的实操步骤

Step 1: 列出项目中"新人入职第一周会搞错的事"
        → 这些就是你的领域专属知识

Step 2: 把它们分成"概念层"和"实现层"
        概念层（稳定）：业务规则、流程、约束
        实现层（易变）：代码值、方法名、字段名

Step 3: 概念层 → 直接写入知识文件
        实现层 → 只写 @source 锚点，指向源码位置

---

Phase 2：架构设计 — 四层文件体系

文件命名即架构

{project}-agent-teams/
├── {project}-orchestrator-*   # L0 编排层：路由、调度、协调
├── {project}-agent-*          # L1 角色层：产品经理、开发、测试等
├── {project}-skill-*          # L2 技能层：可执行的具体指导
├── {project}-knowledge-*      # L3 知识层：只读参考事实
└── scripts/                   # L4 自动化：lint、检查、部署

每层的职责边界：

层	包含什么	不包含什么
Orchestrator	角色分工、路由规则、工作流时序、门禁条件	具体实现细节
Agent	角色定义、输出模板、工作方法、检查清单	通用技能（LLM 自带的）
Skill	项目专属的实现指导、代码模板、最佳实践	通用编程知识
Knowledge	领域事实（实体、状态机、业务流程、术语）	实现建议（那是 Skill 的事）

最小启动集

不要一开始就建 40 个文件。最小启动集只需要：

必建（Day 1）：
  1 个 knowledge 文件  — 核心领域模型（实体 + 状态机 + 业务流程）
  1 个 agent 文件      — 开发者角色（你的 agent 最常扮演的角色）
  CLAUDE.md            — 行为准则

按需扩展（遇到问题再建）：
  orchestrator         — 当角色超过 3 个，需要协调时
  更多 knowledge       — 当单文件超过 500 行，需要拆分时
  skill 文件           — 当某类任务反复出现且需要具体指导时
  scripts              — 当某条规则可以自动化检查时

反模式：先设计完美架构再填内容。正确做法是从最小集开始，遇到问题再扩展。

---

Phase 3：内容编写 — 只存语义，锚点指向代码

核心原则：知识文件只放 agent 直接用不会出错的内容

不要用"信任分层协议"告诉 agent 哪些要验证 — 那是规则，agent 可以不遵守。
正确做法是从结构上消除错误源头：知识文件里根本不放易变的代码值。

直接写入知识文件（语义层，稳定）         从知识文件删除（实现层，易变）
├── 业务术语定义                        ├── 枚举数字值（code = 1, 2, 3...）
├── 架构约束                            ├── 方法签名精确参数
├── 实体层次关系                        ├── 字段精确类型/长度
├── 状态转换方向                        └── 级联更新的具体字段列表
└── 业务规则 / 判断标准

删除的内容怎么办？ 用 @source 锚点替代 — 告诉 agent 去哪里读，而不是缓存一份在知识文件里。

@source 锚点模式

### Mission 状态码

> **@source** `src/main/java/.../consts/MissionConstant.java`
> **@verify** 实现代码前必须 Read 源文件确认精确值。

| 枚举名 | 业务含义 |
|--------|---------|
| PENDING | 待发布（新创建默认值） |
| PROCESSING | 进行中（已发布） |
| COMPLETED | 已完成 |

> ⚠️ 精确 code 数值从源文件获取，不从本表获取。

好处：

• 知识文件不会因为代码改枚举值而过期
• Agent 被明确引导去读源码，而不是用缓存值
• 维护成本趋近于零（语义层很少变）

内容编写三原则

原则 1：写"会搞错的"，不写"能搜到的"

❌ "Spring Boot 使用 @Transactional 管理事务"
✅ "UAR 中所有状态变更必须在 @Transactional 内完成，且同一事务内写审计日志"

原则 2：写约束，不写教程

❌ "乐观锁的原理是通过 version 字段实现 CAS 操作..."（教程）
✅ "UserPermission 实体使用 @Version 乐观锁，并发冲突时最多重试 3 次"（约束）

原则 3：写判断标准，不写流程描述

❌ "首先创建 ReviewCycle，然后创建 Mission，接着..."（流程）
✅ "Mission 完成条件：该 Mission 下所有 UserPermission 状态为 APPROVED/REVOKED"（判断标准）

---

Phase 4：行为准则 — CLAUDE.md vs SKILL.md 分工

CLAUDE.md：放行为规则（每次对话都生效）

# CLAUDE.md 应该包含的内容

## 第一性原理
- 代码即真相（不信文档信代码）
- 从源头验证（改代码前先看原始版本）
- 最小必要变更（每行 diff 对应需求条目）

## 项目专属行为约束
- 状态变更必须通过 IXxxStatusService
- Job Handler 只做参数解析 + 委托调用
- 开发阶段不写单测

## 构建 / 测试命令
- mvn clean package ...
- mvn test -pl ...

SKILL.md：放领域知识（按需加载）

CLAUDE.md 和 SKILL.md 的判断标准：

"如果 agent 不遵守这条，每次都会出错" → CLAUDE.md
"如果 agent 不知道这个，特定任务会出错" → SKILL.md

CLAUDE.md 是"做人规矩"，SKILL.md 是"专业知识"。

---

Phase 5：质量约束 — 三层有效性模型

核心洞见：约束 AI agent 的最有效手段不是"告诉它该做什么"（规则），
而是"让错误不可能发生"（结构）和"让正确路径最短"（摩擦）。
评分卡和 checklist 对 AI agent 基本无效 — agent 可以自评满分、自行打勾。

三层约束，按有效性排序

第一层：结构性消除 ─── 让错误源头不存在
│  知识文件不放易变的代码值（枚举数字、方法签名精确参数）
│  只放语义层内容（枚举名 + 业务含义、状态转换方向）
│  效果：源头无错误数据 → agent 无从用错
│
第二层：降低正确路径摩擦 ─── 让正确行为比错误行为更省事
│  @source 锚点标注源码路径，agent 读知识文件时自然看到
│  "去 Read 源码"比"凭记忆猜"更省事 → 自然走正确路径
│  效果：不是靠规则逼它验证，是让验证成为阻力最小的路
│
第三层：关键路径自动化检查 ─── 只卡最危险的口
   lint 脚本检查最容易出事的模式（如 .setStatus() 出现在非 StatusService 中）
   pre-commit hook 阻断违规提交
   效果：不需要全覆盖，只拦截高危操作

无效手段（避免投入）

手段	为什么对 AI agent 无效
评分卡	agent 自评，本质是自说自话
流程 checklist	agent 可自行打勾，无约束力
“MUST verify” 文字协议	写在文件里的规则，agent 可以不遵守
验证分层协议（MAY/MUST）	过度复杂，不如直接用 @source 锚点

投入优先级

第一步（Day 1）：结构性消除 — 重构知识文件，删除缓存的代码值
第二步（Day 2）：降摩擦 — 给易变小节加 @source 锚点
第三步（遇到问题时）：自动化检查 — 对高危模式写 lint 脚本

不做的事比做的事更重要。不写评分卡、不写验证协议、不写 checklist。

---

Phase 6：持续精简 — 迭代修剪

精简三问法

对每个文件问：

Q1: 这个知识 LLM 本身就知道吗？
    → 是 → 删除（RICE 框架、SOLID 原则、设计模式教程）

Q2: 这个知识和具体项目有绑定吗？
    → 没有 → 删除（通用 UX 原则、通用安全 checklist）

Q3: 删掉这个文件，agent 产出质量会下降吗？
    → 不会 → 删除

合并判断标准

信号 1：完成一项任务需要读 3+ 个文件才能凑齐信息 → 合并
信号 2：两个文件有 30%+ 内容重叠 → 合并
信号 3：某个文件从未被 agent 引用 → 考虑删除

精简节奏

第 1 轮（项目启动 1 周后）：
  删除"写了但从没用过"的文件

第 2 轮（项目启动 1 月后）：
  用精简三问法逐文件审查
  合并重叠的 skill 文件
  统计各文件被引用频率

第 3 轮（每季度）：
  重新评估知识文件是否过期
  检查 @source 锚点是否还指向正确路径
  清理不再使用的角色 agent

---

反模式清单

反模式	为什么错	正确做法
教 LLM 它已经知道的	浪费 context window，降低信噪比	只写项目专属知识
在知识文件中缓存代码值	代码改了但文件没同步 → agent 用错值	用 @source 锚点，让 agent 去读源码
先设计完美架构再填内容	你不知道 agent 实际需要什么	最小启动集 + 按需扩展
用 checklist 约束 AI	AI 可以自行打勾，约束力为零	用自动化 lint 或验证协议
一个职责一个文件	过度碎片化，信噪比低，维护成本高	按"完成一项任务需要读几个文件"来组织
把通用框架当 skill	RICE、MoSCoW、OWASP Top 10 不需要教	只写项目中"用这个框架时的特殊规则"
产品侧和技术侧同等投入	AI agent 的核心价值在代码实现，不在管理流程	技术侧 > 知识库 > 产品侧
一次精简到位	没有使用数据支撑的精简是猜测	铺开 → 使用 → 观察 → 精简 → 循环

---

完整生命周期总结

Phase 1  领域建模    识别"只有你知道的"                    产出：知识清单
Phase 2  架构设计    四层体系 + 最小启动集                  产出：目录结构
Phase 3  内容编写    信任分层 + @source 锚点               产出：SKILL.md 文件
Phase 4  行为准则    CLAUDE.md 规则 + 验证协议              产出：CLAUDE.md
Phase 5  质量约束    从 L1 开始，遇到问题才往下加           产出：lint 脚本 / 评分卡
Phase 6  持续精简    精简三问 + 合并信号 + 季度审查         产出：更精简的文件集

核心循环：铺开 → 使用 → 观察 → 精简 → 铺开 ...

最终衡量标准：不是文件数量或行数，而是 agent 在你的项目中产出的代码质量。
如果加一个文件能让 agent 少犯一类错误 → 加。
如果删一个文件 agent 产出不变 → 删。