The 400-line file I couldn’t explain

A few weeks ago I opened my global CLAUDE.md to add a new rule and the file scrolled past 400 lines. I kept scrolling. Near the bottom I found a rule about a plugin I had archived six months ago, sitting there silent, still loading on every Claude Code session I ran. Further up, I found two rules that directly contradicted each other, written two months apart, by me, to me, with no memory of either one existing. I had rules about block themes mixed in with rules about REST API versioning mixed in with rules about how I wanted commit messages formatted. I had notes about a client I had parted ways with. I had a step-by-step debugging procedure for a problem I had not seen in a year.

That was the moment I realized my approach to AI coding context was broken.

The natural instinct when Claude Code gets something wrong is to write another rule. Make the file longer. Spell it out more clearly. If the assistant missed something, your brain says the instructions were not clear enough, so the fix is to be more explicit. I had been doing this for eight months, and the file was a monument to that instinct.

The problem was not that my rules were unclear. The problem was that I was piling four completely different kinds of knowledge into one file that was only ever designed to hold one kind. Rules, facts, procedures, and tool descriptions were all living together, loading together, fighting each other, and rotting together.

What actually fixed it was not writing more rules. It was splitting the file into four layers, where each layer answers a different question and only the layers that matter for the current task get loaded. The trick with CLAUDE.md is not a bigger file. The trick is smaller, layered knowledge.

This is the guide I wish I had eight months ago, written for WordPress developers who are already running Claude Code and starting to feel the weight of their own instructions pile up.

The three ways one big CLAUDE.md quietly fails

If you have been around WordPress development for a while, you will recognize all three of these failure modes immediately.

Failure one: context bleed. A rule about block development fires while you are debugging a WP-Cron job. A note about how you handle REST API versioning fires while you are writing a theme customizer control. Every rule in a single-file CLAUDE.md is always on, no matter whether the current task is the kind of task the rule was written for. This means the assistant spends tokens reading instructions that do not apply, and sometimes actively applies them when it should not. If you have ever watched Claude insist on adding a nonce check to a function that has nothing to do with forms, you have seen context bleed in action.

Failure two: contradiction accumulation. Over months, rules start fighting each other. “Always use WPCS strict mode” and “prototype fast and iterate” both feel true, but they collide when applied to the same code. “Never create new files unless necessary” and “break up large files into smaller ones” both feel right, but they contradict in practice. A monolithic file hides these contradictions because you never read the whole thing top to bottom. The assistant does, every single turn, and has to guess which rule wins.

Failure three: context rot. You archived the plugin, but the rules about it are still in your file. You stopped using that service, but the note about their API is still there. You changed your mind about an approach, but you never deleted the old entry. Nothing in your CLAUDE.md reminds you to clean up, so nothing ever gets cleaned up. Every session starts with a tax of dead instructions that no one is maintaining.

These three failures compound. Context bleed wastes tokens. Contradictions waste quality. Rot wastes trust. And writing more rules to fix any of them is pouring water into a leaking bucket.

Four layers of context, not one

Here is the mental shift that actually fixed things for me. Your instructions file is not a dumping ground for “things the assistant should know.” It is one layer of a four-layer context system, and each layer holds a different kind of knowledge.

Rules live in CLAUDE.md. Rules are short, stable, always-on statements about what to do or not to do. “Never commit without running WPCS first.” “Always enqueue scripts through wp_enqueue_scripts, not hardcoded in the header.” “Use wp_nonce_field on every form.” Rules are timeless and universal within their scope. They do not explain how. They explain what and whether.

Facts live in memory files. Facts are specific, often evolving pieces of knowledge about you, your projects, your preferences, and things you have learned across sessions. “The client’s staging server is behind Basic Auth.” “I prefer bullet summaries over paragraph summaries.” “We decided in February to stop using custom post types for event data and move to a custom table.” Facts are not universal. They are true in a context, and they can change.

Procedures live in skills. A procedure is a multi-step workflow for a class of task. The steps to audit a plugin for SQL injection. The steps to diagnose a white screen. The steps to debug a WooCommerce checkout that silently fails. A procedure has sequence, decision points, and tools. It is too long and too task-specific to sit in your always-on rules file, and it is not a fact.

