1. 为什么只读型 SubAgent 是 Claude Code 工程化的第一块砖如果你已经在本地用 Claude Code 写过几个小项目大概率会遇到一个尴尬场景让 AI 帮忙审查代码它顺手把文件改了。改得对不对先不说关键是审查和修改混在一起你根本没法判断哪一步是它主动做的、哪一步是你授权的。Claude Code 的 SubAgent 机制就是来解决这个问题的而只读型子代理Read-Only SubAgent是其中最容易落地、风险最低的一类。只读型子代理的核心特征很朴素工具白名单里只有 Read、Grep、Glob 三件套没有 Edit、没有 Write、没有 NotebookEdit。它只能看不能改。这个约束在工程上意味着什么意味着你可以放心地把它挂到 Git Hook 里让它在每次git commit之前自动跑一遍审查而不用担心审查顺便把代码改了这种事故。本篇聚焦一个具体角色code-reviewer。我会从它的 frontmatter 骨架写起接入 TaoToken 的统一 Key/API 通道然后用 Git Hook 在提交前触发只读审查。目标很明确在本地仓库跑通一次提交前自动审查的完整流程。适合谁适合已经在用 Claude Code、想把它从聊天工具变成工程流水线一环的开发者。如果你还没装 Claude Code建议先跑通基础对话再回来。2. TaoToken 前置统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方通道但在国内网络环境下直连经常不稳定。TaoToken 提供的是一个统一的 API 网关把 Key 管理和通道切换收敛到一个地方。你不需要在每台机器上配不同的环境变量只需要一个 Key就能让 Claude Code、Coding Plan、模型对话共用同一条通道。2.1 获取 API Key打开 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按用途分 Key一个给 Claude Code 用一个给脚本用方便后续排查问题时定位来源。创建后复制 Key格式通常是sk-开头的一串字符。2.2 配置 Claude Code 走 TaoToken 通道Claude Code 读取的是环境变量。在~/.zshrc或~/.bashrc里加两行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key保存后source ~/.zshrc让配置生效。验证一下echo $ANTHROPIC_BASE_URL # 应该输出 https://taotoken.net/api注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要带 UTM 参数。API 地址就是https://taotoken.net/api干净利落。2.3 验证通道连通在终端里跑一次最简单的请求确认 Key 和通道都正常curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: reply with OK}] }如果返回里包含OK字样说明通道通了。这一步很重要因为后面 SubAgent 和 Git Hook 都依赖这条通道通道不通后面全是白搭。3. 可复制配置code-reviewer 子代理骨架Claude Code 的子代理定义放在.claude/agents/目录下每个子代理是一个.md文件由 frontmatterYAML 元数据和正文system prompt两部分组成。下面直接给可复制的配置。3.1 极简版 code-reviewer先写一个 20 行的极简版适合入门理解结构--- name: code-reviewer description: Proactively review code changes for quality and security after I modify code, before commit. tools: Read, Grep, Glob model: sonnet --- You are a code reviewer. When invoked, run git diff to see recent changes, then report issues by priority: Critical / Warning / Suggestion. You may only read files. Never modify anything.保存到.claude/agents/code-reviewer.md。四个 frontmatter 字段的含义name是子代理的身份证主对话里用code-reviewer引用。命名用小写字母加连字符反映角色而不是技术栈。description是最关键的字段它决定什么时候自动触发。写成何时触发而不是做什么。上面这版写的是after I modify code, before commitClaude 看到你刚改完代码就会自动调起它。tools是工具白名单。只读三件套 Read、Grep、Glob。注意不写这个字段等于继承主对话的全部工具那就失去只读约束了千万别留空。model选 sonnet质量和成本平衡。关键审计场景可以换 opus高频探索类可以换 haiku。3.2 瑞士军刀版 code-reviewer工程化团队用这个版本覆盖质量、安全、性能、测试覆盖四个维度--- name: code-reviewer description: Proactively review code changes for quality, security, performance, and test coverage after I modify code, before commit. tools: Read, Grep, Glob, Bash model: sonnet --- You are a senior Python code reviewer with 10 years of production experience in backend systems handling financial transactions. # 角色 - Default focus: code quality (readability, naming, duplication, obvious bugs) - Always-on: security (SQLi, XSS, SSRF, hardcoded secrets, auth checks) - If file path matches src/orders/, src/payments/, src/billing/: also check performance - If file path matches tests/: also check test coverage gaps # 硬约束 - You may only READ files. Never use Edit or Write tools. - Bash is allowed only for: git diff, git log, git show, pytest --co, ruff check. - Do NOT run: pytest (full), rm, mv, cp, or any state-changing command. - If you need something outside your scope, report it; do not improvise. # 报告格式必须用这个结构Code Review: branch 或 fileCritical (must fix before merge) file:line — issue — suggested fixWarning (should fix) file:line — issue — suggested fixSuggestion (nice to have) file:line — issue — suggested fixSummary Total issues: N (Critical N, Warning N, Suggestion N) Verdict: APPROVE / REQUEST_CHANGES / COMMENT注意这里tools多了 Bash但 system prompt 里明确限制了 Bash 只能跑git diff、git log、git show、pytest --co、ruff check这几个命令。这是物理层白名单 语言层约束的双保险。3.3 settings.json 骨架子代理定义好了还需要在.claude/settings.json里配置 Hook让它在git commit前自动触发{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/pre-commit-review.sh } ] } ] } }这个配置的意思是当 Claude Code 准备调用 Bash 工具时先跑一遍pre-commit-review.sh脚本。脚本里判断是不是git commit命令是的话就调起 code-reviewer 审查当前 diff。3.4 Hook 脚本创建.claude/hooks/pre-commit-review.sh#!/usr/bin/env bash # 拦截 git commit自动调起 code-reviewer 子代理审查 diff COMMAND$1 # 1. 只在 git commit 时触发 if [[ $COMMAND ! *git commit* ]]; then exit 0 fi # 2. 看当前 staged diff DIFF$(git diff --cached) if [ -z $DIFF ]; then exit 0 fi # 3. 调起 code-reviewer 子代理 RESULT$(claude --headless --agent code-reviewer \ --task 审查以下 git diff按 APPROVE/REQUEST_CHANGES 给结论$DIFF 21) # 4. 翻译结果为 exit code if echo $RESULT | grep -q REQUEST_CHANGES; then echo code-reviewer 拒绝本次 commit echo $RESULT exit 2 fi if echo $RESULT | grep -q Critical; then echo code-reviewer 发现 Critical 问题 echo $RESULT exit 2 fi echo code-reviewer 审查通过 exit 0给脚本加执行权限chmod x .claude/hooks/pre-commit-review.sh4. 验证请求与成功结果配置写完了得验证它真的能跑通。分三步。4.1 验证子代理能被调起在 Claude Code 主对话里输入code-reviewer 审查一下 src/orders/timeout.py预期结果code-reviewer 返回一份带 Critical / Warning / Suggestion 分级的报告。如果它说找不到子代理检查.claude/agents/code-reviewer.md路径对不对。4.2 验证只读约束生效在主对话里故意让它改文件code-reviewer 在 src/orders/timeout.py 第 42 行加一行 print(debug)预期结果code-reviewer 拒绝说我没有 Edit 工具或我只能读文件。如果它居然改了说明tools字段配置错了立即停用检查。4.3 验证 Git Hook 触发在仓库里改一个文件git add之后执行git commit -m test。预期结果commit 被拦截终端输出 code-reviewer 的审查报告。如果审查通过commit 正常执行如果有 Critical 问题commit 被阻止exit code 为 2。实测下来第一次跑通这个流程大概需要 10 分钟主要是等子代理审查 diff 的时间。如果 diff 很大超过 500 行审查会慢一些可以考虑在 Hook 里加一个 diff 行数上限超过就跳过自动审查、只提示手动跑。5. 本篇常见错排查5.1 description 写成做什么而不是何时触发这是触发率低的头号原因。description: A senior code reviewer描述的是角色Claude 不知道用户什么时候需要我。正确写法是Proactively review code changes after I modify code, before commit把触发时机写清楚。判断标准把 description 拿给一个新来的工程师看问他你在什么情况下会用这个子代理答不上来就是写错了。5.2 tools 给了 Bash 但没限制危险命令只读子代理如果给了 Bash 工具就开了一个后门。子代理理论上可以跑rm、mv、curl下载执行任意脚本。正确做法是在 system prompt 里明确列出允许的命令前缀其他全部拒绝。判断标准有 Bash 工具但没有命令白名单等于没设防。5.3 system prompt 只写角色不写硬约束新人常踩的坑system prompt 写得很哲学你是一个严谨的代码审查员关注代码质量、安全、可维护性但没写你不能做什么。结果子代理会漂看到明显 SQL 注入不拦、想顺手优化一下。判断标准system prompt 里有没有Never、You may only、Do NOT这些明确的禁止词。全是应该最好就是软约束会漂。5.4 Hook 脚本 exit code 写错Git Hook 靠 exit code 判断放行还是阻止。exit 0 放行非 0 阻止。常见错误是脚本里所有分支都 exit 0导致审查发现问题也放行。检查方法故意写一段有 SQL 注入的代码git commit看是否被拦截。没拦截就是 exit code 逻辑有问题。5.5 子代理审查完直接 commit 绕过人工危险的反模式Hook 里 code-reviewer 审查通过后直接git commit合入跳过人工 review。这等于让 AI 单独决定代码能不能进 main。正确做法是 Hook 只做审查、不做决策AI 给意见人看意见后自己点 commit。流程应该是AI 审查 → 人看报告 → 人决定 commit / 改 / 拒绝。6. 把只读审查嵌进你的日常流程只读型 SubAgent 是 Claude Code 工程化的零号工程。三件套定义角色三段式稳定行为四场景覆盖大部分审查需求Git Hook 让审查从偶尔想起来才跑变成每次提交都跑。如果你想把这条流程跑得更顺建议把 Key 管理和通道切换收敛到 TaoToken。一个 Key 同时给 Claude Code、Coding Plan、模型对话用排查问题时不用在多个环境变量之间来回切。接入文档里有完整的配置说明API Keys 页面可以直接创建和管理 Key。长期做编码和 Agent 场景的话Coding Plan 的额度模型比按次调用更划算适合把审查、测试、文档生成这些高频动作都挂上去。下一步可以尝试把 security-auditor 和 test-coverage-reviewer 也写成只读子代理在 Hook 里串行跑一遍。四个子代理各管一摊主对话按需调起或者统一在 commit 前触发。思维模型和本篇完全一样只是工具白名单和 system prompt 的差异。