DEV Community: Harshit Rathod

Why Large Codebases Drain Your AI Token Budget and How to Fit It

Harshit Rathod — Sun, 05 Jul 2026 13:33:09 +0000

A technical breakdown of where context budget goes in large codebases, and the structural patterns that reduce consumption while increasing accuracy.

Hook: You add a new feature to a large NestJS monorepo with Claude's help. By the end of the conversation, the model has read 40 files, re-derived your module conventions twice, and still got the service placement wrong. You spent thousands of tokens. Claude spent most of them guessing. This guide explains why — and what to do about it.

Key Takeaways

Context windows don't scale with codebases. A large repo has more decisions, more conventions, and more ambiguity — all of which drive up token consumption.
The largest token sinks are re-derivation and uncertainty. Claude reads more files when it doesn't know the architecture; it generates more text when it doesn't know the conventions.
CLAUDE.md is the highest-leverage token saver. A 300-line briefing file can replace hundreds of lines of exploratory file reads per session.
Rules save tokens by preventing regeneration. A wrong pattern that gets corrected costs twice — once to generate, once to fix. A prohibition rule prevents it entirely.
Skills load context on demand. Templates and references in skills only enter the context window when invoked, not on every session.

Quick Answer

Large repositories burn through AI tokens because Claude must read files to infer what any experienced team member already knows: which service owns what, what the error-handling pattern is, how responses are shaped, what's been deliberately removed. Every exploratory read, every wrong-service guess, every pattern that violates a convention and gets corrected is wasted context. The fix is to externalize that tribal knowledge into CLAUDE.md (a briefing loaded every session), rules (prohibitions that prevent wrong output), and skills (on-demand workflows with templates). One-time setup; recurs on every feature.

The Problem: Context Budget Is a Finite Resource

Every token Claude reads or writes is budget spent. Context windows are measured in tokens — not files, not lines — and every session starts with the same ceiling. In a small project, that budget is generous. In a large monorepo with several services, dozens of modules, hundreds of DTOs, and cross-cutting conventions, the budget evaporates fast.

There are two places budget goes:

Input tokens — everything Claude reads: your prompt, files it opens, rules and docs it loads, the running conversation history.
Output tokens — everything Claude generates: code, explanations, corrections, re-generations.

Both are expensive. But in a large repo, the input side is where the hemorrhage starts — because Claude reads aggressively to compensate for what it doesn't know.

Where the Tokens Actually Go

1. Exploratory File Reads

When Claude doesn't know where something lives, it goes looking. In a well-indexed codebase, that might mean reading 3–4 files to locate the right module. In a large monorepo with ambiguous service boundaries, it can mean reading 15–20 before it's confident enough to act.

A typical unconfigured session flow for "add a consumer-visible status to a booking package":

Reads services/ directory listing — orientation
Reads operator-service/src/modules/order/ — wrong service, discovers mismatch
Reads api-service/src/modules/order/ — corrects course
Reads order.entity.ts — finds the shape
Reads order.service.ts — finds the pattern
Reads order.repository.ts — finds the query layer
Reads order.controller.ts — finds the response shape
Reads order.dto.ts — finds the DTO convention
Reads transform-response.helper.ts — finds the adapter pattern
Reads 3–4 more files to verify cross-service adapter usage

That's ~10 file reads before writing a single line of output. Each read costs input tokens. In a large NestJS monorepo, files are not small — services, repositories, and controllers routinely exceed 200–400 lines each.

The same task in a configured session: Claude reads CLAUDE.md, knows the service boundary immediately, reads the 3 directly relevant files, and starts generating. The exploratory reads never happen.

2. Convention Re-derivation

Even when Claude lands in the right file, it still needs to infer your team's conventions. Without explicit documentation, it reads examples to reconstruct patterns:

It reads existing controllers to learn how responses are shaped
It reads existing services to find which logger you use
It reads existing guards to understand your permission system
It reads multiple DTOs to infer your validation patterns

This is pattern-matching by example. It works — but it costs tokens for every session, for every engineer, indefinitely. The conventions don't change; the re-derivation does.

Convention re-derivation cost per session (rough estimate for a large NestJS monorepo):

Convention Claude Must Re-Derive	Files Typically Read	Estimated Token Cost
Service ownership (which belongs where)	3–5 entry points	~2,000–4,000
Response shape and interceptor pattern	2–3 controllers	~1,500–3,000
Permission system (guards + decorators)	2–3 guards/controllers	~1,000–2,000
Error handling (constants + exceptions)	2–3 services	~1,000–2,000
Logger usage	1–2 services	~500–1,000
Import style (alias vs relative)	Several files	~300–600
Total per session (estimation)	~13–18 files	~6,300–12,600 tokens

That's before the prompt, before the output, and before any task-specific reads. It's overhead — pure re-derivation of knowledge your team already has.

3. Wrong-Service Placement and Corrections

When a codebase has multiple services with overlapping domains — say, a package entity that exists in both the operator service (definition) and the consumer API (consumer-visible metadata) — Claude will guess. Sometimes it guesses right. Often it doesn't.

A wrong-service guess costs tokens in three ways:

Exploration in the wrong service — reading module structure, entities, and services in a service that won't receive the change
Generating the wrong output — producing code in the wrong service
Correction — you point out the error; Claude re-reads, re-reasons, and regenerates

In practice, one wrong-service guess can cost more tokens than the correct implementation from the start.

4. Pattern Violations and Regeneration

Without explicit prohibitions, Claude uses its training defaults. Those defaults are reasonable — but they won't match your team's conventions. Common mismatches in NestJS projects:

console.log instead of a structured logger
if (user.roles.includes('admin')) instead of PermissionCodes
Relative ../../ imports instead of the src/ alias
Hardcoded error strings instead of ErrorMessages constants
Raw DB queries in a service instead of going through a repository

Each violation costs tokens twice: once to generate the wrong pattern, once to correct it. A single code generation that needs three corrections has effectively quadrupled the output token cost for that block.

