What is an invariants file?
A short, living list of rules that must always hold in a project, written down the day each one is learned, and read by people and AI before any work starts.
An invariants file is a plain document of rules that must stay true in a project no matter who, or what, is doing the work. Each rule is short, specific and earned: it exists because something broke once.
Why it matters when AI does the building
An AI model starts every session with no memory of last week's mistakes. A person forgets too, just more slowly. The invariants file is where the project's hard-won knowledge lives, so a recon prompt can tell the model to read it before touching anything.
Without one, the same bug comes back every few weeks, and every fix depends on someone remembering.
What goes in it
Good entries are concrete enough to check. Some real examples from Plumerie, the library app behind our method:
- Always write documents with merge, never with a partial update call.
- Deploy cloud functions by name, never all at once.
- Sign-in with Google only works on the production domain, so test previews with email and password.
- Repos live outside cloud-synced folders.
Vague entries like "be careful with the database" don't count. If you can't tell whether a change breaks the rule, rewrite the rule.
How to keep it useful
- Add the rule the day it bites. Not at the end of the sprint.
- Keep it short. A page or two. If it grows past that, split it by area.
- Make it the first thing read. Point to it from your AI instructions file and your function map.
- Delete rules that no longer apply. A stale rule teaches people to skip the file.
For teams
The same idea works outside code. A marketing team's invariants file might say: every statistic links to its source; prices only come from the pricing page; no customer email goes out without a human reading it. It is the written answer to "what is AI allowed to do here?", which is why it sits at the centre of our team workshop.