Making an AI agent follow your project's conventions
24 September 2026 | 6 min
Every agent writes like the average of the internet until you give it a reason not to. Most attempts at giving it one do not work.
The complaint is always the same. The code works, and it does not look like your code. Wrong error handling, a logging style nobody here uses, a dependency added for something the project already has a helper for.
Why a rules file often does nothing
Most projects add a conventions file, and then find the agent follows it for two files and drifts. Three reasons, in roughly this order of frequency:
- It is too long. A thousand-line style guide competes with the code in the context window and loses. The instructions that survive are short and specific.
- It states preferences, not rules. "Prefer functional style" is advice. "Never use a bare except" is checkable.
- It repeats what the code already shows. An agent reading your repository can see your naming convention. Spending context restating it buys nothing.
Write rules that are checkable
The useful test for a line in a conventions file is whether a reviewer could say it was broken without arguing. Compare:
| Not useful | Useful |
|---|---|
| Write clean, readable code | Functions over 40 lines need a comment saying why |
| Handle errors properly | Never catch an exception without logging it or re-raising |
| Follow our testing style | Every test must fail when the behaviour it guards is removed |
| Use our utilities | HTTP calls go through lib/http.py, never requests directly |
Point at examples, not adjectives
One named file that does the thing correctly is worth more than a paragraph describing it. "Match the error handling in api/orders.py" gives an agent something to read. "Handle errors consistently" gives it nothing it did not already assume.
Put the constraint where it is enforced
The most reliable convention is one that fails a check rather than one that lives in a document. A linter rule, a test, or a CI step is a convention an agent finds out about by breaking it, and finding out by breaking it is the mechanism that actually works.
This is the real reason an agent that runs your tests behaves better than one that does not. It is not obedience. It is that the feedback exists at all.
What to write down, then
- Things the code cannot show, such as why a slower approach is used deliberately.
- Things that already went wrong, written as the failure rather than the rule, because the reason makes it stick.
- Where the boundaries are, such as which directories are generated and must not be edited by hand.
Keep it short enough to read in a minute. If it is longer than that, the parts at the bottom are not being followed and you have no way of knowing which.
Where AstraCode fits
AstraCode reads project rules and the repository together, runs the checks your project already has, and shows you what it ran. A convention enforced by a test is one it finds out about immediately rather than one it can quietly ignore. Free tier, no card.
Rules it finds out about by running them
Your linters and your suite are the conventions that actually hold. Free to start, no card.
Also on the blog
- When an AI agent says it is done and it is not
- How to review code an agent wrote
- We benchmarked eleven models in our own editor. The cheapest one won.
- Fable 5.1 cut cache reads to $0.25. Here is what that saves on a real agent run.
- What vibe coding is, and when it stops working
- What Google Antigravity is, and what it costs
- What GPT-6 Astra actually costs to run a coding agent
- GPT-6 Astra's pricing cliff at 272K tokens, and why agent runs fall off it
- How we're benchmarking GPT-6 Astra for coding (and why scores won't tell you)
- How to use GPT-6 Astra in your editor, and when not to