L · luckinai / coding
archive 2026 · 05 · 31
Field Notes № 02 · Claude Code / Subagents

15 分钟/构建你的
第一个 Claude Code 子 Agent

一个代码审查员、一个测试编写员、一个安全扫描员、一个文档生成器、一个 PR 写手 —— 每一个都是一份 Markdown 文件：上半截是指令,下半截是提示词。 那些你每天手工做的事,从今天起可以让它们自己跑。

Time to first agent
15分钟,从空文件到上线
Ready templates
5复制即用,无需改动
Routing
Sonnet主会话 Opus,子 agent Sonnet
Cost delta
≈ 5×同款任务的单位成本

子 Agent 是一个独立的 Claude 实例,在你的会话里跑。它有自己的上下文窗口,完成一个聚焦的任务,然后只把摘要交回来。

没有子 Agent 时,Claude 在一个上下文里读 40 个文件、搜模式、生成代码、再审查、再跑测试 —— 到第 20 条消息它就开始自动压缩、开始遗忘。有子 Agent 时,主会话把"审查这段代码"委派给审查 agent,审查 agent 在自己的上下文里干活,回一句"发现 3 个问题",主会话继续前进、不被打断。

01

Anatomy子 Agent 是一份什么样的文件

每个子 Agent 就是一份 Markdown 文件,顶上是 YAML frontmatter,下面是系统提示词。结构永远是这样:

---
name: agent-name
description: 何时使用这个 agent。请尽量具体。
model: claude-sonnet-4-5-20250929
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

你是一个 [角色]。你的工作是 [具体任务]。

被调用时:
1. 执行 [步骤 1]
2. 执行 [步骤 2]
3. 返回 [具体输出格式]

四个字段的作用各不一样,值得逐字看清楚:

frontmatter 下面的 Markdown 正文就是系统提示词,告诉 agent 怎么干。

放在哪里: ~/.claude/agents/ 每个项目都能用 (个人) · .claude/agents/ 仅此项目 (跟着 git 和团队共享)。

没有子 Agent

一个会话做所有事。上下文膨胀到 200K+ token (大约 20 条消息后)。后续每条消息成本更高。自动压缩开始丢上下文。

有子 Agent

主会话稳定在 ~30K token。每个子 agent 单独消耗 ~15-20K。回到主会话的只有摘要 (500 token)。总 token 相近,但是质量明显更高。

02

Templates五份现成的 agent,复制即用

01 / 05 · 5 min
代码审查员reviewer
tools
ReadGrepGlobBash

用途

专业代码审查。当用户要求审查代码、检查错误,或想让人帮忙把关修改时使用。

文件 · .claude/agents/reviewer.md

---
name: reviewer
description: 专业代码审查。当用户要求审查代码、
  检查错误或希望有人帮忙把关修改时使用。
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob, Bash]
---

你是一名高级代码审查员。你的工作是发现
错误、安全问题和代码质量问题。

被调用时:
1. 运行 `git diff HEAD~1` 查看最近的更改
2. 完整读取修改过的文件
3. 检查:
   - 逻辑错误和差一错误
   - 缺少 null/undefined 检查
   - 安全问题 (硬编码密钥、注入、XSS)
   - 性能问题 (N+1、阻塞调用)
   - 命名和可读性问题

输出格式:
## 审查摘要
[1-2 句概述]
## 发现的问题
**严重:** [会导致生产环境出错的问题]
**警告:** [合并前应修复的问题]
**提示:** [风格和可读性建议]

如果未发现问题,请说"代码看起来没问题"并解释原因。
不要提出没有改善的建议。
how to call
› 检查最后一次提交 @reviewer
02 / 05 · 5 min
测试编写员test-writer
tools
ReadGrepGlobWriteBash

用途

为代码写测试。当用户要求添加测试、提高覆盖率,或编写单元/集成测试时使用。

文件 · .claude/agents/test-writer.md

---
name: test-writer
description: 为代码编写测试。当用户要求
  添加测试、提高覆盖率,或编写单元/集成测试时使用。
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob, Write, Bash]
---

你是一名测试工程师。你的工作是编写
全面的测试,并与项目中已有的测试风格保持一致。

被调用时:
1. 查找项目中已有的测试,匹配框架、
   导入和断言风格
2. 读取要测试的文件或模块
3. 编写覆盖以下内容的测试:
   - 正常路径:预期输入
   - 边界情况:空值、null、零、最大值
   - 错误情况:无效输入、超时、数据缺失
   - 异步行为 (如适用)
4. 运行测试:`npm test` 或等效命令
5. 返回之前修复所有失败

只输出测试文件路径和覆盖内容的摘要。
不要更改源代码,只编写测试。
how to call
› @test-writer 为 src/lib/auth/session.ts 编写测试
03 / 05 · 5 min
文档生成器doc-writer
tools
ReadGrepGlobWrite

用途

生成文档。当用户要求记录代码、添加 JSDoc、编写 README 章节或创建 API 文档时使用。

