--- schemaVersion: 1 slug: gp-206-20260519-claude-code-large-codebase-harness ticketId: GP-206 lang: zh-tw title: 大型程式庫裡的 AI 寫程式，勝負不只在模型 summary: Claude Code 在大型程式庫裡能不能跑起來，關鍵不是只看模型測試分數，而是團隊有沒有替 Agent 鋪好路：清楚的地圖、可靠的自動化、按需載入的專業工具、符號級導航、內部系統入口，以及有人長期維護這套操作架構。 originalDate: 2026-05-14 translatedDate: 2026-05-19 source: Claude Blog sourceUrl: https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start author: null authorshipNote: null canonicalUrl: https://gu-log.vercel.app/posts/gp-206-20260519-claude-code-large-codebase-harness status: published replacementTicketId: null replacementUrl: null --- # 大型程式庫裡的 AI 寫程式，勝負不只在模型 > **來源:** [Claude Blog](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) 大型程式庫不是「檔案很多」而已。它比較像一座蓋了好幾十年的地下迷宮：有些通道是 Git 裡的單一大型儲存庫，有些通道散在幾十個服務，有些角落還住著 C、C++、C#、Java、PHP 這些大家以為 AI 寫程式工具比較不愛碰的語言；近期模型版本下，[Claude Code](https://gu-log.vercel.app/glossary#claude-code) 在這些環境的表現常比團隊預期更好。 Claude Code 在這種環境能不能做事，重點不只是模型夠不夠聰明。更殘酷的問題是：模型一進門，知不知道該往哪裡走？碰到舊系統、內部工具、不同子目錄的測試指令、同名函式、生成檔、權限規則時，有沒有一套軌道把它導到正確位置？ 這套軌道，才是大型組織導入 AI 寫程式最容易低估的部分。 ## 不是把整座城市塞進向量資料庫 一種常見做法是先把整個程式庫切塊、嵌入、建索引，查詢時再撈出看起來相關的片段。這條路在小專案很直覺，在大型組織卻容易變成時間膠囊：工程師每天提交新程式碼，索引卻可能停在幾小時、幾天，甚至幾週前。最後撈出來的函式兩週前已經改名，模組上一個衝刺已經刪掉，系統還一臉正經地說「這很相關」。 Claude Code 的路線比較像工程師自己進儲存庫：走檔案系統、讀檔案、用搜尋找線索、順著引用追下去。它在開發者機器上看的是活的程式碼，不需要先把整個程式庫上傳或維護中央索引。 但這不代表可以把 [Agent](https://gu-log.vercel.app/glossary#agent) 丟進十億行程式碼裡，喊一聲「找一下那個怪怪的模式」。沒有起始脈絡，Agent 也會像新同事第一天報到，被叫去修一個「應該很簡單」的 bug，結果連系統入口在哪裡都不知道。 > **Mogu 歪樓一下：** > > 把大型程式庫全塞進檢索索引，有時候很像在百貨公司迷路後，決定先把整棟樓每個貨架都拍照建相簿。聽起來很科學，但等相簿建完，三樓美食街已經改裝，手搖飲店搬走，廁所入口也不在那裡了。Agent 式搜尋的精神比較像找一個會看現場指標的工程師，但前提是現場真的有指標。 --- ## 操作架構跟模型一樣重要 大型導入最常見的誤會，是把 Claude Code 的能力想成「模型本身的能力」。模型測試分數當然重要，但在真實程式庫裡，模型外面的操作架構常常更決定結果。 可以先不要記工具名字。把 Claude Code 放進大型程式庫時，團隊其實只是在回答三個很樸素的問題：它一進門要先看哪張地圖？哪些固定動作不該交給模型憑記憶？哪些專業工具應該需要時才拿出來？ 第一層是地圖。CLAUDE.md 的工作不是把專案所有知識塞給模型，而是讓 Claude Code 一進門就知道大方向、重要限制、絕對不能踩的坑。根目錄放全域背景，子目錄放局部慣例：這個服務怎麼測、這個模組的命名規則、這裡有哪些歷史包袱。因為這些檔案會在工作階段一開始自動載入，內容一胖就會拖慢整場工作；它不是百科全書，是入口處那張「這棟樓哪裡不能走」的平面圖。 第二層是自動化。可重複、可驗證的動作，不要交給模型憑記憶。[Hooks](https://gu-log.vercel.app/glossary#hooks) 一開始常被拿來防呆，例如阻止不安全操作；更有價值的用法，是讓設定自己變好。工作階段結束時回顧剛剛學到的脈絡，提議更新 CLAUDE.md；工作階段開始時依照模組載入團隊特定設定；格式化、程式碼規範檢查、測試這種確定性規則，直接用 Hook 跑，不要祈禱模型記得。 第三層是按需載入。大型程式庫裡不可能每個工作階段都需要安全審查、文件更新、部署流程、資料處理規則。[Skills](https://gu-log.vercel.app/glossary#skill) 的價值是漸進揭露：需要做安全檢查時才載入安全審查流程，需要改文件時才載入文件處理流程。它也可以綁定路徑，例如付款服務的部署 [Skill](https://gu-log.vercel.app/glossary#skill) 只在付款目錄生效，不會在別的模組亂入。 等這些做法真的有效，才輪到分發。組織裡最可惜的不是沒有人做出好設定，而是好設定只留在少數資深工程師的電腦上，變成部落知識。[外掛套件](https://gu-log.vercel.app/glossary#plugin) 可以把 Skills、Hooks、[MCP](https://gu-log.vercel.app/glossary#mcp) 設定包成可安裝套件，新工程師第一天裝上就拿到同一套能力。Anthropic 分享的案例裡，大型零售組織曾把連接內部分析平台的 Skill 包成外掛套件，讓商業分析人員不用離開原本工作流程就能拉效能資料；這種價值不在「多一個功能」，而在能力能不能被複製。 > **Mogu 忍不住說：** > > 這裡最容易走歪的地方是把 CLAUDE.md 當祖傳大補帖，什麼都塞。結果每次工作階段都像早餐吃滿漢全席，模型還沒開始修 bug，脈絡胃就先爆炸 (；´Д｀) 真正成熟的配置比較像工具箱：入口處只放常用螺絲起子，焊槍和雷射切割機放在櫃子裡，需要再拿。gu-log 之前分別講過 [Hooks](https://gu-log.vercel.app/posts/gp-159-20260404-zodchiii-claude-code-hooks-8-ai/)、[Skills](https://gu-log.vercel.app/posts/gp-118-20260318-trq212-claude-code-skills-lessons/) 和 [外掛套件](https://gu-log.vercel.app/posts/gp-195-20260507-yage-skill-plugin-evolution/)；這篇先抓大方向就好：大型程式庫需要少量常駐地圖，加上一堆需要時才拿出來的工具。 --- ## 真正的導航，不是文字搜尋而已 在小專案裡搜尋函式名稱，大概還找得到方向。在大型程式庫裡搜尋一個常見名字，可能跳出幾千個結果。Agent 開始一個個打開檔案，脈絡視窗像水槽沒關水一樣快速滿出來，最後還不一定找到對的那個符號。 這時候要換一種想法：不要只搜尋字串，要讓 Claude Code 用上 IDE 平常已經在用的符號導航。IDE 裡常見的「跳到定義」「找所有引用」，背後通常是 LSP，也就是語言伺服器在即時分析程式碼結構。把這層能力暴露給 Claude Code，它就能追同一個符號的定義與引用，分辨不同語言、不同模組裡同名但無關的函式。不過這不是自動掉下來的魔法：團隊還要替對應語言裝好程式碼分析外掛和語言伺服器執行檔。 對多語言或強型別大型程式庫，LSP 通常是高報酬投資。Anthropic 分享的另一個導入案例，是有一間企業軟體公司在 Claude Code 大規模導入前，先把 LSP 整合鋪到全組織，目的就是讓 C 與 C++ 的導航可靠起來。大型程式庫裡，找錯符號比模型笨還可怕。 > **Mogu 吐槽時間：** > > 這裡要把邊界畫清楚：這是 Anthropic 分享的部署經驗，不是公開 benchmark。它能支持的結論是「LSP 對大型、多語言程式庫很值得投資」，不要讀成「某家公司的 C++ 效率提升了多少百分比」(｀・ω・´) 另一種導航，是程式碼以外的公司內部世界。Claude Code 看得到檔案，不代表看得到內部文件、工單系統、分析平台、公司自訂搜尋、部署 API。成熟團隊會把這些內部工具包成 MCP 伺服器，讓 Claude 以結構化工具呼叫的方式取得資料，而不是靠人工複製貼上。 等地圖、按需知識、符號導航、內部工具比較穩了，有些團隊才會把大型探索任務拆出去交給 [子 Agent](https://gu-log.vercel.app/glossary#subagent)。子 Agent 是獨立的 Claude 執行個體，有自己的脈絡視窗；它可以負責唯讀探索某個子系統，把結論寫成檔案，再把乾淨結果交回主 Agent 進行實作。這不是為了炫技，而是為了不要讓主工作階段被「找路過程」塞滿：探索歸探索，編輯歸編輯。 > **Mogu 忍不住說：** > > 子 Agent 不是「多叫幾個 AI 來幫忙」這麼浪漫。沒有清楚分工時，多 Agent 很像開會開到一半又加三個人進來，每個人都說「我補充一下背景」。有操作架構以後，子 Agent 才像真的分工：一個去查倉庫，一個看發票，主 Agent 坐在櫃檯處理退貨。 --- ## 大型程式庫要先變得可讀 Claude Code 能不能幫上忙，受限於它能不能找到正確脈絡。載入太多東西，效能變差；載入太少東西，就等於蒙眼走迷宮。幾個成熟部署的共同模式，都在處理同一件事：讓程式庫對 Agent 可讀。 CLAUDE.md 要薄、要分層。根目錄只放最高層資訊與關鍵陷阱，子目錄再補局部規則。Claude Code 在子目錄啟動時，會往上讀沿途的 CLAUDE.md，所以不必每次都從儲存庫根目錄開始。這點在單一大型儲存庫裡有點反直覺，因為很多工具習慣要求根目錄權限；但對 Agent 來說，從相關子目錄開始，通常更容易聚焦。 測試與程式碼規範檢查指令也要跟著子目錄分層。改一個服務就跑全公司測試，像用消防車澆桌上一盆多肉植物：水壓很猛，植物先走。子目錄 CLAUDE.md 應該標出該區域適用的建置、測試、程式碼規範檢查指令。服務導向架構通常比較好做；深度交錯的編譯語言單一大型儲存庫，可能還需要專案自己的建置設定配合。 生成檔、建置產物、第三方程式碼要排除。把 `permissions.deny` 規則提交到 `.claude/settings.json`，團隊就能共享同一套降噪設定。例外也要留下出口：如果某些工程師正在開發程式碼產生器，生成檔本身就是工作對象，本機設定可以覆蓋專案層級的排除規則，不影響其他人。 有些老系統的目錄結構完全不幫忙，這時候一份輕量的程式庫地圖很有用：根目錄 markdown 列出頂層資料夾，每個資料夾一句話說明內容。若頂層資料夾多到爆炸，就做成分層地圖，根目錄只講最高層結構，子目錄再補下一層細節。比較小的情境，直接 `@` 提及相關檔案或目錄也能達成類似效果。 不過這套階層式方法也有邊界。數十萬資料夾、數百萬檔案、非 Git 版本控制、遊戲引擎裡大量二進位資產、非工程師也會提交程式碼的流程，都需要額外設定與判斷。這不是「AI 寫程式已經解決所有大型企業問題」的童話，而是先把大多數傳統軟體工程環境的路鋪好。 --- ## 設定會過期，組織也會漂移 還有一個很容易被忽略的問題：今天有效的指令，明天可能變成枷鎖。 模型進步後，舊 CLAUDE.md 裡用來彌補模型弱點的規則可能不再需要，甚至會阻止新模型做得更好。曾經要求「每次重構只能改單一檔案」的規則，可能幫早期模型不要失控；但當模型已經能處理跨檔案協調時，這條規則就變成腳鐐。某些 Hooks 與 Skills 也是同樣道理：它們可能是為了補工具缺口而生，等 Claude Code 原生支援相關能力後，就該退場。 比較務實的節奏，是每三到六個月做一次配置審查；重大模型更新後，如果團隊感覺效能卡住，也值得重新檢查。這不是文件潔癖，而是避免操作架構從腳手架變成石膏。 技術設定之外，還需要人負責。成功導入通常不只是開放權限，然後期待大家自然學會。比較順的案例會先有一小群人，甚至一個人，把工具、外掛套件、MCP、權限、CLAUDE.md 慣例整理好，再讓更多工程師使用。第一次接觸就能產生正回饋，導入才會擴散；第一次接觸像在半夜修印表機，熱情很快就會蒸發。 這個角色常落在開發者體驗或開發者生產力團隊。更明確的型態，是一個 Agent manager：介於 PM 與工程師之間，負責 Claude Code 生態系。沒有專職團隊時，最低限度也需要一位 DRI，對設定、權限政策、[Plugin](https://gu-log.vercel.app/glossary#plugin) 市集、CLAUDE.md 慣例有決策權，也有責任讓它們保持更新。 大型組織還會很早碰到治理問題：哪些 Skills 和外掛套件可用？如何避免幾千個工程師重複造同一個輪子？AI 產生的程式碼如何走同樣的程式碼審查流程？比較穩的起步方式，是先定義核准過的 Skills、必要審查流程、有限初始使用範圍，再隨信心擴張。工程、資安、治理一起早點進場，比導入之後才互相補洞輕鬆很多。 > **Mogu 真心話：** > > AI 寫程式導入最怕「自由放養」。一開始很熱鬧，大家各自弄一份神祕設定、各自寫一套 prompt、各自發明半套外掛套件。三個月後組織得到的不是生產力，而是一座民俗村，每間小屋都有自己的祖訓。DRI 的工作不是管東管西，而是把真正有效的做法變成公共基礎建設。 --- ## 結語 大型程式庫裡的 AI 寫程式，不是把更強模型插進更大的儲存庫就會自然發光。模型是引擎，但操作架構是道路、號誌、地圖、維修班與交通規則。 好的導入通常長得很像一座整理過的工地：入口有薄薄的地圖，危險區有警示牌，固定檢查交給機器，特殊工具需要時才拿，內部系統有正式入口，太大的探勘任務可以先派人去看路。最後，DRI 或 Agent manager 讓這套東西不會在模型更新、團隊擴張、治理壓力下慢慢爛掉。 大型程式庫的真正門檻，不是 AI 會不會寫程式。真正的門檻是：組織有沒有先把自己的工程世界整理到 Agent 看得懂、走得動，然後再用自己的工具、風險與治理條件，決定哪些地方真的能讓它動手改。