5. Conversation History Accumulation

As a session grows, the running conversation history is included in every subsequent call. In a long debugging or implementation session:

Early file reads stay in context even when they're no longer relevant
Corrections and re-generations add to history
Claude's reasoning about dead ends accumulates

A session that spans 20 exchanges in a large codebase can have a conversation history that alone approaches the token limit of shorter sessions.

The Fix: Externalize Knowledge, Don't Re-Derive It

The underlying cause of excess token consumption is the same in every case: Claude is spending tokens to learn things your team already knows. The fix is to make that knowledge available upfront, in a form Claude can read efficiently, rather than re-deriving it from source files every session.

Three mechanisms do this, each suited to a different type of knowledge:

Mechanism	What it encodes	When Claude reads it	Token impact
`CLAUDE.md`	Architecture, ownership, conventions	Loaded automatically, every session	Replaces exploratory reads
Rules	Hard prohibitions and invariants	Always active; prevents wrong output	Eliminates regeneration cost
Skills	Multi-step workflows + templates	On demand, when invoked	Keeps templates out of always-on context

CLAUDE.md: Replace Exploration With Declaration

CLAUDE.md is the single highest-leverage tool for reducing token consumption. It's loaded at the start of every session, before any file reads, and it replaces the exploratory phase entirely for the information it contains.

The key insight is specificity over completeness. A bloated CLAUDE.md that describes everything about NestJS is worse than a lean one that answers the exact questions Claude would otherwise need to read files to answer:

Which service owns what kind of data?
What does the standard response shape look like?
How does cross-service communication work?
What are the project-specific patterns (logger, errors, permissions)?

A 300-line CLAUDE.md that precisely answers those questions saves more tokens than a 1,000-line one that also explains what a repository pattern is.

What to Include

Service Routing Decision Table

This is the single most effective thing you can document. Instead of Claude reading 10 files to figure out which service owns a new feature, it reads one table:

Which Service Owns What

- operator-service — if the data describes _what an experience is_:
  package definitions, pricing, taxes, availability, operator accounts.
- api-service — if the data describes _a consumer's interaction_:
  bookings, users, auth, trip planning, payments, notifications.

| Task involves...                   | Service                            |
| ---------------------------------- | ---------------------------------- |
| Package categories, pricing, slots | operator-service                   |
| Booking status, user profiles      | api-service                        |
| Stripe payments (consumer side)    | api-service                        |
| Cross-service booking flow         | Start in api-service → IMS adapter |

This table costs ~150 tokens to include in the context. It replaces 2,000–4,000 tokens of exploratory service reads. That's a 10–25× return on every session.

Conventions That Would Otherwise Be Re-Derived

Document only what isn't already obvious from reading a single file:

## What Claude Must Not Do

- `console.log` → use `logMessage()` from `src/common/utils/logger`
- Check `user.role` → use `PermissionCodes` + `@Permissions()`
- DB call inside a loop → use bulk queries (`IN`, `JOIN`)
- Relative `../../` imports → use the `src/` alias
- TypeORM `synchronize: true` → Flyway manages all schema changes

Five prohibitions. ~100 tokens. Replaces all the file reads Claude would do to infer these patterns — and eliminates the regeneration cost when it gets them wrong.

Response Shape

Include the exact shape, not a prose description:

## Standard Response Shape

Controllers return `{ data, meta }`. TransformInterceptor wraps automatically:

return { data: { items }, meta: { path: request.path } };
// → { success: true, data: { items }, meta: { path }, error: null }

Without this, Claude reads 2–3 controllers to infer the pattern. With it, Claude knows immediately — and gets it right the first time.

What to Exclude

The token efficiency of CLAUDE.md depends as much on what you leave out as what you put in:

Framework documentation — Claude already knows what a NestJS guard is. Document only your project-specific guard setup.
Code that's derivable from files — if Claude can read one file and learn a pattern, don't repeat it in CLAUDE.md.
Stable, obvious conventions — use TypeScript, use async/await, follow the module pattern. These are defaults; they cost tokens but add no information.
Task-specific templates — templates belong in skills, not CLAUDE.md. They should enter the context on demand, not every session.

Target: under 300 lines. If your CLAUDE.md is longer, audit it for derivable content. Every line that doesn't prevent a file read or a wrong pattern is a line that should be cut.

Rules: Prevent Regeneration at the Source

A wrong pattern that's regenerated after correction costs twice the tokens of getting it right the first time. Rules cut this cost to zero by making the wrong pattern impossible to generate.

Rules live in .claude/rules/ as Markdown files. They're phrased as prohibitions — not preferences — because "NEVER call the DB in a loop" is enforced, while "prefer bulk queries" is suggestion that gets ignored under pressure.

Token Cost of a Rule vs. a Correction

Consider N+1 queries. Without a rule, here's what happens:

Claude generates code with a DB call inside a loop (output tokens)
You read the generated code and identify the N+1 (your time)
You explain the issue to Claude (input tokens)
Claude re-reads the context to understand the correction (context re-processing)
Claude regenerates the correct bulk-query version (output tokens)

Total: roughly 2× the output tokens for that block, plus the input tokens for the correction exchange.

With a rule:

Rule is in context; Claude generates the correct bulk-query pattern (output tokens)

Total: 1× output tokens.

The rule itself costs ~200 tokens to include in the session. It saves 1× output tokens plus correction overhead on every N+1 occurrence. In a session with 3–4 such violations, it pays for itself many times over.

High-Value Rules for NestJS Projects

Rules that deliver the highest token savings are those that prevent patterns Claude's training considers reasonable but that violate your project's conventions:

N+1 Query Prevention — Claude defaults to per-entity lookups in loops; this stops it:

# Database Query Rules — No N+1

NEVER make a database call inside a loop. Use a single bulk query, then
group results in memory. If unsure whether a pattern causes N+1, ask first.

Permission System — Claude defaults to role-name checks; this redirects it:

# Authorization — Never Check Role Names

