Design CLAUDE.md Hierarchies, Imports, and Path-Scoped Rules

Quick answer

Keep the root CLAUDE.md short and universal: architecture boundaries, authoritative commands, critical safety rules, and links to deeper references. Put package-specific guidance near the package or in path-scoped rules, use imports for maintained source documents, and delete instructions Claude can discover reliably from code. Audit for contradictions and stale commands. Anthropic's memory documentation defines current loading and hierarchy behavior.

Write instructions that change behavior

High-value instructions answer questions the repository cannot safely answer by inspection:

• Which command is authoritative for test, build, lint, and generation?
• Which boundaries must never be crossed?
• Which files are generated or sensitive?
• What compatibility and migration policy applies?
• What must be verified before completion?
• Which seemingly obvious approach is wrong here, and why?

Low-value instructions restate directory names, programming basics, or generic advice such as “write clean code.” Every line competes for attention at session start.

A practical root file

# Repository operating rules

## Architecture
- `apps/` may depend on `packages/`; packages may not import from apps.
- Domain code must not import provider SDKs; use adapters in `infra/`.

## Commands
- Focused test: `pnpm test -- <path>`
- Typecheck: `pnpm typecheck`
- Production build: `pnpm build`

## Safety
- Never edit `generated/`; run `pnpm generate` from its source schema.
- Do not run migrations, deployments, pushes, or external writes without approval.
- Preserve unrelated working-tree changes.

## Completion
- Run the focused test, typecheck, and relevant integration check.
- Report checks not run and why.

Make commands copy-pasteable and avoid environment-specific absolute paths.

Layer instructions by scope

In a monorepo, the root file should not contain every framework convention. Add a package-level CLAUDE.md for genuinely local guidance, or use .claude/rules/ files with path targeting where supported. Examples:

• UI accessibility and screenshot checks only for apps/web/**.
• Transaction rules only for services/billing/**.
• Documentation voice only for docs/**.
• Generated-client policy only for packages/api-client/**.

When multiple layers apply, verify that narrower guidance refines rather than contradicts the root. If conflict is intentional, state the exception explicitly.

Import maintained truth

If the authoritative architecture or workflow already exists in a reviewed document, import or reference it rather than duplicating text. Keep imported material concise enough for startup context. Large API references belong in on-demand skills or documentation tools, not persistent memory.

Never import a file merely because it exists. The imported content gains the same influence as hand-written instructions and can become an injection or staleness vector.

Test the instruction set

Use a fresh session and ask:

Without editing, state the commands and rules that apply to changing
apps/web/src/checkout/Button.tsx. Cite the instruction source for each.
Identify contradictions or missing verification requirements.

Then give Claude a representative task and watch whether it chooses the expected commands and avoids forbidden files. Instructions are operational configuration; test their behavior after changes.

FAQ

Should CLAUDE.md contain the full architecture?

No. Include the boundaries needed for daily decisions and link to maintained detail.

How often should instructions be reviewed?

Review alongside build-system, architecture, and onboarding changes, plus a scheduled staleness audit.

Can CLAUDE.md enforce security?

It influences model behavior but is not an enforcement boundary. Use permissions, sandboxing, hooks, and infrastructure policy for enforcement.