在 monorepo 或大型程式碼庫中設定 Claude Code

​

本指南涵蓋的內容

​

本頁面的設定

​

範例 monorepo

monorepo/
  CLAUDE.md                     # 根指令
  packages/
    api/
      CLAUDE.md                 # API 特定指令
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # 前端特定指令
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # 共享庫指令
      src/

​

選擇在何處啟動 Claude

​

按目錄分層 CLAUDE.md 檔案

• 根 CLAUDE.md：適用於任何地方的指令，例如編碼標準和提交約定
• 按子目錄 CLAUDE.md：特定於該區域堆疊的約定。在 monorepo 中，這是每個套件一個。在大型單樹中，它是每個子系統一個，例如 src/db/ 或 src/api/

從套件目錄而不是 monorepo 根目錄執行套件指令碼。
提交主題前綴為套件名稱，例如 `api: add rate limiting`。
永遠不要編輯 packages/*/generated/ 下的檔案。改為在套件中執行 `npm run codegen`。

執行任何操作之前，將 `.env.example` 複製到 `.env`。沒有它，測試和開發伺服器會失敗。
使用 Knex 查詢建構器編寫資料庫查詢。永遠不要在路由處理程式中放入原始 SQL 字串。
遷移合併後永遠不要編輯它。改為添加新的遷移。

• 在拉取請求中審查：將 CLAUDE.md 編輯視為任何其他文件變更，以便約定跟蹤程式碼
• 在主要模型發佈後重新訪問：適用於舊模型限制的指令在較新模型自行處理該情況後可能會變成開銷。例如，強制單檔案重構的規則在限制消除後可以刪除
• 添加一個 Stop hook 來提議更新：Stop hook 在 Claude 完成回應時接收工作階段記錄的路徑，因此指令碼可以審查工作階段並在暴露的差距仍然新鮮時提議 CLAUDE.md 更新

​

在按目錄 CLAUDE.md 和路徑範圍規則之間選擇

​

排除無關的 CLAUDE.md 檔案

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

• "**/packages/*/CLAUDE.md"：排除每個套件的 CLAUDE.md，同時保留根目錄
• "**/packages/legacy-*/**"：排除每個名稱與 glob 匹配的套件，包括規則
• "/home/user/monorepo/legacy/CLAUDE.md"：按絕對路徑排除一個特定檔案

​

減少 Claude 讀取的內容

​

阻止讀取生成的和供應商程式碼

• 在儲存庫中工作的每個人：將規則提交到 .claude/settings.json，位於儲存庫根目錄（如果您從那裡啟動 Claude），或位於每個套件的 .claude/（如果您從子目錄啟動）。與本頁面上的其他專案設定一樣，該檔案不會從父目錄繼承。
• 僅您自己：在儲存庫根目錄使用 .claude/settings.local.json，它會在儲存庫內的每個 CLI 工作階段中載入，無論啟動目錄如何，除了 Claude Code 不使用儲存庫根目錄的情況，例如在 Windows 上。相對模式（如範例的 Read(./**/vendor/**/*) ）仍然錨定在工作階段的目前工作目錄而不是儲存庫根目錄，因此如果您從子目錄啟動工作階段，請在此檔案中將規則寫為 // 絕對路徑，例如 Read(//absolute/path/to/repo/**/vendor/**/*) 。在 v2.1.211 之前，.claude/settings.local.json 也只從啟動目錄載入。
• 每個人，在每個工作階段中強制執行：在受管理設定中設定規則，使用者和專案設定無法覆蓋。

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

​

使用程式碼智能減少檔案讀取

/plugin install typescript-lsp@claude-plugins-official

• Marketplace "claude-plugins-official" not found：使用 /plugin marketplace add anthropics/claude-plugins-official 添加市場，然後重試安裝。
• 外掛在市場中找不到：檢查外掛名稱。

​

範圍 worktrees 和檔案存取

​

只簽出您需要的目錄

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

​

授予跨套件或儲存庫的存取權限

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

claude --add-dir ../shared

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

​

新增各目錄範圍的 skills

mkdir -p packages/api/.claude/skills/api-testing

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

​

保持 skills 可發現

• 從子目錄（例如 packages/api/）：該目錄的 skills、每個父目錄直到儲存庫根目錄，以及使用者和企業級別的 skills
• 從儲存庫根目錄：根目錄 skills，加上 Claude 在工作階段期間接觸的每個子目錄的 skills，這可能會累積成數百個
• 在使用 --add-dir 新增同層目錄後：該同層目錄的 skills 也會載入。additionalDirectories 設定僅授予檔案存取權限，不會載入 skills

​

當分層停止擴展時集中約定

• 技能：Claude 僅在與任務相關時載入的參考資料
• 外掛：平台團隊集中擁有的技能、hooks 和命令的版本化捆綁
• MCP 伺服器：如果您的組織已經在儲存庫上執行程式碼搜尋或 RAG 索引，請將其公開為 MCP 工具，以便 Claude 查詢它而不是直接讀取檔案

​

在工作階段啟動時推薦正確的外掛

​

將其整合在一起

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

monorepo/
  CLAUDE.md
  .claude/settings.json                           # worktree 工作階段的拒絕規則
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree、additionalDirectories、拒絕規則
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

• 載入根 CLAUDE.md 和 packages/api/CLAUDE.md，跳過 packages/web/CLAUDE.md
• 可以讀取和編輯 packages/api/ 和 packages/shared/ 中的檔案
• 跳過 packages/api/ 中 dist/ 和 build/ 下的建置輸出讀取
• 有 api-testing 技能可按需使用
• 建立包含 .claude/、packages/api/、packages/shared/ 和根級檔案的 worktrees，並從根設定檔案在 worktree 中應用拒絕規則

​

範圍和計劃跨套件的變更

• 在一個工作階段中給 Claude 整個變更：將共享編輯及其呼叫位置一起交付可以保持每個編輯背後的決策一致，而不是按套件重新推導它們
• 在編輯前計劃：先計劃在 Plan Mode 中，Claude 將計劃寫入檔案。長跨套件工作階段在進行中壓縮其上下文。Claude Code 在每次壓縮後重新注入計劃檔案，因此計劃在對話歷史可能不會的地方倖存

​

後續步驟

• 使用 hooks 在 Claude 編輯檔案後執行按目錄的 linters 或類型檢查器
• 審查有效管理成本以瞭解程式碼庫大小如何影響 token 使用以及如何在更廣泛推出前設定支出限制
• 在 Claude 部落格上閱讀Claude Code 如何在大型程式碼庫中工作，瞭解組織推出模式和所有權模型，這些模型位於本頁面上的按儲存庫設定之上