SpyBara
Go Premium

large-codebases.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

511 added, 0 removed.

2026
Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Настройка Claude Code в монорепозитории или большой кодовой базе

Настройте Claude Code для монорепозиториев и больших однодеревных кодовых баз с вложенными файлами CLAUDE.md, разреженными worktrees, интеллектом кода и навыками для каждого пакета, чтобы Claude оставался сосредоточенным на коде, над которым вы работаете.

Большая кодовая база может быть одним репозиторием с миллионами строк или монорепозиторием со множеством пакетов. Claude Code работает при любом размере, но по мере роста кодовой базы параметры по умолчанию, настроенные для меньших проектов, могут заполнить контекстное окно инструкциями и чтениями файлов, не связанными с задачей, что стоит токены и снижает производительность Claude.

Это руководство показывает отдельным разработчикам и командам инженеров, как ограничить Claude той частью кодовой базы, которую затрагивает задача. Каждый раздел отмечает, является ли параметр личным для вашей машины или зафиксирован в репозитории.

Что охватывает это руководство

Таблица ниже перечисляет каждый параметр и то, что он достигает. Дерево файлов после неё — это пример монорепозитория, на который ссылаются все примеры кода на этой странице.

Параметры на этой странице

Каждый параметр ниже независим. Они накладываются друг на друга, а не заменяют друг друга, поэтому применяйте те, которые подходят вашему репозиторию. Выберите, где запустить Claude определяет, где находятся ваши файлы параметров, поэтому прочитайте это в первую очередь. Соберите всё вместе показывает все их в сочетании.

Я хочу Использовать
Загружать только соглашения для кода, который вы трогаете, вместо одного корневого файла, охватывающего каждую подсистему Per-directory CLAUDE.md файлы
Исключить CLAUDE.md файлы для пакетов, в которых вы никогда не работаете claudeMdExcludes
Заблокировать Claude от открытия выходных данных сборки, сгенерированного кода и зависимостей поставщика Read deny правила в permissions.deny
Найти определение символа или вызывающих через языковой сервер вместо сканирования файлов A code intelligence plugin
Проверить только каталоги, которые нужны задаче, когда Claude создаёт worktree worktree.sparsePaths
Читать и редактировать соседний пакет или другой репозиторий из одного сеанса --add-dir или additionalDirectories
Дать Claude процедуры, специфичные для одной области, которые загружаются только при необходимости Per-directory skills
Заменить множество per-directory CLAUDE.md файлов одним набором соглашений, который все устанавливают A plugin во внутреннем маркетплейсе

Пример монорепозитория

Примеры на этой странице ссылаются на монорепозиторий с тремя пакетами. Те же паттерны работают в большой однодеревной кодовой базе: где пример использует packages/api/, подставьте свой собственный каталог подсистемы, такой как src/backend/ или lib/core/.

monorepo/
  CLAUDE.md                     # root instructions
  packages/
    api/
      CLAUDE.md                 # API-specific instructions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # frontend-specific instructions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # shared library instructions
      src/

Выберите, где запустить Claude

Где вы запускаете claude, определяет, какие файлы Claude может читать и редактировать без дополнительного разрешения, какие CLAUDE.md файлы загружаются в контекст при запуске и какие параметры проекта применяются.

Запуск из Доступ к файлам CLAUDE.md загружается при запуске Использовать когда
Корень репозитория Каждый файл Только корневой; файлы подкаталогов загружаются по требованию, когда Claude читает там Задачи охватывают несколько пакетов или подсистем
Подкаталог Только это поддерево, пока вы не предоставите больше Этот каталог плюс каждый предок Работа ограничена одним пакетом или подсистемой

Параметры проекта в .claude/settings.json загружаются только из вашего начального каталога и не наследуются от родительских каталогов так, как это происходит с CLAUDE.md файлами: .claude/settings.json в корне репозитория применяется только при запуске из корня.

Каждый раздел ниже указывает, находится ли его файл параметров в корне репозитория или в подкаталоге, из которого вы запускаетесь, и зафиксирован ли он или хранится локально.

Слоистые CLAUDE.md файлы по каталогам

В большой кодовой базе один CLAUDE.md в корне репозитория имеет тенденцию либо расширяться, чтобы охватить соглашения каждой подсистемы, стоя контекста на инструкциях, не связанных с текущей задачей, либо оставаться слишком общим, чтобы быть полезным. Разделение инструкций между per-directory файлами означает, что Claude загружает правила на уровне репозитория плюс только соглашения для кода, над которым вы работаете.