Tools live in MCP servers. A tool is a runtime capability the assistant can call on demand: run a WP-CLI command, query the database, take a browser screenshot, upload media, check an accessibility rule. Tools are not instructions at all. They are actions. The mistake is writing instructions about a tool into CLAUDE.md instead of letting the MCP describe the tool itself.

Most WordPress developers start by piling rules, facts, procedures, and tool descriptions into CLAUDE.md because that is the first file they meet. Then they wonder why things start drifting. The fix is to recognize that each kind of knowledge has its own layer and belongs there, not in the instructions file.

A bigger instructions file is a symptom of not knowing where each piece of knowledge belongs

CLAUDE.md coverage: global, project, plugin

Your CLAUDE.md should not be one file. It should be three levels deep.

At the global level, you keep things that apply to every WordPress project you ever touch. Your coding standard preference. Your commit message style. Your rule that UI changes must be browser-verified before being marked done. Your rule that you never want AI co-author tags on commits. Your preference for WPCS strict over PSR-12 for WordPress code. These are facts about you, not facts about any project. They live in your user-level file. They follow you everywhere. My global file sits around 200 lines right now, and I am actively trying to get it under 150. Under a hundred lines would be ideal.

At the project level, you keep things that are only true for this one codebase. The site URL. The WP-CLI path. The active theme. The table prefix. Which plugins are required for basic function. Multisite, yes or no. Whether WP_DEBUG is on. The namespace of the custom plugin you are maintaining. The hook where the main bootstrap happens. The fact that the staging server requires a specific SSH key. These things are true for this project and false for the next one. They belong in a CLAUDE.md inside that project’s root, not in your global file.

At the plugin or module level, you keep the architecture and conventions of one unit. For a plugin, this is things like its class autoloader pattern, where its tests live, which database tables it creates, where its cron jobs are registered, how its REST endpoints are namespaced. This is reference material for that one module. You do not need it when you are working on a different plugin, so it does not belong in the project-level file either. It belongs in the plugin’s own directory.

The decision rule is simple. Ask yourself, “Would this rule be wrong in my next project?” If yes, project level. “Would I say this to any WordPress developer I hired?” If yes, global. “Is this about the internal architecture of exactly one plugin?” If yes, module level.

The goal is that your global file stays short. Your project files stay focused on what a new developer on that project would need to know to avoid breaking things on day one. Your module files are reference documents for one unit of code. No layer contains what belongs in another.

Skill coverage: what becomes a skill instead of a rule

Once you have stripped the layers of CLAUDE.md down to actual rules, you will notice something. A lot of what you used to write into CLAUDE.md was never rules at all. It was procedures. Workflows. Multi-step processes for recurring tasks.

Those belong in skills.

A skill is an on-demand procedure document. It has a name, a short description, and a set of instructions for a class of task. It is not loaded by default on every turn. It is loaded when you explicitly invoke it, or when the assistant detects that the current task matches its trigger. This different loading model is the whole point.

For WordPress work, the skills I would tell a new Claude Code user to write first are these five. A bug-fix skill that encodes how you diagnose and fix a reported bug, from evidence gathering to root cause to regression test. A wp-debugging skill that walks through WP_DEBUG, Query Monitor, error logs, plugin conflict isolation, and object cache checks in order. A wp-performance skill for N+1 queries, slow transients, asset bundling, and Core Web Vitals diagnosis. A wp-security-review skill for nonce checks, capability checks, escaping, sanitization, and SQL injection audits. A pr-review skill for how you want Claude to review diffs before you push. These five cover most of the repeatable work a WordPress developer does, and none of them belong in your always-on instructions file.

The rule of thumb is simple. If a piece of guidance has more than three steps, or if it only applies to a particular kind of task, it is a skill. If it has fewer than three steps and it is always true, it is a rule. Not perfect, but close enough to make the decision fast.

Skills also let you share work across projects without copying text. If you write a solid debug-white-screen skill once, you can use it on every WordPress project you touch. If the same guidance was inside a per-project CLAUDE.md, you would be maintaining four copies and they would drift within a month.

