UAM — 统一代理清单

欢迎来到 UAM（Unified Agent Manifest，统一代理清单）！

什么是 UAM？

本意

UAM 即「统一代理清单」，是一份用于定义 AI 编程 Agent 完整行为边界的配置文件。

技术定义

在 AI 辅助开发中，Agent 的行为受多种因素影响：项目规则、技术约束、历史决策、流程规范……这些信息分散在 AGENTS.md、.qoder/rules/、.claude/、openspec/ 等多个目录和文件中。每切换一个工具或项目，开发者都不得不重新配置一套体系。

UAM 将这些分散的能力整合为一个统一的配置文件入口——AGENTS.md。

其核心原则是：将「身份定义 + 规则约束 + 项目记忆 + 可复用技能 + 上下文构建 + 流程规范 + 工具声明」打包为一个标准化的清单文件，供 Agent 在启动时一次性加载并全程遵守。

一个 UAM 最少只需一个 AGENTS.md 文件：

# UAM — Unified Agent Manifest
# 版本: 1.0

## 1. 核心身份
- 技术栈: Java 17, Spring Boot 3, MyBatis-Plus

## 2. 红线规则
- 数据库操作必须使用 MyBatis-Plus，禁止手写 JDBC
- 所有 Controller 返回 `Result<T>`，禁止返回原始对象

## 3. 项目记忆
- 主键策略: Snowflake ID，类型 BIGINT

## 4. 可复用技能
### 代码审查清单
1. 空指针风险
2. 事务边界

## 5. 上下文构建
- 当前任务: [由 Agent 动态填充]

## 6. 工作流规范
所有新功能必须走: 提案 → 任务拆解 → 实施 → 归档

## 7. 外部工具声明
- 数据库 MCP: `npx mcp-mysql-server`

✅ 可选扩展：

• scripts/（执行脚本）
• rules/（规则文件）
• skills/（技能包）
• specs/（规范文档）

UAM = 统一入口 + 分层配置 + 全生命周期管理，是从「多个配置文件各自为政」到「一个清单统领全局」的关键升级。

为什么需要 UAM？

当前 AI 编程工具生态中存在大量概念：Rule、Memory、Skill、Context、OpenSpec、Subagent、MCP……它们本质都是「上下文注入」，却分散在不同目录、不同文件中，由不同工具各自解析。

UAM 解决了三个核心痛点：

痛点	UAM 的解法
配置分散	一个 AGENTS.md 统一管理所有配置
工具锁定	不依赖特定 IDE 或 CLI，任何支持 AGENTS.md 的工具均可使用
学习成本高	只需理解一个文件结构，而非多个概念体系

如何创建 UAM？

方式一：从零创建（推荐）

在项目根目录创建 AGENTS.md 文件，按以下结构填写：

# UAM — Unified Agent Manifest
# 版本: 1.0

## 1. 核心身份
- Agent 名称: [你的项目名] 开发助手
- 技术栈: [语言、框架、数据库]
- 主要目标: [协助完成什么]

## 2. 红线规则
- [规则1]
- [规则2]

## 3. 项目记忆
- [背景知识1]
- [背景知识2]

## 4. 可复用技能
### 技能名
[技能描述和操作步骤]

## 5. 上下文构建
- 当前任务: [由 Agent 动态填充]

## 6. 工作流规范
[开发流程定义]

## 7. 外部工具声明
[MCP 工具配置]

方式二：从现有配置迁移

如果项目已有分散的配置文件（如 .qoder/、.claude/、openspec/），可通过以下步骤整合到 UAM：

# 1. 创建 UAM 入口
touch AGENTS.md

# 2. 从各配置文件中提取关键信息
# - 从 .qoder/rules/ 提取规则 → 填入「红线规则」
# - 从 openspec/specs/ 提取规范 → 填入「工作流规范」
# - 从 .claude/settings.json 提取工具 → 填入「外部工具声明」

# 3. 保留原有目录作为执行层，AGENTS.md 作为统一入口

如何搜索和发现 UAM 实践？

进入项目后，你可以通过以下方式找到适合的 UAM 模板：

• 关键词搜索：在社区搜索「UAM」「AGENTS.md 模板」「AI Agent 配置」，匹配项目类型和技术栈。

• 按场景筛选：

  • Java/Spring Boot 项目：包含 MyBatis-Plus、事务管理、统一响应格式等规则
  • 微服务项目：包含服务间调用规范、分布式事务约束
  • 前端项目：包含组件规范、API 调用约定

