# Claude Code Large codebases and monorepos

> Control Claude Code context, file reads, worktrees, cross-package access and directory-scoped skills in large repositories.

URL: https://docs.passion8.cc/en/docs/claude-code/large-codebases
Language: en
Publisher: Passion8

The common problem in large repositories is reading too many files unrelated to the task. Startup location, layered `CLAUDE.md` instructions, read permissions, worktree scope and skill scope all affect context size, cost and quality.




Passion8 handles model requests; it does not narrow local repository context. Configure large-repository performance and cost controls in Claude Code itself.




## Startup location sets the boundary

Start at the root for tasks spanning packages; start in a subdirectory for one service, frontend package or module.

| Location | File access | Startup instructions | Suitable tasks |
| --- | --- | --- | --- |
| Repository root | Whole repository by default | Root `CLAUDE.md`; child instructions on demand | Cross-package changes, global refactoring, architecture |
| Subdirectory | Its subtree by default | Local and all parent `CLAUDE.md` files | Single-package work, service troubleshooting, reduced context |

Project `.claude/settings.json` is read from the startup directory; it does not inherit parent configuration like `CLAUDE.md`. Teams starting from different subdirectories need local settings or managed configuration.

## Layer `CLAUDE.md`

Do not put every rule in the root file:

- Root: repository structure, shared coding conventions, commits and command entry points.
- Child: package stack, tests, database constraints and component conventions.

```text
monorepo/
  CLAUDE.md
  packages/
    api/
      CLAUDE.md
      src/
    web/
      CLAUDE.md
      src/
    shared/
      CLAUDE.md
      src/
```

Starting in `packages/api` loads root and API rules, rather than Web rules at startup. With [memory and rules](https://docs.passion8.cc/en/docs/claude-code/memory), keep permanent shared instructions at the root and path-specific instructions in child directories or `.claude/rules`.

## Exclude irrelevant instructions

When root startup is necessary but some packages are irrelevant, exclude their instructions with `claudeMdExcludes`:

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

Use `.claude/settings.local.json` for personal exclusions or `.claude/settings.json` for team defaults. Users cannot exclude managed-policy `CLAUDE.md` files.

## Restrict file reads

Ordinary searches respect `.gitignore` for directories such as `node_modules`, `dist` and `build`. For committed generated code, vendor SDKs or legacy packages, add Read deny rules:

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

These prevent read tools from opening matching paths and constrain common file-reading shell commands such as `cat`, `head`, `grep` and `find`. They do not hide path names from recursive search, but prevent continuing into their contents. See [permissions](https://docs.passion8.cc/en/docs/claude-code/permissions).

## Use code intelligence to reduce scanning

Language-server plugins help locate definitions, references and diagnostics without repeatedly scanning a large repository with `rg`:

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

Each developer needs the corresponding language-server binary. Restricted networks can host marketplaces in internal Git or local paths. See [plugins and skills](https://docs.passion8.cc/en/docs/claude-code/plugins).

## Sparse worktrees

`--worktree` creates an isolated workspace for parallel tasks and recovery. Use `worktree.sparsePaths` to avoid checking out the entire large tree:

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

- List directories in `sparsePaths`, not individual files.
- Root-level files are included with the listed directories; other root directories are not automatic.
- Include `.claude` when the worktree needs root settings, rules or skills.
- `symlinkDirectories` avoids duplicating `node_modules` per worktree.

See [worktrees](https://docs.passion8.cc/en/docs/claude-code/worktrees) and [parallel agents](https://docs.passion8.cc/en/docs/claude-code/parallel-agents).

## Cross-package access

Authorize additional package directories with configuration or startup arguments:

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

For a single run:

```bash
claude --add-dir ../shared
```

| Method | Extra directory `CLAUDE.md`/rules | Skills | Suitable for |
| --- | --- | --- | --- |
| `additionalDirectories` | Not loaded | Not loaded | Fixed team cross-package access |
| `--add-dir` or `/add-dir` | Requires an additional environment setting | Loaded | Temporary cross-directory tasks |

To load instructions from an added directory:

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

## Directory-scoped skills

Subdirectories can have their own `.claude/skills`. Names and descriptions participate in matching; the body loads only when needed. Use them for long, occasional workflows.

```text
packages/api/
  .claude/
    skills/
      api-testing/
        SKILL.md
```

Example `SKILL.md`:

```markdown
---
name: api-testing
description: Testing patterns for packages/api. Use when writing or modifying API tests.
---

## Running tests

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

## Patterns

- Use supertest for HTTP assertions.
- Wrap database tests in transactions that roll back.
```

Put shared workflows in root `.claude/skills`. Package cross-repository or platform-team workflows as plugins.

## Cross-package workflow

- Explore first and save a plan such as `docs/changes/user-role-plan.md`.
- Handle shared types and their callers in one session to avoid rediscovering context per package.
- Use subagents for read-only research or non-overlapping implementation, not simultaneous edits to the same files.
- Use `/compact` in long sessions, with the important plan saved to disk for recovery.
- For cost-sensitive work, read [cost optimization](https://docs.passion8.cc/en/docs/claude-code/cost-saving) and [prompt caching](https://docs.passion8.cc/en/docs/claude-code/prompt-caching).

## Official references

- [Set up Claude Code in a monorepo or large codebase](https://code.claude.com/docs/en/large-codebases.md)
- [Memory and project instructions](https://code.claude.com/docs/en/memory.md)
- [Permissions](https://code.claude.com/docs/en/permissions.md)
- [Worktrees](https://code.claude.com/docs/en/worktrees.md)

## Recommended starting points



- [Work on one package](https://docs.passion8.cc/en/docs/claude-code/context): Start in a subdirectory, then add other directories when needed.
- [Parallel cross-package development](https://docs.passion8.cc/en/docs/claude-code/worktrees): Control disk and context scope with worktrees and sparsePaths.
- [Shared team rules](https://docs.passion8.cc/en/docs/claude-code/enterprise-admin): Govern settings, plugins and MCP centrally.
- [Enterprise deployment](https://docs.passion8.cc/en/docs/claude-code/enterprise-deployment-overview): Include repository strategy in rollout and managed settings.
- [Restrict reads](https://docs.passion8.cc/en/docs/claude-code/permissions): Deny sensitive or generated files with Read rules and permission modes.