用途
Agent Development 用于为 Claude Code 设计并构建自定义智能体。目标是让智能体具备有效的委派能力、恰当的工具访问权限与可自我记录的提示词，使新会话在没有历史上下文的情况下也能独立复现同等质量的行为。
主要能力
- 智能体描述模式：通过 description 字段决定 Claude 是否自动委派。强触发模式包含角色说明、"MUST BE USED when..."、"Use PROACTIVELY for..." 以及触发关键词。
- 委派机制：显式委派使用 Task 工具的 subagent_type: "agent-name"；自动委派依赖 Claude 将任务与描述匹配，需要强措辞。创建或修改智能体后需重启会话。
- 工具访问原则：按需最小化授权。仅创建文件时给 Read、Write、Edit、Glob、Grep，不给 Bash；需运行脚本或 CLI 时再加 Bash；仅读取/审计时只给 Read、Glob、Grep。原因在于模型默认使用 cat > file << '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 *)。
- 模型选择（质量优先）：Opus 用于创意工作（页面构建、设计、内容）；Sonnet 用于大多数智能体（内容、代码、研究，默认）；Haiku 仅用于质量不重要的脚本运行。不要为绕过问题而降级质量，应修复根因。
- 内存限制：根因修复为在 ~/.bashrc 或 ~/.zshrc 中加入 export NODE_OPTIONS="--max-old-space-size=16384"，将 Node.js 堆从 4GB 提升到 16GB。即使修复后，并行限制仍为任意智能体 2-3 个，高内存创意（Opus）1-2 个。恢复方式为 source ~/.bashrc 或重启终端，也可用 NODE_OPTIONS="--max-old-space-size=16384" claude 启动。
- 子代理 vs 远程 API：始终优先 Task 子代理。远程 API 调用无工具访问、需在提示中传入全部内容、仅单一上下文窗口、输出通常约 100 行；Task 子代理有完整工具访问、可迭代读取文件、可跨文档推理、给出带依据的具体决策、输出可达 600+ 行。
- 声明式优于命令式：描述要达成的目标，而非如何使用工具。
- 应包含与应跳过：包含任务目标与上下文、输入文件路径、输出文件路径与格式、成功/失败标准、阻塞检查（前置条件）、质量检查清单；跳过显式 bash/工具命令、"Use X tool to..."、逐步工具调用、shell 管道语法、微观管理的工作流。
- 自我记录原则：智能体必须能在没有你的上下文时独立复现行为。每次改进都应编码进智能体提示词。需编码的内容包括：缺陷修复模式→"Corrections"或"Common Issues"段；质量要求→"Quality Checklist"段；文件路径约定→"Output"段；工具使用模式→"Process"段；阻塞前置条件→"Blocking Check"段。测试方法：以无上下文视角阅读提示词，判断新会话能否产出同等质量，否则补充缺失说明、模式或引用。
- 反模式："As we discussed earlier..."（无先前上下文）；依赖开发期间读过的文件（智能体可能不会读同样文件）；假设从错误中获得的知识（智能体看不到你的调试）；"Just like the home page"（智能体没建过首页）。
- 灵活度与刚性：按任务类型匹配规格化程度。机械/重复任务用高（刚性步骤）；判断型任务用低（指导原则）；创意任务用最少（仅目标）。过度规格化的迹象包括：用"N/A"填充模板、无关阶段也全部执行、评分产生无意义数字、范围与假设不符即失败、简单任务却写超过 150 行。灵活型智能体应：描述要查找什么而非具体步骤、给出输出示例而非固定模板、包含范围控制（"若超过 30 项，询问用户"）、提供逃生通道（"若不明确，标记待审"）、判断型任务保持 100 行以内；不应：要求填满模板每一段、创建复杂加权评分系统、穷举所有检查、未经询问假设范围。
- 提示词结构：Your Role、Blocking Check、Input、Process、Output、Quality Checklist、Common Issues。
- 流水线代理：向编号流水线插入新智能体时，需更新新智能体的"Workflow Position"图与"Next"字段，以及前驱智能体的"Next"字段指向新智能体；常见缺陷是新智能体被"孤立"，因前驱仍指向旧的下一个。可用 grep -n "Next:.*→|Then.runs next" .claude/agents/.md 验证。
- 最佳适用点：重复但需要判断的任务，例如审计 70 个技能，每个都需智能判断（查文档、比版本、决定修复什么），适合带清晰指令的并行智能体。不适合：简单任务、高度创意任务、需要跨文件协调的任务。
- 有效提示词模板：对每个 [item]：1. 读取 [source file]；2. 用 [external check - npm view、API 调用等] 验证；3. 检查 [authoritative source]；4. 评分/评估；5. 修复发现的问题（关键指令）。关键要素："FIX issues found"（没有它智能体只报告，有它会采取行动）、精确文件路径、输出格式模板、批量约 5 项。
- 工作流模式：1. 我：用相同提示、不同条目标启动 2-3 个并行智能体；2. 智能体：并行工作（读取→验证→检查→编辑→报告）；3. 智能体：返回结构化报告（评分、状态、已应用修复、修改文件）；4. 我：审查改动（git status、抽查 diff）；5. 我：分批提交并写有意义的变更日志；6. 我：推送并更新进度跟踪。智能体不负责提交，以便人工审查、分批和干净的提交历史。
- 任务适配信号：适合——对许多条目重复相同步骤、每项需判断、条目彼此独立、有清晰成功标准、存在权威来源可验证。不适合——条目相互依赖、需要创意/主观决定、单一复杂任务（应使用常规智能体）、流程中需人工输入。
使用方式
快速参考：
- 智能体 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 审批泛滥：若非必要从 tools 移除 Bash；将关键指令放在最前（紧跟 frontmatter 之后）；在 .claude/settings.json 使用允许清单。
- 内存崩溃恢复：export NODE_OPTIONS="--max-old-space-size=16384"；source ~/.bashrc && claude。
适用场景
适合重复但需判断的审计、评估类任务，可用并行智能体加速处理大量条目。
限制
不适合简单任务、高度创意任务或需要跨文件协调的任务；并行数量即使修复内存后仍受限；创建或修改智能体后必须重启会话；远程 API 不提供工具访问。