NEVER check `user.role`, `user.roles`, or any role-name string.
Use `@Permissions([PermissionCodes.X])` with `PermissionsGuard` instead.

Import Style — Claude defaults to relative imports; this enforces the alias:

# Imports — Always Use the Path Alias

NEVER use relative imports that traverse more than one directory level.
Use `src/modules/...` alias imports everywhere.

Each of these rules costs ~100–200 tokens per session to include. Each saves the token cost of generating a violation plus the correction exchange — conservatively 500–2,000 tokens per occurrence.

Skills: Keep Templates Out of Always-On Context

Skills are on-demand context. Templates, references, and workflow guides for repeated tasks are exactly the kind of high-token content that should not be in CLAUDE.md — because they're only relevant when you're doing that specific task.

A controller template for your NestJS service is ~50–100 lines. In a CLAUDE.md, that's 50–100 lines of context included in every session, even when you're debugging, writing tests, or reading logs. In a skill, those same lines only enter the context when you run /api-development.

Token Budget Impact of Skills

Content	In CLAUDE.md (always loaded)	In a skill (on demand)
Controller template (80 lines)	~400 tokens × every session	~400 tokens × only when invoked
Service template (80 lines)	~400 tokens × every session	~400 tokens × only when invoked
Repository template (60 lines)	~300 tokens × every session	~300 tokens × only when invoked
DTO examples (40 lines)	~200 tokens × every session	~200 tokens × only when invoked
Total	~1,300 tokens per session	~1,300 tokens when you need it

If you scaffold endpoints 3 times a week but run 20 sessions per week, templates in CLAUDE.md cost 20 × 1,300 = 26,000 tokens. In a skill, they cost 3 × 1,300 = 3,900 tokens. Same result, 85% fewer tokens for the templates alone.

Skill Structure

.claude/skills/api-development/
├── SKILL.md                    # Workflow: trigger, steps, decision points
├── assets/
│   ├── controller-template.md  # Real, compilable code templates
│   ├── service-template.md
│   ├── repository-template.md
│   └── dto-template.md
└── references/
    ├── nestjs-conventions.md
    └── swagger-documentation.md

The SKILL.md workflow guides Claude through the task deterministically — DTO first (it defines the contract), then repository (queries only), then service (business logic), then controller (HTTP routing). Without the workflow, Claude invents its own order and sometimes generates the controller before the DTO exists, requiring re-generation.

Architecture: Per-Service CLAUDE.md Files

A monorepo has a root context problem. Everything in the root CLAUDE.md loads every session, regardless of which service you're working in. Details specific to operator-service's DI patterns are wasted tokens when you're debugging auth in api-service.

The fix is a two-level structure:

.claude/CLAUDE.md                   # Cross-cutting: routing, shared conventions
services/
  api-service/CLAUDE.md             # api-service specific: module patterns, auth, DI
  operator-service/CLAUDE.md        # operator-service specific: IMS adapter, pricing

Claude reads the root CLAUDE.md always, and the service-level file when you work in that directory. Cross-cutting concerns (service ownership, response shape, shared error constants) live at root. Service-specific depth (auth flows, module patterns, DI tokens) lives in the service.

Token impact: If each service file is 150 lines (~750 tokens), keeping them separate means you load at most 750 extra tokens per session instead of both services' details at all times. For a multi-service monorepo, that's up to 2,250 tokens of context avoided per session.

Measuring the Impact

Here's the before/after for a realistic "add a consumer-visible booking status" task in a large NestJS monorepo:

Without Configuration

Phase	Token Estimate
Exploratory directory reads (service placement)	~3,000
Convention re-derivation (logger, perms, errors)	~6,000
Wrong-service generation and correction	~4,000
Pattern violations and regeneration (3×)	~3,000
Actual task output (correct code, 4 files)	~4,000
Total	~20,000

With CLAUDE.md + Rules + Skills

Phase	Token Estimate
CLAUDE.md load (routing, conventions, shape)	~1,500
Rules load (3 rules)	~600
Targeted file reads (3 directly relevant files)	~2,500
Skill invocation (templates, workflow)	~1,300
Actual task output (correct code, 4 files)	~4,000
Total	~9,900

~50% reduction in total token consumption for a single task. For a team running dozens of sessions per week, the savings are substantial — and they compound because the ratio stays roughly constant across tasks.

Common Mistakes That Maximize Token Waste

Each of these looks harmless and silently burns budget across every session.

Putting templates in CLAUDE.md. Templates are task-specific. Loading them every session is waste. Move them to skills.
Writing CLAUDE.md as a tutorial. Explaining NestJS fundamentals Claude already knows inflates context without replacing any file reads. Document only what's unique to your project.
Omitting the routing decision table. Service placement ambiguity is the single largest driver of exploratory reads. A table makes the decision free.
Writing rules as preferences. "Prefer bulk queries" leaves Claude room to choose. "NEVER call the DB in a loop" doesn't. The second form prevents regeneration; the first doesn't.
One flat CLAUDE.md for a monorepo. All service-specific content loads every session. Split into root + per-service files.
No cross-service communication rules. Without explicit guidance, Claude reaches across service boundaries — reads the wrong DB, imports across services. The correction exchange is expensive. One sentence in CLAUDE.md prevents it.

Real-World Example: Token Budget on a Feature Request

The request: "Add a consumer-visible status to a booking package."

Unconfigured session token trace:

[read] services/                              ~200 tokens
[read] operator-service/src/modules/order/ ~150 tokens
[read] operator-service order.entity.ts    ~600 tokens  ← wrong service
[read] api-service/src/modules/order/      ~150 tokens  ← course correction
[read] api-service order.entity.ts         ~500 tokens
[read] api-service order.service.ts        ~800 tokens
[read] api-service order.repository.ts     ~600 tokens
[read] api-service order.controller.ts     ~700 tokens
[read] api-service order.dto.ts            ~400 tokens
[read] transform-response.helper.ts          ~300 tokens
[read] ims-adapter.ts                        ~700 tokens
...                                          ~3,000 more (permissions, logger, errors)
[generate] wrong permission check            ~400 tokens
[correction] permission explanation          ~200 tokens
[generate] correct permission                ~200 tokens
[generate] actual implementation (4 files)  ~4,000 tokens
Total: ~12,900 input + ~4,600 output ≈ 17,500 tokens