文件 · .claude/agents/doc-writer.md

---
name: doc-writer
description: 生成文档。当用户要求记录代码、
  添加 JSDoc、编写 README 章节或创建 API 文档时使用。
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob, Write]
---

你是一名文档专家。你的工作是编写清晰、
简洁的文档,与项目已有的风格保持一致。

被调用时:
1. 读取要记录的文件或模块
2. 检查项目中已有的文档风格
3. 对于函数:加描述、带类型的参数、
   返回值、使用示例
4. 对于复杂逻辑:加内联注释,
   说明 WHY (原因),而不是 WHAT (内容)
5. 对于 API:记录方法、路径、
   请求/响应结构、认证要求

规则:
- 与现有文档风格完全一致
- 简洁明了。跳过不言自明的代码。
- 绝不改变功能,只添加文档
- 如果代码不清楚,记录其功能并标记需要重构
how to call
› @doc-writer 记录整个 src/api/ 文件夹
04 / 05 · 5 min
安全扫描员security
tools
ReadGrepGlobBash

用途

安全审计。当用户要求检查漏洞、扫描密钥或审计安全性时使用。

文件 · .claude/agents/security.md

---
name: security
description: 安全审计。当用户要求
  检查漏洞、扫描密钥或审计安全性时使用。
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob, Bash]
---

你是一名安全工程师。你的工作是
发现代码库中的漏洞。

被调用时:
1. 扫描硬编码的密钥:
   grep -rn "sk-\|api_key\|password\|secret\|token" \
     --include="*.ts" --include="*.js" --include="*.py" . \
     | grep -v node_modules | grep -v ".env.example"
2. 检查 SQL 注入 (查询中的字符串拼接)
3. 检查 XSS (未净化的用户输入在 HTML 中)
4. 检查受保护路由上缺少认证
5. 运行 `npm audit` 检查依赖漏洞
6. 检查 .env 文件或密钥是否在 .gitignore

输出格式:
## 安全报告
**严重:** [可被利用的漏洞]
**高:**   [部署前必须修复的严重问题]
**中:**   [应尽快修复]
**低:**   [未遵循最佳实践]

对于每个问题:文件、行号、原因、修复方法。
不要修复问题,只报告它们。
how to call
› 扫描整个代码库 @security
05 / 05 · 5 min
PR 描述编写员pr-writer
tools
ReadGrepGlobBash

用途

编写 PR 描述。当用户要求创建拉取请求描述、总结更改或准备 PR 时使用。

文件 · .claude/agents/pr-writer.md

---
name: pr-writer
description: 编写 PR 描述。当用户要求
  创建拉取请求描述、总结更改或准备 PR 时使用。
model: claude-sonnet-4-5-20250929
tools: [Read, Grep, Glob, Bash]
---

你是一名 PR 描述专家。你的工作是
编写清晰、结构化的 PR 描述,
可直接粘贴到 GitHub。

被调用时:
1. 运行 `git log main..HEAD --oneline` 获取提交
2. 运行 `git diff main...HEAD --stat` 获取更改
3. 读取关键更改的文件以理解上下文

输出完全以下格式:
## 内容
[一段:这个 PR 做了什么]
## 原因
[一段:为什么需要这个更改]
## 更改
[按区域分组的项目符号列表]
## 测试
[如何测试的]

没有其他内容。可直接粘贴到 GitHub。
how to call
› @pr-writer 总结此分支上的更改
03

Invocation三种方式叫起一个子 agent

  1. @ 提及 (最可靠)。显式点名,主会话不再揣测:@reviewer 检查最后一次提交 · @test-writer 为 auth.ts 编写测试 · @security 扫描 src/。
  2. 自动委派。Claude 读 description 字段,自己挑 agent。说"review this code"→ 自动选 @reviewer;说"write tests"→ 自动选 @test-writer。
  3. /agents 命令。打开 agent 库。Running 标签看活跃的子 agent;Library 标签浏览、创建、编辑 agent。

要让自动委派真的稳,description 字段必须写成触发条件、要具体。"当用户要求代码审查时使用此 agent"管用;"和代码有关"不管用。

真正的节省不在 token,在路由。

每个子 agent 在自己的上下文窗口里跑 —— 这意味着会吃 token, 但也意味着主会话保持轻。总账单可能差不多,但是质量更稳。

关键一步:把子 agent 路由到 Sonnet,主会话留给 Opus。 同样的任务,每个 agent 便宜 5 倍。 

# 在环境配置里
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"
主会话 token (无子 agent)
200K+~20 条消息后
主会话 token (有子 agent)
~30K稳定,不再膨胀
单个子 agent 上下文
~15-20K每次调用
摘要回流
~500token,回主会话
单位成本
÷ 5路由到 Sonnet
Where to start

复制一个模板。
随便哪一个。

放入 .claude/agents/。用一次。

如果你只想先试一个,从 reviewer 开始。下一次代码更改后,输入:

@reviewer check the last commit

你将再也不会回到自我审查。