从 Claude Code 源码学 Agent 开发

---name: code-reviewerdescription: 专业代码审查 Agent，代码改动后主动调用。发现质量/安全问题立即触发。tools: Read, Grep, Glob, Bash     # 只允许只读工具model: sonnet                      # 指定模型：haiku/sonnet/opus/inheritmemory: project                    # 持久记忆：user/project/localpermissionMode: dontAsk            # 权限模式：自动拒绝未授权操作---# 系统提示（Markdown 正文）你是资深代码审查专家，专注代码质量、安全漏洞、最佳实践。审查流程：1. 运行 `git diff` 获取本次改动2. 重点关注修改的文件3. 按优先级输出问题：Critical → Warning → Suggestion

# 优先级从高到低1. --agents CLI 参数     # 当前会话，不落盘2. .claude/agents/       # 项目级，建议 Git 提交共享3. ~/.claude/agents/     # 用户级，全项目通用4. plugins/agents/       # 插件提供，优先级最低

Use the code-reviewer agent to check my recent changes

@"code-reviewer (agent)" review the auth module changes

claude --agent code-reviewer# 或通过 CLI 参数动态注入 Agent 定义claude --agents '{  "debugger": {    "description": "Debugging specialist for errors",    "prompt": "You are an expert debugger...",    "tools": ["Read", "Edit", "Bash", "Grep"],    "model": "sonnet"  }}'

前台 Agent（Foreground）：阻塞主对话直到完成，权限提示直接透传给用户。

后台 Agent（Background）：并发运行，启动前预批准所有所需权限。运行期间 无法再次询问用户，未预授权操作自动拒绝。按 Ctrl+B 可将当前任务切到后台。

// Agent 工具的 JSON Schema（从源码中整理）{  "tool_name": "Agent",  "tool_input": {    "prompt": "分析 auth 模块的安全漏洞",    "description": "安全分析任务",       // 简短描述，用于日志    "subagent_type": "security-reviewer", // 指定 Sub-Agent 类型    "model": "opus",                    // 可覆盖 Agent 定义的模型    "run_in_background": false          // 前台/后台运行  }}

# 方式一：allowlist（只允许列出的工具）tools: Read, Grep, Glob, Bash# 方式二：denylist（继承全部，排除指定工具）disallowedTools: Write, Edit# 方式三：限制可以启动的子 Agent 类型tools: Agent(worker, researcher), Read, Bash# 只允许启动 worker 和 researcher 两种 Sub-Agent

SessionStart ↓ UserPromptSubmit ↓ 【Agentic Loop】 ├─ PreToolUse → PermissionRequest → PostToolUse / PostToolUseFailure ├─ SubagentStart → ... → SubagentStop ├─ TaskCreated → ... → TaskCompleted └─ Stop / StopFailure ↓ TeammateIdle → PreCompact → PostCompact ↓ SessionEnd 异步事件（并行）：Elicitation、WorktreeCreate/Remove Notification、ConfigChange、FileChanged、CwdChanged

// 类型一：Command Hook（最常用）{  "type": "command",  "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate.sh",  "timeout": 30,  "async": false}// 类型二：HTTP Hook（调用外部服务）{  "type": "http",  "url": "http://localhost:8080/hooks/pre-tool",  "headers": { "Authorization": "Bearer $MY_TOKEN" },  "allowedEnvVars": ["MY_TOKEN"]}// 类型三：Prompt Hook（让 AI 校验）{  "type": "prompt",  "prompt": "Is this database operation safe? $ARGUMENTS",  "model": "fast-model"}// 类型四：Agent Hook（用 Sub-Agent 做复杂校验）{  "type": "agent",  "prompt": "Verify this file modification won't break the build. $ARGUMENTS"}

# .claude/settings.json{  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [{          "type": "command",          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"        }]      }    ],    "PostToolUse": [      {        "matcher": "Write|Edit",  // 正则匹配多个工具        "hooks": [{          "type": "command",          "command": "npx prettier --write $TOOL_INPUT_FILE_PATH"        }]      }    ]  }}

#!/bin/bash# .claude/hooks/block-dangerous.shINPUT=$(cat)  # Claude 通过 stdin 传入 JSONCOMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')# 阻止危险命令if echo "$COMMAND" | grep -qE '\b(rm\s+-rf|DROP\s+TABLE|git\s+push\s+--force)\b'; then  echo "⛔ 危险命令已阻止：$COMMAND" >&2  exit 2  # 退出码 2 = 阻塞并将 stderr 反馈给 Claudefiexit 0

// stdout 输出 JSON 可以修改工具输入{  "hookSpecificOutput": {    "hookEventName": "PreToolUse",    "permissionDecision": "allow",  // allow | deny | ask    "updatedInput": {              // 修改后的工具参数      "command": "npm run lint && npm test"    },    "additionalContext": "已自动补充 lint 检查"  }}

// .claude/settings.json{  "permissions": {    "allow": [      "Bash(git *)",          // 允许所有 git 命令      "Bash(npm run *)",       // 允许 npm 脚本      "Edit(src/**)"           // 允许编辑 src 目录    ],    "deny": [      "Bash(rm -rf *)",        // 禁止危险删除      "Agent(Explore)",        // 禁用内置 Explore Agent      "Write(*.env)"           // 禁止修改环境文件    ]  }}

