第 16 章 | 编写 agent 文件

更新于 2026/5/11
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 16 章：编写 agent 文件

学习目标

写出真的能被 main Claude 找到并 dispatch 的 agent 文件。

文件结构

flowchart TB
    File[".claude/agents/<name>.md"] --> FM["frontmatter
(name/description/tools/model)"]
    File --> Body["system prompt
(角色定义 + 工作流 + 约束)"]

    FM --> N["name: 唯一标识"]
    FM --> Desc["description: 何时被调用"]
    FM --> Tools["tools: 允许使用的工具"]
    FM --> Model["model: opus / sonnet / haiku"]

    style FM fill:#fff9c4
    style Body fill:#c8e6c9

Frontmatter 字段详解

---
name: developer
description: Implements one group of tasks from the active OpenSpec change's tasks.md. Also fixes issues when sent back from tester or reviewer.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---
字段 作用 写法关键
name 唯一标识 用 kebab-case，跟文件名匹配
description 决定何时被调用 写得具体——main Claude 通过这个判断要不要 dispatch
tools 限制工具集 不写 = 全部；写了就只有列出的可用
model 用哪个模型 sonnet（默认）/ opus（深度）/ haiku（琐碎）

description 的关键作用

main Claude 看 description 决定"现在要不要派这个 agent 出来"。所以：

❌ "Helps with development"
   → 太宽，啥都派 → 浪费 dispatch
   
✅ "Implements one group of tasks from active OpenSpec change's tasks.md.
    Also fixes issues when sent back from tester (test failures) or
    reviewer (rejection)."
   → 具体说"什么场景调我" → 派得准

写 description 公式：<做什么> + <什么时候被叫>。

system prompt 写作要点

四段式：

flowchart TB
    SP["system prompt"] --> S1["1. 你是谁
(身份 + 边界)"]
    SP --> S2["2. 你的输入
(briefing 会给什么)"]
    SP --> S3["3. 你的工作流
(步骤 + 约束)"]
    SP --> S4["4. 你的输出格式
(报告 schema)"]

    style SP fill:#fff9c4

实例：developer.md 解剖

---
name: developer
description: Implements one group of tasks ...
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---

# 你是 doc2video 的实现工程师

[1. 身份 + 边界]
你的工作：把调度者指定的一组 OpenSpec 任务变成可运行的代码。

[2. 输入]
## 输入（调度者会在 prompt 里给）
- active change 路径
- 组号 + 组名
- 该组所有 - [ ] 任务原文
- 必读文件：design.md / spec.md
- 上一轮反馈（仅当回炉）

[3. 工作流]
## 工作流程
1. 读完必读文件
2. 理解任务范围
3. 实现
4. 本地验证
5. 提交

[3-bis. 严格约束 = 反模式列表]
## 严格约束
- 不写测试（tester 的事）
- 不改规约（specs/ design.md proposal.md 禁动）
- 不擅自扩大范围
- 不自动修复命令报错（design D6）

[4. 输出]
## 完成时回报（结构化）
\`\`\`
## Developer Report — Group N
**Status:** done | blocked
...
\`\`\`

→ 4 段式让 agent 知道做什么、不做什么、怎么报告。

测试 agent 是否好用

写完一个新 agent，手动 dispatch 一次看产出：

你: 用 developer agent 实现 group 1
   ↓
观察:
- 它读了哪些文件？（看 Read 调用）
- 它改了哪些文件？（git diff）
- 报告格式对吗？（看输出）
- 越界了吗？（改了不该改的？）

如果有任何不对，改 agent 文件而不是教它一次次 —— system prompt 是它的 DNA，每次 dispatch 都重新读。

反模式

❌ description 写得像广告 ("超强实现 agent")
❌ system prompt 没有"严格约束"段
❌ 没有结构化输出格式（main Claude 不知道怎么解析）
❌ 把整个 CLAUDE.md 复制进 agent prompt（重复 + 维护噩梦）
❌ 给 agent 它不该有的工具（如 reviewer 给 Edit）

工具集的常见配方

角色 推荐工具
developer Read, Edit, Write, Bash, Grep, Glob
tester 同上（要写测试 + 跑 pytest）
e2e-tester Read, Bash, Grep, Glob, Write（不给 Edit，只能写 report）
reviewer Read, Bash, Grep, Glob, Write（同上）
architect 同 reviewer

→ 工具不是越多越好——少 = 行为可预测。

你现在能做什么

  • 写一份能被 main Claude 找到的 agent 文件
  • 用 4 段式 system prompt 写清职责
  • 通过 dispatch 测试验证 agent 行为

下一章给每个角色配模型——成本与能力的最佳点。