Configured session token trace:

[load] CLAUDE.md (routing, conventions)      ~1,500 tokens
[load] rules (3 rules)                        ~600 tokens
[invoke] /api-development skill             ~1,300 tokens
[read] api-service order.service.ts        ~800 tokens  ← targeted read
[read] api-service order.repository.ts     ~600 tokens  ← targeted read
[read] ims-adapter.ts                        ~700 tokens  ← targeted read
[generate] implementation (4 files, correct) ~4,000 tokens
Total: ~5,500 input + ~4,000 output ≈ 9,500 tokens

The implementation output is nearly identical. The savings come entirely from eliminating exploratory reads, wrong-service generation, and pattern violations.

Summary: The Token Budget Formula

Token consumption in a large repo follows a predictable formula:

Total tokens = (exploration overhead) + (re-derivation overhead) + (correction overhead) + (actual task output)

Configuration attacks the first three terms:

CLAUDE.md eliminates exploration overhead and most re-derivation overhead
Rules eliminate correction overhead
Skills shift task-specific re-derivation from every-session to on-demand

The actual task output — the code you asked for — is roughly constant. Everything else is overhead, and it's reducible.

FAQ

Why does Claude read so many files in a large repo?
Claude compensates for uncertainty with exploration. When it doesn't know which service owns a feature, it reads multiple services to decide. When it doesn't know your response shape, it reads multiple controllers. CLAUDE.md replaces that uncertainty with declared knowledge, eliminating the reads.

Does a larger CLAUDE.md always save more tokens?
No — the relationship inverts past a threshold. A 300-line CLAUDE.md that answers the right questions saves more tokens than a 1,000-line one that also includes tutorials and templates. The goal is maximum information density per line, not maximum coverage.

How much do wrong patterns actually cost?
A single N+1 query correction in a longer session can cost 500–2,000 tokens: input for your correction message plus output for the re-generation. Across a week of development with multiple sessions, prevention rules pay for themselves quickly.

Can I measure token usage per session in Claude Code?
Claude Code doesn't currently expose per-session token metrics directly. Proxy signals: session length before context compression kicks in, whether you see "context window approaching limit" warnings, and how many file reads appear in the tool call log.

Are skills just macros?
Skills are more than macros — they bundle a workflow (ordered steps, decision points), templates (compilable code), and references (conventions, Swagger patterns) into a single invocable command. The workflow is what prevents out-of-order generation and the correction overhead that comes with it.

Should CLAUDE.md be the same for every engineer on the team?
Yes — commit it to git so the configuration is shared and versioned. Personal overrides go in .claude/settings.local.json, which is gitignored. The team-level conventions in CLAUDE.md apply to everyone.

