Figures on this page were verified 31 August 2026 against the providers' own documentation. Pricing, context windows and rate limits change without notice, so confirm any number against the provider before you rely on it. Tell us if something here is out of date.
A rules file is a system prompt that ships with your repository, and it is charged on every single request. That framing settles most of the arguments about what belongs in one. Rules must be specific, verifiable and short, because a long file costs money on every call and a vague one changes nothing.
Write rules a reviewer could check
The most common failure is aspirational instructions. “Write clean, maintainable code” is unfalsifiable, so it changes nothing while still costing tokens on every request. A good rule states a decision that would otherwise have to be guessed.
| Weak | Strong |
|---|---|
| Write clean, maintainable code | Functions over 40 lines must be split |
| Handle errors properly | Never catch a bare Exception; catch the specific class |
| Follow our conventions | Use snake_case for functions, PascalCase for classes |
| Write good tests | Every bug fix adds a regression test that fails without the fix |
| Be careful with dependencies | Do not add a dependency without asking first |
Every rule on the right can be checked against a diff. Every rule on the left cannot, which is why they are ignored in practice.
State the things that cannot be inferred
A model can read your code. It cannot read your history. The highest-value content in a rules file is the reasoning that is invisible in the repository.
# Project rules
## Commands
- Test: pytest -x -q
- Lint: ruff check .
- Build: make build
## Non-obvious constraints
- Python 3.9 in production. Do not use 3.10+ syntax such as match.
- `legacy/` is generated. Never edit it by hand.
- Database migrations are applied manually. Write them, do not run them.
- We use requests, not httpx. A previous migration was reverted for
connection-pool reasons; do not reintroduce httpx.
## Conventions
- snake_case functions, PascalCase classes.
- Catch specific exception classes, never bare Exception.
- Every bug fix adds a regression test that fails without the fix.The httpx line is the kind of entry that pays for itself repeatedly. Without it, every model and every new colleague will reasonably suggest the same reverted change.
Keep it short, because you pay for it every time
A rules file is prepended to effectively every request. At 5,000 tokens and 500 requests a day, that is 2.5 million input tokens a month before anyone asks a question. Most of that is affordable only because of prompt caching, and caching only helps if the file is stable, which is another argument against constant tinkering.
Aim for one page. If it is longer, most of it is either obvious from the code or aspirational filler. Both should be deleted.
Maintain it like code
- Commit it. It is shared context, not a personal preference file.
- Delete stale rules. A rule describing a framework you migrated away from actively misleads.
- Add a rule when you correct the same thing twice. That is the signal a convention is not discoverable from the code.
- Prefer tooling. Anything a linter or formatter can enforce belongs there, not in a prompt paid for on every request.
That last point is the sharpest test. If a rule can be enforced deterministically by a tool, a rules file is the more expensive and less reliable place to put it.
Frequently asked questions
What makes a rule effective?
That a reviewer could check it against a diff. Write clean code is unfalsifiable, so it changes nothing while still costing tokens on every request. Functions over 40 lines must be split is checkable, so it gets followed.
What belongs in a rules file that is not in the code?
The reasoning that is invisible in the repository: which directories are generated, which Python version production runs, and which previously attempted change was reverted and why. That last kind of entry pays for itself repeatedly.
How long should it be?
About one page. The file is prepended to effectively every request, so at 5,000 tokens and 500 requests a day it costs 2.5 million input tokens a month. Anything a linter can enforce belongs in tooling, not in a prompt you pay for every time.
