1. 提交前代码审查为什么总在踩坑
写代码快，提交前审查慢，这是很多用 Claude Code 做日常开发的人共同的体感。问题不在于 AI 不会写代码，而在于未提交的改动没有被系统性地检查过。我见过太多场景：功能跑通了，测试也过了，git add -A && git commit -m "fix"一提交，第二天 code review 被同事挑出空指针、边界条件、硬编码密钥。返工的成本远高于提交前花三分钟过一遍 diff。
Claude Code 高效编程实践的核心，其实就落在提交前这一段：用 CLAUDE.md 把审查规则固化下来，让 Claude Code 对git diff输出的未提交改动做逐项检查，再生成规范的 commit 信息。这套流程解决三个具体问题。
第一，审查标准不统一。今天想起来查空指针，明天忘了查 SQL 注入，靠人脑记清单必然漏。把规则写进 CLAUDE.md，每次会话启动自动加载，等于给 AI 注入了团队规范。
第二，diff 太长看不过来。一个中等功能改动动辄几百行 diff，人工逐行读容易疲劳漏看。让 Claude Code 先扫一遍，按严重程度分级输出，人只需要看 Critical/Major。
第三，commit 信息随手写。update、fix bug、修改这类信息在git log里毫无价值。用 Conventional Commits 格式 + AI 生成，提交历史立刻可读。
这套方法适合谁？适合已经在用 Claude Code 写代码、但提交环节还靠手动git diff肉眼扫的开发者；适合团队里想统一审查标准、又不想上重型 CI 门禁的小团队；也适合刚接触 Claude Code、想知道 CLAUDE.md 到底该怎么写才不浪费的新手。下面从配置到验证，一步步给可复制的片段。
2. TaoToken 前置：把 Claude Code 的模型通道配好
在讲 CLAUDE.md 和 code-review 之前，得先把 Claude Code 能正常调用模型这件事解决掉。很多人卡在第一步：Claude Code 装好了，但请求发不出去，或者报401、local proxy failed。这里用 TaoToken 作为模型接入通道，它提供兼容 Anthropic 的 API 端点，Claude Code 可以直接对接。
先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来形如sk-xxxxxxxx。这个 Key 只显示一次，建议先存到密码管理器。
然后配置 Claude Code 的环境变量。Claude Code 读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量。Base URL 填 TaoToken 的 API 地址，注意这里不带任何查询参数：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"如果你用的是 zsh，把这两行写进~/.zshrc；bash 就写进~/.bashrc。写完执行source ~/.zshrc生效。想确认变量进去了，跑echo $ANTHROPIC_BASE_URL，应该输出https://taotoken.net/api。
模型 ID 这块，Claude Code 默认会请求claude-sonnet-4-5这类模型名。TaoToken 的模型列表可以在 https://taotoken.net/models 查到，选一个支持长上下文和工具调用的即可。如果你在配置里需要显式指定模型，用ANTHROPIC_MODEL变量：
export ANTHROPIC_MODEL="claude-sonnet-4-5"三件套凑齐：Base URL、API Key、Model ID。这三个缺一个都会出问题，后面排障章节会逐个对照报错。
配好之后，进任意一个 git 仓库，终端输入claude，进入交互会话。第一次会提示你信任当前目录，确认即可。然后随便问一句「解释这个项目的目录结构」，如果它能正常读文件并回答，说明通道打通了。这一步别跳过，通道没通就往下写 CLAUDE.md，后面所有验证都会失败。
有一点要提醒：Claude Code 的配置是读环境变量的，不是读某个配置文件。所以你在 A 终端配好了，换到 IDE 内置终端可能又是另一套环境。建议统一在 shell 配置文件里写死，避免「明明配了却报 401」这种玄学问题。
3. 可复制配置：CLAUDE.md 与 code-review 提示词模板
这一节给两份可直接粘贴的东西：项目根目录的CLAUDE.md，以及审查未提交 diff 的提示词模板。先看 CLAUDE.md。
在项目根目录新建CLAUDE.md，提交进 Git 和团队共享。Claude Code 每次启动自动读取它，相当于给 AI 注入「项目 README + 编码规范 + 审查清单」。下面这份模板以 PHP + Laravel 为例，你按自己技术栈替换命令和规范即可：
# 项目概述 这是 PHP + Laravel 电商后端，使用 MySQL 8，PHP 8.2。 ## 常用命令 - 跑测试：`./vendor/bin/pest` - 单文件测试：`./vendor/bin/pest tests/Unit/UserServiceTest.php` - 构建：`npm run build` - Lint：`./vendor/bin/pint` ## 编码规范 - 所有 PHP 文件使用 `declare(strict_types=1);` - Controller 不许直接写 DB 查询，必须走 Service 层 - 所有新 API 必须写集成测试 - 禁止在代码中硬编码密钥、token、config - 数组访问前必须判空，ID 参数必须校验为正整数 ## Git 约定 - 功能分支：`feature/xxx`，修复：`fix/xxx` - Commit 使用 Conventional Commits 格式：`type(scope): subject` - type 取值：feat / fix / refactor / test / docs / chore ## 提交前审查规则 审查未提交改动时，按以下清单逐项检查，只报 Critical/Major： 1. 空指针 / NULL 未判空 2. 边界条件：数组越界、除零、负数 ID 3. 异常处理是否向上传播，有无吞异常 4. SQL 注入 / 未鉴权接口 5. 硬编码密钥或配置 6. 逻辑错误是否会影响生产行为 输出格式：文件:行号 + 问题描述 + 建议修复。不报风格 nit。个人偏好放CLAUDE.local.md，加进.gitignore，团队共享的规范放CLAUDE.md。这样你本地的编辑器习惯、临时调试偏好不会污染团队仓库。
接下来是 code-review 提示词模板。Claude Code 有内置的/code-review命令，改完代码未 commit 时直接输入即可，它会启动子 Agent 读当前git diff（工作区未暂存 + 已暂存），重点找 bug、边界条件、安全问题和遗漏的错误处理，按严重程度分级输出。但内置命令的检查项是通用的，想更可控就用手动 Prompt：
检查我尚未提交的改动（git diff），重点关注： - 空指针 / NULL 未判空 - 边界条件（数组越界、除零、负数 ID） - 异常处理是否向上传播 - SQL 注入 / 未鉴权接口 - 是否有逻辑错误会影响生产行为 只报 Critical/Major 问题并给文件和行号，不报风格 nit。如果你在非交互场景，比如 CI 脚本或终端一键，可以用管道：
git diff | claude -p "审查以下 diff，找会导致生产 bug 的逻辑错误，给出文件:行号和建议修复"想对比指定基准分支，比如审查当前分支相对 main 的全部改动：
审查 git diff main...HEAD 中的改动，检查是否与需求一致、有无引入不相关修改这里有个关键点：审查未提交改动和审查已提交分支是两件事。git diff看的是工作区和暂存区，git diff main...HEAD看的是分支差异。提交前用前者，提 PR 前用后者。别混用，否则要么漏看未暂存的改动，要么把已提交的历史又审一遍。
4. 验证请求：从 diff 到 commit 的完整闭环
配置写好了，得跑一遍完整流程验证它真的工作。下面用一个真实的小 bug 修复场景走一遍：UserService.php里getUserById($id)没校验$id为正数。
先建分支：
git checkout -b fix/user-id-validation在 Claude Code 会话里，用最小改动的提示词让它修：
修复 UserService.php 中 getUserById($id) 未校验 $id 为正的 bug。 - 先定位相关文件并说明计划 - 最小改动，不重构其他逻辑 - 修改后跑 ./vendor/bin/pest tests/Unit/UserServiceTest.php - 告诉我应该运行哪些验证命令Claude Code 会先读文件、给计划，你确认后它改代码。改完先别急着 commit，跑git diff人工过一眼：
git diff输出大概是这样：
diff --git a/app/Services/UserService.php b/app/Services/UserService.php index 3a1b2c4..5d6e7f8 100644 --- a/app/Services/UserService.php +++ b/app/Services/UserService.php @@ -12,6 +12,9 @@ class UserService public function getUserById(int $id): ?User { + if ($id <= 0) { + throw new InvalidArgumentException('User ID must be positive'); + } return User::find($id); } }确认改动范围合理，没有无关文件混进来。然后在 Claude Code 会话里跑审查：
/code-review它会读当前 diff，输出分级结果。假设它报了一条 Major：UserService.php:15抛出的异常类型InvalidArgumentException在调用方没有被捕获，可能导致 500。这就是审查的价值——它看到了你改动的下游影响。
按建议补上调用方的异常处理，再跑一次测试确认：
./vendor/bin/pest tests/Unit/UserServiceTest.php测试通过后，生成 commit 信息。用内置/commit，它会分析 diff 生成规范信息：
/commit生成的 commit message 类似：
fix(user): validate user id is positive before query Throw InvalidArgumentException when id <= 0 to prevent invalid queries reaching the database layer.确认无误后提交：
git add -p git commit -m "fix(user): validate user id is positive before query" git push注意git add -p是逐块暂存，比git add -A安全，能避免把调试代码、临时文件一起提交。整个闭环：建分支 → 编码 → 跑测试 → git diff 人工过 → /code-review 审查 → /commit 生成信息 → git add -p → commit → push。
出问题怎么回滚？未 commit 的改动，git checkout .丢弃；已 commit 想撤，git revert HEAD生成反向提交，或者git reset --hard HEAD~1直接回退（后者会丢改动，慎用）。大改之前建议先打个检查点：git add -A && git commit -m "checkpoint before refactor"，出事能回滚到这个点。
5. 本篇常见错排查：401、local proxy failed、reading choices
配置和流程讲完了，实际跑起来最容易撞的几个报错，逐个对照排查。
报错一：401 Unauthorized。最常见。原因通常是 API Key 没配、配错、或者环境变量没生效。先确认echo $ANTHROPIC_API_KEY有输出且以sk-开头。如果输出为空，说明 shell 配置文件没 source，或者你换了个终端。如果 Key 有输出但还是 401，去 https://taotoken.net/api-keys 确认这个 Key 没被删除或过期。还有一种情况：Key 复制时带了空格或换行，用echo $ANTHROPIC_API_KEY | wc -c看长度对不对。
报错二：local proxy failed 或 connection refused。这个通常指向 Base URL 配错。确认echo $ANTHROPIC_BASE_URL输出的是https://taotoken.net/api，注意结尾不要多加斜杠，也不要带查询参数。有些教程会让你填带/v1的路径，Claude Code 自己会拼，填多了会 404 或连接失败。如果变量对但还是失败，检查本机网络能不能访问这个域名，curl -I https://taotoken.net/api看返回码。
报错三：reading choices 相关错误。这类报错一般出现在模型返回格式不符合预期时，根因往往是模型 ID 配错，或者选了一个不支持工具调用的模型。Claude Code 依赖模型的 tool use 能力，如果模型不支持，返回结构里就没有choices或content字段，解析就崩。去 https://taotoken.net/models 确认你用的模型 ID 支持 function calling / tool use，然后在ANTHROPIC_MODEL里填对。
报错四：OAuth 相关提示。Claude Code 某些版本会尝试走 OAuth 登录流程，如果你用的是 API Key 模式，这个提示会干扰。确认没有同时设置冲突的认证变量，比如既设了ANTHROPIC_API_KEY又设了别的 token 变量。清理掉多余的，只留 Base URL + API Key + Model ID 三件套。
报错五：/code-review 没反应或报找不到命令。内置命令依赖 Claude Code 版本，老版本可能没有。先claude --version看版本，升级到较新版本。如果升级后还是没有，直接用第 3 节的手动 Prompt 替代，效果一样。
排查通用思路：先确认三件套（Base URL + Key + Model ID）齐全且正确，再看网络，最后看版本。90% 的问题出在三件套上。每次改完环境变量记得source或重开终端，这是最容易被忽略的一步。
6. 把审查闭环变成日常习惯
回到最开始的问题：提交前审查慢、标准不统一、commit 信息随手写。这套流程的价值不在于某一次审查抓到了 bug，而在于它把「提交前过一遍」变成了不需要意志力的默认动作。CLAUDE.md 定规矩，/code-review审未提交 diff，/commit生成规范信息，三步串起来，每次提交前花两三分钟，省下的是第二天返工的一小时。
几个实操建议。第一，CLAUDE.md 别一次写太满，先放最关键的五六条审查规则，跑一两周觉得漏了什么再加，写太多 AI 反而抓不住重点。第二，/code-review报的问题不一定都对，它可能误报，也可能漏报，把它当第一道筛子而不是最终裁判，Critical 必看，Major 扫一眼，Minor 和风格问题直接忽略。第三，commit 信息生成后自己读一遍，AI 有时会把 scope 写得太宽，手动收窄一下。
如果你还没配好通道，先去 https://taotoken.net/api-keys 拿 Key，按第 2 节把三件套配上，再回来跑第 4 节的完整闭环。想先感受一下模型对话效果，可以到 https://taotoken.net/chat 试几句。长期做编码和 Agent 任务的，Coding Plan 在 https://taotoken.net/coding-plan 有更合适的额度方案。接入文档在 https://taotoken.net/doc ，配置细节对不上时以文档为准。
最后留一个我自己的习惯：每次大改前先git commit一个检查点，改完审查通过再 squash 掉。这样审查过程中随时能回滚，心理负担小很多，也敢让 AI 做更大胆的重构。