Claude Code загружает каждый CLAUDE.md файл из вашего рабочего каталога и каждого родительского каталога при запуске, затем загружает файл каждого подкаталога по требованию, когда он читает файлы там. Корневой файл устанавливает правила на уровне репозитория, и каждый подкаталог добавляет свой собственный.

Общее разделение — два уровня:

  • Root CLAUDE.md: инструкции, которые применяются везде, такие как стандарты кодирования, соглашения о коммитах и макет репозитория
  • Per-subdirectory CLAUDE.md: соглашения, специфичные для стека этой области. В монорепозитории это один на пакет. В большом однодеревном это один на подсистему, такую как src/db/ или src/api/

Зафиксируйте эти файлы в репозитории, чтобы товарищи по команде их унаследовали. Владелец каждого каталога обычно поддерживает его файл.

Корневой CLAUDE.md ориентирует Claude на структуру репозитория:

This is a monorepo with three packages under packages/:

- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL
- packages/web: React frontend with Vite, TypeScript, and TailwindCSS
- packages/shared: shared TypeScript utilities used by both api and web

Run commands from the package directory, not the monorepo root.
Each package has its own tsconfig.json, package.json, and test suite.

CLAUDE.md каждого подкаталога, здесь packages/api/CLAUDE.md, добавляет контекст, специфичный для стека этой области:

This package is the REST API server.

- Run tests: `npm test` (uses Vitest)
- Run dev server: `npm run dev` (port 3001)
- Database migrations: `npm run migrate`
- Environment variables: copy `.env.example` to `.env`

API routes are in src/routes/. Each route file exports an Express router.
Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

Когда вы запускаете Claude из packages/api/, он загружает как packages/api/CLAUDE.md, так и корневой CLAUDE.md. Claude видит локальные инструкции наряду с правилами на уровне репозитория, без инструкций из packages/web/ в контексте. То же самое относится к любому подкаталогу в non-monorepo дереве.

Несколько способов держать файлы в актуальном состоянии по мере изменения кодовой базы и моделей:

  • Проверка в pull requests: рассматривайте редактирование CLAUDE.md как любое другое изменение документации, чтобы соглашения отслеживали код
  • Пересмотр после крупных выпусков моделей: инструкции, которые обходили ограничение старой модели, могут стать накладными, как только новая модель справляется с этим случаем самостоятельно. Например, правило, которое заставляет рефакторинг одного файла, можно удалить, как только ограничение исчезнет
  • Добавьте Stop hook, который предлагает обновления: Stop hook получает путь к транскрипту сеанса, когда Claude заканчивает ответ, поэтому скрипт может проверить сеанс и предложить обновления CLAUDE.md, пока разрыв, который он обнаружил, свежий

Для получения дополнительной информации о том, как загружаются и взаимодействуют CLAUDE.md файлы, см. Memory and project instructions.

Выберите между per-directory CLAUDE.md и path-scoped правилами

Per-directory CLAUDE.md файлы и path-scoped правила под .claude/rules/ оба позволяют вам нацелить инструкции на часть дерева. Они отличаются тем, где находится файл и когда он загружается.

Подход Расположение файла Загружается когда Использовать когда
Per-directory CLAUDE.md Внутри каталога, рядом с его кодом При запуске из этого каталога или по требованию, когда Claude читает файл там Владельцы каталогов поддерживают свои собственные соглашения; инструкции версионируются с кодом
Path-scoped правило в .claude/rules/ Центральный .claude/ в корне репо Когда Claude работает с файлом, соответствующим glob paths: правила Вы хотите все соглашения в одном месте, или одно и то же правило применяется ко многим разбросанным путям

Для сравнения, которое также охватывает skills, см. Compare similar features.

Исключите неуместные CLAUDE.md файлы

Когда вы запускаете Claude из корня репозитория, CLAUDE.md каждого подкаталога загружается, как только Claude читает файл в этом каталоге. Параметр claudeMdExcludes пропускает определённые файлы по пути или glob паттерну, чтобы они никогда не загружались.

Используйте это для каталогов, в которых вы никогда не работаете, таких как пакеты других команд, устаревший код или зависимости поставщика. Список исключений статичен, а не переключатель для каждой задачи. Чтобы сосредоточиться на одном пакете сегодня и другом завтра, запустите Claude из каталога этого пакета вместо редактирования исключений.

