My clear, practical take on the agent rule file problem: why Markdown sprawl and token bloat happen, and how Baz fixes it by turning agent prompts into a single, versioned policy that is translated into tool-specific rule files for consistent, auditable agent behavior.
Cursor reads .cursor/rules
Copilot looks for .github/copilot-instructions.md
Continue has its own config
Other agents expect agent.md, AGENTS.md, or SYSTEM.md
The result is predictable: The same intent is duplicated across files, rules drift, agents behave differently depending on where they run. This is a tooling problem, not a prompting/context problem.
It started with good intentions. Agent models like Claude and other code-focused models were trained and prompted to think step by step, breaking large tasks into structured reasoning. Anthropic and other tool builders encouraged agents to create persistent plans, checklists, summaries, and scratchpads in Markdown. That made sense. Markdown files are easy to read, version control, and keep context across long sessions or sub-agents.
Files such as PLAN.md and SUMMARY.md became the agents' external memory. They helped agents avoid forgetting steps, reduce hallucinations, and handle large codebases without overloading the context window. Standards such as agents.md and CLAUDE.md amplified this pattern, turning one-off plans into habitual output.
But it went wrong. System prompts push verbosity in the name of safety and completeness. Agents started producing unnecessary files every few prompts: summaries of nothing, redundant reviews, and "closing thoughts" no one asked for. The result is token bloat and repo clutter. Engineers report sessions dying from tokens wasted on irrelevant greps and Markdown spam. Repos fill with dozens of throwaway docs. Rules that say "no Markdown files unless requested" are ignored.
The irony is sharp. agents.md is praised as a clean standard for project context and has been adopted widely. The very agents that agents.md is meant to guide are often the biggest polluters. What was meant to make agents smarter and more reliable has turned into digital hoarding. Teams spend time purging files before commits or hacking .gitignore. The tools designed to reduce manual work now require babysitting.
Most repositories already contain some form of agent guidance, intentional or accidental. These files overlap heavily in content and intent: coding standards, architectural constraints, what an agent may change, and what must never be changed. But each tool reads a different subset and none agree on structure or precedence. Common examples are:
Teams copy and paste. Rules drift. Agents behave inconsistently across IDEs, CI, and local runs. That inconsistency breaks trust.
Baz introduces a single canonical source of truth for agent behavior, independent of where the agent runs. Instead of treating agent instructions as raw prompts, Baz treats them as structured policy. From one definition Baz can generate the files each tool expects, for example:
AGENTS.md for repo-level portability.cursor/rules for Cursor users.github/copilot-instructions.md for Copilot ChatThis is a translation layer, not another config file. You define intent once. Baz emits the artifacts agents need and enforces consistency.
Agent behavior must be consistent across environments. An agent reviewing a change in CI should follow the same constraints as an agent editing code in an IDE. A breaking-change detector should operate under the same policy as a refactoring agent. When rules drift, trust breaks.
Centralizing agent intent makes behavior predictable, reviewable, and versioned alongside code. It reduces the need for manual cleanup and lowers the risk of hidden costs from token bloat and needless file churn.
Most teams still think in terms of prompts: long system messages copied between tools. Baz treats agent instructions as policy instead. Policy can be diffed, reviewed, and enforced. Policy can be applied uniformly to any agent at any stage of the lifecycle.
This is the same shift that happened in code review: from freeform comments to structured checks that are easy to audit and automate.
As more agents enter every stage of development, rule sprawl will get worse unless we standardize how intent is authored, stored, and translated. The winning model is not better prompts. It is a shared contract between humans, agents, and tooling. We're building that contract.. stay tuned for more on this soon.