你好，我是黄佳。

上一讲我们理解了子代理的核心概念，今天我们要动手实战——创建一个只能看、不能改的代码审查员子代理。

为什么要从“只读型”子代理开始？

因为权限边界是子代理最重要的工程价值之一。代码审查是一个完美的场景：审查者需要完整的读取能力来分析代码，但绝对不应该在审查过程中修改代码。如果你的审查工具可能在“帮你”"的过程中偷偷改了什么，那还叫审查吗？

今天的目标就下面三个。

创建一个只有读取权限的代码审查子代理。

用它来发现示例代码中的安全问题。

体验“最小权限原则”的工程价值。

同时，我们也将从真实工程痛点出发，理解"为什么需要这个子代理"的设计思维，并学会将工程经验翻译为子代理的职责边界与调用结构。

好，现在一起开始动手。

项目场景：代码审查

一个后端开发项目中，我们刚刚好写完了一段认证逻辑，想让 Claude Code 帮你审查一下有没有安全问题。你在主对话中说：“帮我检查一下 auth.js 的安全性”。

Claude 完成这个任务当然不在话下，它读了你的代码，发现了硬编码的密钥，然后顺手帮你改成了环境变量读取。等等，发现哪里不对了么？你只是想让它看看有没有问题，并没有让它改啊！而且，它的“好心修复”可能引入了新的问题——比如你根本不想配置任何环境变量。

这就是为什么我们需要只读型子代理：

代码审查员的职责边界： ✅ 可以做：读取代码、分析问题、输出报告 ❌ 不可做：修改文件、执行可能有副作用的命令

从工程痛点到子代理设计：一种思维方式

在我们动手写配置之前，先停下来想一个问题：我们为什么要创建这个子代理？

这不是一个哲学问题，而是一个工程方法论问题。课程留言区有同学提出了一个非常好的观察：

“网上的各类 Skill、SubAgent 排行榜一大堆，如果只是为了获取结果，直接用现成插件就行了。课程到底是在教原理，还是在教工具配置？”

这个问题问到了核心。我们这门课的目标不是教你再造一个 review 工具，而是帮你建立一种从痛点出发、反推设计的工程思维：

工程痛点 → 分析缺什么能力 → 设计职责边界 → 选择工具组合 → 配置子代理

具体来说，你在真实项目中遇到的每一个“AI 做得不够好”的场景，都可以用这个思路来拆解。

这个表格背后的思维过程，比任何一份具体的配置文件都重要。掌握了它，你就能面对任何工程场景设计出合适的子代理。

这一讲使用的实战项目位于我们课程 Repo 的03-SubAgents/projects/01-code-reviewer/目录，结构如下：

01-code-reviewer/ ├── src/ │ ├── auth.js # 认证模块（包含安全问题） │ ├── database.js # 数据库模块（包含 SQL 注入风险） │ └── api.js # API 模块（包含不良实践） ├── .claude/ │ └── agents/ │ └── code-reviewer.md # 代码审查子代理配置 └── README.md

这些js示例代码故意包含了一些安全问题，用于演示审查器的发现能力。

下面我们一步一步往前走，从理解这些“问题代码”开始，到创建属于我们自己的“代码审查”Sub-Agent，并运行它们，同时验证权限边界、扩展审查维度，完成代码审查子代理的设计和使用闭环。

第一步：理解“有问题”的代码

在创建审查器之前，让我们先看看它要审查的代码有什么问题，以设计更好的审查 prompt。在我的Repo中，auth.js 以及database.js都存在大量的安全隐患。

auth.js 中的安全问题

// 问题 1: 硬编码的密钥 const SECRET_KEY = 'super-secret-key-12345'; const API_KEY = 'sk-live-abcdef123456';

// 问题 2: 弱密码验证 function validatePassword(password) { // 只检查长度，没有复杂度要求 return password.length >= 6; }

// 问题 3: 不安全的 token 生成 function generateToken(userId) { // 使用可预测的方式生成 token const timestamp = Date.now(); return Buffer.from(${userId}:${timestamp}).toString('base64'); }

// 问题 4: 明文存储密码比较 function checkPassword(inputPassword, storedPassword) { // 应该使用 bcrypt 等哈希比较 return inputPassword === storedPassword; }

// 问题 5: 信息泄露的错误消息 function login(username, password) { const user = findUserByUsername(username);

