How I Structure Claude Code Projects for a Multi-Service Monorepo
A deep dive into configuring Claude Code for monorepos with multiple apps, shared libraries, and different conventions per package. Covers CLAUDE.md hierarchy, .claude/rules/ with path patterns, scoping Claude's attention, and CI/CD integration.
Quick Reference
- →Use a root CLAUDE.md for global conventions + per-package CLAUDE.md for package-specific rules
- →Put path-scoped rules in .claude/rules/ to target specific packages automatically
- →Scope Claude's attention: 'Only look at the apps/api package for this task'
- →Each package can have its own build, test, and lint commands in its CLAUDE.md
- →Use 'What packages are affected by this change?' to understand cross-package impact
- →Keep shared types in a dedicated package and reference it from CLAUDE.md
- →Run Claude Code checks per package in CI to keep feedback fast and focused
- →Use worktrees or separate sessions for parallel work on different packages
The Monorepo Challenge for AI Tools
Monorepos are increasingly common — a single repository containing multiple applications, shared libraries, infrastructure code, and configuration. For a developer, this structure offers code sharing and atomic changes. For an AI coding tool, it presents a unique challenge: different parts of the repo have different languages, frameworks, conventions, and build systems. Without explicit configuration, Claude Code treats the entire monorepo as one undifferentiated codebase and may apply the wrong conventions to the wrong package.
In a monorepo, the React component conventions for apps/web are completely different from the Express middleware patterns in apps/api. Claude needs to know which rules apply where. Without this, it will suggest React hooks in your API code or Express middleware patterns in your frontend.