agent-development

Claude Code 的 Agent 开发

通过恰当的任务委派、工具访问权限和提示词设计，为 Claude Code 构建高效的自定义 Agent。

Agent 描述模式

描述字段决定了 Claude 是否会自动委派任务。

强触发模式

---
name: agent-name
description: |
  [Role] specialist. MUST BE USED when [specific triggers].
  Use PROACTIVELY for [task category].
  Keywords: [trigger words]
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

弱描述与强描述

弱（不会自动委派）	强（会自动委派）
“分析截图中的问题”	“视觉 QA 专家。分析截图时必须使用。主动用于视觉 QA。”
“运行 Playwright 脚本”	“Playwright 专家。运行 Playwright 脚本时必须使用。主动用于浏览器自动化。”

关键短语：

• “必须在……时使用”
• “主动用于……”
• 包含触发关键词

委派机制

1. 显式：Task tool subagent_type: "agent-name" - 始终有效
2. 自动：Claude 根据 Agent 描述匹配任务 - 需要使用强措辞

创建或修改 Agent 后必须重启会话。

工具访问原则

如果 Agent 不需要 Bash，就不要授予它 Bash。

Agent 需要……	授予工具	不授予
仅创建文件	Read, Write, Edit, Glob, Grep	Bash
运行脚本/CLI	Read, Write, Edit, Glob, Grep, Bash	—
仅阅读/审计	Read, Glob, Grep	Write, Edit, Bash

原因？ 模型默认会使用 cat > file << 'EOF' heredoc，而不是 Write 工具。每条 Bash 命令都需要审批，因此每次 Agent 运行都会出现数十条审批提示。

允许列表模式

不要限制 Bash，而是在 .claude/settings.json 中将安全命令加入允许列表：

{
  "permissions": {
    "allow": [
      "Write", "Edit", "WebFetch(domain:*)",
      "Bash(cd *)", "Bash(cp *)", "Bash(mkdir *)", "Bash(ls *)",
      "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(grep *)",
      "Bash(diff *)", "Bash(mv *)", "Bash(touch *)", "Bash(file *)"
    ]
  }
}

模型选择（质量优先）

不要为了绕过问题而降低质量——应修复根本原因。

模型	适用场景
Opus	创意工作（页面构建、设计、内容）——质量很重要
Sonnet	大多数 Agent——内容、代码、研究（默认）
Haiku	仅用于对质量要求不高的脚本运行器

内存限制

修复根本原因（必需）

添加到 ~/.bashrc 或 ~/.zshrc：

export NODE_OPTIONS="--max-old-space-size=16384"

将 Node.js 堆内存从 4GB 提高到 16GB。

并行数量限制（即使已修复）

Agent 类型	最大并行数	备注
任意 Agent	2-3	上下文会累积；分批处理后暂停
高负载创意任务（Opus）	1-2	占用更多内存

恢复

1. 执行 source ~/.bashrc 或重启终端
2. 执行 NODE_OPTIONS="--max-old-space-size=16384" claude
3. 检查现有哪些文件，并从那里继续

子 Agent 与远程 API

始终优先选择 Task 子 Agent，而不是远程 API 调用。

方面	远程 API 调用	Task 子 Agent
工具访问	无	完整（Read, Grep, Write, Bash）
文件读取	必须在提示词中传入所有内容	可以迭代读取文件
交叉引用	单个上下文窗口	可以跨文档推理
决策质量	通用建议	具体决策并附带理由
输出质量	通常约 100 行	600 行以上，内容具体

// ❌ WRONG - Remote API call
const response = await fetch('https://api.anthropic.com/v1/messages', {...})

// ✅ CORRECT - Use Task tool
// Invoke Task with subagent_type: "general-purpose"

声明式优于命令式

描述要完成的目标，而不是如何使用工具。

错误（命令式）

### Check for placeholders
```bash
grep -r "PLACEHOLDER:" build/*.html

### Right (Declarative)

```markdown
### Check for placeholders
Search all HTML files in build/ for:
- PLACEHOLDER: comments
- TODO or TBD markers
- Template brackets like [Client Name]

Any match = incomplete content.

应包含的内容

包含	略过
任务目标和上下文	明确的 Bash/工具命令
输入文件路径	“使用 X 工具……”
输出文件路径和格式	逐步调用工具的说明
成功/失败标准	Shell 管道语法
阻塞性检查（前置条件）	过度管理的工作流
质量检查清单

自我文档化原则

“无法获取你的上下文的 Agent，必须能够独立复现相同行为。”

每项改进都必须写入 Agent 的提示词中，不能仅作为隐性知识保留。

需要编码的内容

发现	记录位置
Bug 修复模式	Agent 的“Corrections”或“Common Issues”部分
质量要求	Agent 的“Quality Checklist”部分
文件路径约定	Agent 的“Output”部分
工具使用模式	Agent 的“Process”部分
阻塞性前置条件	Agent 的“Blocking Check”部分

测试：一个全新的 Agent 能成功吗？

完成任何 Agent 改进之前：

1. 假设自己没有任何背景信息，阅读 Agent 提示词
2. 自问：新会话能否遵循这些内容并达到同样的质量？
3. 如果不能：补充缺失的说明、模式或参考资料

