Large codebases and monorepos

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.

#Startup location sets the boundary

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

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.

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, 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:

{
  "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:

{
  "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.

#Use code intelligence to reduce scanning

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

/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.

#Sparse worktrees

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

{
  "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 and parallel agents.

#Cross-package access

Authorize additional package directories with configuration or startup arguments:

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

For a single run:

claude --add-dir ../shared

To load instructions from an added directory:

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.

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

Example SKILL.md:

---
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 and prompt caching.

#Official references

• Set up Claude Code in a monorepo or large codebase
• Memory and project instructions
• Permissions
• Worktrees

#Recommended starting points