3.1 - CLAUDE.md Hierarchy, Scoping, and Modular Organisation

Build exercise: Build a Multi-Level CLAUDE.md Configuration

Beginner · 30 minutes

You'll practice:

• Understand the three-level CLAUDE.md hierarchy (user, project, directory) and when to use each
• Configure modular project standards using @ path imports
• Use .claude/rules/ for topic-specific rule files
• Diagnose configuration scoping issues with the /memory command
• Identify root cause when a new team member does not receive instructions

1. Create a project-level .claude/CLAUDE.md with universal coding standards: naming conventions, error handling patterns, and a code review checklist

   Project-level configuration is the foundation of team-wide standards. The exam tests whether you place shared conventions here rather than in user-level config, which is the most common misconfiguration scenario.

   You should see: A .claude/CLAUDE.md file at the repository root containing at least three sections: naming conventions, error handling patterns, and a code review checklist. Running /context in the project root lists this file under Memory files.

   Hints

   1. Think about which directory makes configuration version-controlled and shared via git.

   2. The project-level file lives at .claude/CLAUDE.md or at the repository root as CLAUDE.md. Both are valid project-level locations.

   3. Create the file at .claude/CLAUDE.md with content like:
      # Coding Standards
      
      ## Naming Conventions
      - Use camelCase for variables and functions
      - Use PascalCase for classes and components
      
      ## Error Handling
      - Always use typed error classes
      - Never swallow exceptions silently
      
      ## Code Review Checklist
      - Verify test coverage for new functions
      - Check for hardcoded credentials

2. Create a directory-level CLAUDE.md in a /packages/api/ subdirectory with API-specific conventions (REST endpoint naming, request/response schema requirements)

   Directory-level configuration scopes conventions to a specific package. The exam tests whether you know that directory-level CLAUDE.md applies only within that directory, not across the entire project.

   You should see: A CLAUDE.md file inside /packages/api/ containing REST-specific conventions. When you run /context while working in /packages/api/, both the project-level and directory-level files appear under Memory files.

   Hints

   1. Directory-level CLAUDE.md files sit inside subdirectories and apply only when working in that directory.

   2. Create /packages/api/CLAUDE.md with conventions specific to the API package that differ from or extend the root conventions.

   3. Create packages/api/CLAUDE.md with content like:
      # API Conventions
      
      - Use kebab-case for REST endpoint paths
      - All responses must follow the shape: { data, error, metadata }
      - Validate all request bodies with Zod schemas at the handler boundary

3. Create .claude/rules/testing.md with test-specific conventions (test naming pattern, assertion style, fixture usage)

   The .claude/rules/ directory holds topic-specific rule files that can optionally include YAML frontmatter for path scoping. Understanding this mechanism is tested alongside path-specific rules in Task Statement 3.3.

   You should see: A testing.md file inside .claude/rules/ containing at least three test conventions. Running /context lists this rules file under Memory files.

   Hints

   1. Rules files go in the .claude/rules/ directory at the project root.

   2. Each file in .claude/rules/ is a standalone Markdown file. Without YAML frontmatter path scoping, it loads for all sessions.

   3. Create .claude/rules/testing.md with content like:
      # Test Conventions
      
      - Name tests using the pattern: describe("ModuleName") > it("should behaviour when condition")
      - Use factory functions for test data, not inline literals
      - Mock external services at the module boundary

4. Use an @ path import in the project-level CLAUDE.md to reference a shared standards file at ./standards/naming.md

   The @ import syntax enables modular organisation of conventions. There is no @import keyword - a path prefixed with @ on its own line is the import. Each package can import only relevant standards, reducing duplication and drift in the source files. The exam tests whether you know the mechanism exists and how the syntax actually looks.

   You should see: The project-level .claude/CLAUDE.md contains a line beginning with @ pointing to ./standards/naming.md. A separate file at .claude/standards/naming.md (or standards/naming.md relative to the CLAUDE.md) exists with naming conventions. Running /context confirms the imported content is loaded inline.

   Hints

   1. The import syntax in CLAUDE.md is the @ character followed by a relative or absolute path. No keyword - the @ is the directive.

   2. Create a separate naming.md file and reference it with @./standards/naming.md (on its own line) inside your .claude/CLAUDE.md file.

   3. First create .claude/standards/naming.md with your naming rules, then add this line to .claude/CLAUDE.md:
      @./standards/naming.md

5. Run /context in different directories to verify the correct files are loaded in each context

   The exam tests that the diagnostic command reveals loaded files but does not trigger loading - configuration loads automatically based on location. The guide names /memory for this; current Claude Code reports the loaded set under /context, so that is what you run here.

   You should see: In the project root, /context shows the project-level CLAUDE.md and rules files under Memory files. In /packages/api/, it additionally shows the directory-level CLAUDE.md. The imported standards file content appears as part of the project-level configuration.

   Hints

   1. Navigate to different directories and run /context in each to compare the loaded files.

   2. Run /context at the repo root, then cd into /packages/api/ and run /context again. Compare the two Memory files lists to see the directory-level file appear.

   3. Run these commands in sequence:
      1. cd /your-project && /context
      2. cd /your-project/packages/api && /context
      Compare the output lists to confirm directory-level scoping.

6. Move one convention from project-level to user-level (~/.claude/CLAUDE.md) and verify that a different user session does NOT pick it up - confirming the scoping boundary

   This is the exam favourite trap scenario. When conventions live in user-level config, new team members who clone the repo do not receive them. Proving this boundary experimentally cements the concept.

   You should see: After moving a convention to ~/.claude/CLAUDE.md, your own /context shows it loaded. A simulated second user session (or a fresh clone without your home directory config) does NOT show that convention. This confirms the scoping boundary.

   Hints

   1. User-level config lives at ~/.claude/CLAUDE.md and is never shared via git.

   2. Move one naming convention from .claude/CLAUDE.md to ~/.claude/CLAUDE.md. Then check /context in a fresh session or ask a teammate to run /context on their machine.

   3. Move a rule to ~/.claude/CLAUDE.md:
      # Personal Preferences
      - Always use verbose variable names
      
      Then verify: your /context shows it, but a colleague cloning the repo fresh will not see it in their /context output.