主会话权限上下文 ↓ 继承 Sub-Agent 权限上下文 ├─ 继承父会话的 allow/deny 规则 ├─ 可通过 permissionMode 字段覆盖模式 ├─ 工具白名单进一步缩小可用工具集 └─ 注意：父 bypassPermissions → 子强制继承，无法覆盖

---name: code-reviewerdescription: 代码审查专家，积累项目代码规范和历史问题记录memory: project   # 启用项目级记忆---你是代码审查专家。每次审查完成后，将以下内容更新到 MEMORY.md：- 发现的代码规范违规模式- 项目特有的架构约定- 高频出现的 Bug 类型下次开始前，先读取 MEMORY.md 中的历史知识。

从 Claude Code 源码中提炼出的工程实践模式，直接可用于自己的 Agent 开发：

1

隔离高容量操作

将产生大量输出的操作（跑测试、抓文档、处理日志）委派给 Sub-Agent， 详细输出留在子上下文，主对话只收到摘要。

上下文隔离Sub-Agent

2

并行研究模式

对相互独立的调查方向，同时启动多个 Sub-Agent 并行探索， 最后在主 Agent 中汇总合并结果。

并行执行效率

3

串行流水线

多步骤工作流用 Sub-Agent 链式执行：Reviewer → Optimizer → Tester， 每步结果传入下一步。

流水线工作流

4

模型路由策略

Haiku 处理批量低复杂度任务（命名、分类）， Sonnet 处理主要编码工作，Opus 处理需要深度推理的架构决策。

成本优化模型选择

5

Hook 守卫模式

用 PreToolUse Hook 校验所有工具调用，确保操作符合规范。 Hook 可修改输入、阻止执行或注入额外上下文。

安全防护Hooks

6

技能封装模式

将可复用的工作流封装为 Skill（SKILL.md）， 可注入到 Sub-Agent 上下文，实现团队知识共享和工作流标准化。

知识复用Skills

模型选择决策树

任务类型？ ├─ 批量、低复杂度（批量命名、分类、格式化） │ └─→ Haiku（低延迟，成本节省 3x） │ ├─ 中等复杂度（代码生成、Bug 修复、代码审查） │ └─→ Sonnet（最佳编码能力） │ └─ 高复杂度（架构设计、安全分析、深度推理） └─→ Opus（最强推理能力）

🚀 完整实战示例：构建一套代码审查 Agent 团队

以下是一套可直接用于实际项目的 Agent 配置，包含代码审查、安全检查、 自动修复三个协作 Agent。

文件结构

.claude/
  agents/
    code-reviewer.md    # 代码审查 Agent
    security-check.md   # 安全扫描 Agent
    auto-fixer.md       # 自动修复 Agent
  hooks/
    post-edit-lint.sh   # 编辑后自动 lint
    block-secrets.sh    # 阻止提交敏感信息
  settings.json         # Hooks 配置
CLAUDE.md               # 项目级系统提示

代码审查 Agent（code-reviewer.md）

---
name: code-reviewer
description: 专业代码审查。代码改动后主动使用。检查质量、安全、性能问题。
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
permissionMode: dontAsk
---

你是资深 Code Reviewer，熟悉项目代码规范。

启动时：
1. 读取 MEMORY.md 获取项目历史审查知识
2. 运行 `git diff HEAD~1` 获取最新改动
3. 按 Critical / Warning / Suggestion 分级输出问题

完成后，将新发现的规范模式和高频问题更新到 MEMORY.md。

安全扫描 Agent（security-check.md）

---
name: security-check
description: 安全漏洞扫描。处理用户输入、认证、API 密钥时主动使用。
tools: Read, Grep, Glob
model: opus
permissionMode: plan
---

你是安全专家，专注 OWASP Top 10 和代码安全审计。

检查重点：
- 硬编码 API Key / 密码 / Token
- SQL 注入风险
- XSS 漏洞
- 未验证的用户输入
- 不安全的依赖版本

发现 Critical 问题时，输出 ⛔ CRITICAL 并给出修复方案。

Hooks 配置（settings.json）

{
"permissions": {
"allow": ["Bash(git *)", "Bash(npm run *)"],
"deny": ["Bash(git push --force*)"]
  },
"hooks": {
"PreToolUse": [
      {
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-secrets.sh"
        }]
      }
    ],
"PostToolUse": [
      {
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-lint.sh",
"async": true
        }]
      }
    ],
"SubagentStop": [
      {
"hooks": [{
"type": "command",
"command": "echo 'Sub-Agent 完成' >> /tmp/agent.log"
        }]
      }
    ]
  }
}

使用方式

# 串行流水线：先审查，再安全扫描
Use the code-reviewer agent to review my changes, then use security-check agent to scan for vulnerabilities

# 并行研究：同时分析多个模块
Research the auth, payment, and user modules in parallel using separate subagents

# 后台执行：不阻塞主对话
Run the test suite in a background subagent and report only failing tests

💡 最佳实践：将 .claude/agents/ 目录提交到 Git， 让整个团队共享同一套 Agent 配置。随着项目演进，Agent 的记忆文件 （.claude/agent-memory/）也可以提交，积累团队集体知识。

🔗 相关资源

• 📦 Claude Code GitHub 仓库（官方）
• 📖 官方文档：Overview
• 🤖 官方文档：Sub-Agents 完整指南
• ⚡ 官方文档：Hooks 系统
• 🔒 官方文档：权限系统
• 🧠 官方文档：Memory & CLAUDE.md
• 📡 官方文档：MCP 集成
• 🛠️ 官方文档：Skills（可复用工作流）