/
← L3: Tool Use for Reliable Structured Output L5: Custom Slash Commands and Skills →
Module 5 — AI Powered Code Gen & Engg Standards

L4: CLAUDE.md Configuration Hierarchy

L4: CLAUDE.md Configuration Hierarchy

CLAUDE.md Configuration Hierarchy

In Module 0, we introduced Claude Code as an agentic, terminal-based coding assistant. However, out of the box, Claude Code lacks context about your specific project. It doesn't know if you prefer npm over yarn, if your team uses strict TypeScript interfaces, or how to build your unique architecture.

As an architect, you solve this by implementing CLAUDE.md. This lesson covers how to structure these configuration files across complex, multi-service enterprise repositories.

1. What is CLAUDE.md?

CLAUDE.md is an invisible but critical bridge between human developers and the AI agent. It is a standard Markdown file placed in your file system that Claude Code automatically reads every time it boots up in a directory.

Architectural Purpose:

It acts as a dynamic System Prompt. The contents of CLAUDE.md are silently prepended to the context window of your Claude Code session. It dictates:

  • Build/Run Commands: (e.g., "Always use npm run dev to test frontend changes").

  • Coding Standards: (e.g., "Never use var. Always prefer functional components over class components.")

  • Architectural Boundaries: (e.g., "The /lib folder is strictly for pure functions; do not write stateful logic here")

2. The Three-Tier Configuration Hierarchy

Enterprise codebases are rarely flat. You might have a Python backend, a React frontend, and infrastructure-as-code in the same repository. A single set of rules won't work. Therefore, Claude Code respects a strict cascading hierarchy , reading files from the bottom up.

  • Level 1: The Directory Level (Deepest)

    • Location: Inside a specific subfolder (e.g., /project/frontend/CLAUDE.md).

    • Purpose: Rules that apply only to that specific microservice or module.

  • Level 2: The Project Level (Root)

    • Location: At the root of your Git repository (e.g., /project/CLAUDE.md).

    • Purpose: Global repository standards, primary build commands, and architectural overviews that apply to the whole app.

  • Level 3: The User Level (Global)

    • Location: In your user's home directory (e.g., ~/.claude.md on macOS/Linux).

    • Purpose: Your personal developer preferences (e.g., "Always explain code changes concisely," or "Use Vim keybindings in terminal output").

3. Resolution Logic (How Rules Merge)

When you run the claude command inside /project/frontend/src, Claude Code traverses upward. It reads the User level, then the Project level, and finally the Directory level.

The Golden Rule of Overrides: Specificity wins. * If your Global config says "Use Python 3.10" but the Project config says "Use Python 3.12," the Project config overrides the global one.

  • If your Project config says "Use npm" but the Frontend directory config says "Use yarn," the Directory config wins for any actions taken inside that folder.

  • Architectural Note: The files are concatenated. The deepest file is placed closest to the bottom of the system prompt, giving it the highest algorithmic weight when the LLM makes a decision.

4. The @import Directive (Modular Configuration)

For massive enterprise teams, copying and pasting the same CLAUDE.md across 50 different microservice repositories is an anti-pattern. If a core security standard changes, you would have to update 50 files.

To solve this, architects use the @import directive.

Inside a CLAUDE.md file, you can reference external or shared markdown files:

Markdown

# Local Frontend Rules
Always use Tailwind CSS.

# Corporate Standards
@import "../shared-org-rules/security-standards.md"
@import "../shared-org-rules/api-guidelines.md"

When Claude Code reads this file, it dynamically resolves the @import paths and pulls the text from those shared files into its context window. This allows a central architecture team to maintain a single source of truth for coding standards while allowing individual squads to maintain their own local rules.

5. Best Practices & Token Economy

Because CLAUDE.md is prepended to the system prompt, it consumes tokens on every single interaction in your session.

  • Be Concise: Do not paste entire software engineering textbooks into CLAUDE.md. Write clear, dense, bulleted instructions.

  • No Secrets: NEVER put API keys, passwords, or database URIs in CLAUDE.md. It is meant to be committed to version control. If Claude Code needs an API key to run a script, instruct it to read from a local .env file instead.

  • Use Clear Headings: Use standard markdown headers (## Build Commands, ## Style Guide) so the LLM can quickly index the file and jump to the relevant section when needed.