Если вы хотите эти исключения только для себя, поместите параметр в .claude/settings.local.json, который игнорируется git и не зафиксирован. Паттерны используют синтаксис glob, сопоставленный с абсолютными путями файлов, поэтому начните паттерны в стиле relative с **/, чтобы совпадать в любом месте дерева. Пример ниже исключает пакеты, принадлежащие другим командам:

{
  "claudeMdExcludes": [
    "**/packages/admin-dashboard/**",
    "**/packages/legacy-*/**"
  ]
}

Это пропускает каждый CLAUDE.md и файл правил под этими пакетами. Корневой CLAUDE.md и пакеты, в которых вы работаете, загружаются нормально.

Эти паттерны охватывают другие распространённые случаи:

  • "**/packages/*/CLAUDE.md": исключает CLAUDE.md каждого пакета, сохраняя корневой
  • "**/packages/web/**": исключает всё под пакетом web, включая правила
  • "/home/user/monorepo/legacy/CLAUDE.md": исключает один конкретный файл по абсолютному пути

Управляемые политикой CLAUDE.md файлы не могут быть исключены, поэтому инструкции на уровне организации всегда применяются. Вы можете установить claudeMdExcludes в любой области параметров: пользователь, проект, локальный или управляемый. Массивы объединяются в областях, поэтому команда может установить значения по умолчанию на уровне проекта, а отдельные лица добавить локальные переопределения.

Для полной документации исключения см. Exclude specific CLAUDE.md files.

Уменьшите то, что читает Claude

Инструкции — это только часть того, что попадает в контекст Claude. Чтения файлов — это ещё одна стоимость, которая растёт с кодовой базой. Параметры ниже блокируют чтения неуместных путей и заменяют исчерпывающие сканирования файлов поиском на языковом сервере.

Блокируйте чтения сгенерированного и зависимостей поставщика кода

Поиск контента Claude уважает .gitignore по умолчанию, поэтому пути, уже указанные там, такие как node_modules/, dist/ и build/, остаются вне результатов поиска без дополнительной конфигурации.

Для путей, которые зафиксированы, таких как зависимость поставщика SDK или зафиксированный сгенерированный код, добавьте Read deny правила в permissions.deny, чтобы заблокировать Claude от открытия этих файлов, даже когда поиск их перечисляет.

Чтобы применить эти исключения для всех, работающих в репозитории, зафиксируйте их в .claude/settings.json. Чтобы держать их личными, используйте .claude/settings.local.json вместо этого. Как и другие параметры проекта на этой странице, эти файлы загружаются только из вашего начального каталога. Поместите их в корень репозитория, если вы запускаете Claude там, или в каждый .claude/ пакета, если вы запускаете из подкаталогов. Чтобы применить одни и те же deny правила в каждом сеансе независимо от начального каталога, установите их в управляемых параметрах, которые параметры пользователя и проекта не могут переопределить.

Пример ниже блокирует артефакты сборки и зависимость поставщика SDK:

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

Deny правила охватывают встроенные инструменты файлов Claude и распознанные Bash команды файлов, включая cat, head, grep и find, когда запрещённый путь передаётся как аргумент. Они не фильтруют запрещённые пути из выходных данных рекурсивного поиска и не охватывают произвольные подпроцессы, которые открывают файлы сами. Для полного синтаксиса паттерна см. Read and Edit permission rules.

Уменьшите чтения файлов с помощью code intelligence

В большой кодовой базе поиск того, где определён или используется символ, может стоить много чтений файлов и вызовов grep. Code intelligence plugins подключают Claude к языковому серверу, чтобы он мог переходить к определениям, находить ссылки и выявлять ошибки типов напрямую вместо сканирования дерева.

Официальный маркетплейс имеет плагины для TypeScript, Python, Go, Rust и других распространённых языков. Пример ниже устанавливает плагин TypeScript:

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

Чтобы включить плагин для всех в репозитории, а не устанавливать его самостоятельно, добавьте его в параметр проекта enabledPlugins.

Code intelligence plugins требуют двоичного файла языкового сервера языка на машине каждого разработчика. См. какой двоичный файл требует каждый язык. Установка из официального маркетплейса требует доступа в сеть к GitHub, где размещается маркетплейс. На ограниченной сети добавьте маркетплейс с внутреннего хоста Git или локального пути вместо этого.

