agent-builder

Agent Builder

创建 Claude Code 自定义 Agent 的完整指南。Agent 是专门的 AI 助手，在独立的上下文窗口中运行，从而专注、自主地执行任务。

---

快速参考

YAML Frontmatter 字段

字段	必填	说明
name	是	唯一标识符（小写字母，以连字符分隔）
description	是	何时调用——对发现至关重要
tools	否	允许使用的工具（省略时继承所有工具）
model	否	haiku、sonnet、opus 或 inherit
permissionMode	否	default、acceptEdits、bypassPermissions、plan
skills	否	Agent 启动时自动加载的 Skills

文件位置

范围	位置	用途
项目	.claude/agents/agent-name.md	团队工作流（通过 git 共享）
个人	~/.claude/agents/agent-name.md	个人使用（适用于所有项目）

常见工具模式

# Read-only (safest)
tools: Read, Grep, Glob

# File modification
tools: Read, Write, Edit, Grep, Glob

# Git operations only
tools: Bash(git:*)

# Specific commands
tools: Bash(npm test:*), Bash(npm run:*), Read, Grep

# Full shell (use sparingly)
tools: Bash

模型选择指南

模型	最适合	权衡
haiku	快速检查、简单任务	快速、便宜，但能力较弱
sonnet	均衡的工作（默认）	均衡性好
opus	复杂分析、关键任务	能力最强，但速度较慢、成本较高
inherit	与主对话保持一致	根据用户的模型调整

---

6 阶段工作流

阶段 1：收集需求

使用 AskUserQuestion 了解用户的需求：

关键问题：

1. 这个 Agent 应处理什么任务？
2. 它应具备哪些专业知识或职责？
3. 谁会使用它——团队还是个人？
4. 它应该能做什么，又不能做什么？
5. 它应该如何呈现结果？

问题示例：

What specific task should this agent handle?
├── Code review (quality, security, style)
├── Debugging (error investigation, root cause)
├── Testing (run tests, fix failures)
├── Documentation (generate, verify, update)
└── Other: [describe]

Who will use this agent?
├── Just me (personal: ~/.claude/agents/)
├── My team (project: .claude/agents/)

阶段 2：选择范围

决策树：

Is this a team workflow?
├── Yes → Project scope: .claude/agents/
│         (Committed to git, shared automatically)
│
└── No → Is it project-specific?
         ├── Yes → Project scope: .claude/agents/
         └── No → Personal scope: ~/.claude/agents/
                  (Available across all your projects)

创建文件：

# Project scope (team)
mkdir -p .claude/agents
touch .claude/agents/agent-name.md

# Personal scope (individual)
mkdir -p ~/.claude/agents
touch ~/.claude/agents/agent-name.md

阶段 3：撰写描述

description 字段至关重要——它决定 Claude 是否会自动发现并使用你的 Agent。

公式：[职责/专业领域] + [功能] + [调用时机] + [触发词]

不佳（无法被发现）：

description: Helps with code

良好（具体、易于发现）：

description: Expert code reviewer specializing in security and quality. Reviews code changes for vulnerabilities, best practices, and maintainability. Use when reviewing code, checking PRs, or when the user mentions code review, pull request review, or security audit.

拆解优质描述：

1. 职责/专业领域：“专注于安全与质量的代码审查专家”
2. 功能：“审查代码变更，检查漏洞、最佳实践和可维护性”
3. 调用时机：“用于代码审查、检查 PR 时”
4. 触发词：“代码审查、拉取请求审查或安全审计”

主动触发措辞（提高自动调用的概率）：

• “代码变更后主动使用”
• “测试失败时必须调用”
• “用户提到……时自动使用”

触发词类别：

• 操作：审查、分析、调试、修复、测试、检查、审计
• 对象：代码、PR、测试、错误、性能、安全
• 情境：部署前、变更后、失败时、审查过程中

长度：50–150 个英文单词最合适。

阶段 4：工具配置

安全原则：从最少的工具开始，只添加必需的工具。

渐进式工具访问：

# Level 1: Read-only (safest)
tools: Read, Grep, Glob

# Level 2: Can modify files
tools: Read, Write, Edit, Grep, Glob

# Level 3: Specific shell commands
tools: Read, Grep, Glob, Bash(git:*), Bash(npm test:*)

# Level 4: Full shell (use carefully)
tools: Read, Write, Edit, Bash, Grep, Glob

细粒度 Bash 模式：

# Git commands only
tools: Bash(git:*)

# Specific git commands
tools: Bash(git diff:*), Bash(git log:*), Bash(git status:*)

# npm commands only
tools: Bash(npm:*)

# Test commands only
tools: Bash(npm test:*), Bash(pytest:*), Bash(jest:*)

按 Agent 类型选择工具：

Agent 类型	推荐工具
代码分析器	Read, Grep, Glob
代码审查器	Read, Grep, Glob, Bash(git diff:*)
测试运行器	Read, Edit, Bash(npm test:*), Grep, Glob
调试器	Read, Edit, Bash, Grep, Glob
修复器/重构器	Read, Write, Edit, Grep, Glob

Phase 5：系统提示词设计

关键见解：Agent 在独立上下文中运行——它们看不到对话历史。系统提示词必须自包含，并包含完整的工作流。

有效结构：

You are [role] specializing in [expertise].

## When Invoked
1. [First action — gather context]
2. [Second action — analyze/process]
3. [Third action — produce output]
4. [Fourth action — verify/validate]

## Focus Areas
- Specific thing to check
- Another thing to verify
- Important consideration

## Output Format
[How to present results]

## Constraints
- What NOT to do
- Boundaries to respect

