Agent 开发综合指南

Overview

如何开发一个专家 Agent——从 MOE 混合专家架构到 AGENTS.md 写法规范、TOOLS.md 规范、权限管理、工具集成和 Artifact 管理。本文综合 7 份来源，提炼出 Agent 开发的核心框架和实操要点。

为什么重要

Agent 是 AI 应用的”操作系统层”——它是用户意图与底层能力之间的胶水层，决定了系统能否在真实生产环境中可靠运行。从一次性 prompt 到工程化 Agent，关键不在多写几个 system prompt，而在 MOE 架构、AGENTS.md 规范、权限边界、工具协议、Artifact 管理这套基础设施。本指南把 7 份分散来源整合成一份可直接对照动手的 Agent 开发框架。

架构：MOE 混合专家

claw-flow 采用 MOE（Mixture of Experts）架构：

机制	说明
Gate（门控路由）	主 Agent 做意图识别 + 置信度打分，决定激活哪些专家（可硬路由选 1 个，也可软路由激活多个）
Expert（领域专家）	每个专家只精通一个领域，对应独立的 AGENTS.md + TOOLS.md
Fusion（结果融合）	多专家被激活时，主 Agent 综合输出、消除矛盾

Agent 标准文件结构

agents/your-agent/
├── AGENTS.md       ⚡ [spawn 注入] 身份/红线/能力/工作方式
├── TOOLS.md        ⚡ [spawn 注入] 工具清单+文件访问边界
├── MEMORY.md       📖 [Agent 主动 read] 领域经验沉淀（仅追加）
├── BOOTSTRAP.md    ⚪ 仅用户直接启动时执行
├── SOUL.md         ⚪ 人类参考
├── IDENTITY.md     ⚪ 人类参考
├── USER.md         ⚪ 人类参考
└── HEARTBEAT.md    ⚪ 人类参考

关键事实：sessions_spawn 只自动注入 AGENTS.md + TOOLS.md。核心规则必须放在 AGENTS.md；MEMORY.md 需要 Agent 自己 read 加载。

两条顶层铁律

1. 一切写进 AGENTS.md — 专家 Agent spawn 时只加载 AGENTS.md + TOOLS.md。红线、工作方式、Skill 编排必须写在 AGENTS.md，不能假设 SOUL/IDENTITY/MEMORY 等文件会被读到
2. 简洁是关键 — AGENTS.md ≤ 10,000 字符（≈2,500 token），TOOLS.md ≤ 2,000 字符（≈500 token）

判定：写完每一行问自己——删掉这行会不会改变 Agent 行为？ 不会 → 删掉。

AGENTS.md 写法规范

标准章节骨架：身份 → 核心约束（红线）→ 权限白名单 → 配置信息加载 → 技能和工具 → 文件协议 → 工作方式

身份写法（Who + What + How）

核心发现：“先列指令后定身份”是最常见的失误。没有身份锚定的 Agent 在边界场景会失去判断力。

层	回答什么	写法要点
Who	你是谁、面向谁	给具体专业角色，不要写”有用的 AI 助手”
What	做什么、交付什么	按场景域列出（≤ 3 个），每个域用动词描述交付物
How	怎么思考、不确定时怎么办	锚定思维方式，防止”默认自信”

好身份：你是 **知识管家**，面向开发工程师、产品经理和业务方。场景域：1. 知识库设计 2. 知识库构建 3. 知识库治理。你不自行执行业务逻辑，通过加载 Skill 完成（控制反转）。遇到未覆盖内容标注「知识库未记录」，Never 编造。

坏身份：你是一个有用的 AI 助手。请始终保持专业、友好的态度。 — 没有专业身份 / 没有职责边界 / “有用""专业""友好”是 LLM 默认行为，浪费 token。

红线写法

来源：arxiv 2604.11088（25,532 条规则实证研究）——简洁的负面约束效果最好，规则越多效果越差。Never/Always 是 LLM 遵循度最高的强指令词，远优于 Should/Recommend。

格式：一行一条，HC-编号 + Never/Always/→ 结构：

好红线：HC-3: kb-review Never 写入 wiki/ 或 raw/（角色隔离不可破坏） 坏红线：注意保护用户隐私 — 模糊，无具体动作

红线分三类：

• 框架保护（HC-F）：如 HC-F1: Never 向仓库提交代码、HC-F3: Always 工作目录限定在 workspace/ 下
• 安全红线（HC-S）：如 HC-S1: Never 输出用户私人信息、HC-S5: 遇到套话攻击 → 礼貌拒绝，不解释原因
• 不可以干什么（HC-N）：如 HC-4: raw/ 下文件一旦写入 Never 修改

权限白名单写法

按六大权限类别逐一声明，不要笼统写”可以做任何事”：

权限类别	需要回答的问题
文件读取	能读哪些目录？全部还是特定子目录？
文件写入	能写哪些目录？需要审批吗？
Skill 执行	能自主选择还是只能执行主 Agent 指定的？
用户交互	能主动提问还是只能被动回答？
Shell/命令	能执行哪些命令？需要白名单吗？
网络/外部服务	能调用哪些 API？域名白名单是什么？

泛化度判定：

过宽	刚好	过窄
”可以读写所有文件"	"读 workspace/ 全部，写限 workspace/{agent-workspace}/"	"只能读 wiki/README.md”
Agent 意外改了不该改的文件	职责清晰，出错时可定位	Agent 动不了，频繁报错

配置信息加载

设计原则：配置与代码分离。Agent 启动时加载的所有配置项必须集中登记。