Это хорошо сочетается с claudeMdExcludes и Read deny правилами выше. Они держат неуместный контент вне контекста, а code intelligence держит Claude от чтения через то, что остаётся, чтобы найти определение.

Область worktrees и доступ к файлам

Эти параметры контролируют, что находится на диске в worktrees и какие каталоги Claude может читать и писать за пределами вашей начальной точки.

Проверьте только каталоги, которые вам нужны

Флаг --worktree запускает сеанс в новом git worktree, чтобы изменения оставались изолированными от вашего основного checkout. По умолчанию он проверяет весь репозиторий. В большом репозитории параметр worktree.sparsePaths использует git sparse-checkout для записи только перечисленных каталогов плюс файлы на уровне корня на диск, поэтому worktrees запускаются быстрее и используют меньше места.

Если все, работающие в этом каталоге, нуждаются в одних и тех же путях, зафиксируйте параметр в .claude/settings.json. Чтобы добавить пути для себя, используйте .claude/settings.local.json: списки объединяются в областях, поэтому локальный файл может добавить пути к зафиксированному списку, но не удалить их. Пример ниже показывает зафиксированный файл:

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

Когда Claude создаёт worktree, он проверяет только .claude/, packages/api/ и packages/shared/ вместо полного дерева. Пути в sparsePaths относительны к корню репозитория, независимо от того, из какого подкаталога вы запускаете Claude. Здесь работают любые пути каталогов, не только корни пакетов.

Это особенно полезно для изоляции worktree подагента. Подагенты — это параллельные экземпляры Claude, порождённые для подзадач, и каждый, который работает в worktree, получает лёгкий checkout вместо полного дерева. Все worktrees в сеансе используют одни и те же sparsePaths, поэтому если один подагент нуждается в packages/api/ и другой нуждается в packages/web/, перечислите оба.

Перечислите каталоги в sparsePaths, а не отдельные файлы. Файлы на уровне корня, такие как package.json, tsconfig.base.json и файлы блокировки, всегда проверяются наряду с каталогами, которые вы перечисляете. Каталоги на уровне корня нет, поэтому включите .claude в список, если вы хотите, чтобы .claude/settings.json, .claude/rules/ или .claude/skills/ корня репозитория были доступны внутри worktree.

Чтобы избежать дублирования больших каталогов, таких как node_modules, в worktrees, объедините sparsePaths с symlinkDirectories в одном .claude/settings.json:

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

Это создаёт символическую ссылку из node_modules/ каждого worktree обратно на копию основного репозитория вместо дублирования её на диск.

Для полного справочника параметров worktree см. Worktree settings.

Предоставьте доступ в пакеты или репозитории

Этот раздел применяется, когда вы запускаете Claude из подкаталога или когда задача охватывает несколько checkouts. Если вы запускаете из корня репозитория в одном большом дереве, Claude уже имеет доступ к каждому файлу и вы можете пропустить это.

Когда вы запускаете Claude из packages/api/, он может читать и писать файлы в этом каталоге. Если задача требует изменений в пакетах, такие как обновление общего типа, который импортируют как api, так и web, вам нужно предоставить доступ к соседнему каталогу. Тот же механизм предоставляет доступ к отдельно проверенному репозиторию.

Параметр additionalDirectories в .claude/settings.json даёт Claude доступ к каталогам вне рабочего каталога. Пример ниже предоставляет доступ к двум соседним пакетам:

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

Относительные пути разрешаются относительно каталога, из которого вы запускаете Claude. С этой конфигурацией Claude может читать и редактировать файлы в packages/shared/ и packages/web/ при работе из packages/api/.

Вы также можете предоставить доступ во время выполнения без редактирования параметров, передав --add-dir при запуске Claude:

claude --add-dir ../shared

Однако вы добавляете каталог, Claude может читать и редактировать файлы в нём. Загружаются ли CLAUDE.md, файлы .claude/rules/ и skills каталога, зависит от того, как вы его добавили:

Добавлено с Загружает CLAUDE.md и правила Загружает skills
Параметр additionalDirectories Никогда Никогда
Флаг --add-dir или команда /add-dir Только с переменной окружения ниже Да

Чтобы загружать CLAUDE.md и файлы правил из каталога, добавленного с --add-dir или /add-dir, установите переменную окружения CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

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

Переменная окружения не влияет на каталоги, перечисленные в параметре additionalDirectories. См. Load from additional directories для деталей.

