Boris Cherny, the creator of Anthropic’s Claude Code, has a blunt prescription for developers who rely on the AI coding agent: treat your project’s CLAUDE.md files like code—subject to ruthless refactoring—not like a permanent scrapbook of every past failure and workaround. In a discussion surfaced by The AI Automators and summarized by Geeky Gadgets, Cherny argued that cluttered, contradictory, or simply outdated project instructions actively degrade Claude Code’s reliability, and that the quickest fix is often to delete or radically pare back the accumulated context.
His message arrives as AI coding agents become embedded in everyday development, including on Windows, where teams run Claude Code in PowerShell, WSL, or CI pipelines. A CLAUDE.md file starts as a useful home for project conventions, but over weeks of adding exceptions, deprecated constraints, and personal preferences, it can metastasize into a load of context that obscures rather than illuminates.
Why Context Bloat Is a Reliability Killer
Claude Code discovers CLAUDE.md files along the directory tree and concatenates them into the session context. That design is convenient: a developer corrects the agent once, adds a note, and never has to repeat the instruction. Yet the model has no inherent way to distinguish between a security-critical build rule and a leftover note from a frustrating Tuesday three sprints ago.
When the context grows beyond a few hundred lines, Claude begins to struggle with adherence. Anthropic’s own documentation recommends keeping CLAUDE.md under 200 lines and warns that longer files “consume context and can reduce adherence.” The agent may miss newer instructions buried in the noise, apply obsolete rules, or be paralyzed by contradictory guidance. For Windows repositories that span PowerShell, Batch, .NET, Node.js, and WSL workflows, a global directive like “always use Bash” can wreak havoc when a task actually needs a Windows-native shell.
Cherny’s advice to “delete it” is best understood as a call for intentional reset, not a repudiation of documentation. The exercise is straightforward: make a copy of the file, strip out anything you cannot justify, then run a representative set of tasks—a bug fix, a refactor, a test run—and observe whether Claude Code falters. Only restore the instructions that demonstrably improve the outcome, and do so in the most concise form possible.
Who This Affects – From Weekend Coders to Enterprise DevOps
The practical impact depends on how deeply your workflow depends on agent-provided context.
Individual developers and hobbyists on Windows may find Claude Code unpredictably ignoring their preferences or making assumptions that were true two library versions ago. If you keep a single CLAUDE.md in your personal project, schedule a monthly pruning session. The same applies to auto-memory files that Claude Code generates; without review, they can accumulate ephemeral corrections that no longer apply.
Professional Windows development teams should treat CLAUDE.md as living configuration, not static documentation. In a monorepo, a sprawling root file can conflict with path-scoped instructions. Anthropic supports scoped rules that load only when work touches specific directories—a cleaner pattern for separating frontend, backend, and infrastructure conventions. The rule of thumb: if a rule must be enforced, encode it in a linter, CI check, or git hook. If it’s a preference, ask whether it belongs in the AI’s context at all. A team that never audits its CLAUDE.md risks having the agent respond to assumptions no one would defend in a code review.
IT professionals and DevOps engineers who run Claude Code in automated pipelines or as a CLI assistant should pay particular attention to permission boundaries. Cherny’s remarks touched on Claude Code’s security posture, but a leaner prompt file is not a substitute for least-privilege access, sandboxing, or mandatory human approval of high-risk commands. Keep CI as the final authority on builds and tests; don’t rely on prose in a Markdown file to prevent destructive actions.
How CLAUDE.md Files Evolved Into Unmanageable Document Graveyards
When Claude Code first introduced persistent project memory, the feature was rightly celebrated. Instead of typing the same boilerplate preamble into every session, a team could document build commands, architectural notes, and coding standards once and have the agent apply them consistently.
The trouble began when the file turned into a running transcript of every edge case. A rule added to paper over an old model weakness persisted after the model improved. A temporary migration constraint outlived the migration. A developer’s pet formatting rule became de facto law for the entire repo. Because Claude Code discovers and merges files from multiple levels, downstream instructions can conflict with upstream ones in ways that are hard to debug.
Cherny’s commentary, as reported by Geeky Gadgets, reflects a broader industry realization: AI agent instructions need versioning, ownership, and review, just like build scripts and test suites. Anthropic’s own practice of “ablation”—systematically removing components to measure their impact—provides a mental model for CLAUDE.md hygiene. If no one can articulate why a rule exists, remove it and let the agent rely on code structure, tests, and normal task framing instead.
Practical Steps to Tame Your Agent Instructions
Reclaim control with a structured audit, not a single panicked delete.
- Inventory the instructions. List every rule in every CLAUDE.md file (root, subdirectories, and auto-memory). Note which ones are redundant, which are contradicted by later rules, and which reflect temporary workarounds.
- Test without them. Fork a branch, remove or comment out low-confidence instructions, and run a suite of representative tasks. Use the same prompts you would in daily work. If Claude Code no longer respects a critical convention, restore just that rule in a minimal form.
- Move enforcement out of prompts. Formatting rules belong in a formatter. Security policies belong in branch protections. Build commands belong in package scripts. A CLAUDE.md file should describe what, not enforce; that job is for hooks and CI.
- Adopt path-scoped rules. Split a monorepo’s monolithic CLAUDE.md into smaller files located beside the code they govern. A root file can hold universal guidance (e.g., “never commit secrets”), while
src/backend/CLAUDE.mdcovers that subsystem’s specifics. - Add expiration dates to temporary rules. If a workaround must be added, prefix it with a comment like
<!-- REMOVE AFTER: 2025-12-01 – Migration X completes -->. Schedule a calendar reminder to review. - Use Anthropic’s tools for iterative refinement. The
claude-system promptand the environment variableCLAUDE_CODE_SIMPLE=1can help you test stripped-down configurations quickly. Cherny mentioned these as part of a workflow that treats prompt design as an ongoing experiment, not a one-off document. - Distinguish human-maintained instructions from auto memory. Claude Code’s auto memory learns from corrections and preferences, but it can become just as cluttered. Treat it as a cache that may need periodic clearing. If you find the same instruction repeatedly being auto-saved, it probably belongs in the human-curated CLAUDE.md.
| What to Remove | What to Keep | Where to Enforce It |
|---|---|---|
| Obsolete workarounds (e.g., pinned dependency versions no longer needed) | Stable build and test commands | CI pipeline, package.json, Makefile |
| Duplicate or contradictory style rules | Architecture constraints (e.g., “services must not import controllers”) | Code review, linting rules |
| Personal preferences elevated to global defaults | Project-specific entry points and configuration | Configuration files, .editorconfig |
| Instructions that parrot what the code already expresses | Security boundaries (e.g., “do not modify authentication module without review”) | Branch protections, CODEOWNERS |
The Path Ahead for AI Development Hygiene
Cherny’s advice is a preview of a maturing discipline: prompt engineering as configuration management. As Claude Code and similar agents handle longer, more autonomous tasks, the cost of stale context will rise. Anthropic may eventually build features that auto-expire or flag outdated instructions, but for now, the responsibility sits with developers.
Windows teams in particular will need to watch how agent instructions interact with shell environments, path separators, and platform-specific toolchains. A rule that makes sense in a WSL session may be actively harmful when the agent is working from PowerShell. The answer isn’t more rules; it’s more specific, scoped rules and robust enforcement outside the prompt.
Expect the conversation about CLAUDE.md hygiene to intensify as coding agents move from assistant to colleague. The developers who treat their project instructions as living, reviewed artifacts will get sharper, more predictable results than those who let them fossilize.