介绍
# Agent Development for Claude Code
通过适当的委托、工具访问和提示词设计，为 Claude Code 构建高效的自定义 agent。
## Agent 描述模式
描述字段决定了 Claude 是否会自动委托任务。
### 强触发器模式
```yaml --- 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 --- ```
### 弱描述 vs 强描述
| 弱（不会自动委托） | 强（会自动委托） | |---------------------------|-------------------------| | "Analyzes screenshots for issues" | "Visual QA specialist. MUST BE USED when analyzing screenshots. Use PROACTIVELY for visual QA." | | "Runs Playwright scripts" | "Playwright specialist. MUST BE USED when running Playwright scripts. Use PROACTIVELY for browser automation." |
**关键短语**： - "MUST BE USED when..." - "Use PROACTIVELY for..." - 包含触发关键词
### 委托机制
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` 中允许列表安全命令：
```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`： ```bash export NODE_OPTIONS="--max-old-space-size=16384" ```
将 Node.js 堆内存从 4GB 增加到 16GB。
### 并行限制（即使有修复）
| Agent 类型 | 最大并行数 | 备注 | |------------|--------------|-------| | 任何 agent | 2-3 | 上下文会累积；批量处理然后暂停 | | 重度创意 | 1-2 | 使用更多内存 |
### 恢复
1. `source ~/.bashrc` 或重启终端 2. `NODE_OPTIONS="--max-old-space-size=16384" claude` 3. 检查存在的文件，从那里继续
## 子 Agent vs 远程 API
**始终优先使用 Task 子 agent 而非远程 API 调用。**
| 方面 | 远程 API 调用 | Task 子 Agent | |--------|-----------------|----------------| | 工具访问 | 无 | 完整（Read, Grep, Write, Bash） | | 文件读取 | 必须在提示词中传递所有内容 | 可以迭代读取文件 | | 交叉引用 | 单个上下文窗口 | 可以跨文档推理 | | 决策质量 | 通用建议 | 具有理由的具体决策 | | 输出质量 | 通常约 100 行 | 600+ 行的具体内容 |
```typescript // ❌ 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" ```
## 声明式优于命令式
描述要完成**什么**，而不是**如何**使用工具。
### 错误（命令式）
```markdown ### Check for placeholders ```bash grep -r "PLACEHOLDER:" build/*.html ``` ```
### 正确（声明式）
```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/tool 命令 | | 输入文件路径 | "使用 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 提示词包括：
```markdown ## 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。
**验证**： ```bash 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 ```
**关键要素**： - **"FIX issues found"** - 没有这个，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 模板
```yaml --- 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` 中使用允许列表
### 内存崩溃恢复
```bash export NODE_OPTIONS="--max-old-space-size=16384" source ~/.bashrc && claude ```