Для соседних каталогов, которые нужны всем в этой области, зафиксируйте additionalDirectories в .claude/settings.json. Для личного выбора или одноразового доступа используйте .claude/settings.local.json или передайте --add-dir при запуске.

Добавьте per-directory skills

Любой подкаталог может определить skills, ограниченные своим собственным стеком. Skill загружается по требованию, когда Claude определяет, что это релевантно, поэтому инструментарий, специфичный для API, не потребляет контекст во время работы фронтенда.

Skills находятся под .claude/skills/ внутри каталога. Зафиксируйте их рядом с кодом этой области, чтобы каждый, кто клонирует репозиторий, получил их. В монорепозитории это может быть один набор skills на пакет. В большой однодеревной кодовой базе это один набор на подсистему, такую как src/db/.claude/skills/.

Создайте каталог skill внутри подкаталога:

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

Затем напишите SKILL.md внутри этого каталога, здесь packages/api/.claude/skills/api-testing/SKILL.md. Этот пример учит Claude паттернам тестирования пакета API:

---
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/web/.claude/skills/component-patterns/ описывает соглашения компонентов фронтенда вместо тестирования. Когда Claude работает с файлом в packages/api/, он загружает skill api-testing. Когда он работает в packages/web/, он загружает component-patterns вместо этого. Ни один из skills каталогов не загружается во время задач другого.

