CLAUDE.md in Monorepos: A Tree of Context Files

1/23/2026

The Pattern

Are you using the monorepo pattern?

I use Claude Code to do all sorts of stuff:

Build my branding website which is an Astro statically generated website.
Claude wrote my ruby indexer.
Manages my infrastructure with Teraform.
Help me do research for youtube videos and create thumbnails.

I want everything in one place.

If you have worked with split architectures: ie, React frontend + Rails backend you are probably familiar with versioning issues. Instead of struggling to keep different apps in sync (version wise), put both apps in the same version controller project. Do both the backend and frontend changes on the same branch, then merge and deploy at the same time.

Docker Compose handles this perfectly well from an infrastructure perspective.

How do you deal with it from a CLAUDE.md perspective, how to keep claude’s context focussed on each part of the project?

In a monorepo, you can have multiple CLAUDE.md files at different levels:

project/
├── CLAUDE.md              # Root - project overview, shared standards
├── website/
│   └── CLAUDE.md          # Website-specific context
├── api/
│   └── CLAUDE.md          # API-specific context
└── react/
    └── CLAUDE.md          # React frontend

How It Works

Claude reads CLAUDE.md files based on your current working directory:

Working in project/ → reads root CLAUDE.md
Working in project/website/ → reads both root AND website/CLAUDE.md

The top-level claude file can have a 1-liner to explain what the sub-projects are and how to find their CLAUDE.md.

Then if you do run claude from the top-level dir, and you tell Claude:

Lets work on the website

Claude will know where that dir is, where its CLAUDE.md file is and how to load it.

Child Claude.md files can reference the top-level CLAUDE.md file also - to give broader context:

# Website

**Parent context:** See `../CLAUDE.md` for project-wide standards.

This helps a bunch when working on the API for instance - and then asking Claude to help you build the frontend. Claude moves seamlessly from one CLAUDE.md file to the other.

Keep It Lean

Each CLAUDE.md file should contain only what’s relevant to that scope. Don’t repeat parent info - reference it.

Audit Your Tree

The claude-md-best-practices plugin will audit your CLAUDE.md in whatever directory you run it in.

This allows you to check your whole Claude.md tree:

# Audit root
/gsd:claude-md-bp

# Audit website sub-context
cd website
/gsd:claude-md-bp

# Audit api sub-context
cd ../api
/gsd:claude-md-bp

Each run checks the CLAUDE.md in that directory against the 18-point checklist. Ensures consistency across your monorepo.

Subscribe to Skills Weekly, a digest of the hottest plugins & industry news. Only one email a week.

Want to unsubscribe?

We respect your privacy. Unsubscribe anytime. Privacy Policy

← Back