Does this approach work for repos that aren't NestJS?
The token-saving logic applies to any large codebase with team-specific conventions. The specific content changes (replace NestJS patterns with your stack's patterns), but the structure — CLAUDE.md for routing and conventions, rules for prohibitions, skills for repeated workflows — is framework-agnostic.

Key Takeaways (Recap)

Token waste in large repos has a root cause: Claude reads files to learn what your team already knows. The fix is to tell it upfront.
CLAUDE.md replaces exploration. A service routing table costs ~150 tokens; it replaces 2,000–4,000 tokens of exploratory reads per session.
Rules eliminate regeneration. A prohibition costs ~200 tokens once; it saves 500–2,000 tokens every time the wrong pattern would have been generated.
Skills keep templates off the always-on context. Load them only when you're scaffolding, not in every session.
Split by service. Per-service CLAUDE.md files prevent service-specific context from loading in unrelated sessions.
The savings compound. Every session, every engineer, every feature — the overhead reduction is consistent because the root cause is structural.

Conclusion

Token exhaustion in large repositories isn't a limitation of the AI — it's an information architecture problem. Claude reads aggressively because the knowledge it needs to act confidently isn't in any single file. It re-derives conventions that haven't changed. It generates wrong patterns that get corrected. It explores the wrong service before finding the right one.

The fix isn't a larger context window. It's externalizing your team's tribal knowledge into structured, version-controlled form — a CLAUDE.md that answers the questions Claude would otherwise spend tokens asking, rules that prevent the patterns it would otherwise spend tokens regenerating, and skills that load task-specific context only when you need it.

The investment is a few hours. The savings recur on every session, for every engineer, indefinitely.

Claude Code for NestJS Monorepos: A Practical Setup Guide

Harshit Rathod — Sun, 07 Jun 2026 08:53:54 +0000

A practical, step-by-step guide to configuring Claude Code with CLAUDE.md, rules, and skills so AI-generated code matches your team's conventions in a large NestJS monorepo.

Hook: Ask Claude to "add a consumer-visible status to a booking" in an unconfigured monorepo, and it will happily edit the wrong microservice, hardcode an error string, and check user.role === 'admin'. None of that is Claude being wrong — it's Claude guessing. This guide removes the guessing.

Key Takeaways

Claude Code reads .claude/ from your git root, so one configuration governs every service in the monorepo.
Three mechanisms do the heavy lifting: CLAUDE.md (always-loaded project briefing), rules (hard prohibitions), and skills (multi-step workflows with templates).
The single biggest win is service routing — a decision table in CLAUDE.md stops Claude from putting consumer logic in the operator service.
Write rules as prohibitions, not preferences — "NEVER query the DB in a loop" is enforced; "prefer bulk queries" is ignored under pressure.
Setup is a few hours, one-time, and pays back on every feature: faster scaffolding, fewer convention violations in review, and faster onboarding.

Quick Answer

To set up Claude Code for a NestJS monorepo:
(1) install it with npm install -g @anthropic-ai/claude-code and authenticate once via claude; (2) create a root .claude/CLAUDE.md that documents which service owns what, your request pipeline, and your standard response shape; (3) add a .claude/rules/ folder with hard prohibitions (no N+1 queries, no role-name checks, no relative imports); (4) build a .claude/skills/ folder with multi-step workflows and code templates for repeated tasks like creating an endpoint; and (5) add .claude/settings.json to allow safe commands and deny destructive ones. Commit .claude/ to git so the whole team shares it. The result: Claude generates code that follows your conventions on the first try, instead of guessing.

The Problem: Why Claude Struggles With Large NestJS Projects

A large NestJS monorepo is one of the hardest environments for any AI coding assistant, because correctness depends on conventions that are invisible in any single file. A codebase with dozens of modules, hundreds of DTOs, and custom guards, interceptors, filters, and adapters is genuinely ambiguous. Without context, Claude fills that ambiguity with reasonable defaults — and those defaults won't match your team's conventions.

Concretely, an unconfigured Claude will:

Call the database directly from a service instead of going through a repository
Hardcode error strings instead of using your ErrorMessages constants
Put a new file in the wrong service (booking logic in operator-service when it belongs in api-service)
Check user.role === 'admin' instead of using PermissionCodes
Use console.log instead of your structured logger
Write ../../common/utils instead of the src/ path alias

Why This Problem Exists

These aren't bugs in Claude — they're the predictable result of asking a model to infer team-specific decisions it was never told about. An AI assistant only sees the files it reads in a session; it cannot see why your team removed RolesGuard, that synchronize must stay false, or that two services communicate only over HTTP adapters. Tribal knowledge that lives in your engineers' heads is exactly the knowledge Claude lacks.

The fix is to externalize that tribal knowledge into version-controlled context through three mechanisms, each suited to a different kind of knowledge:

Mechanism	What it encodes	When Claude uses it
`CLAUDE.md`	Architecture, ownership, conventions	Loaded automatically every session
Rules	Hard prohibitions and invariants	Enforced on every code generation
Skills	Multi-step workflows + templates	Invoked on demand for repeated tasks

Repository Structure

Before configuring anything, anchor on the layout. A well-structured NestJS monorepo looks like this:

my-backend/
├── .claude/                  # Everything Claude needs to operate well
│   ├── CLAUDE.md             # Root-level instructions (always loaded)
│   ├── rules/                # Enforced coding constraints
│   ├── skills/               # Custom slash commands with deep context
│   └── settings.json         # Command permissions
├── services/
│   ├── api-service/          # NestJS consumer API (port 5001)
│   ├── operator-service/     # NestJS operator/vendor API (port 5002)
│   ├── chat-service/         # Express + Socket.IO (JavaScript, port 5005)
│   └── job-service/          # Scheduled jobs, no HTTP server
├── db/migration/             # Flyway migrations per schema
└── package.json              # Root: only husky + lint-staged

Each service is an independent NestJS app with its own package.json, tsconfig.json, and build output. Inside each service, every feature module follows the same strict three-layer structure:

src/modules/booking/
├── booking.module.ts
├── controllers/    # HTTP routing only, no logic
├── services/       # Business logic and orchestration
├── repositories/   # TypeORM queries only
└── dtos/           # Request/response shapes, validation

Why it matters: This separation is exactly what Claude needs to respect. If it doesn't know the pattern, it mixes layers — services querying the DB directly, controllers calling repositories.

Suggested visual: a diagram of the git-root .claude/ directory applying across all four services.

Step-by-Step: Configuring Claude Code for NestJS

Step 1 — Install Claude Code

npm install -g @anthropic-ai/claude-code
claude   # opens a browser for one-time OAuth

After authenticating, claude works from any directory. Each developer installs and authenticates independently — there's no shared API key.

Monorepo tip: Claude reads .claude/ from the git root, so its instructions apply no matter where you invoke Claude. When working on one service, cd into it (e.g. services/api-service/) so file searches and commands scope correctly.

Step 2 — Create CLAUDE.md

CLAUDE.md is the single most important file you will write — it's the briefing Claude reads at the start of every session. Think of it as onboarding documentation for a senior engineer on day one. Place it at two levels:

Root .claude/CLAUDE.md — service ownership, shared conventions, the request pipeline
Per-service services/{service}/CLAUDE.md — module patterns, auth, and DI specific to that service

The Root CLAUDE.md

Problem: Claude can't tell which service should own a new file, so it guesses — and lands consumer logic in the operator service.
Solution: A routing decision table plus explicit "never do this" rules.
Result: Files land in the correct service on the first pass.

# CLAUDE.md

## Monorepo Structure

Four services under `services/`, each independently runnable.
Run all commands from inside the service directory.

| Service            | Port | Stack                    | Purpose              |
| ------------------ | ---- | ------------------------ | -------------------- |
| `api-service`      | 5001 | NestJS + TypeScript      | Consumer-facing API  |
| `operator-service` | 5002 | NestJS + TypeScript      | Operator/vendor mgmt |
| `chat-service`     | 5005 | Express + Socket.IO + JS | Real-time messaging  |
| `job-service`      | —    | Node.js + TypeScript     | Scheduled jobs       |

## Which Service Owns What

- **operator-service** — if the data describes _what an experience is_:
  package definitions, pricing, taxes, availability, operator accounts.
- **api-service** — if the data describes _a consumer's interaction_:
  bookings, users, auth, trip planning, payments, notifications.

| Task involves...                   | Service                            |
| ---------------------------------- | ---------------------------------- |
| Package categories, pricing, slots | operator-service                   |
| Booking status, user profiles      | api-service                        |
| Stripe payments (consumer side)    | api-service                        |
| Cross-service booking flow         | Start in api-service → IMS adapter |

## Global Request Pipeline (in order)

1. `TraceContextMiddleware` — sets `correlationId` in `AsyncLocalStorage`
2. `ValidationPipe` — whitelist mode, flattens DTO errors
3. `LoggerInterceptor` — logs request/response
4. `TransformInterceptor` — wraps return value in the standard shape
5. Exception filters (`HttpExceptionFilter`, `TypeOrmExceptionFilter`, …)

## Standard Response Shape

Controllers return `{ data, meta }`; `TransformInterceptor` wraps it:
return { data: { items }, meta: { path: request.path } };
// → { success: true, data: { items }, meta: { path }, error: null }

## Cross-Service Communication

api-service NEVER touches operator-service's database. All reads/writes go
through HTTP adapters in `src/common/adapters/` (they handle OAuth refresh and
trace propagation). Need operator data? Call the adapter, never the DB.

## What Claude Must Never Do

- Use `console.log` → use `logMessage()` from `src/common/utils/logger`
- Check `user.role` → use `PermissionCodes` + `@Permissions()`
- Query the DB inside a loop → use bulk queries (`IN`, `JOIN`)
- Use relative `../../` imports → use the `src/` alias
- Set TypeORM `synchronize: true` → Flyway manages all schema changes

What makes a good CLAUDE.md:

Decision rules over directory listings. "If the data describes what an experience is, it lives in operator-service" lets Claude resolve ambiguity without asking you.
Include the response shape. Otherwise Claude manually wraps responses in every controller, creating inconsistencies.
List what NOT to do. "Never use console.log" is more actionable than "use our logger."
Document what was removed. When you delete a RolesGuard or a synchronize flag, say why — or Claude will reintroduce it because it looks natural.

Service-Level CLAUDE.md

Each service gets its own file for details too specific for the root:

# api-service/CLAUDE.md

## Module Architecture — never mix layers

controllers/ HTTP routing only — call service, return data
services/ Business logic — orchestrate repos, no direct DB calls
repositories/ TypeORM queries only — accept EntityManager for transactions

## Authentication

- `JwtAuthGuard` validates Bearer tokens, attaches `UserRequest`
- `PermissionsGuard` reads `@Permissions([PermissionCodes.X])`
- Never use RolesGuard or check role names — removed intentionally

## Dependency Injection

Register services by interface token, and inject by token, not class:
{ provide: SERVICE_INTERFACE.BOOKING_SERVICE, useClass: BookingService }

## Background Jobs

BullMQ + Redis. Processors live in `src/modules/{module}/processors/`.
Enqueue via the module's service — never from a controller.

Step 3 — Add Rules

Rules are hard prohibitions — they don't describe architecture, they prevent specific patterns, like an ESLint config for AI-generated code. They live in .claude/rules/ as Markdown files.

Use `CLAUDE.md` for	Use `rules/` for
Architecture, module structure	Hard prohibitions
Service ownership decisions	Patterns Claude must never emit
Conventions, command reference	Security / performance invariants

Rule: Prevent N+1 Queries

Problem: N+1 queries are easy to introduce and slip through review.
Solution: a prohibition rule with a correct bulk-query pattern.
Result: Claude writes the bulk query at generation time — the bug is never created.

.claude/rules/database-queries.md

// Wrong — N queries
for (const b of bookings) {
  b.user = await this.userRepo.findOne(b.userId);
}

// Correct — one query
const users = await this.userRepo.find({ where: { id: In(userIds) } });
const userMap = new Map(users.map((u) => [u.id, u]));
bookings.forEach((b) => {
  b.user = userMap.get(b.userId);
});

Rule: Permission Checks

.claude/rules/permissions.md

// Wrong
if (user.roles.includes('admin')) { ... }

// Correct
@Permissions([PermissionCodes.MANAGE_BOOKINGS])
@UseGuards(JwtAuthGuard, PermissionsGuard)

Why: role names get merged, split, and renamed; checks against them break
silently. PermissionCodes are stable constants that survive role
restructuring. Import from src/common/constants/permissions.constant.ts.

Rule: Import Style

.claude/rules/imports.md

// Wrong
import { UserService } from "../../services/user.service";
// Correct
import { UserService } from "src/modules/user/services/user.service";

The src/ alias is configured in tsconfig.json (baseUrl: "./") and Jest's
moduleNameMapper. Use it everywhere.

Other Rules Worth Defining

The same prohibition pattern applies to many recurring NestJS pitfalls. A few more rules worth their own file:

Error handling — always throw from ErrorMessages/ResponseCodeKeys constants and use NestJS exceptions; never hardcode strings or return raw error objects.
Logging — use the structured logMessage() helper at the right level; never console.log.
Transactions — multi-write operations must run in a single EntityManager transaction; never fire independent writes that can half-commit.
DTO validation — every request DTO needs class-validator decorators; the ValidationPipe whitelist drops anything undecorated, so missing decorators silently lose data.
Entity ↔ migration parity — any entity change needs a matching Flyway migration; synchronize stays false.
Swagger coverage — every endpoint carries @ApiSpec + a typed response DTO so the generated docs stay accurate.

Step 4 — Build Skills

Skills are project-specific slash commands that bundle a workflow, code templates, and references — they turn a repeated multi-file task into one command. Write one for any repeated, multi-step task: building an endpoint, writing a migration, scaffolding a module, reviewing a PR.

Skill Structure

.claude/skills/api-development/
├── SKILL.md                    # Workflow, trigger, steps
├── assets/
│   ├── controller-template.md
│   ├── service-template.md
│   ├── repository-template.md
│   └── dto-template.md
└── references/
    ├── nestjs-conventions.md
    └── swagger-documentation.md

Writing SKILL.md

# API Development Skill

## Trigger

Invoke with `/api-development` when building or modifying a NestJS endpoint.

## Workflow

1. **Determine service & module** — check CLAUDE.md routing; ask if ambiguous.
2. **Read what exists** — entities, repositories, DTOs already in the module.
3. **Generate the DTO first** — it defines the contract. class-validator
   decorators; extend `PaginationRequestDTO` for lists.
4. **Generate the repository** — inject `DataSource`; accept an optional
   `EntityManager` for transactions; queries only, no logic.
5. **Generate the service** — inject the repository interface token; use
   `ErrorMessages` constants; throw `NotFoundException` etc.
6. **Generate the controller** — `@ApiSpec` + `@ApiOkResponse`; return
   `{ data, meta }`; no business logic.
7. **Wire the module** — add to `providers`, export by interface token.

Asset Template (example)

Templates should be real, compilable code — not pseudocode. assets/controller-template.md:

@ApiTags("bookings")
@Controller("bookings")
export class BookingController {
  constructor(
    @Inject(SERVICE_INTERFACE.BOOKING_SERVICE)
    private readonly bookingService: IBookingService,
  ) {}

  @Post()
  @UseGuards(JwtAuthGuard, PermissionsGuard)
  @Permissions([PermissionCodes.CREATE_BOOKING])
  @ApiSpec({ summary: "Create a new booking" })
  @ApiCreatedResponse({ type: CreateBookingSuccessDto })
  async createBooking(
    @Body() dto: CreateBookingDto,
    @Req() req: UserRequest,
  ): Promise<{ data: BookingEntity }> {
    const booking = await this.bookingService.createBooking(dto, req.user.id);
    return { data: booking };
  }
}

With this skill, a complete endpoint (controller + service + repository + DTOs, wired into the module) takes under 3 minutes instead of ~20 — and matches your conventions on the first try.

Other Skills Worth Building

Any repeated, multi-step workflow with team-specific conventions is a skill candidate. Beyond endpoint scaffolding:

Migration generator — scaffold a Flyway migration in the right schema folder with your versioning and naming convention, plus the matching entity change.
Module scaffolder — generate a full module skeleton (module file, three layers, DI tokens) wired and ready.
PR review — review a diff against your conventions: N+1 checks, permission usage, layer boundaries, missing tests.
Test generator — produce *.spec.ts files following your mocking and fixture patterns for a given service.
Cross-service adapter — generate a new IMS adapter method plus its response interface and transform helper.
Use-case / BDD docs — turn a requirement into user stories with Given/When/Then acceptance criteria.

Step 5 — Configure Settings & Permissions

.claude/settings.json controls which Bash commands run without a permission prompt. Allow read-only and safe test/lint operations freely; deny anything destructive.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(npx jest *)"
    ],
    "deny": ["Bash(rm -rf *)", "Bash(git push *)", "Bash(git reset --hard *)"]
  }
}

