Skip to content
Irregularpedia Logo Irregularpedia

Directory-Scoped CLAUDE.md Files

Directory-Scoped CLAUDE.md Files

Section titled “Directory-Scoped CLAUDE.md Files”

When using Claude Code in a monorepo or multi-package repository, place a CLAUDE.md file at each meaningful directory level instead of putting all instructions in the repository root.

Section titled “Recommended pattern”
  • Keep broad rules in the root CLAUDE.md.
  • Add more specific CLAUDE.md files in subdirectories such as apps/ or apps/app/workers/.
  • Claude Code loads these progressively as it navigates deeper into the directory tree, so lower-level rules can refine higher-level ones.

Benefits

Section titled “Benefits”
  • Lean context: Only the conventions relevant to the current work area are loaded.
  • Locality: Rules live next to the code they govern, which makes them easier to maintain.
  • Scalability: This pattern works well for monorepos and other large codebases.

Practical guidance

Section titled “Practical guidance”

Treat CLAUDE.md files similarly to README.md files: use one per directory that has its own concerns.

Source: Contributed from IrregularChat discussion