Agent Development — 代理 Development

代理 Development for Claude Code

Build effective custom 代理s for Claude Code with proper delegation, 工具 访问, and prompt de签名.

代理 Description Pattern

The description field determines whether Claude will automatically delegate tasks.

Strong Trigger Pattern

---

name: 代理-name description: | [角色] specia列出. MUST BE USED when [specific triggers]. Use PROACTIVELY for [task category]. Keywords: [trigger words] 工具s: Read, Write, Edit, Glob, Grep, Bash 模型: sonnet

---

Weak vs Strong Descriptions Weak (won't auto-delegate) Strong (auto-delegates) "Analyzes screenshots for issues" "Visual QA specia列出. MUST BE USED when analyzing screenshots. Use PROACTIVELY for visual QA." "运行s Playwright scripts" "Playwright specia列出. MUST BE USED when 运行ning Playwright scripts. Use PROACTIVELY for browser 自动化."

Key phrases:

"MUST BE USED when..." "Use PROACTIVELY for..." Include trigger keywords Delegation Mechanisms Explicit: Task 工具 sub代理_type: "代理-name" - always works Automatic: Claude matches task to 代理 description - requires strong phrasing

会话 re启动 required after creating/modifying 代理s.

工具 访问 Principle

If an 代理 doesn't need Bash, don't give it Bash.

代理 needs to... Give 工具s Don't give 创建 files only Read, Write, Edit, Glob, Grep Bash 运行 scripts/命令行工具s Read, Write, Edit, Glob, Grep, Bash — Read/审计 only Read, Glob, Grep Write, Edit, Bash

Why? 模型s default to cat > file << 'EOF' heredocs instead of Write 工具. Each bash command requires 应用roval, causing dozens of prompts per 代理 运行.

Allow列出 Pattern

Instead of restricting Bash, allow列出 safe commands in .claude/设置tings.json:

{ "权限s": { "allow": [ "Write", "Edit", "网页Fetch(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 )" ] } }

模型 Selection (质量 First)

Don't 降级 质量 to work around issues - fix root causes instead.

模型 Use For Opus Creative work (page building, de签名, content) - 质量 matters Sonnet Most 代理s - content, code, re搜索 (default) HAIku Only script 运行器s where 质量 doesn't matter Memory Limits Root Cause Fix (REQUIRED)

添加 to ~/.bashrc or ~/.zshrc:

导出 NODE_OPTIONS="--max-old-space-size=16384"

Increases Node.js heap from 4GB to 16GB.

Parallel Limits (Even With Fix) 代理 Type Max Parallel Notes Any 代理s 2-3 上下文 accumulates; batch then 暂停 Heavy creative (Opus) 1-2 Uses more memory 恢复y source ~/.bashrc or re启动 terminal NODE_OPTIONS="--max-old-space-size=16384" claude 检查 what files exist, continue from there Sub-代理 vs Remote API

Always prefer Task sub-代理s over remote API calls.

Aspect Remote API Call Task Sub-代理 工具 访问 None Full (Read, Grep, Write, Bash) File reading Must pass all content in prompt Can read files iteratively Cross-referencing Single 上下文 window Can reason across documents Decision 质量 Generic suggestions Specific decisions with rationale 输出 质量 ~100 lines typical 600+ lines with specifics // ❌ WRONG - Remote API call const 响应 = awAIt fetch('https://API.anthropic.com/v1/messages', {...})

// ✅ CORRECT - Use Task 工具 // Invoke Task with sub代理_type: "general-purpose"

Declarative Over Imperative

Describe what to accomplish, not how to use 工具s.

Wrong (Imperative)

检查 for placeholders

grep -r "PLACEHOLDER:" build/.html

Right (Declarative)

markdown

检查 for placeholders

搜索 all HTML files in build/ for:

• PLACEHOLDER: comments
• TODO or TBD markers
• Template brackets like [命令行工具ent Name]

Any match = incomplete content.

What to Include Include Skip Task goal and 上下文 Explicit bash/工具 commands 输入 file paths "Use X 工具 to..." 输出 file paths and 格式化 Step-by-step 工具 invocations 成功/失败 criteria Shell 流水线 syntax Blocking 检查s (prerequisites) Micromanaged 工作流s 质量 检查列出s Self-Documentation Principle

"代理s that won't have your 上下文 must be able to reproduce the behaviour independently."

Every improvement must be encoded into the 代理's prompt, not left as implicit knowledge.

What to Encode Discovery Where to Capture Bug fix pattern 代理's "Corrections" or "Common Issues" section 质量 requirement 代理's "质量 检查列出" section File path convention 代理's "输出" section 工具 usage pattern 代理's "Process" section Blocking prerequisite 代理's "Blocking 检查" section Test: Would a Fresh 代理 Succeed?

Before completing any 代理 improvement:

Read the 代理 prompt as if you have no 上下文 Ask: Could a new 会话 follow this and produce the same 质量? If no: 添加 missing instructions, patterns, or references Anti-Patterns Anti-Pattern Why It FAIls "As we discussed earlier..." No prior 上下文 exists Relying on files read during dev 代理 may not read same files Assuming kno