系统提示词模式：

1. 角色定义：

You are a senior code reviewer specializing in security vulnerabilities.
Your primary focus is identifying OWASP Top 10 risks.

2. 被调用时（对自主工作至关重要）：

## When Invoked
1. Run `git diff HEAD` to see recent changes
2. Identify modified files and their purpose
3. Review each change against security checklist
4. Present findings with severity levels

3. 检查清单模式：

## Review Checklist
- [ ] No SQL injection vulnerabilities
- [ ] Input validation on all boundaries
- [ ] No exposed secrets or credentials
- [ ] Proper authentication checks
- [ ] Authorization verified for each endpoint

4. 输出格式：

## Output Format
Present findings as:

### Summary
[One-line verdict: PASS/FAIL/NEEDS ATTENTION]

### Critical Issues
[Must fix before merge]

### Warnings
[Should fix]

### Suggestions
[Nice to have]

5. 约束：

## Constraints
- Do NOT modify code unless explicitly asked
- Do NOT change API contracts
- Focus ONLY on security-related issues
- ALWAYS explain WHY something is a risk

6. 决策树（用于分支逻辑）：

## Decision Flow
If no changes detected:
  → Report "No changes to review"
If only test files changed:
  → Focus on test coverage and assertions
If API endpoints modified:
  → Prioritize authentication/authorization review
Otherwise:
  → Full security review

Phase 6：测试与迭代

测试发现：

# Natural language requests (should trigger agent)
> Review my recent code changes
> Check this PR for security issues
> Audit the authentication module

# Explicit invocation (always works)
> Use the code-reviewer agent to check this

验证工具访问权限：

# Check agent can use its tools
# If agent needs git, test manually first
git diff HEAD
git log --oneline -5

调试：

# View agent loading errors
claude --debug

# List available agents
/agents

迭代检查清单：

• Agent 能否通过自然语言请求被发现？
• 是否选择了正确的 Agent（而非其他 Agent）？
• Agent 是否有必要的工具访问权限？
• 输出格式是否符合预期？
• 是否遵守了约束？

---

Agent 模式

代码质量 Agent

• code-reviewer：系统地审查代码质量和风格
• security-auditor：专注于 OWASP 的漏洞检测
• performance-analyzer：识别瓶颈和低效之处
• architecture-reviewer：评估设计模式和结构

开发工作流 Agent

• debugger：分析错误的根本原因
• test-runner：运行测试并修复失败
• refactorer：安全地重构代码
• pr-reviewer：分析拉取请求

研究 Agent

• codebase-explorer：浏览并理解代码结构
• dependency-auditor：检查过时或存在漏洞的软件包
• documentation-checker：验证文档是否与实现一致

自动化 Agent

• commit-helper：生成有意义的提交消息
• deploy-checker：部署前验证
• migration-assistant：协助升级框架和版本

---

常见陷阱

1. 描述含糊（无法发现 Agent）

# Bad
description: Helps with code

# Good
description: Expert code reviewer. Reviews code for quality, security, and maintainability. Use when reviewing code changes, PRs, or when user mentions code review.

2. 缺少工具访问权限（Agent 无法完成任务）

# Agent needs to run git commands but can't
tools: Read, Grep, Glob  # Missing Bash(git:*)

# Fixed
tools: Read, Grep, Glob, Bash(git:*)

3. 提示词不自包含（依赖上下文）

# Bad - assumes agent sees conversation
Review the code I just showed you.

# Good - self-contained
## When Invoked
1. Run `git diff HEAD` to see recent changes
2. Focus on modified files
3. Review systematically

4. 工具权限过于宽泛（安全风险）

# Risky - full shell access
tools: Bash
permissionMode: bypassPermissions

# Safer - scoped access
tools: Bash(git:*), Bash(npm test:*)
permissionMode: default

5. 没有输出格式（结果不一致）

# Bad - no guidance on output
Review the code for issues.

# Good - explicit format
## Output Format
Present as markdown checklist:
- Critical: [must fix]
- Warning: [should fix]
- Suggestion: [nice to have]

---

何时使用 Agent，而非其他方案

场景	最佳选择	原因
复杂的多步骤任务	Agent	适合使用专注、隔离的上下文
需要隔离工具	Agent	可以按 Agent 限制工具
长时间运行的分析	Agent	不会让主对话变得臃肿
团队工作流标准化	Agent	行为一致，并通过 git 共享
扩展 Claude 的知识	Skill	共享上下文，渐进式加载
经常输入的提示词	Slash Command	用户调用，可快速访问
简单的单步骤任务	直接请求	无需额外开销

Agent 检查清单——在以下情况下使用 Agent：

• 任务复杂且包含多个步骤
• 任务适合使用新鲜、专注的上下文
• 你想限制可用工具
• 任务不需要完整的对话历史
• 你想要一致、可复用的行为

---

资源

• 模板：渐进式示例见 templates/
• 示例：18 个完整可用的 Agent 示例见 examples/
• 参考资料：语法指南、最佳实践和故障排除见 reference/

---

快速入门

1. 创建文件：

touch ~/.claude/agents/my-agent.md

2. 添加内容：

---
name: my-agent
description: [Role]. [What it does]. Use when [trigger conditions].
tools: Read, Grep, Glob
---

You are [role].

## When Invoked
1. [First step]
2. [Second step]
3. [Third step]

## Output Format
[How to present results]

3. 测试：

> [Natural language request matching description]

4. 迭代：

• 无法发现？→ 让描述更具体
• 输出有误？→ 明确输出格式
• 无法完成某项操作？→ 添加必要的工具