Running AI Agents in Large Monorepos

The problem with big repos

A monorepo often holds many subprojects: a backend, a frontend, shared libraries. One single CLAUDE.md for everything either grows huge (eating up context on every session, even for tasks that don't need it) or stays so generic it barely helps.

The fix: multiple CLAUDE.md files

Instead of one file for everything, give each subproject its own CLAUDE.md. A file at the repo root holds rules that apply everywhere (commit style, overall layout). Each subproject gets its own file with its specific commands and conventions.

How loading actually works

Start the agent at the repo root, and it loads only the root CLAUDE.md at launch; files in subfolders load only once the agent actually reads files there. Start it directly inside a subproject, and it gets that folder's file plus every parent one — but by default only file access to that subtree.

Forcing focus

For tasks that clearly belong to one subproject, it pays to start the agent right there instead of at the root. That keeps context and file access narrow automatically, without you having to explain on every task which parts of the repo are irrelevant right now.