• 查看 UAM 示例：每个 UAM 示例展示名称、适用场景、核心规则和技能定义。点击进入详情页，查看完整配置。

如何下载和使用 UAM？

下载 UAM

方式一：直接创建（推荐）

在项目根目录创建 AGENTS.md 文件，参考模板手动填写。

方式二：克隆示例

# 从模板仓库复制
git clone https://github.com/your-org/uam-templates.git
cp uam-templates/spring-boot/AGENTS.md ./

使用 UAM

在各类软件中使用 UAM

UAM 遵循通用的 AGENTS.md 协议，本质上是一套「结构化 Agent 配置清单」。只要软件支持加载 AGENTS.md，就可以集成使用。

核心思路

把 AGENTS.md 当作 Agent 的「启动配置文件」：它包含身份定义、规则约束、技能模板和流程规范，软件只需在启动时读取并解析，即可让 Agent 遵循既定行为边界。

通用集成步骤

1. 获取 UAM 文件

   • 在项目根目录创建 AGENTS.md
   • 或从模板仓库复制现成的配置文件

2. 确保 Agent 工具读取该文件

   • Qoder：自动读取项目根目录的 AGENTS.md
   • CodeBuddy：自动识别并加载
   • Claude Code：默认读取 AGENTS.md 或 CLAUDE.md

3. 验证配置生效

   • 启动 Agent 后，询问「当前项目的技术栈是什么？」
   • 检查 Agent 是否遵守规则（如生成代码时是否使用 MyBatis-Plus）

4. 在对话或工作流中调用

   • 通过自然语言触发（如"帮我做一次代码审查"），Agent 自动加载对应的 Skill
   • 或通过命令显式调用（如 /review）

常见软件类型的集成方式

软件类型	典型集成方式	示例
Qoder	自动读取项目根目录 AGENTS.md	Qoder CLI / IDE
CodeBuddy	自动识别 AGENTS.md 并加载	CodeBuddy IDE / CLI
Claude Code	读取 AGENTS.md 或 CLAUDE.md	Claude Code CLI
Cursor	通过 AGENTS.md 定义项目规则	Cursor IDE
其他 AI 编程助手	配置读取 AGENTS.md 路径	支持通用 AGENTS.md 协议的工具

关键检查点

• ✅ 文件是否命名为 AGENTS.md 并放在项目根目录
• ✅ 是否定义了「红线规则」（硬约束）
• ✅ 是否定义了「核心身份」（技术栈、目标）
• ✅ 技能模板是否包含清晰的输入输出说明
• ✅ 工作流规范是否完整（提案→实施→归档）

在代码中使用 UAM

# 以 Python 示例展示 Agent 读取 UAM 配置
from uam_agent import UAMAgent

agent = UAMAgent(
    manifest_path="./AGENTS.md",  # UAM 配置文件路径
    model="Qwen/Qwen3-235B-A22B-Instruct-2507"
)

# 自动加载规则、记忆、技能和流程
result = agent.run("实现一个用户积分查询接口")
print(result)

# 验证配置是否生效
rules = agent.list_rules()
skills = agent.list_skills()
print(f"已加载 {len(rules)} 条规则，{len(skills)} 个技能")

注意事项

• 首次使用建议在隔离环境中测试 UAM 配置，避免误修改
• 部分技能依赖外部 API 或数据库，需自行配置连接信息
• 使用前请阅读 UAM 模板中的技能描述，确保参数格式正确
• 如遇问题，可在社区「UAM 交流」区反馈，或查看示例项目

与传统配置的对比

维度	传统方式（分散配置）	UAM（统一清单）
入口文件	.qoder/、.claude/、openspec/ 多个目录	一个 AGENTS.md
规则管理	分散在各工具配置中	统一在「红线规则」章节
技能复用	不同工具各自定义	统一的技能模板格式
工具切换	需重新配置	切换工具只需迁移一个文件
学习成本	需理解多个概念体系	只需理解一个文件结构

UAM 不是新概念，而是对现有概念的重新组织——用一份文件、一个入口、一套结构，让 AI Agent 从「碎片化配置」走向「统一行为边界」。

2026年一个普通Coder，面对AI Coding领域概念爆炸、工具林立、规则割据的局面，写下的“独立宣言”。