Navigating Claude Code: CLAUDE.md Done Right  🔗 **Source:** [Navigating Claude Code: CLAUDE.md Done Right](https://hackernoon.com/navigating-claude-code-claudemd-done-right) > [!note]+ Document Notes > --- > tags: [claude-code, claude-md, prompt-context, project-conventions, developer-tools, configuration] > author: Oleg Efimov > source: HackerNoon > reference: https://hackernoon.com/navigating-claude-code-claudemd-done-right > date created: 2026-08-04 16:30 > --- > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > # 🏷️ Title: Navigating Claude Code: CLAUDE.md Done Right > ## 🧭 Table of Contents > - [Summary](#-summary) > - [Main Content](#-main-content) > - [References](#-references-1) > - [Paraphrase](#-paraphrase) > - [Newsletter](#-newsletter) > - [Action Items](#-action-items) > - [Hypotheses](#-hypotheses) > - [Methodology](#-methodology) > - [Questions](#-questions) > - [Future Research](#-future-research) > - [Implications](#-implications) > - [Learning Styles Assessment](#-learning-styles-assessment) > - [Accessibility Assessment](#-accessibility-assessment) > - [DEIB Assessment](#-deib-assessment) > - [Logical Validity](#-logical-validity) > - [DARVO Analysis](#-darvo-analysis) > - [Conclusion](#-conclusion) > - [Refactor Appendix](#-refactor-appendix--navigating-claude-code:-claude.md-done-right) > ### 🔗 References > - [Original HackerNoon article](https://hackernoon.com/navigating-claude-code-claudemd-done-right) > - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview) — verify version-sensitive product claims here. > ## 📝 Summary > - **What happened:** Oleg Efimov explains one part of a ten-article Claude Code workflow series and offers configuration patterns drawn from practice. > - **Why it matters:** CLAUDE.md should contain durable, non-obvious operational context and point to detailed rules only when needed; hard enforcement belongs outside the file. > - **Stakeholders:** developers, maintainers, DevRel teams, OSPO staff, security reviewers, and WordPress contributors using coding agents. > - **Risks and tradeoffs:** The article's hierarchy and import claims are product-version specific. A fixed line-count threshold is a heuristic, not a universal quality measure. > - **Bottom line:** Treat the recommendations as testable workflow proposals, not permanent product facts. > ## 📖 Main Content > - Use the file hierarchy and imports to load context at the narrowest useful scope. > - Keep commands, architectural exceptions, and recurring gotchas; delete generic advice. > - Review and prune instructions as the repository changes. > - The strongest cross-series principle is separation of concerns: persistent context, enforcement, external tools, isolated work, and coordination each solve different problems. > - Product-specific details should be verified against current Anthropic documentation before changing production policy. > ## 🗒️ Notes > - **Central thesis:** CLAUDE.md should contain durable, non-obvious operational context and point to detailed rules only when needed; hard enforcement belongs outside the file. > - **Evidence type:** practitioner explanation, configuration examples, and operational heuristics; no controlled benchmark or independent replication is reported. > - **Most useful transfer:** turn each recommendation into a bounded experiment with a visible success measure. > - **Primary limitation:** The article's hierarchy and import claims are product-version specific. A fixed line-count threshold is a heuristic, not a universal quality measure. > ## 📚 References > - [Original HackerNoon article](https://hackernoon.com/navigating-claude-code-claudemd-done-right) > - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview) — verify version-sensitive product claims here. > ## 🗣️ Paraphrase > 1. The article identifies a recurring Claude Code workflow problem and explains why the default behavior can waste context, cost, or attention. > 2. It separates the relevant configuration mechanisms and describes where each one belongs. > 3. It gives practical patterns for a small setup, then contrasts them with common failure modes. > 4. It closes with operational advice that readers can try in a repository. > 5. Read as a whole, the piece argues for deliberate boundaries and measurable verification rather than bigger configurations. > ## 📰 Newsletter > Claude Code configuration can look like a new hobby with a terminal attached. Navigating Claude Code: CLAUDE.md Done Right offers a better frame: pick the smallest control that fits the job, keep context focused, and make “done” observable. WordPress contributors can apply the idea to plugin reviews, Core ticket research, release QA, and documentation work—while checking every version-sensitive claim against the [current Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/overview). > ## ✅ Action Items > #### DevRel > - Publish a small reproducible demonstration based on this article and report the conditions, failure cases, and measured outcome. > - Teach contributors to distinguish advisory prompt context from enforced policy. > #### OSPO > - Document approved coding-agent tools, data boundaries, review requirements, and incident paths. > - Require human-readable evidence for generated changes that affect releases or security. > #### Community > - Run a paired workflow clinic and collect where the advice helps or fails for newcomers. > - Keep contributor onboarding possible without paid tools or hidden personal configuration. > #### WordPress > #### Core > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Core Performance > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Core AI > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Core Program Team > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Mobile > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Playground > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Community > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Training > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Marketing > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Support > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Design > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Documentation > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Photos > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### TV > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Polyglots > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Accessibility > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Meta > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### CLI > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Hosting > - Test the article's routing and verification advice against this team's real contribution workflow; record evidence and limits. > #### Tide > - T #### Previously in the series * [The Bare Minimum Setup](https://hackernoon.com/navigating-claude-code-the-bare-minimum-setup). #### Introduction In the previous article, I covered the config file hierarchy, a minimal `settings.json`, and why deny rules are not a reliable security boundary. That gave us a working installation. This one is about the single file that determines whether Claude Code feels like a capable colleague or a confused intern. `CLAUDE.md` looks simple — it is just markdown — but I have rewritten my own files enough times to know **there is a real gap between having one and getting value from it**. This article covers the full file hierarchy, the import mechanism, path-scoped rules, and the mistakes that cause Claude to quietly ignore what you wrote. #### How CLAUDE.md gets loaded Claude Code walks up the directory tree from your working directory, checking each level for a `CLAUDE.md`. It also checks a few fixed locations. From broadest scope to most specific, here is what Claude Code checks: At the top sits managed policy — `/Library/Application Support/ClaudeCode/CLAUDE.md` on macOS, `/etc/claude-code/CLAUDE.md` on Linux. This is for enterprise teams pushing organization-wide rules. Most individual developers will never see this file, let alone create one. User global at `~/.claude/CLAUDE.md` loads in every session, across every project. Personal defaults go here — things like "never use `rm -rf` without confirmation" and "use the `gh` CLI for GitHub operations." Project root at `./CLAUDE.md` is the most common location. You commit this. It holds your stack, build commands, and coding conventions. The whole team shares it. There is an alternative at `./.claude/CLAUDE.md` if you prefer keeping config files grouped under `.claude/`. Pick one. Do not use both — they have the same priority, and Claude will load whichever it finds, which gets confusing fast. Local project at `./CLAUDE.local.md` is for personal project-specific tweaks you do not want to commit. You need to add this to `.gitignore` yourself — it is not handled automatically. Subdirectory files like `packages/api/CLAUDE.md` or `src/components/CLAUDE.md` are not loaded at launch. They load on demand when Claude starts reading files in that directory. This is where monorepos become manageable — your frontend and backend can have completely different conventions without bloating the root file. The precedence rule is the same as for `settings.json`: more specific wins. If your global file says "use spaces" and your project file says "use tabs," tabs win. But do not count on clean conflict resolution. I have seen Claude blend instructions from both levels or follow whichever appeared more recently in context. **Treat cross-level conflicts as undefined behavior and keep each file's scope distinct.** #### When the File Gets Too Long A focused service might only need fifteen lines in its `CLAUDE.md`. But real projects accumulate context, and at some point, you need to split the file. The `@` import syntax handles this: ``` # Project overview See @README.md for architecture details. # Code conventions @docs/coding-standards.md # Personal overrides @~/.claude/my-project-preferences.md ``` Claude replaces each `@path` with the contents of that file at load time. Your main `CLAUDE.md` stays short, but Claude still gets everything. The first time Claude Code encounters external imports in a project, it shows an approval dialog. If you decline, those imports stay disabled, and the dialog does not come back — you would need to re-approve manually. Also, the `@` syntax is only evaluated outside of code blocks, so file paths in code examples will not trigger an import. Watch out for heading levels in imported files. They do not get adjusted. If your main file has a `# Code conventions` section and the imported file starts with its own `#` heading, that becomes a top-level sibling, not a subsection. There was [a GitHub issue](https://github.com/anthropics/claude-code/issues/6321) about this, closed as not planned — so do not expect a fix. Keep heading levels consistent across files yourself. #### Path-Scoped Rules For larger projects, even imports are not granular enough. You do not want your migration rules loaded every time Claude touches a React component. The `.claude/rules/` directory solves this. ``` .claude/rules/ ├── api-conventions.md ├── testing.md ├── migrations.md └── frontend.md ``` Each file can include a `globs` frontmatter field: ``` --- globs: src/api/**/*.ts --- # API conventions - All endpoints must validate input with Zod schemas - Use the standard error response format from src/api/errors.ts - Never return raw database objects — always map to DTOs ``` Rules without frontmatter apply globally, the same as the content in the root `CLAUDE.md`. Rules with globs only load when Claude reads files matching those patterns. Run `/memory` to verify what actually loaded — I cannot stress this enough, because failures here are silent. There is a gotcha. The documentation originally described a `paths:` frontmatter field. In practice, `globs:` is the format that works. I spent real time debugging why path-scoped rules were being silently ignored before finding [the GitHub issue](https://github.com/anthropics/claude-code/issues/17204) about it. Use `globs:` with comma-separated patterns. #### Pitfalls ##### The Bloated File This is the single most common mistake I see. A team starts with a reasonable ten-line file. Over months, everyone adds to it. Nobody removes anything. Six months later, it is 400 lines, and Claude ignores half of it. Anthropic's own documentation says files over 200 lines consume more context and reduce instruction adherence. That matches my experience. Even with a 1M token context window, the issue is not capacity — it is attention. The more text Claude has to wade through at the start of a session, the less reliably it follows any single instruction. Every line of `CLAUDE.md` competes with the code Claude is actually working on. Here is what a bloated file looks like: ``` # Project overview This is a Next.js application built with TypeScript and Tailwind CSS. We use React Server Components where possible. The application was started in 2023 and has grown significantly. Our team consists of 5 developers across 2 time zones. We follow agile methodology with 2-week sprints. Our product manager is Sarah and our tech lead is Mike. The application serves approximately 50,000 daily active users. We deploy to AWS using CDK... ``` Claude does not need to know your team size. It does not care about your sprint cadence or your PM's name. Strip it: ``` # Project Next.js 15, TypeScript strict mode, Tailwind, React Server Components by default. ``` One line. Claude has everything it needs to write correct code for this stack. For every line in `CLAUDE.md`, ask yourself: Would removing this cause Claude to make a mistake? If the answer is no, cut it. ##### The Instruction-Stuffing Trap Related to bloat, but distinct. I have seen `CLAUDE.md` files where half the rules ban things Claude would never do unprompted: ``` - Never use var, always use const or let - Always use arrow functions for callbacks - Never use any type, use unknown instead - Always handle errors with try/catch - Never use console.log in production code - Always use named exports - Never use default exports ``` Twenty rules like this eat a real chunk of context for things Claude mostly gets right on its own. I have yet to see Claude reach for `var` unprompted. Save your `CLAUDE.md` space for rules that fix problems you have actually observed. If Claude has never done the thing, you do not need a rule banning it. ##### Conflicting Instructions Across Files The risk grows as you add more files to the hierarchy. Your global file says "always use Prettier." Your project file says "use ESLint for formatting." A subdirectory rule says nothing about formatting. There is no merge strategy, no error message. Claude sees all the instructions and picks one. You get inconsistent behavior that feels random. Treat the hierarchy like code. Review it when things go wrong. When you add a project-level rule, check whether it contradicts something in your global file. ##### Treating CLAUDE.md as Configuration This one bit me more than once. `CLAUDE.md` is not a config file that gets parsed and enforced. It is text that goes into the prompt. Claude treats it as strong guidance, but it is not deterministic. Adding `IMPORTANT:` or `YOU MUST` to a rule does increase the odds that Claude pays attention. It does not guarantee compliance. When every other line says `IMPORTANT`, Claude has no way to tell which ones you actually mean. Hard stops belong in `settings.json` permissions, a linter, or a pre-commit hook. A markdown file in the prompt is the wrong place for rules that cannot tolerate exceptions. #### What Earns Its Place Here is what I have learned about what consistently earns its place in `CLAUDE.md` and what does not. Build and test commands are the highest-value content. Claude needs to know how to build your project, run tests, and lint code. Without this, it guesses. With it, you can add a feedback loop — "run `npm test` after changing any test file," — and Claude will catch its own mistakes. Non-obvious architecture belongs in the file. Things Claude cannot infer from the code alone. "All database access goes through `/src/repositories`.” “The `/legacy` directory is frozen — do not modify files there." These save you from explaining the same thing every session. Conventions that break from defaults belong in the file, but only the ones where your project does something unusual. If you use standard React patterns, do not document them. If you have a custom error class or a specific import alias, that goes in. Gotchas belong in the file. Things that have already cost you time. "The auth module uses a custom JWT library, not jsonwebtoken." "Database migrations must be reversible." You add these one at a time, each time Claude makes a mistake that a one-line rule would have prevented. History, rationale, and business logic do not belong in the file. If you are writing a paragraph explaining why a module is structured a certain way, that belongs in a code comment or an `ADR.md`. `CLAUDE.md` is for operations. #### Keeping It Alive A static `CLAUDE.md` decays. Dependencies change, conventions evolve, and rules that made sense six months ago become irrelevant or get contradicted by newer additions. Two things help. First, the `#` key during a session. When you catch Claude doing something wrong, press `#` to add a correction to `CLAUDE.md` without leaving the conversation. Anthropic calls this "compounding engineering" — each correction becomes a permanent context. It is the single best habit I have picked up. Second, treat debugging sessions as maintenance triggers. When Claude does something wrong despite having a rule against it, the file is probably too long, and the rule got lost. Do not add another rule on top. Go back and trim whatever has gone stale — then look at the rule that got ignored and ask whether the wording was actually clear enough. For new projects, `/init` is worth running before you write anything by hand. Claude Code scans the codebase and generates a starter file. The output tends to be verbose — trim it heavily. But it beats starting from nothing. #### Summary The file hierarchy gives you layers — global for personal defaults, project for team conventions, subdirectories for module-specific rules. The `@` import syntax and `.claude/rules/` keep the main file short as complexity grows. The mistakes are predictable: files that are too long, rules for problems that do not exist, conflicts across hierarchy levels, and expectations that a markdown file will behave like an enforced configuration. Do not try to write the perfect file on day one. Start with the basics — stack, build commands, conventions, and gotchas. Add a line each time Claude wastes your time with a mistake that a single rule would have prevented. Over weeks, those additions compound into something that makes Claude genuinely useful for your specific project. In the next article, I will cover models, tiers, and effort — how to pick the right model for each task and what the effort settings actually change., Navigating Claude Code: CLAUDE.md Done Right, Oleg Efimov, 01kz7spvm7fcxgmakvsndm4x4p.