Claude Code 智能体开发

通过适当的任务委派、工具访问和提示设计，为 Claude Code 构建高效的自定义智能体。

智能体描述模式

描述字段决定了 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
---

弱描述与强描述

关键短语：

• “当...时**必须使用**”
• “请**主动将其用于**...”
• 包含触发关键词

委派机制

1. 显式：任务工具 子代理类型："代理名称"- 始终有效
2. 自动: Claude根据任务匹配代理描述 - 需要明确的措辞

需要重启会话在创建/修改代理之后。

工具访问原则

如果代理不需要Bash，就不要给它Bash权限。

为什么？模型默认使用cat > 文件 << 'EOF'使用heredoc替代Write工具。每个bash命令都需要批准，导致每次代理运行产生数十条提示。

允许列表模式

不要限制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 *)"
    ]
  }
}

模型选择（质量优先）

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

内存限制

根本原因修复（必需）

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

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

将Node.js堆内存从4GB增至16GB。

并行限制（即使修复后）

恢复

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

子代理与远程API

应始终优先使用任务子代理而非远程API调用。

// ❌ 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.

包含

自我文档化原则

"没有你的上下文的智能体必须能够独立复现该行为。"

每一个改进都必须编码到智能体的提示中，而不是作为隐性知识留下。

需要编码的内容

测试：新代理能否成功？

在完成任何代理改进之前：

1. 假设你没有任何上下文，重新阅读代理提示
2. 提问：一个新会话能否遵循此提示并产出相同质量的结果？
3. 如果不能：补充缺失的说明、模式或参考信息

反面模式

代理提示结构

有效的智能体提示包括：

## 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]

流水线智能体

当向编号流水线中插入新智能体时（例如，HTML-01→HTML-05→HTML-11）：

常见错误：新智能体被“孤立”，因为前序智能体仍指向旧的下一环节智能体。

验证：

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

最佳应用点

最佳使用场景：适用于那些重复但需要判断力的任务。

示例：手动审核70项技能 = 单调乏味。但每次审核都需要智能判断（查阅文档、比较版本、决定如何修复）。这非常适合拥有明确指令的并行智能体。

不适用于：

• 简单任务（直接执行即可）
• 高度创造性的任务（需要人类指导）
• 需要跨文件协调的任务（智能体独立工作）

高效提示模板

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

关键要素：

• “修复发现的问题”- 没有这一项，智能体只会报告。有了它，它们会采取行动。
• 精确的文件路径- 避免歧义
• 输出格式模板- 确保报告一致且可解析
• 批量处理约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

智能体不提交的原因：允许人工审核、批量处理和清晰的提交历史。

任务符合此模式的迹象

良好匹配：

• 对多个项目重复相同步骤
• 每个项目都需要判断（不仅仅是转换）
• 项目相互独立（无跨项目依赖关系）
• 明确的成功标准（分数、通过/失败等）
• 存在权威来源可供验证

不良匹配：

• 项目结果相互依赖
• 需要创造性/主观决策
• 单一复杂任务（应使用常规代理）
• 处理过程中需要人工输入

快速参考

代理前置模板

---
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. 将关键指令置于首位（紧接前置内容之后）
3. 在.claude/settings.json中使用白名单 .claude/settings.json

记忆崩溃恢复

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