反模式

反模式	失败原因
“就像我们之前讨论的……”	不存在此前的上下文
依赖开发期间读过的文件	Agent 可能不会读取相同的文件
假设 Agent 能从错误中获取知识	Agent 看不到你的调试过程
“就像首页一样”	Agent 没有构建过首页

灵活性与严格性

根据任务类型匹配规范的详细程度。对灵活型 Agent 规定过多会让它们变得脆弱。

任务类型	规范详细程度	示例
机械性／重复性	高（严格步骤）	版本检查器、文件复制器
基于判断的任务	低（指导原则）	文档审查员、代码审查员
创意类	最低（仅目标）	内容撰写员、头脑风暴助手

规范过度的迹象

• Agent 在模板部分填写“N/A”
• 即使某些阶段无关，Agent 仍试图完成所有阶段
• 评分系统生成毫无意义的数字
• 当任务范围与假设不符时，Agent 会失败
• 简单任务却使用篇幅过长的 Agent（>150 行）

灵活型 Agent 指南

应该：

• 说明要查找什么，而非规定精确步骤
• 提供输出示例，而非僵化模板
• 加入范围控制（“如果超过 30 项，请询问用户”）
• 提供退路（“如果不确定，请标记以供审查”）
• 判断类任务的内容控制在 100 行以内

不应该：

• 要求填写模板的每个部分
• 创建复杂的加权评分系统
• 穷举列出所有可能的检查项
• 不经询问就假设任务范围

示例：文档审查员

规范过度（不好）：

## Phase 1: Discovery
Execute Glob for all .md files...

## Phase 6: Generate Report
| Category | Weight | Score | Weighted |
|----------|--------|-------|----------|
| Links    | 20%    | X/100 | X        |

恰到好处（好）：

## What to Check
- TODOs, broken links, stale versions

## Output Format
List issues by severity. Include file:line and fix.

## Scope Control
If >30 files, ask user which to focus on.

---

Agent 提示词结构

有效的 Agent 提示词包括：

## Your Role
[What the agent does]

## Blocking Check
[Prerequisites that must exist]

## Input
[What files to read]

## Process
[Step-by-step with encoded learnings]

## Output
[Exact file paths and formats]

## Quality Checklist
[Verification steps including learned gotchas]

## Common Issues
[Patterns discovered during development]

流水线 Agent

将新 Agent 插入编号流水线时（例如，HTML-01 → HTML-05 → HTML-11）：

必须更新	内容
新 Agent	“Workflow Position”图示和“Next”字段
前置 Agent	将其“Next”字段指向新 Agent

常见 Bug：新 Agent 成了“孤立”节点，因为前置 Agent 仍然指向原来的下一个 Agent。

验证：

grep -n "Next:.*→\|Then.*runs next" .claude/agents/*.md

最佳适用场景

最佳用例：重复性强但需要判断力的任务。

示例：手动审查 70 个技能很繁琐。但每次审查都需要智能判断（检查文档、比较版本、决定要修复什么）。这类任务非常适合交给指令明确的并行 Agent。

不适合：

• 简单任务（直接完成即可）
• 高度创意类任务（需要人工指导）
• 需要跨文件协调的任务（Agent 各自独立工作）

高效提示词模板

For each [item]:
1. Read [source file]
2. Verify with [external check - npm view, API call, etc.]
3. Check [authoritative source]
4. Score/evaluate
5. FIX issues found ← Critical instruction

关键要素：

• “修复发现的问题”——没有这项要求，Agent 只会报告问题；有了它，Agent 就会采取行动。
• 精确的文件路径——避免歧义
• 输出格式模板——确保报告格式一致且易于解析
• 批次大小约 5 项——工作量足够高效，又不至于因失败而引发连锁问题

工作流模式

1. ME: Launch 2-3 parallel agents with identical prompt, different item lists
2. AGENTS: Work in parallel (read → verify → check → edit → report)
3. AGENTS: Return structured reports (score, status, fixes applied, files modified)
4. ME: Review changes (git status, spot-check diffs)
5. ME: Commit in batches with meaningful changelog
6. ME: Push and update progress tracking

Agent 不提交代码的原因：便于人工审查、分批处理，并保持提交历史清晰。

判断任务是否适合此模式

适合：

• 对许多项重复执行相同步骤
• 每一项都需要判断（而不只是转换）
• 各项彼此独立（没有跨项依赖）
• 成功标准明确（评分、通过/失败等）
• 有权威来源可供核验

不适合：

• 各项的结果相互依赖
• 需要创造性或主观判断
• 单个复杂任务（改用常规 Agent）
• 处理中途需要人工输入

快速参考

Agent Frontmatter 模板

---
name: my-agent
description: |
  [Role] specialist. MUST BE USED when [triggers].
  Use PROACTIVELY for [task category].
  Keywords: [trigger words]
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

解决 Bash 审批刷屏问题

1. 如果不需要，请从工具中移除 Bash
2. 将关键指令放在最前面（紧跟 frontmatter 之后）
3. 在 .claude/settings.json 中使用允许列表

内存崩溃恢复

export NODE_OPTIONS="--max-old-space-size=16384"
source ~/.bashrc && claude