CLAUDE.md Configuration Cascade

Run the CLAUDE.md Cascade MicroSim Fullscreen

Edit the MicroSim in the p5.js Editor

You can include this MicroSim on your website using the following iframe:

<iframe src="https://yarmoluk.github.io/Digital-Transformation-with-AI-Spring-2026/sims/claude-md-hierarchy/main.html" height="612px" width="100%" scrolling="no"></iframe>

Description

This MicroSim demonstrates how CLAUDE.md configuration files work in Claude Code — Anthropic's AI coding assistant. CLAUDE.md files act like .editorconfig or .eslintrc but for AI behavior, telling Claude what conventions, constraints, and preferences to follow.

The 4-Layer Cascade

Rules are loaded in this order, with each layer adding to (and potentially overriding) the previous:

Order	Layer	Path	Scope
1	Enterprise	/etc/claude/CLAUDE.md	Organization-wide policies
2	User	~/.claude/CLAUDE.md	Personal global preferences
3	Project	<repo>/CLAUDE.md	Repository-specific conventions
4	Local	<repo>/.claude/CLAUDE.md	Machine-specific overrides (gitignored)

How to Use

1. Click any project tile on a computer in the left panel
2. Click "Next Layer" to step through each cascade level
3. Observe how rules accumulate from enterprise down to local
4. Compare the same project across different computers to see how enterprise and local rules differ
5. Use "Auto Play" to watch the full cascade animate automatically

Key Insights

• Enterprise rules exist on Work Laptop and Cloud Server but not Home Desktop (personal machine)
• Project rules are identical across all computers (they live in the repo and are version-controlled)
• User rules differ per computer (personal preferences for each environment)
• Local overrides are machine-specific (development vs. production settings) and typically gitignored

Lesson Plan

Learning Objectives

• Explain the 4-layer CLAUDE.md hierarchy and the order rules are loaded
• Compare how the same project has different effective configurations on different machines
• Identify which layer is appropriate for different types of rules
• Predict the final set of active rules for a given computer + project combination

Target Audience

Graduate students in digital transformation, software engineering, or AI courses. Also suitable for professional developers learning Claude Code.

Prerequisites

• Basic understanding of configuration files (.gitconfig, .eslintrc, etc.)
• Familiarity with the concept of AI coding assistants

Activities

1. Predict and Verify: Before clicking "Next Layer," predict what rules will appear at each level. Then reveal to check.
2. Compare Environments: Select the same project (e.g., "API Service") on all three computers. Note which rules are consistent and which differ. Why?
3. Design Your Own: After exploring, write your own CLAUDE.md rules for each layer for a hypothetical project. What belongs at enterprise vs. local level?
4. Discussion: Why are local overrides gitignored? What would happen if machine-specific configurations were committed to the repository?

Assessment

1. A developer wants to ensure no one on the team pushes directly to main. Which layer should this rule go in?
2. You prefer dark mode output on your home machine only. Which layer?
3. The project uses React 19. Which layer?
4. Your laptop uses GPU 0 for ML training, but the cloud server uses all 4 GPUs. Which layer for each?

References

1. Claude Code Documentation - Anthropic - Official documentation for Claude Code including CLAUDE.md configuration
2. Configuration Files (Wikipedia) - Overview of configuration file patterns and cascading precedence in software systems
3. EditorConfig - A similar cascading configuration system for code editors that follows the same enterprise → user → project pattern
4. 12-Factor App: Config - Best practices for separating configuration from code, relevant to understanding why local overrides are gitignored