Tutorial ｜构建自定义 Agent¶

难度：⭐⭐⭐⭐ 时间：~2h 前置：deep-dive-agent-tool.md 产物：能在 Claude Code 中 Agent(reviewer, "检查这段代码") 调用的自定义 agent

1. 概念¶

Agent = Claude Code 中的"角色" - 自定义 system prompt - 自定义工具子集 - 自定义模型 - 可被 sub-agent 机制启动

2 种 agent： - 内置（如 Explore、Plan） - 自定义（用户在 .claude/agents/ 或 --agents 定义）

2. 3 种自定义方式¶

2.1 Markdown 文件（推荐）¶

# 项目级
.claude/agents/reviewer.md

# 用户级
~/.claude/agents/reviewer.md

Markdown 格式 —— 最简单。

2.2 `--agents` CLI¶

claude --agents '{"reviewer": {"description": "...", "prompt": "..."}}'

CLI inline —— 临时使用。

2.3 Plugin¶

# plugin 提供 agents
plugin marketplace add ...

plugin 提供 —— 团队分发。

3. Markdown 格式¶

---
name: reviewer
description: Reviews code for security and quality
tools: Read, Grep, Glob
model: sonnet
---

You are a code reviewer focused on:
1. Security vulnerabilities
2. Code quality
3. Best practices

When reviewing:
- Be concise
- Cite specific line numbers
- Suggest concrete improvements

5 字段： - name —— 唯一 ID - description —— 简短描述 - tools —— 可用工具（逗号分隔） - model —— 模型别名 - prompt —— system prompt 主体

4. 实战：Reviewer Agent¶

4.1 创建文件¶

mkdir -p ~/.claude/agents
cat > ~/.claude/agents/reviewer.md <<'EOF'
---
name: reviewer
description: Reviews code for security and style issues
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer.

Focus on:
- Security vulnerabilities (OWASP Top 10)
- Code style and readability
- Performance issues
- Best practices for the language

Output format:
- For each issue: file:line, severity (critical/medium/low), description, suggested fix
- Be specific and actionable
- Cite exact code snippets
EOF

4.2 使用¶

# 在 Claude Code 中
> Use the reviewer agent to check src/auth/login.ts

# 或 CLI
claude -p "Use reviewer agent" --agents '...'

4.3 验证¶

# 检查 agent 加载
ls .claude/agents/

# 在 Claude Code 中查看
# Agent list 显示 reviewer

5. 5 个高级配置¶

5.1 工具子集¶

tools: Read, Grep, Glob          # 只读
tools: Read, Edit, Bash         # 可改
tools: Bash, Read              # 最小集
tools: ""                      # 无工具

4 种工具集： - 只读：Read, Grep, Glob - 读写：Edit, Write - 命令：Bash - 自定义：MCP tools

5.2 模型别名¶

model: sonnet   # 默认
model: opus     # 高级
model: haiku    # 快速
model: inherit  # 继承主对话

4 模型。

5.3 颜色 / 名称¶

// main.tsx CLI
--agent-name "Code Reviewer" --agent-color "#ff0000"

视觉区分（sub-agent 显示）。

5.4 Plan Mode Required¶

--plan-mode-required

必须先 plan。

5.5 父 session¶

--parent-session-id <uuid>

追溯到主。

6. 实战：Test Generator Agent¶

---
name: test-gen
description: Generates unit tests for code
tools: Read, Grep, Glob, Write
model: sonnet
---

You generate unit tests using the project's testing framework.

Steps:
1. Read the source file
2. Identify exported functions
3. For each function:
   - Generate happy path test
   - Generate edge case tests
   - Generate error case tests
4. Place tests in the conventional test location
5. Ensure tests follow project conventions

Output:
- File path
- Complete test code
- Brief explanation

完整可用。

7. 实战：Sub-agent 委派¶

7.1 在主对话中¶

> Use the reviewer agent to check this PR
> Use test-gen to add tests for src/api/users.ts
> Use 3 agents in parallel: reviewer, test-gen, doc-gen

主对话委派。

7.2 在 agent 中¶

# Sub-agent 启动 sub-agent
You can spawn sub-agents using the Agent tool.

Example:
- Agent(reviewer, "check src/auth")
- Agent(test-gen, "test src/api")

嵌套。

8. 8 个最佳实践¶

单一职责 —— 一个 agent 一个角色
明确工具 —— 不给过多工具
示例 prompt —— 给具体示例
错误处理 —— 教 agent 失败怎么办
输出格式 —— 强制结构
避免循环 —— 不让 agent 反复做同样事
可观测 —— 让 agent 输出 reasoning
可测 —— 自己跑一遍验证

8 条 —— 来自经验。

9. 调试 agent¶

9.1 查看加载¶

# 重启 Claude Code 后
> /agents  # 推测有命令

9.2 测试 agent¶

# 简单 prompt 测试
> Use my agent to do X

9.3 调整 prompt¶

# 改完保存，重启

10. 进阶：Agent 工具¶

Agent 工具让 agent 可启动 sub-agent：

tools: Agent  # 允许 sub-agent

循环调用——小心。

11. 常见问题¶

11.1 Agent 不显示¶

检查 .claude/agents/ 路径
检查 markdown frontmatter
重启 Claude Code

11.2 Agent 工具不足¶

加 --tools flag
或 YAML tools: 字段

11.3 Agent 输出不符预期¶

改 prompt 加示例
加输出格式约束

12. 完整示例¶

---
name: security-auditor
description: Audits code for OWASP Top 10 vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
color: "#ff6b6b"
---

You are a security auditor specializing in OWASP Top 10.

For each file reviewed:
1. Identify vulnerabilities
2. Assign severity (Critical/High/Medium/Low)
3. Cite specific line numbers
4. Suggest concrete fixes
5. Reference CWE numbers when applicable

OWASP Top 10:
- A01: Broken Access Control
- A02: Cryptographic Failures
- A03: Injection
- A04: Insecure Design
- A05: Security Misconfiguration
- A06: Vulnerable Components
- A07: Authentication Failures
- A08: Software & Data Integrity
- A09: Logging & Monitoring
- A10: SSRF

Be thorough but concise. Focus on actionable findings.

完整 —— 9 字段 frontmatter + 完整 prompt。

13. 下一步¶

写你的第一个 agent
跑 /agents 测试
调 prompt
团队分享

Tutorial ｜ 构建自定义 Agent¶