Using and Maintaining CLAUDE.md Files Correctly

1. What a CLAUDE.md actually is and what it does

A CLAUDE.md is a markdown file in the project root (or in subdirectories) that Claude Code automatically loads into context as soon as a session starts in that directory. Technically it is nothing special, just text handed to the model before the actual prompt. The effect is still significant: instead of explaining in every new session that the project runs Magento 2.4.8 with the Hyvä theme, requires PHP 8.4 with strict types, and only deploys through Docker wrapper scripts, that information is written once and automatically taken into account on every request.

The central mistake in many first attempts at a CLAUDE.md is treating the file like project documentation meant to cover everything. But the model has a limited context window, and every line in the CLAUDE.md competes with the actual code Claude needs to read for a given task. A good CLAUDE.md does not optimize for completeness, it optimizes for hit rate: it contains the information Claude would otherwise infer incorrectly, and leaves out everything that can be read from the code itself in seconds.

2. What belongs in a CLAUDE.md

A CLAUDE.md should contain information that is not readable from the code itself, or only with considerable search effort, but that is supposed to influence Claude's behavior on every task. That includes the tech stack with concrete versions, binding coding standards such as constructor property promotion or a ban on assert(), project-specific architecture decisions such as preferring ViewModels over Block classes, and the commands used daily, for example a Docker wrapper instead of calling php bin/magento directly.

Security rules that Claude could otherwise accidentally violate belong here too: protected files, forbidden destructive commands, or the rule to never commit secrets. Another important block covers recurring patterns that are convention in the project but deviate from general best practices, for example a dual-vendor workflow where every file is maintained in parallel across two directories. Without that note, Claude Code would not guess this convention, even if it sees both directories in the repository.

# Good CLAUDE.md content: rules Claude cannot infer from code alone

## Tech Stack
- Magento 2.4.8-p4, PHP 8.4 (strict_types=1), Hyva Theme, Tailwind CSS v4, Alpine.js
- No jQuery, no Knockout.js, no Luma, no UI Components

## Coding Standards
- Prefer ViewModels (ArgumentInterface) over Block classes
- Use constructor property promotion for all dependency injection
- Plugins (interceptors) instead of class preferences
- Declarative schema (db_schema.xml) instead of install scripts

## Commands (never call php bin/magento directly)
- bin/magento [command]        # Magento CLI via Docker wrapper
- bin/cache-clean [tags]       # Clear cache, Hyva watcher stays active
- bin/analyse app/code/Vendor/Module --level=5   # PHPStan

## Forbidden patterns
- assert() for type narrowing -> use /** @var Type $var */ instead
- @ error silencing -> use try/catch or a PHPStan ignore comment

3. What does not belong in a CLAUDE.md

Implementation details that Claude can find out simply by reading the code do not belong in a CLAUDE.md. A list of every class in a module, the exact signature of a method, or a description of what a specific file does will inevitably go stale on the next change, and Claude can look them up with a single tool call anyway. Writing such details into the CLAUDE.md doubles maintenance effort and risks contradictions between documentation and actual code, which the model then treats as fact.

Equally out of place are generic programming truisms that would apply to any PHP project and provide no project-specific value, for example that variable names should be meaningful. Temporary information such as the current state of an ongoing refactor or a to-do list for next week also does not belong here, separate files like a changelog or a project management tool exist for that. The rule of thumb: if a code change would force a change in the CLAUDE.md, the information was probably too granular for this file.

# Anti-pattern: implementation detail that will rot within days

## SeoSuiteHelper.php
- Line 42: getMetaTitle() reads the "meta_title" attribute
- Line 58: fallback logic uses product name if meta_title is empty
- Constructor takes StoreManagerInterface and ProductRepositoryInterface

# This belongs nowhere in CLAUDE.md - Claude reads the file directly
# and the description is already stale after the next refactor.

4. Structure and order: what gets read first

The order of sections in a CLAUDE.md is not a cosmetic detail. Claude reads the file linearly as part of the system context, and information placed early is followed more reliably than information buried at the end of a long file. A proven pattern: tech stack first in a few lines, then binding coding standards, then the most common commands, and only at the end detail rules for edge cases such as PHPStan exceptions for known Magento interface gaps.

Short, scannable lists beat long prose paragraphs. Claude processes a list with clear bullet points more reliably than a paragraph where the same rule is hidden in a subordinate clause. Headings with ## and ### help further, because they clearly separate thematic blocks and let Claude pull in the relevant section for a concrete task instead of weighting the entire file equally. Code examples inside the CLAUDE.md itself should stay short and illustrative, not serve as a complete reference implementation.

# Recommended order inside a CLAUDE.md

## 1. Tech Stack (always first, a few lines)
## 2. Coding Standards & Patterns (binding rules)
## 3. Common Commands (CLI, Docker, build)
## 4. Project Structure (paths, vendor conventions)
## 5. Known Exceptions & Edge Cases (last, rarely needed)

# Anti-pattern: everything in one long prose paragraph
# without headings and without bullet points

5. Hierarchy: global, project, and directory CLAUDE.md

Claude Code supports several CLAUDE.md files at once that complement rather than replace each other. A global CLAUDE.md under ~/.claude/CLAUDE.md applies to all of a user's projects and suits personal preferences such as response language or general git safety rules. A project-specific CLAUDE.md in the repository root, checked into git, applies to everyone working on that project and holds the project conventions described in this article.

