Lesson 11 – Claude Certified Architect – Full Course

Understanding the CLAUDE.md File

In the rapidly evolving landscape of AI-assisted development, tools like Anthropic’s Claude Code offer a compelling alternative to traditional coding assistants by leveraging a simple markdown file for context injection. Known as CLAUDE.md, this file acts as the bridge between a developer’s intentions and the model’s behavioral output. Instead of meticulously crafting a prompt for every interaction to explain coding conventions, project architecture, or best practices, developers can codify these instructions into a persistent memory system. This lesson from the Claude Certified Architect course addresses a critical friction point: why team members often complain that Claude Code is not adhering to shared conventions, even when a configuration seems to exist. The root cause, as explored in this 32-minute deep dive, is often a fundamental misunderstanding of file placement and the tool’s hierarchical layering system. By the end of this analysis, the architecture of the CLAUDE.md hierarchy becomes a powerful tool for standardizing AI behavior across personal, project, and directory-specific scopes.

The Problem of Invisible Configuration

The core issue identified at the start of the lesson is a common scenario in collaborative software development. A developer configures their CLAUDE.md file with specific linting rules, code styles, or database access patterns, yet their teammates report that Claude Code ignores these rules entirely. This disconnect occurs because the initial configuration is likely placed at the user level, a scope that operates on a per-machine basis and is not checked into version control. The course instructor emphasizes that this is not a bug within Claude Code but a design feature that prioritizes personal preference isolation. Understanding this segregation is the first step toward fixing broken team workflows. The lesson serves as a practical guide to shifting critical rules from the isolated user space into the shared, project-level scope where the entire team can benefit from a single source of truth. This shift eliminates the “works on my machine” syndrome that plagues AI-assisted development when tools rely heavily on local state.

Deconstructing the Three-Level Hierarchy

Central to the episode is the detailed breakdown of the three-level CLAUDE.md hierarchy. The first layer is the User-level configuration, which functions as a global personal note. This is where an individual developer might store general stylistic preferences that are not necessarily specific to a single repository but apply to their entire way of coding. The second, and most critical for team alignment, is the Project-level configuration. This file is typically placed at the root of a repository and version-controlled, making it the mechanism for enforcing architectural decisions, naming conventions, and security protocols across all contributors. The lesson clarifies that any instruction that needs to be universally understood by the team must reside at this project level. Finally, the Directory-level configuration allows for surgical precision, providing context or overriding rules that apply only to a specific sub-folder. This is particularly useful in monorepos or complex applications where the standard Rails MVC structure might require drastically different instructions than a microservices directory within the same project.

Project-Level Configuration and Team Consensus

The lesson dives deep into the mechanics of the project-level config, marking it as the cornerstone of standardized AI behavior. When a CLAUDE.md file is placed in the repository root, it becomes the single pane of glass that Claude Code references for that project regardless of which user executes the command. The instructor walks through examples of what types of content belong in this shared file, such as linking to specific API documentation, defining the preferred testing framework, and establishing boundaries for code generation. By moving crucial logic from the user level to the project level, teams can significantly reduce the time spent on code review feedback loops that fix inconsistencies introduced by the AI. The psychological shift here is treating the CLAUDE.md file not just as a prompt but as a living design document that must be curated and negotiated by the team, just like a traditional architecture decision record.

The Power of Modularization with @import

As projects grow, a single CLAUDE.md file can become unwieldy, creating a tension between comprehensive documentation and the context window limitations of the underlying AI model. To solve this, the lesson explores the @import directive. This feature allows developers to create a modular web of configuration files, similar to breaking down a monolithic script into a library of utilities. Using @import, a main CLAUDE.md file can stitch together specialized files, such as data-models.md, deployment-process.md, or testing-conventions.md. This approach not only keeps the configuration organized but allows the AI to pull in only the most relevant subsets of instructions based on the task at hand, implicitly mirroring the concept of lazy loading. The instructor highlights that this declarative composition pattern is essential for maintaining sanity in large-scale enterprise applications where a single CLAUDE.md file could otherwise stretch to thousands of lines.

Advanced Scoping with .claude/rules and Glob Patterns

For scenarios demanding even more granular control than the directory-level hierarchy, the lesson introduces the .claude/rules/ directory and the integration of glob patterns within YAML frontmatter. This technique enables conditional loading where a rule file only activates when a specific file type is being read or written by Claude Code. For example, a rule set formatted as .claude/rules/frontend.md could automatically attach specific React patterns only when the model interacts with .jsx or .tsx files. The instructor emphasizes the precision this offers, ensuring that backend logic requiring strict immutability does not bleed into frontend components. This section includes a deep analysis of the YAML frontmatter paths: field, which explicitly defines the matchers. The glob pattern demonstration reveals how to target all CSS files, specific test directories, or legacy code modules with distinct behavior sets, creating a highly disciplined and context-aware AI assistant that adapts its “personality” based on the code it is touching.

Debugging the State with /memory

The instructor presents the /memory command as a debugging superpower that is often underutilized. When a user suspects that Claude Code is ignoring an instruction, it is rarely due to a failure of the rules engine but rather a failure of the user’s assumption about the context currently loaded into memory. The /memory command provides a transparent snapshot of all active file contents, imported modules, and active rules at that exact moment in the conversation. The lesson explains how to use this output to trace the origin of a specific instruction—whether it came from the user layer, the project root, or a dynamic glob match—and quickly identify configuration overlaps or omissions. This debugging workflow transforms the opaque nature of AI context windows into a deterministic, inspectable stack trace, enabling developers to systematically troubleshoot incorrect AI outputs and verify that their modular @import structures are resolving as expected before executing coding tasks.

Exam Preparation and Practical Application

The final segment of the lesson connects the theoretical architecture directly to the Claude Certified Architect Sample Question 6. The instructor performs a detailed distractor analysis, demonstrating how the exam tests the candidate’s ability to differentiate between the scopes when presented with a scenario where a colleague’s settings are not being applied. The scenario requires the candidate to select the correct fix—moving the configuration to the project level or utilizing the appropriate @import path—among attractive but incorrect answers suggesting file renaming or syntax changes. This practical application solidifies the learning objectives of Module 3, Task Statements 3.1 and 3.3. Ultimately, the lesson positions mastery of the CLAUDE.md hierarchy not just as a certification objective but as a fundamental operational skill for platform engineering teams aiming to embed consistency and reliability into their AI-driven development lifecycle.