大多數人把 CLAUDE.md 當成提示詞檔案。

這就是錯誤所在。

如果你希望 Claude Code 感覺像是住在你 repo 裡的資深工程師，而不是一個湊巧能存取檔案的聊天機器人，你的專案就需要結構。Claude 隨時需要四件事：為什麼（系統做什麼）、地圖（東西在哪裡）、規則（什麼被允許）、以及工作流程（工作如何完成）。

以下是讓這一切運作的五個層次。

1. CLAUDE.md — Repo 記憶（保持簡短）

這是北極星檔案。它是 Claude 進入你專案時第一個讀取的東西，並為隨後的一切定調。

但大多數團隊就是在這裡出錯：他們把 CLAUDE.md 變成知識傾倒場。架構文件、程式碼規範、API 參考、部署流程——全部塞進一個檔案裡。

結果？模型開始遺漏重要脈絡，因為雜訊太多。

讓 CLAUDE.md 專注於三件事：

  • 目的 — 這個系統為何存在？
  • Repo 地圖 — 什麼東西放在哪裡？
  • 規則與指令 — 什麼被允許、什麼不被允許，以及工作如何完成？

就這樣。其他一切都屬於下面其中一個層次。

2. Skills — 可重複使用的專家模式

別再每個工作階段都重寫指示。

Claude Code skills（.claude/skills/ 或 ~/.agents/skills/）讓你將常見工作流程打包成可重複使用的模組，Claude 會按需載入。把它們想像成專家模式：

  • 程式碼審查檢查表
  • 重構劇本
  • 發布流程
  • 除錯流程

結果就是跨工作階段與團隊成員的一致性。當你的 skills 結構良好時，Claude 不只是產生程式碼——它會遵循你團隊的實際流程。

如果你正在使用 OpenClaw 或類似的代理框架，skills 會變得更加強大。它們可以將腳本、參考文件和資產打包成可攜式套件，讓任何代理都能直接取用。

想進一步了解 skill 建立工具如何演進，請參閱我們近期關於 Anthropic 的 skill creator 與 Google 的 Workspace CLI 的文章。

3. Hooks — 不會遺忘的護欄

模型會遺忘。Hooks 不會。

Claude Code hooks 是會自動觸發的確定性動作——在 Claude 執行某些操作之前或之後。把它們用在必須每次發生的事情上：

  • 在檔案編輯後執行格式化工具
  • 在核心模組變更時執行測試
  • 封鎖不安全的目錄（auth、billing、migrations）

這個區別很重要：提示詞是建議。Hooks 是保證。當你在提示詞中告訴 Claude「在編輯 src/auth/ 後永遠要執行測試」，它可能在第三次編輯時就忘了。當你把它接成 hook，就是自動的。

4. Docs — 漸進式脈絡

別把 Claude 可能需要的所有東西都塞進提示詞。相反地，給 Claude 一張地圖，指引真相所在：

  • 架構概觀 — 系統設計、資料流程、基礎架構
  • ADRs（Architecture Decision Records）— 你為何做出這些選擇
  • 營運 runbook — 如何部署、除錯與復原

Claude 擅長按需讀取檔案。它不需要預先掌握每個細節——它需要知道去哪裡找。一個組織良好的 docs/ 目錄意味著 Claude 可以在相關時機精準地提取脈絡。

5. 針對高風險模組的本機 CLAUDE.md

這是大多數團隊完全錯過的層次。

在你程式碼庫的尖銳邊緣附近放置小型、專注的 CLAUDE.md 檔案：

src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md

這些檔案包含模組特定的陷阱、限制與警告。當 Claude 在 src/auth/ 中工作時，它會自動看到認證專屬的指引——權杖輪替的怪異之處、工作階段處理的邊界情況、「未更新 migration 前絕不修改此函式」的警告。

這就是如何在不让根 CLAUDE.md 膨脹的情況下獲得外科手術般精準度的方法。

結構優於提示

提示是暫時的。結構是永久的。

當你的 repo 以這種方式組織時，Claude 不再表現得像聊天機器人，而是開始像專案原生工程師般行動。它了解脈絡、遵循流程、尊重護欄，並找到正確的文件——因為專案本身教會了它如何工作。

AI 程式碼 CLI 的版圖快速演進。Claude Code、Codex CLI、Gemini CLI——它們都在推出代理功能。但獲得真正價值的團隊，不是擁有最佳提示詞的團隊。而是擁有最佳結構 repo 的團隊。

Kevin Kaminski 是 Microsoft MVP，同時為 Big Hat Group 的 Principal，在此協助企業團隊部署 AI 代理、Windows 365 與現代化管理解決方案。如需協助規劃你的 AI 程式碼工作流程，請與我們聯絡。