File	Applies to	Committed
`.claude/settings.json`	Everyone on the team	Yes
`.claude/settings.local.json`	You only (overrides)	No (gitignored)

Best Practices

Best Practice callout: Treat .claude/ as production code. It ships your conventions to every engineer and every AI session — review it, version it, and prune it like any other source.

Keep CLAUDE.md under ~300 lines. Context has a cost; a bloated file crowds out the code Claude needs to read. If it's derivable from the code, cut it.
Write rules as prohibitions, not guidance. "NEVER call the DB in a loop" is enforced; "prefer bulk queries" is ignored under pressure.
Put templates in skills, not CLAUDE.md — they should load only when the skill is invoked, not on every session.
Version .claude/ in git. It's part of your codebase: same review, same history. New rules get PRs; stale rules get deleted.
Use decision tables liberally. Anywhere two reasonable choices exist — DTO placement, entity location, service boundaries — a table beats prose.

Recommended `.claude/` layout

.claude/
├── CLAUDE.md                  # Root guide (<300 lines)
├── settings.json              # Team permissions (committed)
├── rules/
│   ├── database-queries.md    # No N+1
│   ├── permissions.md         # PermissionCodes, no role checks
│   └── imports.md             # src/ alias only
└── skills/
    └── api-development/
        ├── SKILL.md
        ├── assets/            # controller/service/repository/dto templates
        └── references/        # conventions, swagger