Additionally, CLAUDE.md files can be placed in subdirectories, where their content only becomes relevant when Claude actually works in that directory, for example a CLAUDE.md in app/code/Mironsoft/SeoSuite/ with module-specific rules that would be irrelevant to the rest of the project. This split prevents the root CLAUDE.md from being overloaded with specialized knowledge that applies to only a small part of the codebase. It matters to avoid duplicate or contradictory rules between levels, because it is unclear which level takes priority in a conflict.

# Typical CLAUDE.md hierarchy in a multi-module Magento project
~/.claude/CLAUDE.md                              # personal, global preferences
src/CLAUDE.md                                    # project-wide conventions
src/app/code/Mironsoft/SeoSuite/CLAUDE.md         # module-specific rules only

# Check which CLAUDE.md files are currently loaded in a session
find . -name "CLAUDE.md" -not -path "*/vendor/*" -not -path "*/node_modules/*"

6. Maintaining it over the project lifetime: when and how to update

A CLAUDE.md is not an artifact written once, it is a living document that ages with the project. The most reliable trigger for an update is a code review situation where Claude repeatedly makes the same mistake or violates a convention the team already knows. If a developer has to correct, for the third time in a session, that plugins should be used instead of preferences, that rule belongs in the CLAUDE.md, not in the next prompt.

Likewise, every major architecture decision, for example switching from an old frontend stack to the Hyvä theme, should be reflected in the CLAUDE.md immediately so Claude does not keep working from stale assumptions. A simple currency test: at every larger merge into the main branch, briefly check whether tech stack details or commands have changed. Anyone who never touches the CLAUDE.md again after writing it once risks, after a few months, a file that actively carries wrong assumptions, which is worse than having no CLAUDE.md at all.

7. CLAUDE.md in a team: versioning and consistency

Because a project-wide CLAUDE.md is part of the repository, it goes through the same review process as any other code change. That is intentional: a new rule in the CLAUDE.md affects every team member working with Claude Code, and should therefore not be introduced unilaterally. In practice it works well to bundle CLAUDE.md changes into the same pull request as the corresponding code change, so the context for the rule is visible right next to the rule itself.

A common problem in teams is drift between what the CLAUDE.md states and what is actually practiced in the code. If the file mandates using only ViewModels instead of Block classes, but half the existing code still uses Block classes, confusion arises over whether the rule applies to new code, existing code, or both. An explicit phrasing such as new classes use ViewModels, existing Block classes get migrated when touched resolves that ambiguity and stops Claude from guessing anew on every task.

8. Practical example: a CLAUDE.md for a Magento project

A concrete example makes the previous sections tangible. The following structure is modeled on a real Magento 2 project with the Hyvä theme and shows how compact an effective CLAUDE.md can be without omitting important information. Notice how brief every section is: no point needs more than two lines to be effective.

Equally notable is what this example deliberately leaves out: no list of every module, no explanation of how db_schema.xml works in general, no copy of the Magento documentation. Claude can look all of that up itself or read it from the code when needed. The CLAUDE.md focuses exclusively on project-specific decisions and deviations from standard Magento practice.

{
  "example_structure": "CLAUDE.md sections for a Magento 2 / Hyva project",
  "sections": [
    "Tech Stack: Magento version, PHP version, Hyva Theme, no jQuery/Knockout",
    "Coding Standards: ViewModels over Blocks, constructor DI, plugins over preferences",
    "CLI Commands: Docker wrapper scripts, never call php bin/magento directly",
    "Deploy Sequence: exact order of build, static-content:deploy, cache:flush",
    "PHPStan: target level, known Magento interface gaps with ignore comments",
    "Forbidden Patterns: assert(), @ error silencing, addFieldToFilter with int",
    "Module Conventions: every module ships config.xml, system.xml, acl.xml"
  ]
}

9. Common pitfalls compared

Most problems with CLAUDE.md files trace back to a handful of recurring patterns. The following table sets common mistakes against the recommended alternative, each with the concrete consequence for working with Claude Code.

What stands out is that almost all pitfalls trace back to the same root cause: treating the CLAUDE.md like a wiki instead of a curated rulebook. A wiki is allowed to grow, because readers search it deliberately. A CLAUDE.md is loaded fully into context on every request, which means every superfluous line has a real cost, both in tokens and in the likelihood that an important rule gets lost in the noise.

10. Summary

A good CLAUDE.md solves a concrete problem: it gives Claude Code project knowledge that cannot be reliably derived from the code alone, without overloading the file with information Claude can look up in seconds anyway. Tech stack, coding standards, commands, and project-specific deviations belong in it. Implementation details, generic programming truisms, and temporary to-dos do not. Short lists structured with headings are followed more reliably than long prose paragraphs.

The biggest lever is continuous maintenance: a CLAUDE.md that is never touched again after the first version inevitably drifts from the actual state of the project and, after a few months, becomes a source of wrong assumptions. Treating CLAUDE.md changes like ordinary code changes, in the same pull request as the corresponding rule, reviewed by the team, keeps the file a reliable foundation for working with Claude Code across the entire project lifetime.

11. FAQ: Using and Maintaining CLAUDE.md Files Correctly