if (!user) { // 泄露用户是否存在 throw new Error(User '${username}' not found); }

if (!checkPassword(password, user.password)) { throw new Error('Invalid password'); }

return { token: generateToken(user.id), user: { // ... password: user.password, // 问题 6: 返回密码！ } }; }

// 问题 7: 无会话过期检查

// 问题 8: eval 使用 - 代码注入风险 function processUserConfig(configString) { return eval('(' + configString + ')'); }

auth.js 中的问题主要集中在身份认证和敏感凭据的处理上。代码中存在硬编码密钥（SECRET_KEY、API_KEY），这会导致一旦代码仓库泄露，密钥也随之暴露，且无法进行安全轮换。

此外，密码相关逻辑也存在多处不安全的实现，包括弱密码校验（仅检查长度）、明文密码比较、以及使用可预测数据（用户 ID + 时间戳）生成 token。这些都会降低攻击成本，使暴力破解、重放攻击和伪造身份成为可能。

同时认证流程中还存在信息泄露问题，例如在登录失败时区分“用户不存在”和“密码错误”，以及在接口返回中直接包含用户密码字段。此外，代码中使用 eval 解析用户提供的配置字符串，带来了严重的代码注入风险。这些问题说明认证模块没有正确假设“用户输入是不可信的”，也未采用成熟的安全实践来处理密码、token 和错误信息。

database.js 中的 SQL 注入风险

// 问题 1: 硬编码数据库凭据 const DB_CONFIG = { host: 'localhost', user: 'root', password: 'root123', // 硬编码密码 database: 'production_db' };

class Database { // 问题 2: SQL 注入漏洞 async findUser(username) { // 直接拼接用户输入到 SQL 语句 const query = SELECT * FROM users WHERE username = '${username}'; return this.execute(query); }

// 问题 3: 多个注入点 async searchProducts(searchTerm, category) { const query = SELECT * FROM products WHERE name LIKE '%${searchTerm}%' AND category = '${category}' ; return this.execute(query); }

// 问题 4: 敏感数据日志 async createUser(userData) { // 记录了密码到日志 console.log('Creating user:', JSON.stringify(userData)); // ... } }

database.js 中的问题主要集中在数据库访问层的输入处理和凭据管理上。代码将数据库账号和密码硬编码在源码中，并使用高权限用户连接数据库，这在生产环境中存在较大风险。一旦源码泄露，攻击者可能直接获取数据库的完全访问权限。

更严重的问题是 SQL 注入漏洞。findUser 和 searchProducts 等方法直接将用户输入拼接到 SQL 语句中，没有使用参数化查询或预编译语句，攻击者可以通过构造恶意输入篡改查询逻辑，进而绕过认证或读取、修改数据库中的敏感数据。此外，代码在日志中直接打印完整的用户数据对象，可能将密码等敏感信息写入日志系统，进一步扩大数据泄露范围。

上述这些身份认证以及SQL 注入是最常见的 Web 安全漏洞之一，我们下面要开始创建的代码审查器必须也应该是肯定能识别这类问题。

第二步：创建代码审查子代理

现在让我们创建代码审查子代理。首先是创建.claude/agents/目录，然后在其中创建代码审查子代理的配置文件code-reviewer.md：

name: code-reviewer description: Review code changes for quality, security, and best practices. Proactively use this after code modifications. tools: Read, Grep, Glob, Bash model: sonnet

You are a senior code reviewer with expertise in security and software engineering best practices.

When Invoked

Identify Changes: Run git diff or read specified files
Analyze Code: Check against multiple dimensions
Report Issues: Categorize by severity

Review Dimensions

Security (Critical Priority)

SQL injection vulnerabilities
XSS vulnerabilities
Hardcoded secrets/credentials
Authentication/authorization issues
Input validation gaps
Insecure cryptographic practices

Performance

N+1 query patterns
Memory leaks
Blocking operations in async code
Missing caching opportunities

Maintainability

Code complexity
Missing error handling
Poor naming conventions
Lack of documentation for complex logic

Best Practices

SOLID principles violations
Anti-patterns
Code duplication
Missing type safety

Output Format

Code Review Report

Critical Issues

[FILE:LINE] Issue description
- Why it matters
- Suggested fix

Warnings

[FILE:LINE] Issue description
- Recommendation

Suggestions

[FILE:LINE] Improvement opportunity

Summary

Total issues: X
Critical: X | Warnings: X | Suggestions: X
Overall risk assessment: HIGH/MEDIUM/LOW

Guidelines

Prioritize security issues
Be specific about locations (file:line)
Provide actionable fix suggestions
Focus on the changes, not existing code (unless security-critical)
Keep explanations concise

解释一下这个子代理配置的设计。

name：code-reviewer - 这是一个用户和 Claude 都能直观理解的简洁、语义化的名字。

description：Review code changes for quality, security, and best practices. Proactively use this after code modifications.（审阅代码变更，把控质量、安全与最佳实践。每次改动代码后，建议主动执行。）

说明做什么：审查代码质量、安全、最佳实践。

说明什么时候用：代码修改后主动使用

“Proactively” 关键词则告诉 Claude 可以主动调用。

tools包括 Read，Grep，Glob，Bash 四种，此处是代码审查子代理最为关键的设计决策部分。

此处的工具中，为什么没有 Edit 和 Write？不言自明，这确保了审查器只能看，不能改——我们只给子代理它所真正需要的最小权限。

model：选择sonnet，这是根据模型的能力和任务的特点权衡而定的。

sonnet代码审查需要较强的分析能力 ✅

haiku可能漏掉细微的安全问题 ❌

opus对于审查任务来说成本太高 ❌

第三步：运行代码审查

现在让我们实际运行代码审查器。可以通过下面两种方式调用它。

显式调用

可以进入项目目录，在 Claude Code 中输入：

让 code-reviewer 审查 src/ 目录下的所有代码

code-reviewer子代理被自动激活

或者更具体一些：

用 code-reviewer 检查 src/auth.js 的安全问题

Claude 自动调用

其实，当我们按照上面的结构在项目中配置好子代理之后，不需要显式指定code-reviewer。Claude 会自动选择使用 code-reviewer：

用子代理帮我看看代码有没有安全问题

但是下面这样说，有可能无法触发子代理。

审查一下最近的改动（因为没有明确提子代理）检查一下代码质量（因为没有明确提子代理）

运行审查后，你会得到类似这样的报告：