Вы также можете ограничить skill по паттерну файла вместо размещения. Поле frontmatter paths принимает glob паттерны, и Claude автоматически загружает skill только когда работает с совпадающими файлами. Используйте это для skill, который находится в .claude/skills/ корня репозитория, но применяется только к определённым файлам, где бы они ни появлялись, такие как skill миграции базы данных, ограниченный **/migrations/**.

Для получения дополнительной информации о создании и организации skills см. Skills.

Держите skills обнаруживаемыми

С skills, разбросанными по многим каталогам, список, из которого Claude выбирает, может вырасти большим. Claude выбирает skill, читая имя и описание каждого обнаруженного skill, и только содержимое выбранного skill загружается в контекст. Этот раздел охватывает, как держать этот список маленьким и писать описания, которые выживают при сокращении.

Какие skills находятся в области, зависит от того, где вы запускаете Claude:

  • Из подкаталога, такого как packages/api/: skills из этого каталога, каждый родитель вверх до корня репозитория и уровни пользователя и предприятия
  • Из корня репозитория: skills из каждого подкаталога, который Claude трогает во время сеанса, что может накопиться в сотни
  • После добавления соседа с --add-dir: skills этого соседа также загружаются. Параметр additionalDirectories предоставляет доступ к файлам только и не загружает skills

Имена всегда загружаются, но описания сокращаются, когда их много, что может удалить ключевые слова, которые Claude использует, чтобы решить, применяется ли skill. Держите описания короткими и начните со слов, которые содержал бы запрос, таких как "writing or modifying tests in packages/api/".

Для skills, которые многие каталоги используют совместно, такие как соглашения PR или контрольный список развёртывания, поместите их в .claude/skills/ корня репозитория, чтобы они загружались из любого начального каталога. Когда общие skills нуждаются в своей собственной истории версий или должны работать в репозиториях, упакуйте их как plugin вместо этого. Plugin skills используют пространство имён plugin-name:skill-name, поэтому они никогда не конфликтуют с per-directory skills. Команда платформы может версионировать и обновлять их в одном месте.

Чтобы найти, какие skills остаются неиспользованными, включите OpenTelemetry logs exporter и установите OTEL_LOG_TOOL_DETAILS=1, чтобы имена skills записывались дословно вместо редактирования. Событие skill_activated записывает каждый вызов в его атрибут skill.name, и invocation_trigger записывает, вызвал ли его команда, Claude или вложенный skill, что говорит вам, что консолидировать или снять с производства.

Централизуйте соглашения, когда слоистость перестаёт масштабироваться

Per-directory CLAUDE.md файлы могут стать трудными для управления по мере роста кодовой базы. Соглашения дрейфуют, файлы устаревают, и никто не владеет корневым. Решение этого обычно падает на команду, которая поддерживает настройку Claude Code репозитория, а не на каждого разработчика, работающего в своей собственной области.

Переместите соглашения и справочный контент из всегда загружаемого CLAUDE.md в механизмы, которые загружаются по требованию:

  • Skills: справочный материал, который Claude загружает только когда релевантно задаче
  • Plugins: версионированные пакеты skills, hooks и команд, которыми владеет команда платформы централизованно
  • MCP servers: если ваша организация уже запускает поиск кода или RAG индекс над репозиторием, выставьте его как инструмент MCP, чтобы Claude запрашивал его вместо чтения файлов напрямую

См. server-managed или endpoint-managed параметры для того, как команды платформы могут применять это централизованно.

Рекомендуйте правильный plugin при запуске сеанса

Как только соглашения живут в plugins, товарищ по команде, запускающий Claude в незнакомой части дерева, не имеет сигнала о том, какой plugin поддерживает владельцы этой области. SessionStart hook может закрыть этот разрыв, так как всё, что hook печатает в stdout, добавляется в контекст Claude перед первым запросом.

Например, вы можете написать скрипт, который читает каталог запуска из входных данных hook, ищет его в карте path-to-plugin, зафиксированной в репозитории, и печатает рекомендацию для Claude, чтобы передать в его первом ответе. См. Automate actions with hooks для написания и регистрации hook.

Соберите всё вместе

Объединённая конфигурация ниже использует макет монорепозитория. Те же файлы работают для любого подкаталога в большом однодеревном. Параметры проекта загружаются только из каталога, из которого вы запускаете Claude, поэтому .claude/settings.json каждого подкаталога должен быть самодостаточным, а не слоистым на корневом файле.

Пример зафиксирует worktree, additionalDirectories и Read deny правила в .claude/settings.json, чтобы каждый разработчик в packages/api/ получил одинаковый доступ к соседям, разреженные пути и исключения. Файл ниже — это зафиксированные параметры для каждой области для packages/api/:

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

Потому что этот сеанс запускается из packages/api/, CLAUDE.md файлы соседних пакетов уже вне области, поэтому claudeMdExcludes не нужен здесь. Добавьте его в .claude/settings.local.json корня репозитория вместо этого, если вы также запускаете сеансы из корня.

Запись additionalDirectories применяется, когда вы запускаете Claude из packages/api/ напрямую. Внутри worktree, созданного из этого сеанса, рабочий каталог — это корень worktree, поэтому этот файл параметров не загружается. Соседние пакеты уже достижимы внутри worktree без него, но deny правила нуждаются во второй копии в .claude/settings.json корня репозитория, чтобы сеансы worktree их подхватили, как описывает примечание параметров worktree:

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

После настройки репозиторий имеет этот макет:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # deny rules for worktree sessions
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, deny rules
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

С этой настройкой, запуская Claude из packages/api/:

  • Загружает корневой CLAUDE.md и packages/api/CLAUDE.md, пропускает packages/web/CLAUDE.md
  • Может читать и редактировать файлы в packages/api/ и packages/shared/
  • Пропускает чтения выходных данных сборки под dist/ и build/ в packages/api/
  • Имеет skill api-testing доступным по требованию
  • Создаёт worktrees, содержащие .claude/, packages/api/, packages/shared/ и файлы на уровне корня, с deny правилами, применёнными в worktree из файла параметров корня

Область и план изменений, которые охватывают пакеты

Конфигурация выше контролирует, что видит Claude. Когда одно изменение трогает несколько пакетов, такие как обновление общего типа наряду с каждым местом вызова, которое его использует, как вы ограничиваете и последовательно выполняете задачу, также влияет на результат.

Два метода помогают держать кросс-пакетное изменение согласованным:

  • Дайте Claude всё изменение в одном сеансе: передача общего редактирования и его мест вызова вместе держит решения за каждым редактированием согласованными, а не переопределяя их на пакет
  • Сохраните план в файл перед редактированием: план сначала и попросите Claude написать план в файл markdown в репозитории. Длинный кросс-пакетный сеанс компактирует свой контекст по пути, и сохранённый план выживает, где история разговора может не выжить

Следующие шаги

Как только эта конфигурация на месте, вы можете её уточнить:

  • Используйте hooks для запуска per-directory linters или type-checkers после редактирования Claude файлов
  • Проверьте Manage costs effectively для понимания того, как размер кодовой базы влияет на использование токенов и как установить лимиты расходов перед более широким развёртыванием
  • Прочитайте How Claude Code works in large codebases в блоге Claude для паттернов развёртывания организации и моделей владения, которые находятся выше per-repository конфигурации на этой странице