Claude Code 在大型代碼庫中的工作方式：最佳實踐與起步指南
整理版優先睇
Claude Code 喺大型代碼庫成功嘅關鍵係 Harness 而唔係模型本身；要先令代碼庫對 Claude 可讀，再由專人維護配置先推得開。
呢篇文章來自 Anthropic Applied AI 團隊，係「Claude Code at scale」系列嘅開篇。佢哋想解決一個核心問題：點樣喺上千萬行嘅 monorepo、跨越數十年嘅遺留系統、或者有成千人嘅大型組織入面有效使用 Claude Code。作者觀察到，好多團隊一開始淨係關注模型嘅 benchmark 分數，但實際部署時，決定 Claude Code 表現嘅往往係圍繞佢建立嘅 harness——即係 CLAUDE.md、hooks、skills 等擴展點嘅組合。
文章結論係：Claude Code 採用 agentic search，直接喺開發者本地操作檔案系統，唔使另外整 embedding 索引，所以永遠都係最新嘅代碼。但呢種方式高度依賴起手嘅上下文質量，即係代碼庫本身要對 Claude「可讀」。所以前期投入時間整理 CLAUDE.md 分層結構、設定 permissions.deny、部署 LSP 呢類基礎設施，比起淨係諗點樣提升模型能力更加重要。
另外，文章強調組織層面嘅投入：如果冇專人（或者叫做 DRI）去維護配置、將有效做法打包成 plugin 分發，就算有再好嘅技術設定，最終都會因為知識碎片化而令採用率見頂。所以成功部署嘅團隊通常會喺 DevEx 或者開發者生產力部門入面指派一個 agent manager，專門負責 Claude Code 生態。
- Claude Code 用 agentic search，唔使維護索引，永遠用最新代碼，但極度依賴起手上下文質量。
- Harness（包括 CLAUDE.md、hooks、skills、plugins、MCP、LSP、subagents）對表現嘅影響大過模型本身。
- CLAUDE.md 必須精簡分層：根文件只放指針同陷阱，子目錄入面先放局部約定。
- Skills 按需加載、按路徑限定作用域，避免將所有專長塞入 CLAUDE.md 變成噪音。
- 組織要指派 DRI 或 agent manager 負責配置維護、定期回顧，有效經驗要打包成 plugin 分發先唔會碎片化。
Claude Code at scale 系列博客
Anthropic 官方博客，詳細講解 Claude Code 喺大型代碼庫入面嘅最佳實踐同配置框架。
Harness 點先搭得靚：五層擴展點逐個拆
Harness 係圍繞 Claude Code 嘅生態系統，由五個擴展點組成：CLAUDE.md、hooks、skills、plugins 同 MCP servers，再加上 LSP 集成 同 subagents。搭建順序好重要，每一層都建立喺上一層之上。
Hooks 嘅最好用途唔係「阻止 Claude 做錯嘢」，而係持續改進。例如一個 stop hook 可以喺會話結束時反思發生咗咩，自動建議更新 CLAUDE.md；一個 start hook 可以動態加載適合當前任務嘅上下文。
Skills 透過漸進披露解決專長常駐問題，按任務需要先加載。例如安全審查 skill 只喺評估漏洞時加載，文檔處理 skill 只喺代碼變更需要更新文檔時加載。Skills 仲可以綁定到特定路徑，避免喺 monorepo 嘅其他地方誤觸發。
Plugins 係將 skills、hooks 同 MCP 配置打包成可安裝單元，解決好嘅設置只喺小圈子流傳嘅問題。新工程師安裝 plugin 後，即刻擁有同老員工一樣嘅能力。LSP 提供符號級精度，尤其喺 C/C++ 呢類語言入面，令 Claude 可以按函數調用跳轉，而唔係靠字符串 grep 撞彩。
- 1 CLAUDE.md：每次會話自動加載嘅上下文文件，必須精簡分層。
- 2 Hooks：喺關鍵節點運行嘅腳本，用嚟自動化一致行為同捕獲會話經驗。
- 3 Skills：按需加載嘅專門工作流，避免常駐所有專長。
- 4 Plugins：將有效配置打包分發，避免部落化。
- 5 LSP 集成：提供符號級導航，尤其係多語言代碼庫嘅高 ROI 投入。
- 6 MCP servers：連接內部工具同數據源，但要等基礎穩定先加。
- 7 Subagents：用獨立 Claude 實例分離探索同編輯，避免同一會話混雜噪音。
成功部署嘅三種重複模式
Anthropic 團隊觀察到，喺大型代碼庫成功部署 Claude Code 嘅組織，通常出現三種模式。第一種：令代碼庫喺規模下保持可導航。即係前期投入精力整好 CLAUDE.md 分層、喺子目錄初始化 Claude、按子目錄劃分 test 同 lint 命令、善用 .ignore 同 permissions.deny、必要時整份輕量級代碼庫地圖、同埋運行 LSP server。
第二種：隨模型演進主動維護 CLAUDE.md。Model 會進步，以前幫佢繞過弱點嘅規則可能反過來束縛新模型。例如一條「將每次重構拆成單檔案改動」嘅規則，新模型可能已經勝任跨檔案協調編輯。團隊應該每 3 到 6 個月做一次配置回顧，或者喺大版本模型發佈後立即觸發一次。
對於受監管行業，要及早建立治理：從受限範圍起步，例如一套已審批嘅 skills、必經嘅代碼評審流程、有限嘅初始訪問權限，然後隨信心建立再擴張。跨職能工作組（工程、信息安全、治理）一齊定義需求係最順暢嘅做法。
上手清單：將模式化成行動
將 Anthropic 嘅建議濃縮成一份起步順序，建議咁樣推進：先建立 CLAUDE.md「根 + 子目錄」骨架，根文件只放指針同陷阱；整好 .claude/settings.json 嘅 permissions.deny，排除生成產物同第三方代碼；喺子目錄啟動 Claude 而唔係倉庫根。
- 多語言或大型代碼庫盡早裝 LSP 插件。
- 從 stop hook 同 lint/format hook 起步，令設置同時自我改進同有確定性約束。
- 將領域專長抽成 Skills 並按路徑限定作用域，唔好塞入 CLAUDE.md。
- 當有效設置成型後打包成 Plugin 分發，避免部落化。
- MCP 留到最後，先等基礎穩定先接入內部工具。
- 複雜探索任務用 Subagent 隔離，主 agent 接收結論就得。
- 每 3 到 6 個月或模型大版本後做一次配置回顧，刪除過時嘅「補丁」。
- 指定一位 DRI，哪怕兼職都好過冇人負責。
最後，記住呢個原則：Harness 比模型本身更重要。與其淨係追模型 benchmark，不如花心機整好 CLAUDE.md、hooks、skills、plugins 呢啲基礎設施，呢啲先係 Claude Code 喺大型代碼庫入面發揮作用嘅真正關鍵。
Anthropic 最新博客，「Claude Code 喺大型代碼庫入面嘅工作方式：最佳實踐同起步指南」，作為 「Claude Code at scale」 系列嘅開篇，集中講企業級環境下 Claude Code 嘅落地模式。
https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start[1]
Claude Code 已經喺多種嚴苛環境投入生產：上千萬行嘅 monorepo、跨越幾十年嘅遺留系統、橫跨幾十個倉庫嘅分佈式架構，同埋擁有上千個開發者嘅大型組織。呢啲環境帶嚟嘅挑戰係小型代碼庫冇嘅——每個子目錄嘅構建命令都唔同，遺留代碼散落喺冇共同根嘅文件夾，團隊甚至成日用緊 C、C++、C#、Java、PHP 呢啲「AI 編碼工具唔係好擅長」嘅語言。
今日我哋一齊整理學習 Anthropic Applied AI 團隊喺大規模部署入面反覆觀察到嘅成功模式，一份可以作為起點嘅通用框架。
Claude Code 點樣喺大型代碼庫入面導航
Claude Code 嘅導航方式同一個人類工程師一樣：遍歷文件系統、讀取文件、用 grep 精確定位、沿着引用跨文件跳轉。佢完全喺開發者本地運行，唔需要構建、維護或上傳任何代碼庫索引。
呢個同上一代 AI 編碼工具嘅路線形成鮮明對比。後者普遍依賴 RAG：先將成個代碼庫做成 embedding，查詢嗰陣再檢索相關片段。呢條路線喺規模化嗰陣容易失敗——embedding 流水線追唔上活躍工程團隊嘅提交速度。等開發者發起查詢嗰陣，索引反映嘅可能係幾日、幾星期甚至幾小時前嘅代碼：返回嘅係兩星期前被重新命名嘅函數，或者上個 sprint 已經被刪除嘅模塊，而且完全冇過時提示。
Agentic search 規避咗呢種失敗模式。冇 embedding 流水線，冇需要隨住成千上萬次提交同步嘅中心化索引，每個開發者嘅實例都直接工作喺當下嘅代碼上。
代價係：呢種方式高度依賴起手嘅上下文質量。如果畀 Claude 喺十億行代碼入面揾一個含糊嘅模式，佢會喺開始工作前就用盡上下文窗口。Claude 導航嘅好壞，取決於代碼庫本身被組織得有幾「易讀」——而呢個正正係 CLAUDE.md 同 skills 呢啲機制嘅用武之地。前期喺代碼庫可讀性上做投入嘅團隊，會得到明顯更好嘅結果。
Harness 比模型本身更加重要
關於 Claude Code，最常見嘅誤解係將佢嘅能力等同於背後模型嘅能力。團隊傾向於睇住 benchmark 同測試任務嘅表現。但係喺實際部署入面，圍繞模型構建嘅生態系統——即係 harness——對 Claude Code 表現嘅影響，往往超過模型本身。
Harness 由五個擴展點構成：CLAUDE.md 文件、hooks、skills、plugins 同 MCP servers。佢哋嘅搭建順序好重要，每一層都建立喺前一層之上。再加上兩項輔助能力——LSP 集成同 subagents——共同構成完整嘅設置。
CLAUDE.md：第一塊基石
CLAUDE.md 係 Claude 喺每次會話開始嗰陣自動讀取嘅上下文文件。根目錄嘅文件提供全局視角，子目錄嘅文件提供局部約定。佢畀咗 Claude 做任何嘢都需要嘅代碼庫基礎知識。
正因為佢喺每次會話都會加載，一定要只放真正具有普遍適用性嘅內容，否則就會變成性能負擔。
Hooks：等設置自我改進
多數團隊將 hooks 當作「阻止 Claude 做錯嘢」嘅腳本，但佢哋更加有價值嘅用法係持續改進：
- 一個 stop hook 可以喺會話結束嗰陣反思啱先發生咗啲乜，趁住上下文仲新鮮，提出對 CLAUDE.md 嘅更新建議
- 一個 start hook 可以根據當前任務動態加載團隊特定嘅上下文，等每個開發者唔使手動配置就可以拎到適合自己模塊嘅設置
- 對於 lint 同 format 呢種確定性檢查，hook 強制執行比起畀 Claude「記住」一條指令要穩定得多
Skills：等專長按需出現
大型代碼庫嘅任務類型繁多，冇可能畀所有專長都常駐喺每個會話入面。Skills 通過 漸進披露 解決咗呢個問題：將專門嘅工作流同領域知識抽離出嚟，淨係喺任務真係需要嗰陣加載。
例如，安全審查 skill 淨係喺 Claude 評估漏洞嗰陣加載；文檔處理 skill 淨係喺代碼變更需要更新文檔嗰陣加載。
Skills 仲可以綁定到特定路徑，淨係喺代碼庫嘅相關部分激活。負責支付服務嘅團隊可以將佢哋嘅部署 skill 綁到對應目錄，咁樣當其他人在 monorepo 第度工作嗰陣，呢個 skill 就唔會被誤觸發。
Plugins：等有效嘅設置唔再「部落化」
大型代碼庫嘅一個典型問題，係好嘅設置淨係喺小圈子入面流傳。Plugin 將 skills、hooks 同 MCP 配置打包成一個可安裝單元——當一個新工程師喺第一日安裝呢個 plugin 嗰陣，佢就即刻擁有咗同老員工一樣嘅上下文同能力。Plugin 嘅更新仲可以通過 managed marketplace 喺成個組織入面分發。
我哋合作過嘅一間大型零售企業，曾經構建咗一個將 Claude 接入內部分析平台嘅 skill，等業務分析師唔使離開工作流就可以拉取業績數據。佢哋喺向業務部門大規模推開之前，先將呢個 skill 打包成 plugin 分發。
LSP：將 IDE 嘅導航能力交畀 Claude
大型代碼庫嘅 IDE 通常已經喺度行 LSP，背後驅動住「跳轉到定義」同「揾曬所有引用」。將呢層能力暴露畀 Claude，等於畀咗佢符號級精度：可以沿函數調用跳到定義、跨文件追蹤引用、區分唔同語言入面同名嘅函數。
冇 LSP 嗰陣，Claude 淨係可以基於文本做模式匹配，容易揀錯符號。一間企業軟件公司喺全公司推廣 Claude Code 之前，專登先部署咗 LSP 集成，目標就係等 C 同 C++ 喺大規模代碼下嘅導航變得可靠。對多語言代碼庫嚟講，呢個係 ROI 最高嘅投入之一。
MCP servers：連接外部世界
MCP servers 係 Claude 接入內部工具、數據源同 API 嘅標準方式。最成熟嘅團隊會通過 MCP 將「結構化搜索」暴露成一個 Claude 可以直接調用嘅工具，其他團隊就用佢接入內部文檔、工單系統或者分析平台。
Subagents：將探索同編輯分開
subagent 係一個獨立嘅 Claude 實例，擁有自己嘅上下文窗口。佢接受一個任務、完成工作、淨係將最終結果返回畀父 agent。當 harness 就位之後，常見做法係先派一個唯讀 subagent 去勘察某個子系統、將發現寫入文件，然後等主 agent 帶住完整圖景再去編輯。
一張速查表
| 組件 | 是什麼 | 幾時加載 | 最適合用途 | 常見誤區 |
|---|---|---|---|---|
| CLAUDE.md | 自動讀取嘅上下文文件 | 每次會話 | 項目特定約定、代碼庫知識 | 用佢承載本應放進 skill 嘅可複用專長 |
| Hooks | 喺關鍵節點運行嘅腳本 | 事件觸發 | 自動化一致行為、捕獲會話經驗 | 用 prompt 做本應自動化嘅事 |
| Skills | 針對特定任務類型嘅打包指令 | 按需 | 跨會話、跨項目複用嘅專長 | 一嘢塞曬入 CLAUDE.md |
| Plugins | skills/hooks/MCP 嘅打包 | 配置後常駐 | 將可用嘅設置分發到全組織 | 將好嘅設置停留喺小圈子 |
| LSP | 語言特定服務器提供嘅實時代碼智能 | 配置後常駐 | 符號級導航、類型語言入面嘅錯誤檢測 | 誤以為佢會自動啓用 |
| MCP servers | 接入外部工具同數據嘅連接 | 配置後常駐 | 等 Claude 觸達到原本掂唔到嘅內部工具 | 喺基礎未打好之前就疊 MCP |
| Subagents | 用於特定任務嘅獨立 Claude 實例 | 調用時 | 拆分探索同編輯、並行作業 | 喺同一會話入面混合探索同編輯 |
嚟自成功部署嘅三種配置模式
點樣為大型代碼庫配置 Claude Code，好大程度上取決於代碼庫自身嘅結構。但喺我哋觀察到嘅成功部署入面，有三種模式反覆出現。
模式一：等代碼庫喺規模下保持可導航
Claude 喺大型代碼庫入面嘅能力，被佢「揾到正確上下文嘅能力」所限定。塞太多上下文會拖累性能，塞太少就等佢喺黑暗中摸索。最有效嘅部署都會前期投入精力，等代碼庫對 Claude 嚟講係「清晰可讀」嘅。常見做法包括：
- 保持 CLAUDE.md 精簡同分層。Claude 會喺穿越代碼庫嗰陣逐級加載呢啲文件：根文件畀全局視角，子目錄文件畀局部約定。根文件淨係應該包含「指針」同「關鍵陷阱」，其餘內容都會淪為噪音。
- 喺子目錄入面初始化，而唔係喺倉庫根。Claude 喺被限定到任務真正相關嘅嗰部分代碼嗰陣表現最好。喺 monorepo 入面呢個睇起嚟反直覺，因為工具鏈通常假設根訪問，但 Claude 會自動向上走目錄樹並加載沿途每一個 CLAUDE.md，所以根級上下文唔會丟失。
- 按子目錄劃分 test 同 lint 命令。Claude 改咗一個服務就成個套件走一次，會導致超時並將上下文浪費喺無關輸出上。子目錄級嘅 CLAUDE.md 應該指明淨係屬於呢部分代碼嘅命令。呢種做法喺面向服務嘅代碼庫入面效果好好；喺跨目錄強依賴嘅編譯型語言 monorepo 入面就比較難落地，可能需要項目特定嘅構建配置。
- 善用
.ignore文件與permissions.deny規則，將生成產物、構建工件同第三方代碼排除出去。將規則提交到.claude/settings.json，意味住所有人都共享同樣嘅降噪效果，唔使自己配置。如果某啲開發者本身就在做代碼生成相關嘅工作，佢哋可以喺本地覆蓋項目級排除規則，唔影響其他人。 - 當目錄結構本身冇辦法說明問題嗰陣，建立一份代碼庫地圖。如果代碼冇按常規方式組織，可以喺倉庫根放一份輕量級 markdown，列出每個頂級文件夾同埋佢嘅一行說明，畀 Claude 一份打開文件之前可以睇一眼嘅「目錄」。對於頂級文件夾有上百個嘅代碼庫，建議分層處理：根文件淨係描述最高層結構，子目錄嘅 CLAUDE.md 按需要提供下一層細節。對更簡單嘅情況，直接 @-提及具體文件或目錄都可以起到同樣作用。
- 運行 LSP server，等 Claude 按符號而唔係字符串搜索。喺大型代碼庫入面 grep 一個常見函數名會返回上千條結果，Claude 會消耗大量上下文逐一甄別。LSP 淨係返回指向同一符號嘅引用，過濾工作發生喺 Claude 讀取任何文件之前。
需要說明嘅係，就算採用上述分層方法，仍然有邊緣情況會失效——例如擁有幾十萬文件夾、上百萬文件嘅代碼庫，或者運行喺非 git 版本控制系統上嘅遺留系統。呢啲挑戰會留到呢個系列後續文章入面討論。
模式二：隨模型演進，主動維護 CLAUDE.md
模型喺進化，針對當前模型寫嘅指令，可能反過來束縛未來嘅模型。曾經為幫助 Claude 繞過某個弱點而寫嘅 CLAUDE.md 規則，喺下一代模型發佈之後可能變得多餘，甚至成為約束。
舉個例子：一條要求 Claude「將每次重構拆成單文件改動」嘅規則，可能幫過舊模型保持專注，但會阻止新模型完成佢本來已經可以勝任嘅跨文件協調編輯。
同樣，嗰啲為咗彌補特定模型侷限——無論係推理上嘅定係 Claude Code 工具鏈上嘅——而寫嘅 skills 同 hooks，一旦底層侷限消失，就會變成純粹嘅開銷。例如一個曾經攔截文件寫入、強制執行 p4 edit 嘅 hook，喺 Claude Code 加入原生 Perforce 支持之後就變成咗冗餘。
團隊應該每 3 到 6 個月做一次有意義嘅配置回顧；如果喺某次大版本模型發佈之後感覺性能停滯，都值得即刻觸發一次。
模式三：為 Claude Code 嘅管理同推廣明確歸屬人
技術配置本身唔會驅動採用，做得啱嘅組織喺組織層都做咗投入。
推得最快嘅部署，都喺大規模開放訪問之前先完成咗基礎設施投入。有時只係一個小團隊、甚至一個人，提早將工具連接好，等開發者第一次接觸 Claude 嗰陣佢已經契合佢哋嘅工作流。喺一間公司，幾位工程師喺推廣前就建立好咗一整套 plugin 同 MCP；喺另一間公司，成支團隊專門負責管理 AI 編碼工具嘅基礎設施。兩種情況下，開發者嘅首次體驗都係「順手」而唔係「挫敗」，採用率自然就傳播開嚟。
承擔呢件事嘅團隊，通常隸屬於 DevEx 或開發者生產力部門——即係平時負責工程師入職同工具鏈建設嘅嗰個職能。一啲組織正在湧現一個新角色——agent manager：一個混合 PM 同工程師特徵嘅崗位，專門管理 Claude Code 生態。對冇專門團隊嘅組織嚟講，最低可行版本係一位 DRI（直接負責人）：一個對 Claude Code 配置擁有所有權、有權決定設置、權限策略、插件市場同 CLAUDE.md 規範、同埋負責等佢哋持續保持新鮮嘅人。
自下而上嘅採用可以製造熱情，但若果冇人沉澱有效經驗，就會陷入碎片化。需要有人或團隊牽頭整理同推廣 Claude Code 嘅統一規範（例如一個標準嘅 CLAUDE.md 層級，或者一套精選嘅 skills 同 plugins）。冇呢一步，知識會停留喺部落化階段，採用率會觸頂。
喺大型組織——尤其是受監管行業——治理問題會好早出現：邊個嚟管控可用嘅 skill 同 plugin？點樣避免幾千個工程師獨立重造同一個轆？點樣保證 AI 生成代碼經過同人類代碼一樣嘅評審流程？建議從受限範圍起步：一套已審批嘅 skills、必經嘅代碼評審流程、有限嘅初始訪問權限，然後隨住信心建立再擴張。
部署最順暢嘅組織，都好早就建立咗跨職能工作組——將工程、信息安全和治理代表聚埋一齊，共同定義需求，共建推廣路線圖。
將呢啲模式應用到你嘅組織
Claude Code 係圍繞傳統軟件工程環境設計嘅：工程師係代碼庫嘅主要貢獻者、倉庫使用 git、代碼遵循標準目錄結構。多數大型代碼庫都符合呢個前提，但一啲非典型場景需要額外嘅配置工作——例如包含大量二進制資產嘅遊戲引擎、使用非常規版本控制嘅環境，或者非工程人員都參與貢獻嘅代碼庫。
我哋將 Anthropic 博客濃縮成一份上手清單，建議咁樣推進：
- 先建立 CLAUDE.md 嘅「根 + 子目錄」骨架，根文件淨係放指針同陷阱
- 加上
.claude/settings.json的permissions.deny，排除生成產物、構建工件、第三方代碼 - 喺子目錄入面啟動 Claude，而唔係倉庫根
- 多語言或大型代碼庫盡早裝 LSP 插件
- 從 stop hook 同 lint/format hook 起步，等設置同時具備自我改進同確定性約束
- 將領域專長抽成 Skills 並按路徑限定作用域，而唔係塞入 CLAUDE.md
- 當有效設置成型之後打包成 Plugin 分發，避免部落化
- MCP 留到最後，淨係喺基礎穩定之後接入內部工具同數據源
- 複雜嘅探索任務交畀 Subagent 隔離，等主 agent 接收結論而唔係一肚雜音
- 每 3 到 6 個月、或者喺模型大版本之後做一次配置回顧，刪除已被新模型超越嘅「補丁」
- 指定一位 DRI，就算只係兼職，都比「冇人負責」好得多
Claude Code 嘅導航路徑係 agentic 而唔係索引式嘅，呢個意味住佢將代碼庫可讀性嘅責任交返畀使用佢嘅團隊。模型會繼續進化，而真正決定佢喺你嘅代碼庫入面可以行幾遠嘅，係 harness 嘅搭建質量同組織層嘅持續投入。
推薦資源
/goal 理論同實踐全解 - 點樣用好 Codex 同 Claude Code 連續行幾個鐘直到完成目標嘅自主任務模式？
Agent Harness Engineering 三重前沿實踐：Codex、Claude Code、Cursor 點樣令人類從編碼者升格為架構師
Anthropic 最新博客，"Claude Code 在大型代碼庫中的工作方式：最佳實踐與起步指南"，作為 "Claude Code at scale" 系列的開篇，聚焦企業級環境下 Claude Code 的落地模式。
https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start[1]
Claude Code 已經在多種嚴苛環境中投入生產：上千萬行的 monorepo、跨越數十年的遺留系統、橫跨數十個倉庫的分佈式架構，以及擁有上千名開發者的大型組織。這些環境帶來的挑戰是小型代碼庫所沒有的——每個子目錄的構建命令都不一樣，遺留代碼散落在沒有共同根的文件夾中，團隊甚至常常在使用 C、C++、C#、Java、PHP 等"AI 編碼工具不太擅長"的語言。
今天咱們一起整理學習 Anthropic Applied AI 團隊在大規模部署中反覆觀察到的成功模式，一份可以作為起點的通用框架。
Claude Code 如何在大型代碼庫中導航
Claude Code 的導航方式與一名人類工程師相同：遍歷文件系統、讀取文件、用 grep 精確定位、沿着引用跨文件跳轉。它完全在開發者本地運行，不需要構建、維護或上傳任何代碼庫索引。
這與上一代 AI 編碼工具的路線形成鮮明對比。後者普遍依賴 RAG：先把整個代碼庫做成 embedding，查詢時再檢索相關片段。這一路線在規模化時容易失敗——embedding 流水線追不上活躍工程團隊的提交速度。等開發者發起查詢時，索引反映的可能是幾天、幾周甚至幾小時前的代碼：返回的是兩週前被重命名的函數，或者上個 sprint 已被刪除的模塊，而且毫無過時提示。
Agentic search 規避了這種失敗模式。沒有 embedding 流水線，沒有需要隨成千上萬次提交同步的中心化索引，每個開發者的實例都直接工作在當下的代碼上。
代價是：這種方式高度依賴起手的上下文質量。如果讓 Claude 在十億行代碼中尋找一個含糊的模式，它會在開始工作前就耗盡上下文窗口。Claude 導航的好壞，取決於代碼庫本身被組織得有多"易讀"——而這正是 CLAUDE.md 和 skills 等機制的用武之地。前期在代碼庫可讀性上做投入的團隊，會得到明顯更好的結果。
Harness 比模型本身更重要
關於 Claude Code，最常見的誤解是把它的能力等同於背後模型的能力。團隊傾向於盯着 benchmark 和測試任務的表現。但在實際部署中，圍繞模型構建的生態系統——也就是 harness——對 Claude Code 表現的影響，往往超過模型本身。
Harness 由五個擴展點構成：CLAUDE.md 文件、hooks、skills、plugins 和 MCP servers。它們的搭建順序非常重要，每一層都建立在前一層之上。再加上兩項輔助能力——LSP 集成和 subagents——共同構成完整的設置。
CLAUDE.md：第一塊基石
CLAUDE.md 是 Claude 在每次會話開始時自動讀取的上下文文件。根目錄的文件提供全局視角，子目錄的文件提供局部約定。它給了 Claude 做任何事都需要的代碼庫基礎知識。
正因為它在每次會話都會加載，必須只放真正具有普遍適用性的內容，否則就會變成性能負擔。
Hooks：讓設置自我改進
多數團隊把 hooks 當作"阻止 Claude 做錯事"的腳本，但它們更有價值的用法是持續改進：
- 一個 stop hook 可以在會話結束時反思剛發生了什麼，趁着上下文還新鮮，提出對 CLAUDE.md 的更新建議
- 一個 start hook 可以根據當前任務動態加載團隊特定的上下文，讓每個開發者無需手動配置就能拿到適合自己模塊的設置
- 對於 lint 和 format 這種確定性檢查，hook 強制執行比讓 Claude "記住"一條指令要穩定得多
Skills：讓專長按需出現
大型代碼庫的任務類型繁多，不可能讓所有專長都常駐在每個會話裏。Skills 通過 漸進披露 解決了這個問題：把專門的工作流和領域知識抽離出來，只在任務真正需要時加載。
例如，安全審查 skill 只在 Claude 評估漏洞時加載；文檔處理 skill 只在代碼變更需要更新文檔時加載。
Skills 還可以綁定到特定路徑，只在代碼庫的相關部分激活。負責支付服務的團隊可以把他們的部署 skill 綁到對應目錄，這樣當其他人在 monorepo 別處工作時，這個 skill 就不會被誤觸發。
Plugins：讓有效的設置不再"部落化"
大型代碼庫的一個典型問題，是好的設置只在小圈子裏流傳。Plugin 把 skills、hooks 和 MCP 配置打包成一個可安裝單元——當一名新工程師在第一天安裝這個 plugin 時，他就立即擁有了和老員工一樣的上下文與能力。Plugin 的更新還可以通過 managed marketplace 在整個組織內分發。
我們合作過的一家大型零售企業，曾構建了一個把 Claude 接入內部分析平台的 skill，讓業務分析師不必離開工作流就能拉取業績數據。他們在向業務部門大規模推開前，先把這個 skill 打包成 plugin 分發。
LSP：把 IDE 的導航能力交給 Claude
大型代碼庫的 IDE 通常已經在跑 LSP，背後驅動着"跳轉到定義"和"查找所有引用"。把這層能力暴露給 Claude，等於給了它符號級精度：可以沿函數調用跳到定義、跨文件追蹤引用、區分不同語言中同名的函數。
沒有 LSP 時，Claude 只能基於文本做模式匹配，容易選錯符號。一家企業軟件公司在全公司推廣 Claude Code 之前，專門先部署了 LSP 集成，目標就是讓 C 和 C++ 在大規模代碼下的導航變得可靠。對多語言代碼庫而言，這是 ROI 最高的投入之一。
MCP servers：連接外部世界
MCP servers 是 Claude 接入內部工具、數據源和 API 的標準方式。最成熟的團隊會通過 MCP 把"結構化搜索"暴露成一個 Claude 可以直接調用的工具，其他團隊則用它接入內部文檔、工單系統或分析平台。
Subagents：把探索和編輯分開
subagent 是一個獨立的 Claude 實例，擁有自己的上下文窗口。它接受一個任務、完成工作、只把最終結果返回給父 agent。當 harness 就位後，常見做法是先派一個只讀 subagent 去勘察某個子系統、把發現寫入文件，然後讓主 agent 帶着完整圖景再去編輯。
一張速查表
| 組件 | 是什麼 | 何時加載 | 最適合用途 | 常見誤區 |
|---|---|---|---|---|
| CLAUDE.md | 自動讀取的上下文文件 | 每次會話 | 項目特定約定、代碼庫知識 | 用它承載本應放進 skill 的可複用專長 |
| Hooks | 在關鍵節點運行的腳本 | 事件觸發 | 自動化一致行為、捕獲會話經驗 | 用 prompt 做本應自動化的事 |
| Skills | 針對特定任務類型的打包指令 | 按需 | 跨會話、跨項目複用的專長 | 一股腦塞進 CLAUDE.md |
| Plugins | skills/hooks/MCP 的打包 | 配置後常駐 | 把可用的設置分發到全組織 | 讓好的設置停留在小圈子 |
| LSP | 語言特定服務器提供的實時代碼智能 | 配置後常駐 | 符號級導航、類型語言中的錯誤檢測 | 誤以為它會自動啓用 |
| MCP servers | 接入外部工具與數據的連接 | 配置後常駐 | 讓 Claude 觸達原本碰不到的內部工具 | 在基礎未夯實前就堆 MCP |
| Subagents | 用於特定任務的獨立 Claude 實例 | 調用時 | 拆分探索與編輯、並行作業 | 在同一會話裏混合探索和編輯 |
來自成功部署的三種配置模式
如何為大型代碼庫配置 Claude Code，很大程度上取決於代碼庫自身的結構。但在我們觀察到的成功部署中，有三種模式反覆出現。
模式一：讓代碼庫在規模下保持可導航
Claude 在大型代碼庫中的能力，被它"找到正確上下文的能力"所限定。塞太多上下文會拖累性能，塞太少則讓它在黑暗中摸索。最有效的部署都會前期投入精力，讓代碼庫對 Claude 來說是"清晰可讀"的。常見做法包括：
- 保持 CLAUDE.md 精簡且分層。Claude 會在穿越代碼庫時加性地加載這些文件：根文件給全局視角，子目錄文件給局部約定。根文件只應包含"指針"和"關鍵陷阱"，其餘內容都會淪為噪音。
- 在子目錄裏初始化，而不是在倉庫根。Claude 在被限定到任務真正相關的那部分代碼時表現最好。在 monorepo 裏這看起來反直覺，因為工具鏈通常假設根訪問，但 Claude 會自動向上走目錄樹並加載沿途每一個 CLAUDE.md，所以根級上下文不會丟。
- 按子目錄劃分 test 和 lint 命令。Claude 改了一個服務就跑全量套件，會導致超時並把上下文浪費在無關輸出上。子目錄級的 CLAUDE.md 應當指明只屬於該部分代碼的命令。這種做法在面向服務的代碼庫裏效果很好；在跨目錄強依賴的編譯型語言 monorepo 裏則較難落地，可能需要項目特定的構建配置。
- 善用
.ignore文件與permissions.deny規則，把生成產物、構建工件和第三方代碼排除出去。把規則提交到.claude/settings.json，意味着所有人共享同樣的降噪效果，無需各自配置。如果某些開發者本身就在做代碼生成相關的工作，他們可以在本地覆蓋項目級排除規則，不影響其他人。 - 當目錄結構本身無法說明問題時，構建一份代碼庫地圖。如果代碼沒有按常規方式組織，可以在倉庫根放一份輕量級 markdown，列出每個頂級文件夾及其一行說明，給 Claude 一份打開文件之前可掃一眼的"目錄"。對於頂級文件夾有上百個的代碼庫，建議分層處理：根文件只描述最高層結構，子目錄的 CLAUDE.md 按需提供下一層細節。對更簡單的情況，直接 @-提及具體文件或目錄也能起到同樣作用。
- 運行 LSP server，讓 Claude 按符號而非字符串搜索。在大型代碼庫裏 grep 一個常見函數名會返回上千條結果，Claude 會消耗大量上下文逐一甄別。LSP 只返回指向同一符號的引用，過濾工作發生在 Claude 讀取任何文件之前。
需要說明的是，即便採用上述分層方法，仍有邊緣情況會失效——例如擁有幾十萬文件夾、上百萬文件的代碼庫，或運行在非 git 版本控制系統上的遺留系統。這些挑戰將留到本系列後續文章中討論。
模式二：隨模型演進，主動維護 CLAUDE.md
模型在進化，針對當前模型寫的指令，可能反過來束縛未來的模型。曾經為幫助 Claude 繞過某個弱點而寫的 CLAUDE.md 規則，在下一代模型發佈後可能變得多餘，甚至成為約束。
舉個例子：一條要求 Claude "把每次重構拆成單文件改動"的規則，可能幫過舊模型保持專注，卻會阻止新模型完成它本來已經能勝任的跨文件協調編輯。
同樣，那些為了彌補特定模型侷限——無論是推理上的還是 Claude Code 工具鏈上的——而寫的 skills 和 hooks，一旦底層侷限消失，就會變成純粹的開銷。例如一個曾經攔截文件寫入、強制執行 p4 edit 的 hook，在 Claude Code 加入原生 Perforce 支持後就成了冗餘。
團隊應當每 3 到 6 個月做一次有意義的配置回顧；如果在某次大版本模型發佈後感覺性能停滯，也值得立即觸發一次。
模式三：為 Claude Code 的管理與推廣明確歸屬人
技術配置本身不會驅動採用，做對的組織在組織層也做了投入。
推得最快的部署，都在大規模開放訪問之前先完成了基礎設施投入。有時只是一個小團隊、甚至一個人，提前把工具連結好，讓開發者第一次接觸 Claude 時它就已經契合他們的工作流。在一家公司，幾位工程師在推廣前就構建好了一整套 plugin 和 MCP；在另一家公司，一整支團隊專門負責管理 AI 編碼工具的基礎設施。兩種情況下，開發者的首次體驗都是"順手"而非"挫敗"，採用率自然就傳播開來。
承擔這件事的團隊，通常隸屬於 DevEx 或開發者生產力部門——也就是平時負責工程師入職和工具鏈建設的那個職能。一些組織正在湧現一個新角色——agent manager：一個混合 PM 與工程師特徵的崗位，專門管理 Claude Code 生態。對沒有專門團隊的組織而言，最低可行版本是一位 DRI（直接負責人）：一個對 Claude Code 配置擁有所有權、有權決定設置、權限策略、插件市場和 CLAUDE.md 規範、並負責讓它們持續保鮮的人。
自下而上的採用能製造熱情，但若沒有人沉澱有效經驗，就會陷入碎片化。需要有人或團隊牽頭整理並推廣 Claude Code 的統一規範（例如一個標準的 CLAUDE.md 層級，或一套精選的 skills 和 plugins）。沒有這一步，知識會停留在部落化階段，採用率會觸頂。
在大型組織——尤其是受監管行業——治理問題會很早出現：誰來管控可用的 skill 和 plugin？怎樣避免數千工程師獨立重造同一個輪子？怎樣保證 AI 生成代碼經過和人類代碼同樣的評審流程？建議從受限範圍起步：一套已審批的 skills、必經的代碼評審流程、有限的初始訪問權限，然後隨信心建立再擴張。
部署最順暢的組織，都很早就建立了跨職能工作組——把工程、信息安全和治理代表聚在一起，共同定義需求，共建推廣路線圖。
把這些模式應用到你的組織
Claude Code 是圍繞傳統軟件工程環境設計的：工程師是代碼庫的主要貢獻者、倉庫使用 git、代碼遵循標準目錄結構。多數大型代碼庫都符合這個前提，但一些非典型場景需要額外的配置工作——例如包含大量二進制資產的遊戲引擎、使用非常規版本控制的環境，或非工程人員也參與貢獻的代碼庫。
咱們把 Anthropic 博客濃縮成一份上手清單，建議這樣推進：
- 先建 CLAUDE.md 的"根 + 子目錄"骨架，根文件只放指針與陷阱
- 加上
.claude/settings.json的permissions.deny，排除生成產物、構建工件、第三方代碼 - 在子目錄裏啓動 Claude，而不是倉庫根
- 多語言或大型代碼庫儘早裝 LSP 插件
- 從 stop hook 和 lint/format hook 起步，讓設置同時具備自我改進與確定性約束
- 把領域專長抽成 Skills 並按路徑限定作用域，而不是塞進 CLAUDE.md
- 當有效設置成型後打包成 Plugin 分發，避免部落化
- MCP 留到最後，只在基礎穩定後接入內部工具與數據源
- 複雜的探索任務交給 Subagent 隔離，讓主 agent 接收結論而非一肚子雜音
- 每 3 到 6 個月、或在模型大版本之後做一次配置回顧，刪除已被新模型超越的"補丁"
- 指定一位 DRI，哪怕只是兼職，也比"無人負責"強得多
Claude Code 的導航路徑是 agentic 而非索引式的，這意味着它將代碼庫可讀性的責任交回給了使用它的團隊。模型會繼續進化，而真正決定它在你的代碼庫裏能走多遠的，是 harness 的搭建質量與組織層的持續投入。
推薦資源
/goal 理論和實踐全解 - 讓 Codex 和 Claude Code 連續跑數小時直到完成目標的自主任務模式怎麼用好？
Agent Harness Engineering 三重前沿實踐：Codex、Claude Code、Cursor 如何讓人類從編碼者升為架構師