Claude Code for Large Codebases: Add Directories, Limit Scope, and Avoid Token Waste

Claude Code is a powerful agentic CLI for editing real codebases — but the default behavior assumes a small, focused project. Drop it into a Turborepo monorepo with 80 packages, and without proper scoping it can wander through tens of thousands of files, waste a significant chunk of your context window on generated output and lock files, and produce confused suggestions that blend concerns from unrelated packages.

This guide covers the two core tools for keeping Claude surgical in large codebases — --add-dir and .claudeignore — plus monorepo-specific patterns for per-package context and token budgeting.

The Problem: Large Codebases Without Scope Are Expensive

A typical enterprise Next.js monorepo might have:

• apps/web — the main app
• apps/admin — a separate admin panel
• packages/ui — shared component library
• packages/db — Prisma schema and database utilities
• packages/shared — type definitions and constants
• node_modules/ — hundreds of megabytes of dependencies
• dist/, build/, .next/, .turbo/ — compiled output

If you launch claude from the repo root and ask it to "add a new field to the user settings form," Claude may start by indexing every subdirectory it can reach. Without boundaries, it might read lock files, compiled artifacts, and packages completely unrelated to the task at hand — every token spent there is a token not available for the actual code you want changed.

Two features address this directly.

By Default: Claude Works Inside Your Current Directory

When you run claude from a terminal, Claude Code can read and write files relative to the directory you launched it from — and nothing else. That is the safe default.

If you are in apps/web/, Claude can see everything under apps/web/. It cannot reach packages/ui/ one level up, even if your component imports from it. This is intentional: it prevents accidental cross-package writes and keeps the blast radius small.

The challenge is that in a monorepo, the package you are editing almost always imports from shared packages. When Claude cannot read those packages, it either guesses at type signatures or asks you to paste code inline — both of which are friction.

Expanding Scope with --add-dir

The --add-dir flag tells Claude Code that it has permission to read and write those additional directories alongside the working directory. You can add multiple directories in a single invocation:

claude --add-dir ../shared-utils --add-dir ../design-system

Practical Monorepo Example (Turborepo / pnpm workspace)

Say you are working on apps/web but your components import from packages/ui and your API routes import from packages/db:

# Working on apps/web, but need access to packages/ui and packages/db
cd apps/web
claude --add-dir ../../packages/ui --add-dir ../../packages/db

Now Claude can read the component types in packages/ui and understand the Prisma schema in packages/db without you needing to paste anything manually. It can also write to those packages if a fix needs to land there — for instance, adding an exported type that both apps/web and apps/admin need.

Persistent Configuration via settings.json

If you always want certain packages available when working from a directory, codify it in .claude/settings.json at the package level:

{
  "additionalDirectories": ["../../packages/ui", "../../packages/db"]
}

This file lives inside apps/web/.claude/settings.json. Every time someone runs claude from apps/web/, those directories are automatically available without typing the flags. Commit this file so the whole team benefits.

Limiting Scope with .claudeignore

The second half of scoping is telling Claude what not to read. Create a .claudeignore file in your project root using the same syntax as .gitignore:

# Dependencies — never useful for Claude to read
node_modules/
.pnp/
.pnp.js

# Build output
.next/
dist/
build/
out/

# Turbo and cache
.turbo/
.cache/

# Coverage and test artifacts
coverage/
.nyc_output/

# Minified and compiled
*.min.js
*.min.css
*.map

# Lock files
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml

# Generated files
*.generated.ts
*.generated.graphql
**/__generated__/

# Static assets Claude doesn't need to index
public/static/
public/images/

Claude Code will not read or traverse ignored paths. On a typical Next.js monorepo, ignoring node_modules/, .next/, and generated files can reduce the number of indexable files from tens of thousands down to a few hundred — the actual source you care about.

What .claudeignore Actually Prevents

When Claude receives a task like "find where we handle auth errors," without .claudeignore it might look through:

• node_modules/passport/lib/ — not what you want
• .next/server/chunks/ — compiled output, not readable
• coverage/lcov-report/ — not relevant
• dist/ — stale compiled artifacts

With .claudeignore, that search hits only your actual source files. Results come back faster, use fewer tokens, and are far less likely to surface a false positive from a dependency's internals.

Monorepo-Specific Strategies

1. Launch from the Package, Not the Root

Always cd into the specific package before launching Claude:

# Do this
cd apps/web && claude

# Not this (unless you specifically need repo-wide context)
claude  # from repo root

Starting from the package directory means the default scope is already narrow. Add packages on demand with --add-dir rather than trying to limit a root-level launch.

2. Per-Package CLAUDE.md Files

Each package in a monorepo can have its own CLAUDE.md file. When you launch Claude from apps/web, it reads apps/web/CLAUDE.md for package-specific context:

# apps/web CLAUDE.md

## Stack
- Next.js 15 App Router
- Tailwind CSS + shadcn/ui components from ../../packages/ui
- Auth via NextAuth, session types in ../../packages/shared/auth.ts

## Key conventions
- Components go in src/components/, pages in src/app/
- Use the Button component from @company/ui, not a local one
- All DB access must go through the repository pattern in ../../packages/db/src/

## Do not touch
- src/generated/ — auto-generated by graphql-codegen, run pnpm codegen instead

The root CLAUDE.md handles repo-wide conventions (commit format, PR templates, testing requirements), while package-level files handle the specific context for that package.

3. Reference Specific Files with @ in CLAUDE.md

The --add-dir flag grants directory access. A separate but complementary feature is the @file reference syntax inside CLAUDE.md:

# CLAUDE.md

@../../packages/shared/types/user.ts
@../../packages/db/prisma/schema.prisma

This loads the content of those files into Claude's context at startup — useful for small, critical files like type definitions or schemas that Claude should always have in mind. Combine both:

• additionalDirectories in settings.json — so Claude can navigate and edit those packages
• @file references in CLAUDE.md — so key type files are always pre-loaded in context

Working with Large Files

Some files are too large to read wholesale without burning significant token budget:

• Log files — rarely need full content; let Claude use Bash(grep) or Bash(tail) to find relevant lines instead of reading the whole file
• Generated data — database seeds, fixture files, large JSON — put these in .claudeignore
• Large config files — if your next.config.ts or webpack.config.js is very long, split it into focused modules that Claude can read one at a time

Tell Claude explicitly when you want targeted reads:

"Only look at the files in src/auth/ — don't read anything else unless I specifically ask."

Explicit scoping in your prompt costs almost nothing but saves Claude from exploring broadly.

--add-dir vs @file Reference: When to Use Each

Use --add-dir broadly for packages Claude might need to navigate. Use @file selectively for the small set of files Claude should always have memorized.

Checking What Claude Can See

At any point in a session, ask Claude directly:

"What directories do you have access to?"

Claude will list its working directory and any additional directories granted via --add-dir or additionalDirectories. This is useful for debugging why Claude says it "can't find" a file — often the directory simply hasn't been granted access.

Token Budgeting Tips for Large Codebases

Effective token management in large projects comes down to four habits:

1. Start sessions scoped to one module or feature at a time

Instead of "fix the auth system," try "fix the JWT refresh logic in src/auth/refresh.ts." The narrower the task, the less Claude needs to explore.

2. Use /clear between unrelated tasks

The /clear command resets context between tasks. If you just finished work on packages/ui and are now switching to packages/db, clear the session rather than carrying forward unrelated context.

3. Be explicit about file scope in your prompts

"Only look at files in src/api/routes/ — do not read anything outside that directory."

Claude Code respects this kind of explicit instruction. It avoids broad exploration and goes straight to the relevant files.

4. Use .claudeignore aggressively

Start by ignoring everything that is not source code — build output, node_modules, lock files, generated files, static assets. You can always temporarily remove a rule from .claudeignore if Claude genuinely needs to inspect a generated file. The default should be narrow, not wide.

Complete Setup: Turborepo + pnpm Example

Here is a complete working configuration for a typical Turborepo workspace:

File: apps/web/.claude/settings.json

{
  "additionalDirectories": [
    "../../packages/ui",
    "../../packages/db",
    "../../packages/shared"
  ]
}

File: apps/web/.claudeignore

node_modules/
.next/
.turbo/
dist/
build/
coverage/
*.min.js
*.lock
public/static/
**/*.generated.ts
**/__generated__/

File: apps/web/CLAUDE.md

# apps/web

## Key dependencies
- UI components: ../../packages/ui (import from @company/ui)
- DB access: ../../packages/db (use repository pattern, not raw Prisma)
- Shared types: ../../packages/shared

@../../packages/shared/types/index.ts

## Development
- Run: pnpm dev (from this directory)
- Tests: pnpm test
- Build: pnpm build

## Do NOT modify
- src/generated/ — run `pnpm codegen` instead
- prisma/migrations/ — run `pnpm db:migrate` instead

Launching Claude:

cd apps/web
claude
# or, for a one-off session where you also need packages/analytics:
claude --add-dir ../../packages/analytics

Related explainx.ai Guides

• What is CLAUDE.md? — persistent memory for Claude Code sessions
• Claude Code slash commands reference — full command index including /add-dir and /compact
• Claude Code hooks — automate actions on tool calls
• Loop engineering with Claude Code — long-running agents and guardrails

Primary source: Claude Code documentation · Settings reference

Configuration details and flag availability reflect Claude Code as of June 2026. Check the official Claude Code docs for the latest settings reference before writing team runbooks.