Anthropic: large codebases

Source: Set up Claude Code in a monorepo or large codebase

Checked: 13 July 2026. This is rolling product documentation rather than a versioned design paper.

Evidence type: product documentation containing mechanisms and explicit recommendations.

Problem framing

Anthropic frames large-codebase performance as a scoping problem. Defaults that work for a small repository can fill context with irrelevant instructions and file reads as the tree grows. The remedy is not one feature but independent, layered controls over launch scope, instructions, reads, symbol navigation, worktrees, cross-directory access, and skills.

Launch scope controls configuration

The guide maps each need to a distinct, composable mechanism:

• Load conventions only for touched code with per-directory CLAUDE.md files.
• Skip instruction trees a developer never uses with claudeMdExcludes.
• Prevent reads of generated or vendored content with permissions.deny and Read(...) rules.
• Navigate definitions, references, and type errors with a code-intelligence plugin.
• Reduce files materialised in a worktree with worktree.sparsePaths.
• Reach another package or repository with --add-dir or additionalDirectories.
• Load area-specific procedures on demand with nested .claude/skills/.
• Share conventions across repositories with an internal plugin.

Where Claude starts determines three things: default file access, instructions loaded at startup, and project settings. Starting at the repository root is for cross-package work; starting in a package limits default access to that subtree and loads its instructions plus ancestor instructions.

A subtle but important mechanism is that project settings are not inherited from parent directories in the same way as CLAUDE.md. A package-level .claude/settings.json must be self-contained. Worktree creation also changes the effective working directory to the worktree root, so settings required inside worktrees must exist at the root.

The article’s example uses a root CLAUDE.md and package-owned instruction files and skills:

monorepo/
├── CLAUDE.md
└── packages/
    ├── api/
    │   ├── CLAUDE.md
    │   └── .claude/skills/
    ├── web/
    │   ├── CLAUDE.md
    │   └── .claude/skills/
    └── shared/
        └── CLAUDE.md

Starting at the root grants default access across the repository and initially loads only the root instructions; nested files arrive when Claude reads into their directories. Starting in packages/api limits initial file access to that subtree and loads both local and ancestor instructions.

Instruction layering

• Root CLAUDE.md contains repository-wide layout, commands, and conventions.
• Per-directory CLAUDE.md contains stack and subsystem-specific facts and is maintained with that code by its owners.
• Nested instructions load when Claude reads into the directory.
• Path-scoped rules centralise conventions at the root and load on matching file globs; they suit rules that apply across scattered paths.
• claudeMdExcludes statically suppresses irrelevant package, legacy, or vendor instruction trees. It is not intended as a daily task selector; start from the relevant package for that.
• Managed policy instructions cannot be excluded.

Anthropic recommends reviewing instruction changes like code, revisiting model workarounds after major model releases, and optionally using session-end analysis to propose instruction updates while failures are fresh.

Reducing reads

A representative committed exclusion policy is:

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

This is a context and accidental-access control, not a complete process sandbox. Similarly, claudeMdExcludes patterns match absolute paths, so relative-looking globs normally begin with **/; arrays merge across scopes.

Search already respects .gitignore. Checked-in generated or vendored content needs explicit Read deny rules. The documented limitation matters: these rules cover built-in tools and recognised shell file commands but do not erase paths from recursive search output or control arbitrary subprocesses.

Language-server plugins replace sequences of grep and file reads with symbol definition, reference, and type-error operations. They require the language server binary locally. Anthropic presents exclusions and code intelligence as complementary: one removes irrelevant material, the other navigates the remaining code precisely.

Worktree and filesystem scope

• worktree.sparsePaths checks out only required directories plus root files.
• Include .claude explicitly if root agent configuration must exist inside the sparse worktree.
• All subagents in a session share the sparse path set, so it must cover every delegated package.
• symlinkDirectories can share large dependency trees such as node_modules with the primary checkout.
• additionalDirectories and --add-dir grant access beyond the start directory, but their configuration-loading behaviour differs.
• A settings-based additional directory loads neither its instructions nor its skills. --add-dir loads skills, and instructions only with a separate environment flag.

This distinction supports a useful standard: file permission and knowledge discovery are separate capabilities and must not be conflated.

Per-directory skills

Package or subsystem skills live beside the relevant code and load on demand. Names and descriptions are always discovery overhead; full bodies load only when selected. When many skills accumulate, descriptions may be shortened, so Anthropic recommends short descriptions that lead with request-like trigger words. Repository-wide workflows such as PR conventions belong at the root; versioned cross-repository workflows belong in plugins.

Skill activation telemetry can identify unused workflows for consolidation or retirement.

Cross-package changes

Anthropic recommends keeping a logically connected cross-package change in one session so decisions stay consistent. For long changes, explore and plan first, then save the plan in the repository because it survives conversation compaction.

The task statement should name the affected packages, shared contracts, and verification command. Each package still needs its relevant checks; a root suite should not be assumed to prove every boundary.

Standards implications

• Scope task access from the narrowest useful directory outward.
• Define client-neutral outcomes for instruction layering and exclusions, then document Claude-specific configuration separately.
• Require durable plans for long or cross-package work.
• Treat settings inheritance, permissions, and knowledge discovery as explicit runtime semantics that integrations must test.
• Prefer code intelligence and focused checkouts before adding more context.