The test for whether you have done skill coverage right is simple. Pick a random rule from your CLAUDE.md. Ask: “Would this still apply if I was working on a totally unrelated WordPress task right now?” If the answer is no, it should probably be a skill. If the answer is yes, keep it.

MCP coverage: tools, not instructions

MCP servers are the part of this system most WordPress developers understand last, because they look similar to skills at first glance. They are not. A skill is a procedure written in English. An MCP server is an actual running program that exposes callable actions.

For a WordPress developer, the MCPs I would actually recommend installing first are these. Playwright for browser automation and screenshot verification, which is essential if you care about UI correctness. A filesystem MCP for structured file operations. A WP-CLI or local database MCP that can run commands and query your local WordPress install safely. A WPCS or code quality MCP that can lint PHP on demand instead of you running phpcs by hand every time. A content or blog MCP if you publish across multiple WordPress sites (this is how I push posts across a network without logging into seven wp-admins). A research MCP of some kind for keyword or analytics data if you write content. You do not need all of these on day one, but these are the categories that pay for themselves fast.

The mistake people make is writing CLAUDE.md rules like “when working with the database, remember to escape queries with $wpdb->prepare.” That is not a rule worth writing. That is a symptom of not having an MCP that handles the database safely in the first place. If there is a tool that does the right thing, you do not need to write instructions to remind the assistant to do the right thing by hand.

The correct pattern is to give the assistant tools that can only do safe operations, and let the tool’s own description explain what it does. Do not duplicate the tool’s description in your instructions file. That is a copy that will drift and burn tokens on every turn.

There is one more thing to know about MCPs and tokens. Every tool that is always available in a session costs a small amount of context to list. If you have dozens of MCPs you never use, you are paying for all of them on every turn. A good rule: if you have not used an MCP in the last thirty days, disable it. You can re-enable it the moment you need it. Unused tools are a tax that quietly eats your context window.

Memory coverage: facts that evolve

Memory is the layer most WordPress developers do not use at all, and that is a mistake. Memory is where you keep facts that do not fit in any of the other three layers: things you learned across sessions, things about you, things about your projects, decisions you made that you do not want to explain again.

A rule is “never commit without WPCS.” A fact is “I learned the hard way that this client’s server does not support PHP 8.2, so we pin the plugin to 8.1.” The first is a universal rule. The second is a specific fact that will save the assistant from breaking things on that project, but it is not appropriate as a rule because it only matters there and may change when the client upgrades.

Memory is also where user-level facts live. What timezone you work in. What your preferred level of detail is in code review. Whether you want terse answers or verbose ones. How much context you want in commit messages. What you mean when you say “ship it.” These are facts about your working style that help the assistant collaborate with you rather than fight you.

Here is an anti-pattern I tried early and had to burn down. I started dumping every “lesson learned” from every session into memory, hoping the assistant would build up a useful knowledge base over time. Within a month the memory index had 50+ entries, most of them were conversation context rather than actual facts, and the assistant could not find anything useful because the signal-to-noise ratio was terrible. I deleted the whole thing and restarted with hard rules about what qualifies as memory. Today I have exactly one entry. One. That is probably too few, but it is a much healthier starting point than fifty.

The discipline for memory is the opposite of the discipline for CLAUDE.md. In CLAUDE.md you want to prevent sprawl. In memory you want to allow evolution, but keep the index tight. An index entry is one line. A memory file is one concept. If a memory file grows beyond a page, it is probably three memory files in a trench coat.

The things that should never go in memory: code patterns (read the code), git history (read the log), documentation (read the docs), conversation state from the current session (use your own working memory). Memory is for things that survive across sessions and that are not discoverable from reading current state. If the assistant could learn it by running git log, do not memorize it.

The cleanup flow

Most WordPress developers who adopt Claude Code never clean up their context system because there is no reminder to do so. The rules you wrote three months ago are still there. The skill you wrote for a workflow you stopped using is still there. The memory entry about a client you parted ways with is still there. All of it still loads. All of it still costs tokens.

Here is the cleanup flow I recommend running once a month. It takes about an hour.