Common Mistakes

⚠️ Each of these silently degrades output quality — Claude will look like it's working while quietly violating your conventions.

Writing CLAUDE.md as a tutorial. Don't explain what NestJS is — Claude knows. Document only what's unique to your project: module names, error constants, response shape, permission system.
Omitting negative rules. Telling Claude what not to do prevents whole classes of mistakes. The expensive errors are the ones that look correct but violate your patterns.
Cramming everything into the root CLAUDE.md. It loads in every session. Split service-specific depth into per-service files so it doesn't pollute context when you're elsewhere.
No routing decision table. Wrong-service placement comes from ambiguity, not ignorance. A table makes the decision deterministic.
Forgetting the cross-service adapter pattern. In an HTTP-linked monorepo, Claude will try to import across services or query the other DB. Spell out that all cross-service calls go through adapters.
Not mentioning synchronize: false. Claude assumes TypeORM manages the schema. If you use Flyway, entity changes without a matching migration fail silently — say so explicitly.

Real-World Example: Adding a Consumer-Visible Booking Status

A walkthrough of how a configured setup changes one real task.

The request: "Add a consumer-visible status to a booking package."

Without configuration, Claude reasons: "packages live in operator-service," and edits the package entity there — the wrong service. It hardcodes the status string, and adds an if (user.roles.includes('admin')) guard.

With configuration, here's the chain:

Routing table in CLAUDE.md tells Claude that consumer-visible status describes a consumer interaction → it belongs in api-service, not operator-service.
Cross-service rule reminds it the operator's package definition is read via an IMS adapter, so it adds the field to the adapter's transform — not by reaching into the other DB.
/api-development skill scaffolds the DTO, repository method, service logic, and controller in the right order.
Permission rule makes it emit @Permissions([PermissionCodes.VIEW_BOOKING_STATUS]) instead of a role check.
Error rule makes it throw NotFoundException with an ErrorMessages constant.

One ambiguous sentence, resolved into correct, convention-matching code across four files — without a single clarifying question.

Results & Metrics

A few hours of one-time setup changes the day-to-day in measurable ways:

