1. 提交前代碼審查為什么總在踩坑寫代碼快提交前審查慢這是很多用 Claude Code 做日常開(kāi)發(fā)的人共同的體感。問(wèn)題不在于 AI 不會(huì)寫代碼而在于未提交的改動(dòng)沒(méi)有被系統(tǒng)性地檢查過(guò)。我見(jiàn)過(guò)太多場(chǎng)景功能跑通了測(cè)試也過(guò)了git add -A git commit -m fix一提交第二天 code review 被同事挑出空指針、邊界條件、硬編碼密鑰。返工的成本遠(yuǎn)高于提交前花三分鐘過(guò)一遍 diff。Claude Code 高效編程實(shí)踐的核心其實(shí)就落在提交前這一段用 CLAUDE.md 把審查規(guī)則固化下來(lái)讓 Claude Code 對(duì)git diff輸出的未提交改動(dòng)做逐項(xiàng)檢查再生成規(guī)范的 commit 信息。這套流程解決三個(gè)具體問(wèn)題。第一審查標(biāo)準(zhǔn)不統(tǒng)一。今天想起來(lái)查空指針明天忘了查 SQL 注入靠人腦記清單必然漏。把規(guī)則寫進(jìn) CLAUDE.md每次會(huì)話啟動(dòng)自動(dòng)加載等于給 AI 注入了團(tuán)隊(duì)規(guī)范。第二diff 太長(zhǎng)看不過(guò)來(lái)。一個(gè)中等功能改動(dòng)動(dòng)輒幾百行 diff人工逐行讀容易疲勞漏看。讓 Claude Code 先掃一遍按嚴(yán)重程度分級(jí)輸出人只需要看 Critical/Major。第三commit 信息隨手寫。update、fix bug、修改這類信息在git log里毫無(wú)價(jià)值。用 Conventional Commits 格式 AI 生成提交歷史立刻可讀。這套方法適合誰(shuí)適合已經(jīng)在用 Claude Code 寫代碼、但提交環(huán)節(jié)還靠手動(dòng)git diff肉眼掃的開(kāi)發(fā)者適合團(tuán)隊(duì)里想統(tǒng)一審查標(biāo)準(zhǔn)、又不想上重型 CI 門禁的小團(tuán)隊(duì)也適合剛接觸 Claude Code、想知道 CLAUDE.md 到底該怎么寫才不浪費(fèi)的新手。下面從配置到驗(yàn)證一步步給可復(fù)制的片段。2. TaoToken 前置把 Claude Code 的模型通道配好在講 CLAUDE.md 和 code-review 之前得先把 Claude Code 能正常調(diào)用模型這件事解決掉。很多人卡在第一步Claude Code 裝好了但請(qǐng)求發(fā)不出去或者報(bào)401、local proxy failed。這里用 TaoToken 作為模型接入通道它提供兼容 Anthropic 的 API 端點(diǎn)Claude Code 可以直接對(duì)接。先拿 Key。打開(kāi) https://taotoken.net/api-keys 登錄后創(chuàng)建一個(gè) API Key復(fù)制出來(lái)形如sk-xxxxxxxx。這個(gè) Key 只顯示一次建議先存到密碼管理器。然后配置 Claude Code 的環(huán)境變量。Claude Code 讀取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY兩個(gè)變量。Base URL 填 TaoToken 的 API 地址注意這里不帶任何查詢參數(shù)export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key如果你用的是 zsh把這兩行寫進(jìn)~/.zshrcbash 就寫進(jìn)~/.bashrc。寫完執(zhí)行source ~/.zshrc生效。想確認(rèn)變量進(jìn)去了跑echo $ANTHROPIC_BASE_URL應(yīng)該輸出https://taotoken.net/api。模型 ID 這塊Claude Code 默認(rèn)會(huì)請(qǐng)求claude-sonnet-4-5這類模型名。TaoToken 的模型列表可以在 https://taotoken.net/models 查到選一個(gè)支持長(zhǎng)上下文和工具調(diào)用的即可。如果你在配置里需要顯式指定模型用ANTHROPIC_MODEL變量export ANTHROPIC_MODELclaude-sonnet-4-5三件套湊齊Base URL、API Key、Model ID。這三個(gè)缺一個(gè)都會(huì)出問(wèn)題后面排障章節(jié)會(huì)逐個(gè)對(duì)照?qǐng)?bào)錯(cuò)。配好之后進(jìn)任意一個(gè) git 倉(cāng)庫(kù)終端輸入claude進(jìn)入交互會(huì)話。第一次會(huì)提示你信任當(dāng)前目錄確認(rèn)即可。然后隨便問(wèn)一句「解釋這個(gè)項(xiàng)目的目錄結(jié)構(gòu)」如果它能正常讀文件并回答說(shuō)明通道打通了。這一步別跳過(guò)通道沒(méi)通就往下寫 CLAUDE.md后面所有驗(yàn)證都會(huì)失敗。有一點(diǎn)要提醒Claude Code 的配置是讀環(huán)境變量的不是讀某個(gè)配置文件。所以你在 A 終端配好了換到 IDE 內(nèi)置終端可能又是另一套環(huán)境。建議統(tǒng)一在 shell 配置文件里寫死避免「明明配了卻報(bào) 401」這種玄學(xué)問(wèn)題。3. 可復(fù)制配置CLAUDE.md 與 code-review 提示詞模板這一節(jié)給兩份可直接粘貼的東西項(xiàng)目根目錄的CLAUDE.md以及審查未提交 diff 的提示詞模板。先看 CLAUDE.md。在項(xiàng)目根目錄新建CLAUDE.md提交進(jìn) Git 和團(tuán)隊(duì)共享。Claude Code 每次啟動(dòng)自動(dòng)讀取它相當(dāng)于給 AI 注入「項(xiàng)目 README 編碼規(guī)范 審查清單」。下面這份模板以 PHP Laravel 為例你按自己技術(shù)棧替換命令和規(guī)范即可# 項(xiàng)目概述 這是 PHP Laravel 電商后端使用 MySQL 8PHP 8.2。 ## 常用命令 - 跑測(cè)試./vendor/bin/pest - 單文件測(cè)試./vendor/bin/pest tests/Unit/UserServiceTest.php - 構(gòu)建npm run build - Lint./vendor/bin/pint ## 編碼規(guī)范 - 所有 PHP 文件使用 declare(strict_types1); - Controller 不許直接寫 DB 查詢必須走 Service 層 - 所有新 API 必須寫集成測(cè)試 - 禁止在代碼中硬編碼密鑰、token、config - 數(shù)組訪問(wèn)前必須判空ID 參數(shù)必須校驗(yàn)為正整數(shù) ## Git 約定 - 功能分支feature/xxx修復(fù)fix/xxx - Commit 使用 Conventional Commits 格式type(scope): subject - type 取值feat / fix / refactor / test / docs / chore ## 提交前審查規(guī)則 審查未提交改動(dòng)時(shí)按以下清單逐項(xiàng)檢查只報(bào) Critical/Major 1. 空指針 / NULL 未判空 2. 邊界條件數(shù)組越界、除零、負(fù)數(shù) ID 3. 異常處理是否向上傳播有無(wú)吞異常 4. SQL 注入 / 未鑒權(quán)接口 5. 硬編碼密鑰或配置 6. 邏輯錯(cuò)誤是否會(huì)影響生產(chǎn)行為 輸出格式文件:行號(hào) 問(wèn)題描述 建議修復(fù)。不報(bào)風(fēng)格 nit。個(gè)人偏好放CLAUDE.local.md加進(jìn).gitignore團(tuán)隊(duì)共享的規(guī)范放CLAUDE.md。這樣你本地的編輯器習(xí)慣、臨時(shí)調(diào)試偏好不會(huì)污染團(tuán)隊(duì)倉(cāng)庫(kù)。接下來(lái)是 code-review 提示詞模板。Claude Code 有內(nèi)置的/code-review命令改完代碼未 commit 時(shí)直接輸入即可它會(huì)啟動(dòng)子 Agent 讀當(dāng)前git diff工作區(qū)未暫存 已暫存重點(diǎn)找 bug、邊界條件、安全問(wèn)題和遺漏的錯(cuò)誤處理按嚴(yán)重程度分級(jí)輸出。但內(nèi)置命令的檢查項(xiàng)是通用的想更可控就用手動(dòng) Prompt檢查我尚未提交的改動(dòng)git diff重點(diǎn)關(guān)注 - 空指針 / NULL 未判空 - 邊界條件數(shù)組越界、除零、負(fù)數(shù) ID - 異常處理是否向上傳播 - SQL 注入 / 未鑒權(quán)接口 - 是否有邏輯錯(cuò)誤會(huì)影響生產(chǎn)行為 只報(bào) Critical/Major 問(wèn)題并給文件和行號(hào)不報(bào)風(fēng)格 nit。如果你在非交互場(chǎng)景比如 CI 腳本或終端一鍵可以用管道git diff | claude -p 審查以下 diff找會(huì)導(dǎo)致生產(chǎn) bug 的邏輯錯(cuò)誤給出文件:行號(hào)和建議修復(fù)想對(duì)比指定基準(zhǔn)分支比如審查當(dāng)前分支相對(duì) main 的全部改動(dòng)審查 git diff main...HEAD 中的改動(dòng)檢查是否與需求一致、有無(wú)引入不相關(guān)修改這里有個(gè)關(guān)鍵點(diǎn)審查未提交改動(dòng)和審查已提交分支是兩件事。git diff看的是工作區(qū)和暫存區(qū)git diff main...HEAD看的是分支差異。提交前用前者提 PR 前用后者。別混用否則要么漏看未暫存的改動(dòng)要么把已提交的歷史又審一遍。4. 驗(yàn)證請(qǐng)求從 diff 到 commit 的完整閉環(huán)配置寫好了得跑一遍完整流程驗(yàn)證它真的工作。下面用一個(gè)真實(shí)的小 bug 修復(fù)場(chǎng)景走一遍UserService.php里getUserById($id)沒(méi)校驗(yàn)$id為正數(shù)。先建分支git checkout -b fix/user-id-validation在 Claude Code 會(huì)話里用最小改動(dòng)的提示詞讓它修修復(fù) UserService.php 中 getUserById($id) 未校驗(yàn) $id 為正的 bug。 - 先定位相關(guān)文件并說(shuō)明計(jì)劃 - 最小改動(dòng)不重構(gòu)其他邏輯 - 修改后跑 ./vendor/bin/pest tests/Unit/UserServiceTest.php - 告訴我應(yīng)該運(yùn)行哪些驗(yàn)證命令Claude Code 會(huì)先讀文件、給計(jì)劃你確認(rèn)后它改代碼。改完先別急著 commit跑git diff人工過(guò)一眼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); } }確認(rèn)改動(dòng)范圍合理沒(méi)有無(wú)關(guān)文件混進(jìn)來(lái)。然后在 Claude Code 會(huì)話里跑審查/code-review它會(huì)讀當(dāng)前 diff輸出分級(jí)結(jié)果。假設(shè)它報(bào)了一條 MajorUserService.php:15拋出的異常類型InvalidArgumentException在調(diào)用方?jīng)]有被捕獲可能導(dǎo)致 500。這就是審查的價(jià)值——它看到了你改動(dòng)的下游影響。按建議補(bǔ)上調(diào)用方的異常處理再跑一次測(cè)試確認(rèn)./vendor/bin/pest tests/Unit/UserServiceTest.php測(cè)試通過(guò)后生成 commit 信息。用內(nèi)置/commit它會(huì)分析 diff 生成規(guī)范信息/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.確認(rèn)無(wú)誤后提交git add -p git commit -m fix(user): validate user id is positive before query git push注意git add -p是逐塊暫存比git add -A安全能避免把調(diào)試代碼、臨時(shí)文件一起提交。整個(gè)閉環(huán)建分支 → 編碼 → 跑測(cè)試 → git diff 人工過(guò) → /code-review 審查 → /commit 生成信息 → git add -p → commit → push。出問(wèn)題怎么回滾未 commit 的改動(dòng)git checkout .丟棄已 commit 想撤git revert HEAD生成反向提交或者git reset --hard HEAD~1直接回退后者會(huì)丟改動(dòng)慎用。大改之前建議先打個(gè)檢查點(diǎn)git add -A git commit -m checkpoint before refactor出事能回滾到這個(gè)點(diǎn)。5. 本篇常見(jiàn)錯(cuò)排查401、local proxy failed、reading choices配置和流程講完了實(shí)際跑起來(lái)最容易撞的幾個(gè)報(bào)錯(cuò)逐個(gè)對(duì)照排查。報(bào)錯(cuò)一401 Unauthorized。最常見(jiàn)。原因通常是 API Key 沒(méi)配、配錯(cuò)、或者環(huán)境變量沒(méi)生效。先確認(rèn)echo $ANTHROPIC_API_KEY有輸出且以sk-開(kāi)頭。如果輸出為空說(shuō)明 shell 配置文件沒(méi) source或者你換了個(gè)終端。如果 Key 有輸出但還是 401去 https://taotoken.net/api-keys 確認(rèn)這個(gè) Key 沒(méi)被刪除或過(guò)期。還有一種情況Key 復(fù)制時(shí)帶了空格或換行用echo $ANTHROPIC_API_KEY | wc -c看長(zhǎng)度對(duì)不對(duì)。報(bào)錯(cuò)二local proxy failed 或 connection refused。這個(gè)通常指向 Base URL 配錯(cuò)。確認(rèn)echo $ANTHROPIC_BASE_URL輸出的是https://taotoken.net/api注意結(jié)尾不要多加斜杠也不要帶查詢參數(shù)。有些教程會(huì)讓你填帶/v1的路徑Claude Code 自己會(huì)拼填多了會(huì) 404 或連接失敗。如果變量對(duì)但還是失敗檢查本機(jī)網(wǎng)絡(luò)能不能訪問(wèn)這個(gè)域名curl -I https://taotoken.net/api看返回碼。報(bào)錯(cuò)三reading choices 相關(guān)錯(cuò)誤。這類報(bào)錯(cuò)一般出現(xiàn)在模型返回格式不符合預(yù)期時(shí)根因往往是模型 ID 配錯(cuò)或者選了一個(gè)不支持工具調(diào)用的模型。Claude Code 依賴模型的 tool use 能力如果模型不支持返回結(jié)構(gòu)里就沒(méi)有choices或content字段解析就崩。去 https://taotoken.net/models 確認(rèn)你用的模型 ID 支持 function calling / tool use然后在ANTHROPIC_MODEL里填對(duì)。報(bào)錯(cuò)四OAuth 相關(guān)提示。Claude Code 某些版本會(huì)嘗試走 OAuth 登錄流程如果你用的是 API Key 模式這個(gè)提示會(huì)干擾。確認(rèn)沒(méi)有同時(shí)設(shè)置沖突的認(rèn)證變量比如既設(shè)了ANTHROPIC_API_KEY又設(shè)了別的 token 變量。清理掉多余的只留 Base URL API Key Model ID 三件套。報(bào)錯(cuò)五/code-review 沒(méi)反應(yīng)或報(bào)找不到命令。內(nèi)置命令依賴 Claude Code 版本老版本可能沒(méi)有。先claude --version看版本升級(jí)到較新版本。如果升級(jí)后還是沒(méi)有直接用第 3 節(jié)的手動(dòng) Prompt 替代效果一樣。排查通用思路先確認(rèn)三件套Base URL Key Model ID齊全且正確再看網(wǎng)絡(luò)最后看版本。90% 的問(wèn)題出在三件套上。每次改完環(huán)境變量記得source或重開(kāi)終端這是最容易被忽略的一步。6. 把審查閉環(huán)變成日常習(xí)慣回到最開(kāi)始的問(wèn)題提交前審查慢、標(biāo)準(zhǔn)不統(tǒng)一、commit 信息隨手寫。這套流程的價(jià)值不在于某一次審查抓到了 bug而在于它把「提交前過(guò)一遍」變成了不需要意志力的默認(rèn)動(dòng)作。CLAUDE.md 定規(guī)矩/code-review審未提交 diff/commit生成規(guī)范信息三步串起來(lái)每次提交前花兩三分鐘省下的是第二天返工的一小時(shí)。幾個(gè)實(shí)操建議。第一CLAUDE.md 別一次寫太滿先放最關(guān)鍵的五六條審查規(guī)則跑一兩周覺(jué)得漏了什么再加寫太多 AI 反而抓不住重點(diǎn)。第二/code-review報(bào)的問(wèn)題不一定都對(duì)它可能誤報(bào)也可能漏報(bào)把它當(dāng)?shù)谝坏篮Y子而不是最終裁判Critical 必看Major 掃一眼Minor 和風(fēng)格問(wèn)題直接忽略。第三commit 信息生成后自己讀一遍AI 有時(shí)會(huì)把 scope 寫得太寬手動(dòng)收窄一下。如果你還沒(méi)配好通道先去 https://taotoken.net/api-keys 拿 Key按第 2 節(jié)把三件套配上再回來(lái)跑第 4 節(jié)的完整閉環(huán)。想先感受一下模型對(duì)話效果可以到 https://taotoken.net/chat 試幾句。長(zhǎng)期做編碼和 Agent 任務(wù)的Coding Plan 在 https://taotoken.net/coding-plan 有更合適的額度方案。接入文檔在 https://taotoken.net/doc 配置細(xì)節(jié)對(duì)不上時(shí)以文檔為準(zhǔn)。最后留一個(gè)我自己的習(xí)慣每次大改前先git commit一個(gè)檢查點(diǎn)改完審查通過(guò)再 squash 掉。這樣審查過(guò)程中隨時(shí)能回滾心理負(fù)擔(dān)小很多也敢讓 AI 做更大膽的重構(gòu)。