A rules file starts as one page. Six months later it is fourteen pages and nobody can remember what is in it. The team adds a new rule whenever something annoys them and never deletes anything. The agent loads the whole file into context every session, ignores most of it, and the team is convinced it is still useful because they wrote it.
This is the most common end state of a rules file. It is the rules file as junk drawer: a place where good intentions go to coexist with stale advice, redundant facts, and aspirational principles, with everything weighted equally because nothing is curated.
A junk drawer is not a tool. It is a feeling that you have a tool.
What rules are for
A rule, in the AGENTS.md / CLAUDE.md / equivalent sense, has exactly one job: change what the agent does. If an entry in the file does not change what the agent does, it is taking up space at the expense of the entries that do.
This sounds obvious. In practice, most rules fail this test.
The aspiration: “We write clean, maintainable code.” The agent does not know how to act on this. It already wants to write clean code, in whatever sense it learned the term from training. The entry costs context and provides no signal.
The redundancy: “Use TypeScript strict mode.” Strict mode is already on in tsconfig.json. The compiler enforces it. The agent will notice when it runs. The entry is a fact about the codebase the codebase already exposes.
The principle-without-verb: “Prefer composition over inheritance.” Useful for humans during design. Hard for an agent to translate into a concrete decision in the file it is editing right now.
The contradiction: page 3 says “always use async/await”; page 11 says “wrap async calls in our safeAsync helper for error handling.” Both might be true. Together, they leave the agent guessing about precedence.
The prose dump: three paragraphs explaining the history of why the team chose a particular ORM. Interesting. Not actionable. Not load-bearing.
None of these entries are bad. They are simply not earning their place in a file whose only job is to change the agent’s behavior.
The two questions every rule must answer
Before adding an entry, ask:
What would the agent do without this rule? If the answer is “the same thing,” delete it. The rule is describing reality, not changing it.
What is the concrete action the agent should take? If you cannot name one, the entry is a principle, not a rule. Principles belong in design docs. Rules belong in the rules file.
A rule that passes both tests is something like: “When adding a new API endpoint, register it in routes.ts and add a corresponding integration test in tests/api/. Do not add ad-hoc route registrations elsewhere.” Concrete. Acts on a real decision the agent will face. Different from what the agent would do by default.
A rule that fails: “Maintain consistency with existing patterns.” True. Aspirational. Tells the agent nothing it did not already want to do.
What to put in, what to leave out
The file should contain rules that meet a high bar: things the agent will get wrong without them, that are not enforceable by tools the agent already runs, that are specific enough to act on.
Examples of things that belong: layering and architectural boundaries the type system cannot express; naming conventions for new files, modules, or tests; which library to reach for when there is more than one option in your dependencies; how to structure errors that bubble out of service code; where to add new tests, in what file, with what kind of name.
Examples of things that do not: anything your linter, formatter, or type checker already enforces; anything that is true of every codebase (write tests, do not commit secrets, prefer readable code); principles without a verb; historical context with no current implication; rules that exist because of one bad incident two years ago that nobody can remember the details of.
The single most useful question to ask, on every line of an existing rules file: “If I deleted this, would the agent do anything differently?” If the honest answer is no, the line is taking up space.
Pruning is the practice
Adding rules is easy. Deleting them is the discipline.
The same flywheel that adds rules from review comments has to run in the other direction. Someone, on a regular cadence (weekly is fine, monthly is the maximum) reads the rules file end to end and asks the deletion question on each entry. Rules that turned out to be wrong get deleted. Rules superseded by a linter get deleted. Rules nobody remembers the origin of get deleted unless someone can defend them in five seconds. Rules that contradict newer rules get reconciled, or one of them gets deleted.
If you are using Bridle, there are commands to audit the harness (including rule files) for problems to make this a faster process.
A healthy rules file is small. It is small not because the team has fewer opinions than they used to, but because the opinions have moved to the places that enforce them automatically (the linter, the tests, the types) and only the genuinely context-dependent ones remain in the file.
A team that prunes ends up with a rules file in the dozens of lines that actually changes agent behavior. A team that does not ends up with hundreds of lines that mostly do not, and an agent that pays attention to the wrong things because the signal is buried.
A starting rule for your starting rules file
If you have nothing today and you are starting from scratch, do not try to write the complete file in one sitting. You will produce the junk drawer by default. Start with this rule, alone, in the file:
Rules in this file change what the agent does. Add a rule only if you can name the specific behavior it changes and the alternative behavior the agent would default to. Anything else belongs in a design doc or a linter config.
That sentence, sitting at the top of an otherwise-empty file, will guide every addition for the next year. Every other rule will be made better by the discipline that one rule enforces.
The junk drawer is the default. Curation is the work.
