Claude Code 一口氣改 15–20 個檔案，能不能信？不能只看檔案數，也不能只看它說「測試通過」。真正該問的是：如果其中一個假設錯了，損害會擴散到哪裡？你能不能在合併前看見、驗證，並回滾到最後一個正確狀態？
這篇 Claude Code 大型 Repo 安全改版教學會把答案做成一套可操作的工作流：先定義 Blast Radius（爆炸半徑），用 Code Review Graph 找靜態依賴，再用行為測試與 Git diff 交叉驗證，最後交給沒有參與開發的 fresh context 做「冷審查」。核心公式只有一句：
安全改版 ＝ 小批次 × 三角驗證 × 可回滾
Code Graph 預測「可能影響誰」；Tests 驗證「已知行為有沒有壞」；Git diff 約束「實際改了什麼」。三者答案不一致，才是該停下來查的地方。
為什麼現在需要 Claude Code 大型 Repo 安全改版工作流？
需求不是憑空想像。2026 年 7 月 27 日查核時，一則「有人真的信任 Claude Code 修改 15–20 個檔案嗎？」的 Reddit 討論已有至少 40 則留言；另一則描述百萬行、15 年歷史 C#／React SaaS 的 Ask HN，當時是 4 points、16 comments。這些是社群個案，不是科學抽樣，卻準確指出同一個焦慮：AI 可以很快產生跨層變更，但人類 reviewer 的注意力沒有同步增加。
同一週，開源工具 Code Review Graph 在 GitHub Trending weekly 顯示新增 6,423 stars。市場已經不只想要「更多程式碼」，而是想知道變更會穿過哪些 caller、介面、流程與測試。
先把三個名詞講白：
- Blast Radius（爆炸半徑）：一個錯誤在最壞合理情境下，可能影響的模組、使用者流程、資料與部署邊界。
- Code Graph（程式碼圖譜）：把函式呼叫、繼承、測試關係等連成圖，協助追蹤多跳依賴；它是候選範圍，不是執行時真相。
- 冷審查：讓沒有參與原本對話的 reviewer 從零看計畫、diff、測試證據與風險，先假設實作可能錯，再嘗試推翻它。
第一步：開工前，把 Blast Radius 寫成契約
大型 Repo 最危險的起手式是「幫我完成這個功能」。Claude 會自行補齊大量隱含決策，但 reviewer 最後只看到結果。更好的做法是先建立一份 PLAN.md，把它當作此次改版的臨時契約，而且第一輪只准讀、不准改。
契約至少要有四欄
- 現況基準：目前哪些測試通過？哪個畫面、API response、資料表或效能指標代表現有行為？
- 驗收條件：使用者可觀察的結果是什麼？正常、錯誤、權限、重試與相容性情境各要怎麼驗？
- 禁止觸碰範圍：例如 production infra、migration、billing、公開 API schema、產生檔與不相關重構。
- 停止條件：遇到規格衝突、需要資料遷移、無法建立會失敗的測試，或預測範圍超過原計畫，就先回報，不自行擴張。
可直接把下面這段交給 Claude Code：
進入 Plan Mode。先不要修改任何檔案。
任務：<一句話描述功能>
驗收條件：
1. <可觀察行為>
2. <錯誤／權限情境>
3. <相容性條件>
禁止觸碰：
- migrations/**
- infra/prod/**
- 公開 API schema
- 與本功能無關的 rename／cleanup
請先輸出：
1. 現況行為與證據
2. 可能涉及的檔案、caller、測試與資料邊界
3. 最多四個可獨立驗證、可回滾的 commit
4. 每段的驗證指令與停止條件
5. 尚未證明的假設
寫入 PLAN.md 後停止，等我核准。Anthropic 的 Claude Code 最佳實務把複雜任務整理成 Explore → Plan → Implement → Commit，也明確建議給 Claude 可執行的 tests、build 或畫面證據。Plan Mode 可用 /plan 或從終端機啟動：
claude --permission-mode plan「不要碰」要同時有軟規則與硬邊界
CLAUDE.md適合記錄架構、常用命令與約定，但它是上下文指引，不是作業系統級的護欄。對真正敏感的目錄或動作，應再用 Claude Code permissions 的 deny 規則，並把 production credentials、部署身份與正式資料庫隔離在工作環境之外。
{
"permissions": {
"deny": [
"Edit(./migrations/**)",
"Edit(./infra/prod/**)",
"Bash(git push *)"
]
}
}這是「雙層邊界」：PLAN.md與 CLAUDE.md說明意圖，permissions 與環境隔離限制能力。前者幫模型做對決策，後者降低做錯決策時的損失。
第二步：安裝 Code Review Graph，先建立依賴地圖
Code Review Graph 會用 Tree-sitter 解析 AST，把函式、類別、呼叫、繼承與測試關係寫進本機 SQLite 圖譜。它的強項不是替你判斷程式「正確」，而是比純文字搜尋更容易追多跳關係，例如「這個 service 改了，哪些 caller、flow 與測試可能受影響」。
截至 2026 年 7 月 27 日，官方 README 的 Claude Code 快速安裝流程如下；需要 Python 3.10 以上：
python --version
pipx install code-review-graph
cd /path/to/your/repo
code-review-graph install --platform claude-code
code-review-graph build
code-review-graph status安裝器會在 Repo 裡加入工具整合檔，先用 git status --short確認新增內容，再重啟 Claude Code。官方 README 列出的 review 指令是：
/code-review-graph:build-graph
/code-review-graph:review-delta
/code-review-graph:review-pr若重啟後 slash command 沒出現，不要卡在介面；CLI 仍可完成核心分析：
# 先把圖譜更新到目前工作樹，再分析 HEAD 之後的變更
code-review-graph update --base HEAD --brief
code-review-graph impact --base HEAD --depth 2 --max-results 60核心圖譜存在 Repo 的 .code-review-graph 本機資料庫；如果啟用選用的雲端 embeddings，程式碼衍生的識別字、signature 或 docstring 可能送到外部服務，也可能產生成本。敏感 Repo 應先讀完資料邊界，再決定是否啟用。
第三步：不要把 20 個檔案做成一個大 Commit
檔案數不是風險的好代理變數。改 20 個獨立文案檔，可能比改 3 個共用權限元件安全；真正要控制的是耦合程度、行為跨度與可回滾單位。實務上可把跨層功能拆成四段：
- 建立 Judge：先加 characterization test、golden output 或契約測試，證明現況；最好故意破壞一個條件，確認測試真的會紅。
- 核心行為：只改 domain／service，先不接 UI 與大範圍清理。
- 邊界接線：接 adapter、API、UI 或 persistence，保留相容層。
- 補齊與清理：新增錯誤情境、文件與安全刪除；rename、格式化另開 commit。
Anthropic 在 2026 年的 AI code migration 流程把「先打造夠強的 judge」放在前面：用原始程式和刻意破壞的版本測試 judge，先證明驗收機制會抓錯，再讓 agent 大量改。這個原則不只適用 migration；任何大型改版都一樣。
每段完成後，至少留下這組證據：
git diff --check
git diff --stat
git diff --name-only
# 換成此段真正相關的測試，不要一開始只丟整包慢測試
<your scoped test command>
# 圖譜先更新，再看本段 delta
code-review-graph update --base HEAD --brief
code-review-graph impact --base HEAD --depth 2Claude Code 的 checkpoints 很適合撤回對話中的檔案編輯，但 官方限制包括：Bash 造成的變更不在追蹤範圍、subagent 的檔案修改不一定能一起還原，symlink／hard link 也有例外。因此 checkpoint 是短期保險，Git commit 才是跨 session、可審查的回滾單位。
實測：Graph、Tests、Git Diff 為什麼會互相「打臉」？
為避免只抄工具的行銷數字，我在隔離的暫存 Repo 重播 Code Review Graph 自己的一個真實多檔 commit：先 checkout 22b2715 的父版本、用目前 PyPI 2.3.7 建立圖譜，再把該 commit 套進工作樹但不提交。如此 Git diff 就是已知答案，圖譜與測試則各自提供不同證據；若用歷史 commit 當時自帶的舊版分析器，gap 數字會不同。
結果是：
- Git diff：16 個檔案，新增 1,077 行、刪除 94 行。
- 圖譜 delta：分析到 36 個 changed functions／classes，risk 0.60，列出 13 個 test gaps。
- Blast radius：在 depth 2、最多顯示 60 筆的條件下，指出另有 27 個檔案受到關係波及。
- 相關測試：
tests/test_eval.py共 35 項，全部通過；執行時間會依機器與快取而異。
「13 個 test gaps」與「35 tests passed」可以同時成立。前者表示圖譜沒有看見某些 changed symbol 的直接 TESTED_BY 關係，是保守的結構風險提示；後者只證明這 35 個 assertion 在這次執行通過。它們都沒有單獨證明產品行為完整正確。
怎麼找出 false positive 與漏網依賴？
先把圖譜輸出的每個「受影響檔案」分成三類：
- 可證實路徑：能從 changed symbol 沿 caller／inheritance／test edge 走到實際消費者；補上測試或人工驗證。
- 保守候選：關係存在，但本次參數、feature flag 或執行路徑不會到達；記錄排除證據，不直接叫它 bug。
- 圖譜看不見：reflection、dependency injection、字串路由、SQL／schema、設定檔、訊息佇列與遠端 API contract，必須靠搜尋、runtime trace、契約測試與 domain knowledge 補。
反過來也檢查 Git diff：是否出現計畫外檔案、產生檔、lockfile、權限設定或「順手清理」？如果 Graph 預測了某個重要 caller，diff 與 tests 卻完全沒有對應證據，這不是自動判錯，而是 reviewer 的最高優先查核點。
第四步：用第二模型做冷審查，不讓作者替自己辯護
同一個 session 的 Claude 知道自己為什麼這樣寫，也更容易沿用原本假設。冷審查刻意拿掉這層故事：開一個新 session，或交給另一個模型，只提供 PLAN.md、完整 diff、驗收條件、測試輸出與 graph report。不要附上作者長篇推理，也先不要讓 reviewer 修改程式。
Claude Code 官方最佳實務也提出 Writer／Reviewer 分離與 fresh context 的 adversarial review：讓 reviewer 對照計畫檢查需求、邊界測試與 scope，而且只回報 correctness，不做純風格挑剔。可直接使用這份 prompt：
你是沒有參與開發的冷審查員。
先假設這份實作可能錯，任務是嘗試推翻它，而不是替作者補理由。
輸入只有：
- PLAN.md 與驗收條件
- git diff
- scoped test 輸出
- Code Review Graph delta／impact 報告
請逐項查：
1. 是否碰到禁止觸碰區或超出 scope
2. changed API／symbol 的 caller 是否都被處理
3. 測試是否真的覆蓋驗收條件，並至少有一個會失敗的反例
4. 權限、錯誤、重試、相容性與資料邊界
5. Graph 有提示但 diff／tests 沒有證據的路徑
只回報可重現、可定位的 correctness／security 問題。
每項附：嚴重度、檔案／行號、失敗機制、重現或驗證方法。
不要修改程式；證據不足就標示「待證」，不要猜。不同模型能降低部分共享盲點，但不是魔法。Ask HN 個案中，作者自述第二模型找到更多相關問題，這只能當經驗訊號，不能推成一般準確率。更可靠的設計是讓 reviewer 身份、上下文與成功條件獨立；Anthropic 的 AI-native SDLC 安全說明也採用多個狹窄、獨立 reviewer 與硬式存取邊界，而不是讓一個 agent 同時當作者、裁判與部署者。
第五步：review-delta 管小段，review-pr 管整體
兩個 review 指令的使用時機不同：
review-delta：每完成一個 slice 就跑，關注工作樹相對目前基準新增的 changed symbols、受影響 caller 與 test gaps。它回答「這一小段有沒有長出計畫外觸手？」review-pr：所有 slices 完成、準備開 PR 時跑，重新看整個 branch 對 base 的影響，避免每段都合理、合起來卻破壞跨段契約。
圖譜輸出不能取代既有 CI。建議順序是：更新 graph → 跑 review-delta → 跑該段行為測試 → 看 diff → 冷審查；最後再跑 review-pr、完整必要測試與人工驗收。大型 Repo 若已有 LSP，保留它：LSP 擅長精準 symbol 導航，code graph 擅長多跳關係，兩者互補。
Code Review Graph 的 Recall 1.0，為什麼不能當安全保證？
這是本文最重要的工具批判。Code Review Graph 的 README 自己揭露：其 graph-derived ground truth 是從同一張圖產生的答案，所以 recall 1.0 是 by construction 的循環上限，不是拿真實 production incident 做的獨立驗證。專案同頁列出的平均 F1 0.714、precision 0.578，以及 flow detection recall 33%，也都是專案自評結果，不能外推成你的 Repo 準確率。
README 另列出圖查詢相對 whole-corpus context 的中位數約 82× 縮減；但把整個程式庫全塞進 context 本來就是偏弱、甚至不實際的 baseline。小型單檔變更時，正式圖譜 review 還可能比直接讀 changed file 用更多 context。正確解讀是：
- 這些數字支持「圖譜可能幫你縮小候選範圍」，不支持「它找到了所有風險」。
- 對跨模組、跨層、caller 很多的變更，圖譜較有價值；對小 Repo 或 trivial diff，直接讀 code＋跑 tests 往往更快。
- 你真正該量的是自己的 miss：Graph 沒報但測試或人工發現的依賴，以及 Graph 報了但證明不會走到的路徑。
把 graph risk score 當排查順序，不要當合併門票。
可直接照做的 90 分鐘安全改版工作流
- 0–10 分鐘｜鎖現況：乾淨 branch、記錄 baseline、跑 scoped tests，列出 no-touch zones。
- 10–20 分鐘｜只做 Plan：探索依賴、寫
PLAN.md、把任務拆成不超過四個可回滾 slices。 - 20–55 分鐘｜逐段實作：一次只做一個行為；每段跑 judge、diff check、graph delta，再 commit。
- 55–70 分鐘｜三角驗證：逐一解釋 Graph × Tests × Diff 的不一致，將未解風險列成清單。
- 70–85 分鐘｜冷審查：新 session 或第二模型只讀 artifacts，嘗試推翻 correctness。
- 85–90 分鐘｜打包證據：PR 附計畫、commit map、驗收輸出、graph 候選、已排除理由與剩餘風險。
90 分鐘不是所有功能的工時承諾，而是一個最小安全迴圈。變更越深，就重複更多輪；不要把所有安全檢查拖到最後一次做。
七個最常見的失敗方式
- 圖譜沒更新就分析：先跑
update，不要拿舊 graph 對新工作樹下結論。 - 把 recall 1.0 當真實準確率：它的 ground truth 與 graph 同源，不能證明漏網率是零。
- 只問「測試有沒有過」：先故意做一個破壞，確認 judge 真的會失敗。
- 功能、rename、格式化混在一包：diff 變大，Graph 與 reviewer 的訊噪比一起下降。
- 冷 reviewer 看過完整原對話：它會繼承作者的 framing；只給 artifacts 與查核任務。
- 把 no-touch 寫在 Prompt 就放心：敏感區還需要 deny rules、身份與環境隔離。
- 把 checkpoint 當 Git：Bash 與 subagent 變更可能不在回復範圍；分段 commit 才能持久回滾。
Claude Code 大型 Repo 安全改版 FAQ
Claude Code 改 20 個檔案就算危險嗎？
不一定。風險取決於耦合、公開介面、資料與權限邊界，以及能否用小 commit 驗證與回滾。20 個獨立檔案可能比 3 個共用核心檔安全。
Code Review Graph 可以取代測試嗎？
不可以。圖譜回答關係與候選範圍，測試執行實際行為；兩者會有不同的誤報與漏報。
官方寫 recall 1.0，代表不會漏嗎？
不代表。該數字來自 graph-derived ground truth，是循環上限。README 已明示這不是獨立準確率證明。
小 Repo 也值得建 code graph 嗎？
通常先不用。若一個 diff 直接讀完、caller 可由 LSP 找齊，建圖的維護成本可能高於收益。跨模組、多語言或多跳依賴才更值得。
沒有測試的 legacy Repo 怎麼開始？
先建立最小行為 judge。從最重要使用流程、API contract、golden output 或 characterization test 開始，並用刻意破壞確認它真的會紅，再改 production code。
冷審查一定要換模型嗎？
不一定。fresh context 比「品牌不同」更基本；換模型可增加方法多樣性，但仍要靠明確驗收、可重現證據與人類判斷。
Claude Code checkpoint 足夠回滾嗎？
不足。它適合回復 session 內的檔案編輯，但不是 Git 替代品，也不保證覆蓋 Bash、subagent 與所有檔案型態。
PR 最少要附哪些證據？
至少六項：驗收條件、no-touch zones、commit map、scoped tests、graph impact 與排除理由，以及仍未解的風險。讓 reviewer 不必重建作者整段對話。
重點整理
- 不要問「能不能信 Claude Code 改 20 個檔」，要問「錯了時，Blast Radius 是否受控」。
- 開工前先有 baseline、驗收條件、禁止觸碰範圍與停止條件。
- 大型變更用 plan-first、行為 slices 與分段 Git commit，讓每段都可證明、可回滾。
- Code Graph、Behavior Tests、Git Diff 回答不同問題；不一致處就是最高價值的 review queue。
- 冷審查要 fresh context、先假設實作錯，並只接受可定位、可重現的 correctness 證據。
- Code Review Graph 的自述 benchmark 是工具線索，不是你的 Repo 安全保證。
延伸閱讀：把安全改版接進你的 AI 工程工作流
- Graph Engineering 是什麼？Claude Code Dynamic Workflows 實作教學
- Context Engineering 上下文工程：AI 的記憶管理術
- Agent Observability：監看 Claude Code 工具、Token 與卡關位置
- Claude Code 子代理教學：用一個 Repo 把 Claude 變成 AI 團隊
- Loop Engineering：讓 AI 循環執行、驗證與修正
- AI Agent Harness 是什麼？從聊天到可靠執行
- 動手搭一個最小 AI Agent Harness
- Claude Code vs Codex：原理、實測與使用教學
結論：安全不是少改，而是每一步都能被推翻
大型 Repo 不會因為你把 Prompt 寫得更有自信就變安全。真正可複製的 Claude Code 大型 Repo 安全改版，是把每次改動壓成小批次，用 Graph × Tests × Diff 三角驗證，再讓 fresh context 冷審查，最後用 Git 保留回滾路徑。
所以，AI 能不能改 20 個檔案不是關鍵；關鍵是錯了時，你是否能在合併前指出它會傷到哪裡、用什麼證據證明，並只撤回那一小段。
資料與工具介面查核日期：2026-07-27。本文無業配。Code Review Graph 的 benchmark 數字為專案自述；16 檔案例是 AlphaLab 在隔離環境的一次可重播實測，均不構成獨立準確率認證。AI 具有不確定性；命令請先在分支、測試環境與最小權限下執行，正式合併或部署前仍需依 Repo 的 CI、安全與人工審查規範驗收。