Some published agent prompt templates from AI vendors already run to hundreds of lines: voice tone, code review procedures, reactions to conflicting requirements, response formatting, what to do if the user is rude. The problem is visible even in mature engineering teams. Even teams close to model development often rely on long behavioral prompts. If even the creators of the agent cannot hold its behavior in twenty lines and instead write hundreds, the problem might not be the discipline of the team that created a 500-line CLAUDE.md. The file format encourages unrelated rules to accumulate in one place.
Over the past year, many teams use the same pattern: before starting a project, they create a context configuration file — CLAUDE.md, .cursorrules, or an equivalent — and add unrelated instructions to the same file. Code style and communication tone, complex response formatting instructions, corporate regulations. As the file grows, even maintainers stop reading it carefully.
This creates practical problems for agent behavior. Attempting to fix a universal personality and a set of behavioral rules for the agent in a single static file can slow down routine tasks and make outputs less predictable.
What the Model Loses When the File Grows
A long prompt does not only consume tokens; it also makes relevant instructions harder to prioritize. The more background noise loaded into the system context before a specific task, the lower the quality of its execution. In practice, this usually shows up in three ways:
- Irrelevant instructions compete with the current task. The model must process rules that have no relevance to the current step. You ask the agent to write a single regex, but it has to read forty points about how to behave in complex architectural discussions first.
- Requirement conflicts. For example, a rule that asks for detailed comments conflicts with a task that needs a short patch. The broader the file, the more likely such conflicts become.
- Lack of flexibility. Core refactoring, client documentation, a security audit, a quick prototype — these are tasks with opposite requirements for depth, tone, and boundary conditions. A single static file cannot describe all modes well at the same time without degrading in at least one of them.
The issue is not that someone phrased the rules poorly. The issue is using one static file for operational behavior — the attempt to describe behavior for any future situation in advance with a single unchanging text.
What CLAUDE.md Should Be by Design
CLAUDE.md works best as project documentation for the agent. Treat CLAUDE.md as a README for the agent: build and deploy commands, codebase architecture, paths to key files, project conventions. Include only information the agent cannot infer from the repository. Do not duplicate the folder structure the agent will see via ls. Do not restate generic engineering advice.
A README does not grow to five hundred lines because once it starts explaining the obvious, people stop reading it — and the model also has to process low-value text. A CLAUDE.md designed as a repository map rather than a book of job descriptions fails for the same reason. Teams often break this separation not because they misunderstand the README analogy, but because they do not know where to put everything else — tone, depth, boundary conditions, regulations. So they put those rules into the one file that is always loaded.
Rules Belong in the Wrapper, Not the File
This creates a design choice. If CLAUDE.md must remain a map, and operational behavior — tone, depth, focus, constraints — must be real and different at every step, then that behavior has nowhere to fit inside a single file. Shorter rules help, but the stronger fix is to move task-specific behavior outside CLAUDE.md: task-specific operational rules should be assembled by an external wrapper — an orchestrator, pipeline, or CLI/API wrapper that assembles the final context right before assigning a specific task.
One implementation can look like this:
┌─────────────────────────────────────────────────────────┐
│ External Wrapper │
│ (Determines task type, phase, and required work mode) │
└───────────────────────────┬─────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌──────────────────────┐ ┌─────────────────────────┐
│ Base context │ + │ Dynamic context │
│ (Minimal │ │ - Tone and depth │
│ CLAUDE.md) │ │ - Focus vector │
│ │ │ - Boundary conditions │
└──────────────────────┘ └─────────────────────────┘The wrapper classifies the request and assembles the final context itself — instead of storing rules for unrelated tasks into a file the agent reads in full regardless of the task.
What the Wrapper Adds Per Task
Instead of writing rules for every occasion in one file, the wrapper selects instructions for the specific request:
- Output length and explanation depth. For a quick hypothesis check, the instruction "give only working minimal code without explanations" is injected. For an architecture design task, the requirement to conduct risk analysis and compare alternatives.
- Tone and format. Dry and strict format for PRs, looser format for brainstorming, academic for research data analysis.
- Primary priority. Depending on the phase, the wrapper focuses the model on performance, backward compatibility, security, or speed of implementation.
- Task-specific constraints. Compliance with regulations, a ban on specific third-party libraries — these are connected exactly when the task touches the relevant modules, rather than remaining in every prompt when irrelevant.
This pattern is already useful in production workflows. For example, in my content pipeline, I do not store one universal content prompt for all channels — it is assembled on the fly from a prompt tailored to the specific channel, a base voice file (voice/identity.md), a language register (voice/en.md or voice/ru.md), and a single row from the channel settings table (voice/dials.md): maximum provocation level, hook density, and required brand elements. A Telegram post and a LinkedIn post get the same base voice, but different tone, different density, and different constraints — added only when generating that channel’s post, not pre-written in a monolithic "how the author always writes" file.
The same rule applies to the project’s CLAUDE.md. common rules used by at least three skills go into CLAUDE.md; skill-specific rules stay with the skill. The file stays short because there is an explicit placement rule — the same rule this article describes.
The same loading pattern appears in other systems.
Examples:
- Code review bots connect a security checklist only when the diff touches
auth/, not always. - **
.cursor/rules/*.mdcwithglobs:** — a rule is loaded only for files of the relevant type. - RAG support agents mix only the knowledge base articles relevant to the current ticket into the context.
- CI/CD with path-triggers — the set of steps and secrets depends on which paths actually changed.
- Multi-agent orchestrators give each sub-agent its own narrow prompt for a specific step, rather than a shared universal prompt.
The Wrapper Can Also Bloat
Moving rules into a wrapper does not solve maintenance by itself. But any context system can become hard to maintain as it grows. A similar failure appears not just from CLAUDE.md, but from the number of components in a project generally: when there are few, everything is orderly and predictable; when the count reaches dozens, outputs can become inconsistent, and debugging which instruction caused the change becomes difficult. The wrapper can bloat too — it changes where maintenance happens; it does not remove maintenance. The advantage is that the growing part is versioned wrapper logic, not the text the agent is forced to read in full before every task.
Benefits of Moving Task Rules to the Wrapper
The practical benefits are several practical advantages — and together they are the answer to why one large rule file is a design problem, not only a readability problem:
- Fewer irrelevant tokens per task. The agent receives only the instructions needed for the current step. The prompt contains fewer unrelated requirements. Prompt pollution decreases not because there are fewer rules overall, but because there are fewer rules in the specific prompt.
- More predictable outputs. When an instruction is delivered immediately before the task and formulated for a specific context, the model is more likely to follow it. An instruction in a long general file competes with unrelated instructions; an instruction delivered at the moment of the task does not.
- Centralized updates. Changing requirements for tone or security rules can happen in one place — in the wrapper logic — without rewriting configuration files across every repository in the company.
Team Responsibility Changes
For a team, this shifts ownership of behavior rules. CLAUDE.md stops being the place where a universal behavior contract for the agent is fixed — because different task phases require different behavior: the agent must behave differently depending on the phase and type of task. Responsibility for behavior moves into the wrapper logic — versioned and tested code maintained centrally, instead of manual edits across dozens of company repositories simultaneously.
Keep CLAUDE.md as a Repository Map
CLAUDE.md is project documentation, not the place for task-specific operating rules. It should contain a concise repository map: stack, structure, critical environment constraints — information that is stable and not obvious from the code. Tone, explanation depth, priorities, and constraints do not belong in the file at all. That is the job of the dynamic context, assembled per request.
If CLAUDE.md has grown to hundreds of lines, do not only reorganize the file. It is a signal that some task-specific rules probably belong in wrapper code — instead of text the agent loads before even small tasks.