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_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key如果你用的是 zsh把这两行写进~/.zshrcbash 就写进~/.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_MODELclaude-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 8PHP 8.2。 ## 常用命令 - 跑测试./vendor/bin/pest - 单文件测试./vendor/bin/pest tests/Unit/UserServiceTest.php - 构建npm run build - Lint./vendor/bin/pint ## 编码规范 - 所有 PHP 文件使用 declare(strict_types1); - 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输出分级结果。假设它报了一条 MajorUserService.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 做更大胆的重构。