Claude Code 子代理 (Subagents) 深度解析：架构、机制与最佳实践

# 探索型
"使用子代理探索此代码库中的身份验证如何工作"

# 审查型
"让一个单独的代理审查此代码是否存在安全问题"

# 并行型
"并行研究。同时检查 API 路由、数据库模型和前端组件"

# 修复型
"启动子代理以修复不同包中的这些 TypeScript 错误"

Use subagents to explore this codebase in parallel:
1. Find all API endpoints and summarize their purposes
2. Identify the database schema and relationships
3. Map out the authentication flow
Return a summary of each, not the full file contents.

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
  injection risks, auth issues, and sensitive data exposure.
  Use proactively before commits touching auth, payments,
  or user data.
tools: Read, Grep, Glob
model: sonnet
---

You are a security-focused code reviewer. Analyze the provided
changes for:

- SQL injection, XSS, and command injection risks
- Authentication and authorization gaps
- Sensitive data in logs, errors, or responses
- Insecure dependencies or configurations

Return a prioritized list of findings with file:line references
and a recommended fix for each. Be critical. If you find nothing,
say so explicitly rather than inventing issues.

## Code review standards

When asked to review code, ALWAYS use a subagent with READ-ONLY
access (Glob, Grep, Read only). The review should ALWAYS check for:

- Security vulnerabilities
- Performance issues
- Adherence to project patterns in /docs/architecture.md

Return findings as a prioritized list with file:line references.

---
name: deep-review
description: Comprehensive code review that checks security,
  performance, and style in parallel. Use when reviewing staged
  changes before a commit or PR.
---

Run three parallel subagent reviews on the staged changes:

1. Security review - check for vulnerabilities, injection risks,
   authentication issues, and sensitive data exposure

2. Performance review - check for N+1 queries, unnecessary
   iterations, memory leaks, and blocking operations

3. Style review - check for consistency with project patterns
   documented in /docs/style-guide.md

Synthesize findings into a single summary with priority-ranked
issues. Each issue should include the file, line number, and
recommended fix.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-tests.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash

INPUT=$(cat)
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')

# 防止无限循环：如果本轮已经阻止过一次，直接放行
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0
fi

# 运行测试套件
if ! npm test --silent > /dev/null 2>&1; then
  jq -n '{
    decision: "block",
    reason: "Tests are failing. Run `npm test` to see the failures and fix them before finishing."
  }'
  exit 0
fi

exit 0

Before I implement user notifications, use a subagent to research:
- How are emails currently sent in this codebase?
- What notification patterns already exist?
- Where should new notification logic live based on the
  current architecture?
Summarize findings, then we'll plan the implementation together.

Use parallel subagents to update the error handling in these files:
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts
Each should follow the pattern established in src/api/auth.ts.
Work on all three simultaneously.

Use a fresh subagent with read-only access to review my
implementation of the payment flow. It should not see our
previous discussion. I want an unbiased review.

Check for: security vulnerabilities, unhandled edge cases,
and error handling gaps. Be critical.

Let's build this feature as a pipeline:
1. First subagent: Design the API contract and write it to
   docs/api-spec.md
2. Second subagent: Implement the backend endpoints based
   on that spec
3. Third subagent: Write integration tests for the
   implementation
Each stage should complete before the next begins. Use the
output files as the handoff mechanism between stages.

# 好的提示词结构

## 1. 明确目标
"研究认证模块的实现方式"（而非"看看代码"）

## 2. 指定范围
"只查看 src/auth/ 目录下的文件"

## 3. 定义输出
"返回一个包含文件路径、功能描述和潜在问题的表格"

## 4. 设定约束
"不要修改任何文件，只做只读分析"