一句话定义
Agent 是一个有角色、有任务边界、会自己做判断的 AI worker。
在这个 wiki 里，它通常落成一个 .md 文件: 你把“这个角色是谁、负责什么、不负责什么”写清楚，Claude 读到后就会按这个角色工作。
一句人话: agent 更像“岗位”，不是一次性 prompt。
为什么重要
当一类角色会反复出场，而且每次都需要一点判断，单靠聊天里临时交代很快就会乱。agent 的价值，就是把这个角色固定下来。
本仓库里已经有现成例子:
.claude/agents/ai-xueze.md是 AI 学者，负责raw -> wiki的编译、lint 和 IA 守护。- PK 系统里的 Alfred、Tyrion、Jung、Sheep 是不同角色，不是同一个“万能 AI”的不同心情。
这也是为什么 agent 不是“给 AI 起个名字”那么简单。名字只是入口，真正重要的是边界: 谁该上场，谁不该上场。
技术机制
更宽泛的 AI 圈里，agent 常指“能自己用工具完成目标的 AI”。到了 Claude Code 这类 md-based 系统里，它通常表现为 .claude/agents/<name>.md 这样的角色文件，里面写清：
name/display_name: 这个角色叫什么description: 什么任务该交给它tools/model/permissionMode: 它能怎么干- 正文协议: 它的工作目标、边界、交付物、禁区
Anthropic 官方对这类 worker 的核心强调有两点: 靠 description 决定何时委派，靠工具和权限约束能力边界。
所以 agent 的“技术本体”不是人格表演，而是三件事：
- 角色说明书
- 工具与权限边界
- 被调用时的稳定工作协议
如果这三件事没写清，agent 只是一个花名。
最小可跑通例子
最小版本可以先从一个只做评审的 agent 开始:
---
name: my-reviewer
description: Review changed code for readability and obvious risks. Use after edits are complete.
tools: Read, Grep, Glob
model: sonnet
---
只做评审，不改文件。
先列风险，再给建议。放到 .claude/agents/my-reviewer.md 之后，你可以用自然语言让它上场，也可以在支持 agent delegation 的环境里显式派它：
Task(
description="审代码",
prompt="审查 src/auth.ts 的安全和可读性，只报高风险问题。",
subagent_type="my-reviewer",
)这里要注意: 被 Task(...) 派出去时，它就是 subagent 式运行；agent 是角色，subagent 是一种运行方式。
常见误解
- 把 agent 写成 skill。如果一段内容只是“固定步骤的做法”，没有角色判断，就不该伪装成 agent。
- 把 agent 和 subagent 当同义词。agent 讲的是角色；subagent 讲的是这个角色在独立 context 里被派出去执行。
- 一个 agent 囤太多责任。把“写作、审稿、发布”全塞进一个 agent，往往会把起草标准和评审标准搅在一起。更稳的做法是拆角色，再放进 workflow 里编排。
- 以为起个名字就算建好 agent。没有边界、没有禁区、没有交付物的 agent，最后还是会退化成“请你帮我做点什么”的通用聊天。
与其他术语的关系
[[subagent]]：agent 被独立派出去、在隔离 context 里干活时，就是 subagent 式运行。[[skill]]：skill 是 agent 调用的技能包；agent 决定何时调用，skill 负责把某件事做稳。[[workflow]]：workflow 决定先后顺序和协作方式；agent 是其中承担判断的参与者。[[Harness]]：agent 不是凭空存在，它跑在一整套说明书、权限、工具和上下文规则组成的 harness 里。[[CLAUDE.md]]：CLAUDE.md 提供项目级背景和共识；agent 在这个总说明书之上追加自己的角色协议。
陈彬视角
大多数人第一次搭系统，都先搞 Agent（因为有人格、好玩）。正确顺序其实是反过来: 先想清楚 workflow，再决定哪里需要 agent（有判断的地方），剩下的全是 skill。从 workflow 倒推 agent，不从 agent 发散出 workflow。
延伸阅读
[[skill]][[workflow]][[subagent]][[02-基建/平台/claude-code/subagent]][[02-基建/平台/claude-code/agent-teams]][[04-系统/02-机制/多 Agent 协作实战]]
🎬 3 个场景（读者最可能用到的情境）
场景 1 · HR 设”面试官 agent”
HR 每周面试 5 个候选人。把”面试官”做成 agent：固定评估维度、追问策略、禁区（不问婚育/薪资倒推）、输出结构（结论 + 3 条证据 + 风险）。比每次重新贴 prompt 稳。
场景 2 · 写作者设”编辑 agent”
自由撰稿人写完初稿找 AI 审。做一个”编辑”agent：角色=带 10 年经验的非虚构编辑、只挑结构问题和事实漏洞、不改风格、不改句子。同一个编辑反复上场，标准才稳。
场景 3 · 散户设”风控 agent”
散户让 AI 做盘后分析，但怕它滑向”推荐”。做一个”风控”agent：只看仓位集中度/回撤风险/板块暴露，不给买卖建议，不预测行情。角色边界一写清，AI 就不越线。
⚖️ 和最像的邻居比
| 术语 | 本质区别 | 适用边界 |
|---|---|---|
| agent | 有角色判断的岗位 | 同一类任务反复出现、需要稳定视角 |
| skill | 一件事的做法 | 步骤稳定、不需要人格判断 |
| subagent | agent 的一种运行方式（独立 context） | 侧任务、只需要结论不需要中间过程 |
| prompt | 一次性指令 | 这轮就用、下次不复用 |
🚫 反例（不该这么用）
反例 1 · 一个 agent 做所有事
HR 建一个”万能人事 agent”，同时负责招聘、盘点、绩效、薪酬、合同审查。结果每次都得重新解释”这轮是哪个场景”，起草标准和评审标准全混在一起。正确做法：按场景拆 4-5 个独立 agent，每个只管一件事。
反例 2 · agent = 给 AI 起个名字
写一个叫”Kris”的 agent，里面只说”你是一个专业顾问”，没有边界、没有禁区、没有交付物。最后还是退化成通用聊天。正确做法：名字之外，必须写清”什么任务该给它 / 不该给它、输出什么、不做什么”。
❓ 常见误解
- 误解 1：“agent 越多越好” → 实际：每多一个 agent 就多一份维护成本和触发边界混乱，少而精 > 多而散，大多数系统 2-3 个 agent 就够。
- 误解 2：“agent = subagent” → 实际：agent 是角色定义，subagent 是”把 agent 放到独立 context 里跑”的运行方式，一个是名词一个是姿态。
- 误解 3：“先设计 agent 再想工作流” → 实际：正确顺序反过来——先想清楚 workflow，再决定哪个环节需要有判断的 agent。
🧬 历史坐标（最早谁提 · 本质 · 分型 · git）
最早谁提
“Agent” 作为认知单元的用法可追溯到 1986 年 Marvin Minsky 的《Society of Mind》——把心智看成由无数简单 agent 组成的社会。现代 LLM agent 从 2022 年 10 月 Shunyu Yao 等人的 ReAct 论文（arxiv:2210.03629，后发 ICLR 2023）开始工程化：让 LLM 交错产出 reasoning 和 action。
本质（一句话 · 20 字内）
有角色、有工具、会循环判断的 AI worker。
分型 / 演化（2-4 行主线）
- 1986 · Minsky《Society of Mind》奠定”心智 = agent 社会”的概念原型
- 2022-10 · ReAct 论文让 LLM 学会 reason + act 交错循环
- 2023-03 · AutoGPT 把 agent 带出实验室，点燃”LLM 自主完成目标”的社群想象
- 2025-07 · Anthropic 在 Claude Code 里用
.claude/agents/*.md把 agent 角色化、文件化
代表 git / 文档
- ysymyth/ReAct · Shunyu Yao · ReAct 论文官方实现
- Significant-Gravitas/AutoGPT · Toran Bruce Richards · 首个破圈的 LLM autonomous agent
- Building Effective Agents · Anthropic (2024-12) · Agent vs Workflow 的权威分类
为什么要这张表
一个 agent 文件顶部的 frontmatter 写什么、怎么写，决定了这个 agent 能干什么、会不会乱跑。官方文档把 16 个字段分散在多处，这里集中成一张表，方便你对着自己的 .md 文件逐行核对。用不上的字段不填即可，只有 name 和 description 是必填的。
字段全集表（16 个）
| 字段 | 是否必填 | 类型 | 含义 | 举例 |
|---|---|---|---|---|
name | 必填 | string | agent 唯一标识，只用小写字母和连字符 | my-reviewer |
description | 必填 | string | 什么时候交给它——这是 Claude 判断”该不该派它”的主要依据；写 "PROACTIVELY" 可触发 Claude 主动调用 | Review code after edits. PROACTIVELY suggest when files change. |
tools | 选填 | string / list | 允许使用的工具白名单，逗号分隔；不填则继承所有工具；支持 Agent(agent_type) 语法限制可派生的子 agent | Read, Grep, Glob |
disallowedTools | 选填 | string / list | 禁止使用的工具黑名单，从已继承或已指定的列表里移除 | Bash, Write |
model | 选填 | string | 使用哪个模型：sonnet / opus / haiku / 完整模型 ID / inherit（默认） | haiku |
permissionMode | 选填 | string | 权限模式：default / acceptEdits / auto / dontAsk / bypassPermissions / plan | acceptEdits |
maxTurns | 选填 | integer | 最多跑几轮 agentic turn，超过后自动停 | 5 |
skills | 选填 | list | 启动时预加载的 skill 名称列表（完整内容注入，不是只让它”知道”） | [kb-compile, kb-lint] |
mcpServers | 选填 | list | 该 agent 专用的 MCP 服务器，写服务器名字符串或内联 {name: config} 对象 | [context7] |
hooks | 选填 | object | 该 agent 作用域内的生命周期钩子，支持所有 hook 事件，最常用的是 PreToolUse / PostToolUse / Stop | {Stop: [{type: command, command: echo done}]} |
memory | 选填 | string | 持久记忆范围：user / project / local | project |
background | 选填 | boolean | 设为 true 则始终以后台任务方式运行（默认 false） | true |
effort | 选填 | string | 覆盖当前 session 的算力档位：low / medium / high / max（仅 Opus 4.6 支持）；默认继承 session | low |
isolation | 选填 | string | 设为 "worktree" 则在临时 git worktree 里跑，没有变更时自动清理 | "worktree" |
initialPrompt | 选填 | string | 当 agent 以主 session 身份启动（--agent 或 agent 设置）时，自动作为第一个用户 turn 提交，会处理其中的 commands 和 skills，并前置于用户输入 | "先读 CLAUDE.md，再等待任务。" |
color | 选填 | string | 该 agent 在任务列表和对话记录里显示的颜色：red / blue / green / yellow / purple / orange / pink / cyan | blue |
常用 3 个字段的深讲
model — 省钱最直接的一个字段
“Model to use:
sonnet,opus,haiku, a full model ID (e.g.,claude-opus-4-6), orinherit(default:inherit)” — CCBP 原文
人话：不填就跟主 session 用同一个模型。但如果某个 agent 只做搜索和读文件，写 model: haiku 能明显省 token。反过来，负责最终决策的 agent 可以单独升到 opus。这个字段是”按需定级”最简单的入口。
permissionMode — 控制它能不能直接改文件
“Permission mode:
default,acceptEdits,auto,dontAsk,bypassPermissions, orplan” — CCBP 原文
人话：default 每次改文件都问你确认；acceptEdits 静默接受所有文件编辑但其他操作还问；bypassPermissions 完全跳过确认（危险，谨慎用）；plan 只出计划不动文件。如果你让一个 agent 做评审，设成 plan 最稳——它物理上就写不了东西。
tools — 角色边界最具体的一环
“Comma-separated allowlist of tools (e.g.,
Read, Write, Edit, Bash). Inherits all tools if omitted. SupportsAgent(agent_type)syntax to restrict spawnable subagents” — CCBP 原文
人话：不填等于什么工具都能用，风险最大。一个只做代码审查的 agent，填 Read, Grep, Glob 就够了——它连 Write 都没有，物理上改不了文件，边界最清晰。Agent(agent_type) 是进阶写法，限制这个 agent 只能派特定类型的子 agent，防止它随便开分支。
容易踩坑的字段
坑 1：description 写太模糊
description 是 Claude 判断”现在该派哪个 agent”的主要依据。写”帮我处理任务”这种话，Claude 不知道什么时候该触发它。应该写具体场景，比如”审查改完的代码，找可读性问题和潜在风险”。如果想让 Claude 主动调用，在 description 里写上 PROACTIVELY。
坑 2：tools 不填以为”没关系”
不填 tools 等于继承所有工具，包括 Bash（可以跑任意命令）。如果你的 agent 只是一个”读-分析-输出”角色，给它 Bash 权限等于留了一个后门。最小权限原则：只填它真正需要的工具。
坑 3：skills 和”让 agent 知道有哪些 skill”是两回事
skills 字段设计是”预加载”——把 skill 的完整内容直接注入 agent 的 context，不是告诉它”有这个 skill 可以调”。所以列越多，context 越重。只加真正每次都要用的 skill，其余的按需调用。
关联
- 基础定义见 02-agent（agent 是什么、三件事、常见误解）
- 被派出去独立跑时的机制见 04-subagent
- 这 16 个字段与具体运行环境的关系，见正本”技术机制”一节
来源：/Users/chenbin/Documents/Personal Kingdom/知识库/素材_AI使用/项目样本/claude-code-best-practice/github-mirror/claude-code-best-practice/best-practice/claude-subagents.md（CCBP v2.1.101 · 原版 Frontmatter Fields 表，字段数 = 16）