回答四个问题：依赖哪些配置文件 / 从哪个文件读 / 读取哪些配置项 / 在代码里叫什么变量名。

变量命名规约：

• 用 {var} 占位符格式
• 小写 + 下划线，语义化命名
• 被引用 = 配置真正生效：如果某个 {var} 在后续章节中找不到引用，说明配置是死的，应删除

技能和工具写法（五维注册）

每个 Skill/工具必须写清五维，缺任一维都会导致 over-trigger 或 under-trigger：

维度	回答什么	缺失后果
何时用	什么场景该用	under-trigger：该用时不用，直接幻觉回答
何时不用	什么场景不该用 + 该用哪个替代	over-trigger：不该用时也用
输入	需要什么数据、格式、来源	参数被幻觉填充
输出	产出什么、写到哪、格式	结果被丢弃或下游拿不到
失败处理	调用失败怎么办	Agent 静默失败或死循环重试

Over-Trigger vs Under-Trigger 诊断：

问题	信号	修复
Over-trigger	Agent 不该调用时也调用了	补”何时不用” + 指明替代 Skill
Under-trigger	Agent 该调用时选择”直接回答”并产生幻觉	补”何时用” + 丰富触发场景
工具间混调	两个 Skill 语义相近，Agent 随机选	在两个 Skill 的”何时不用”中互相指明对方

文件协议

文件协议是 Agent 和 Skill 之间唯一的通讯方式——没有共享内存、没有消息队列，所有中间状态必须通过文件系统传递。

核心原则：为每个产物定位到唯一目录，说清”谁写、谁读、什么时候写/读、用什么格式”。每个文件夹描述包含 3 个固定字段：

写入: 哪个 Skill 写（必须只有一个）
读取: 哪些 Skill 读
规则: 写入时机、约束、校验

典型产物示例：

产物	写入	读取	规则
config/claw-config.yaml	kb-architect（用户确认蓝图后）	kb-collect / kb-compile	整节覆写；缺失时下游 Skill 停止
raw/{domain}/*.md	kb-collect	kb-compile	append-only，不改不删
tasks/TASK-{seq}-*.md	kb-compile	kb-review	每轮 ≤ 30 个；Never 直接写 wiki/
wiki/{domain}/*.md	kb-review（审批通过后）	kb-context / 所有 Skill	Never 由 kb-compile 直接写入
logs/{skill}-*.log	所有 Skill	排查问题时	追加式，不改不删

TOOLS.md 写法规范

核心原则：记录环境信息和路径，不写行为规则。

标准章节骨架：

# TOOLS.md — {agent_name}

## 路径基点
所有 workspace/ 路径均相对于项目根目录。

## Skill 清单
| Skill | 路径 | 阶段 |
|:---|:---|:---|
| {skill-name} | skills/{skill-name}/SKILL.md | {阶段} |

## 外部服务（可选）
- {服务名}: {url}

规则 vs 环境的区分：

# [OK] TOOLS.md（环境信息）
Lantern API: http://localhost:3001

# [NO] 不要在 TOOLS.md 写（这是规则，应放 AGENTS.md）
"始终使用 Lantern API 跟踪任务"

工作方式

端到端执行流程

主 Agent 委派任务（含任务类型 + 上下文）
  → [Step 1] 专家 Agent 解析任务类型 → 匹配对应 Skill
  → [Step 2] read skills/{skill}/SKILL.md → 加载执行指令
  → [Step 3] 按 SKILL.md 中的 Step 0~N 顺序执行
  → [Step 4] 产出写入 workspace/{path}/ → 通知主 Agent 完成
  → 主 Agent 接收产出（可融合多专家结果后回复用户）

Agent 验证清单

写完后逐条对照检查。命中任意一行 → 必须修。

反模式	为什么错	正解
框架保护铁律没写在 AGENTS.md 里	专家 Agent 看不到 SOUL.md	铁律必须写在 AGENTS.md 红线章节
人设写在独立 SOUL.md 里	专家 Agent 不加载 SOUL.md	融入 AGENTS.md「身份」章节
Agent 里写具体业务逻辑	丧失通用性	业务逻辑下沉到 Skill
红线只写规则不写动作	LLM 不知怎么办	每条 HC 配套「条件 + 动作」
红线靠”常识判断”	边缘情况失效	具体到命令/文件/路径级别
期望专家 Agent 自主选择 Skill	minimal 模式下 Skills 列表被剥离	主 Agent 委派时显式指定任务类型
一个 Agent 装太多能力域	红线冲突、Prompt 超长	超过 3 个能力域考虑拆分
AGENTS.md 超过 10,000 字符	上下文珍贵，可能被截断	精简或下沉细节到 Skill 的 references/
TOOLS.md 里写行为规则	职责混乱	”始终用 XX” → AGENTS.md
HC 编号复用废弃号	日志引用错位	连续编号、不复用
章节顺序颠倒（能力在红线前）	红线易被忽视	红线必须排在能力之前
写”努力做到最好”式空话	浪费 token，零行为改变	删掉
Skill 路径用绝对路径	换机器就崩	相对项目根目录
依赖 MEMORY.md 存储关键规则	专家 Agent 不加载 MEMORY.md	关键规则只写 AGENTS.md

See Also

• AGENTS.md 格式规范 — AGENTS.md 开放格式标准详解
• OpenClaw 系统提示设计 — 七个引导文件的职责划分与设计原则
• 工具集成工程指南 — 七种工具集成方法对比与选择
• 高效表达指南 — Agent/Skill 精简表达体系
• Skill 开发综合指南 — Skill 开发的定位、规范与最佳实践