Before	After
Review every generated file for hardcoded strings, wrong imports, role checks	Rules make those impossible — review focuses on logic, not conventions
New endpoint ≈ 20 min wiring four layers by hand	`/api-development` scaffolds + wires it in under 3 min
Files landed in the wrong service, caught late in review	Routing table places them correctly on the first pass
N+1 queries and `console.log` slipped into PRs	Caught at generation time, never written
New hires guessed at module boundaries and patterns	CLAUDE.md teaches the conventions implicitly on day one

Compounding wins that don't show up in a single PR:

Consistency. Code generated months apart looks the same, because it comes from the same templates and rules — not from whatever Claude inferred that day.
Less review fatigue. Reviewers stop flagging the same convention violations and spend attention on actual design.
Faster onboarding. Routing tables and rules are documentation that also executes — a new engineer's first AI-assisted feature already follows house style.
Lower context cost. A tight CLAUDE.md plus on-demand skills means Claude spends its context budget reading your code, not re-deriving conventions every session.

Extractable insight: The investment pays for itself within the first few features and keeps paying on every one after — because the cost is one-time and the benefit recurs on every task.

FAQ

What is CLAUDE.md?
CLAUDE.md is a Markdown file Claude Code reads automatically at the start of every session. It briefs the AI on your project's architecture, conventions, and prohibitions — the equivalent of onboarding docs for a new engineer.

Where should CLAUDE.md go in a monorepo?
Put a root .claude/CLAUDE.md at the git root for cross-cutting concerns (service ownership, shared conventions), and a CLAUDE.md inside each service for service-specific patterns. Claude reads the root first, then the service-level file when you work in that directory.

What's the difference between CLAUDE.md and rules?
CLAUDE.md describes architecture and conventions; rules (in .claude/rules/) are hard prohibitions Claude must never violate. Use CLAUDE.md for "here's how things work" and rules for "never do this," such as banning N+1 queries or role-name checks.

How do Claude Code skills work?
A skill is a project-specific slash command (e.g. /api-development) backed by a SKILL.md workflow plus code templates and references. Invoking it makes Claude follow a deterministic, multi-step process — like scaffolding a full NestJS endpoint across four files.

How long should CLAUDE.md be?
Aim for under ~300 lines. Context is finite, and a bloated file crowds out the actual code Claude needs to read. Document only what isn't derivable from the codebase itself.

Does Claude Code work with a NestJS monorepo of multiple services?
Yes. Claude reads .claude/ from the git root, so one configuration governs every service. A routing decision table in CLAUDE.md tells Claude which service owns which kind of data.

How do I stop Claude from writing N+1 queries or role-based permission checks?
Add prohibition rules in .claude/rules/. A database-queries.md rule bans DB calls inside loops; a permissions.md rule bans user.role checks in favor of PermissionCodes and @Permissions().

Should I commit the .claude directory to git?
Yes — commit .claude/CLAUDE.md, rules/, skills/, and settings.json so the whole team shares the same configuration. Keep personal overrides in .claude/settings.local.json, which is gitignored.

Key Takeaways (Recap)

Claude struggles in large NestJS monorepos because correctness depends on conventions invisible in any single file.
Externalize that knowledge with CLAUDE.md (briefing), rules (prohibitions), and skills (workflows) — all committed to git.
The service-routing decision table is the highest-leverage thing you can write.
Rules phrased as prohibitions are enforced; preferences are not.
Setup is a few hours, one-time, and compounds across every feature and every new hire.

Conclusion

Setting up Claude Code for a NestJS monorepo isn't about making Claude smarter — it's about eliminating guesswork. A codebase with dozens of modules, hundreds of DTOs, and custom guards and adapters is genuinely ambiguous without context, and Claude's reasonable defaults won't match your conventions.

The investment is small and one-time: a focused CLAUDE.md for routing and prohibitions, a few rules files for hard constraints, and one or two skills for your most repeated tasks. After that, Claude generates code that looks like your team wrote it — not like someone who just read the NestJS docs.

DEV Community: Harshit Rathod

Why Large Codebases Drain Your AI Token Budget and How to Fit It

Key Takeaways

Quick Answer

The Problem: Context Budget Is a Finite Resource

Where the Tokens Actually Go

1. Exploratory File Reads

2. Convention Re-derivation

3. Wrong-Service Placement and Corrections

4. Pattern Violations and Regeneration

5. Conversation History Accumulation

The Fix: Externalize Knowledge, Don't Re-Derive It

CLAUDE.md: Replace Exploration With Declaration

What to Include

Service Routing Decision Table

Conventions That Would Otherwise Be Re-Derived

Response Shape

What to Exclude

Rules: Prevent Regeneration at the Source

Token Cost of a Rule vs. a Correction

High-Value Rules for NestJS Projects

Skills: Keep Templates Out of Always-On Context

Token Budget Impact of Skills

Skill Structure

Architecture: Per-Service CLAUDE.md Files

Measuring the Impact

Without Configuration

With CLAUDE.md + Rules + Skills

Common Mistakes That Maximize Token Waste

Real-World Example: Token Budget on a Feature Request

Summary: The Token Budget Formula

FAQ

Key Takeaways (Recap)

Conclusion

Further Reading

Claude Code for NestJS Monorepos: A Practical Setup Guide

Key Takeaways

Quick Answer

The Problem: Why Claude Struggles With Large NestJS Projects

Why This Problem Exists

Repository Structure

Step-by-Step: Configuring Claude Code for NestJS

Step 1 — Install Claude Code

Step 2 — Create CLAUDE.md

The Root CLAUDE.md

Service-Level CLAUDE.md

Step 3 — Add Rules

Rule: Prevent N+1 Queries

Rule: Permission Checks

Rule: Import Style

Other Rules Worth Defining

Step 4 — Build Skills

Skill Structure

Writing SKILL.md

Asset Template (example)

Other Skills Worth Building

Step 5 — Configure Settings & Permissions

Best Practices

Recommended .claude/ layout

Common Mistakes

Real-World Example: Adding a Consumer-Visible Booking Status

Results & Metrics

FAQ

Key Takeaways (Recap)

Conclusion

Further Reading

Recommended `.claude/` layout