在 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: API 包的测试模式。在 packages/api/ 中编写或修改测试时使用。
---

## 测试结构

测试在 `src/__tests__/` 中，镜像 `src/` 目录结构。
每个路由文件都有一个对应的 `.test.ts` 文件。

## 运行测试

- 所有测试：`npm test`
- 单个文件：`npm test -- src/__tests__/routes/users.test.ts`
- 监视模式：`npm test -- --watch`

## 测试实用程序

- `src/__tests__/helpers/db.ts`：提供 `setupTestDb()` 和 `teardownTestDb()` 用于数据库测试
- `src/__tests__/helpers/auth.ts`：提供 `createTestUser()` 和 `getAuthToken()` 用于认证端点

## 模式

- 使用 `supertest` 进行 HTTP 断言，而不是原始 fetch
- 始终在回滚的事务中包装数据库测试
- 在 `src/__tests__/mocks/` 中模拟外部服务

​

保持 skills 可发现

• 从子目录如 packages/api/：来自该目录、每个父目录直到存储库根目录以及用户和企业级别的 skills
• 从存储库根目录：根 skills，加上来自 Claude 在会话期间接触的每个子目录的 skills，可能累积到数百个
• 在使用 --add-dir 添加同级后：该同级的 skills 也加载。additionalDirectories 设置仅授予文件访问权限，不加载 skills

​

当分层停止扩展时集中约定

• Skills：Claude 仅在与任务相关时加载的参考材料
• Plugins：平台团队集中拥有的 skills、hooks 和命令的版本化包
• MCP servers：如果你的组织已经在存储库上运行代码搜索或 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 skill 按需可用
• 创建包含 .claude/、packages/api/、packages/shared/ 和根级文件的 worktrees，拒绝规则从根设置文件应用于整个 worktree

​

范围和计划跨包的更改

• 在一个会话中给 Claude 整个更改：将共享编辑及其调用站点一起交付保持每个编辑背后的决策一致，而不是按包重新推导它们
• 在编辑前计划：先计划在 plan mode 中，Claude 将计划写入文件。长的跨包会话在进行中压缩其上下文。Claude Code 在每次压缩后重新注入计划文件，所以计划在对话历史可能不会的地方幸存

​

后续步骤

• 使用 hooks 在 Claude 编辑文件后运行按目录的 linters 或类型检查器
• 查看有效管理成本以了解代码库大小如何影响 token 使用以及如何在更广泛推出前设置支出限制
• 在 Claude 博客上阅读Claude Code 如何在大型代码库中工作，了解组织推出模式和所有权模型，这些模型位于本页面的按存储库配置之上