Step one: audit your CLAUDE.md files. Start with global. For every rule, ask two questions. First, “does this apply to every session, or only when I am doing one kind of task?” If only one kind of task, move it to a skill. Second, “is this still true?” If not, delete it. Then do the same for each project-level CLAUDE.md and each module-level CLAUDE.md. Move things that belong at a different level. Delete things that are no longer true. When I ran this on my own files I lost roughly a third of the content and did not miss any of it.

Step two: audit your skills. For each skill, ask: “have I used this in the last ninety days?” If not, archive it. Archive, not delete, because some skills are seasonal. “Is this actually a procedure, or is it a reference list?” If it is a reference list, move it to a documentation file and delete the skill. “Does this duplicate another skill?” If yes, merge them.

Step three: audit your memory. Read every entry. For each one, ask: “is this still true?” “Is this a fact, or is it a rule in disguise?” “Is this discoverable from reading current state?” Delete anything that fails those tests. Rewrite anything that is too long. Move anything that is a rule back to CLAUDE.md.

Step four: audit your MCP servers. List them. For each one, ask: “have I used this in the last thirty days?” If not, disable it. “Do I remember why I installed this?” If not, disable it. You can always re-enable later.

The cleanup flow is boring but it is the single highest-leverage thing you can do for your AI coding quality. A clean context system is not a one-time achievement. It is a monthly discipline.

Start here: your first CLAUDE.md if you are setting this up today

If you are reading this without an existing CLAUDE.md and you are about to write your first one, here are the ten rules I would seed a global file with on day one. These cover the cases I have found myself writing over and over across projects.

  1. Never commit with hooks disabled. If a pre-commit hook fails, fix the underlying issue.
  2. Never add co-author attribution to git commits unless I explicitly ask for it.
  3. Always run WPCS before pushing. Do not skip it.
  4. Every UI change must include its mobile breakpoint in the same commit. Responsive is not a follow-up.
  5. Browser-verify every UI change before marking done. Code passing tests is not the same as a feature working.
  6. Prefer editing existing files over creating new ones.
  7. Use dedicated tools (Read, Edit, Glob, Grep) over shell commands for file operations.
  8. When referencing code, output file_path:line_number so I can click through.
  9. Never mock the database in integration tests. Use a real one.
  10. Match the existing code style of the file. Do not impose a new convention mid-file.

Ten is enough to start. You will add more as you learn what matters to you, and you will delete some of these when you find them too rigid. That is the point. A healthy CLAUDE.md evolves through cleanup, not through accumulation.

Organization discipline

Once you have set up the layers and run cleanup once, there are a few habits that keep the system healthy between cleanups.

One concept, one place. If a rule shows up in two layers, one of them is a copy and it will drift. When you notice duplication, pick a home and delete the other copy immediately.

Precedence is always user instructions first, then project, then skill, then global default. Write this down somewhere so you can refer to it when two layers appear to contradict.

Name files by what they mean, not when you wrote them. A file called feedback_testing.md tells you what it is years later. A file called 2026-april-notes.md does not.

Anything that starts with “when working on…” is a rule or a skill. Anything that starts with “remember that last time…” is memory. The grammar tells you the layer.

If you are about to write the same instruction twice, write it once and link. Duplication is the enemy of maintainability. That is true in WordPress code and it is true in AI context design.

The takeaway

A bigger instructions file is a symptom, not a solution. It is a symptom of not knowing where each piece of knowledge belongs. When you catch yourself adding rule number fifty to your CLAUDE.md, stop. Ask whether the thing you are about to write is actually a rule, or whether it is a fact, a procedure, or a tool description. Put it in the layer that answers its question.

Rules go in CLAUDE.md. Facts go in memory. Procedures go in skills. Tools go in MCP servers. Each has its own loading model, its own purpose, and its own maintenance discipline. When you get this right, your global file shrinks, your tokens drop, your results improve, and the mental overhead of maintaining your AI coding setup goes from stressful to sustainable.

If you have been piling everything into CLAUDE.md, you are not alone. Every WordPress developer using Claude Code does it at first. Cleaning up is a one-hour job that pays back on every session for months.

I would love to see how other WordPress developers are structuring their Claude Code context. If you have a pattern that works, a failure mode I did not cover, or a skill you have written that you think every WP dev should steal, drop it in the comments. The best way this approach gets better is by comparing notes.

Varun