CLAUDE.md · Free worked guide
CLAUDE.md for Monorepos: Scope and Examples
Structure CLAUDE.md guidance in a monorepo so root rules stay stable and package-specific commands remain close to their code.
By ClaudeQuest · Reviewed · Independent learning material
How should CLAUDE.md work in a monorepo?
Keep organization-wide navigation, boundaries, and shared verification at the root. Put package-specific architecture and commands in scoped guidance near that package, avoiding contradictions and duplicated rules.
Decision rule: Place an instruction at the narrowest scope that still covers every task needing it.
Use it in a real situation
A monorepo contains a Next.js app, a Python service, and shared schemas with different test runners.
- Name the observable outcome and the constraint that changes the decision.
- Choose the smallest action that can produce useful evidence.
- Keep permissions, uncertainty, and side effects visible before execution.
- Run a check that could disprove the approach, then record what remains unknown.
Original ClaudeQuest worked example
From vague request to reviewable result
Task or input
Root guidance explains package discovery and cross-package change rules; each package names only its verified local checks and ownership boundaries.
Better result
A UI task does not inherit irrelevant Python commands, while a schema change still triggers the documented cross-package checks.
How to verify it
Run one task in each package and one shared-schema task; inspect which guidance is loaded and whether commands remain accurate.
Three mistakes to avoid
Copying without adaptation. Replace repository, data, user, and authority assumptions with facts from your environment.
Treating prose as enforcement. Use permissions, validation, tests, and human approval for boundaries that must hold.
Calling one success proof. Re-test the decision with a different input or context before treating it as a durable skill.
Related CLAUDE.md guides
Source and scope
Primary technical reference: Claude Code memory documentation. Source reviewed September 13, 2026. Product capabilities can change; verify time-sensitive details against the current primary documentation.
The scenario and worked example are original ClaudeQuest learning material. ClaudeQuest is independent of Anthropic and does not guarantee tool performance, certification results, or professional outcomes.
Read the editorial and evidence method →