A particular fatigue sets in after a few days of working with an AI: explaining yesterday’s convention again today, and walking into a trap this week that you already walked into last week. Every session starts blank — but the project does not. A project accumulates decisions and their reasoning, incidents already suffered, and rules that have to hold.
Closing that gap is simple in principle: turn the accumulation into a document inside the repository and have it read at the start of every piece of work. The repository behind this site runs on exactly that.
What goes in — three kinds of entry
Decisions must carry their reasoning. “We do not use a caching plugin” on its own reads as a preference, and the next person — or the next session — reverses it the moment it looks convenient. Write “…because a plugin cache and the server cache invalidate at different times, leaving the admin and visitors on different versions of the page”, and anyone reversing it at least knows what they are accepting. What makes a decision stick is not authority but the reason attached to it.
For incidents, the trick is to record the symptom before the cause. Next time round, what you hold in your hand is the symptom, not the cause. Written as you saw it on screen — “the list says nothing found while the filter chip beside it says ten” — it becomes searchable the instant that screen reappears months later. An entry containing only the cause is legible only to someone who already knows the cause.
Pair every rule with a check
The third kind is the heart of it. A rule nobody can check is not a rule; it is a wish. So each rule is written together with a one-line command that detects a violation.
# Rule: component styles reference tokens only, never colour literals
# Check: must return nothing
rg '#[0-9a-fA-F]{3,8}' assets/scss/components/
# Rule: no nonce checks on webhook routes (external callers never have one)
# Check: must return nothing
rg 'wp_verify_nonce|check_ajax_referer' includes/gateway-*.phpAttaching a check buys three things at once. The rule stops being ambiguous — if you cannot write a check for it, the rule is not yet properly stated. Anyone, human or model, can verify their own work. And nobody has to argue later about whether the rule was broken; you run the command.
Checks do not need to be sophisticated. Most are at the level of “this string must not appear in this directory” or “this URL must return 200”. What matters is not elegance but existence.
Keeping the document from going stale
The most common failure is the document lagging the code. A wrong document is worse than no document, because readers act on it as fact. Which is why the commit that changes a decision and the commit that changes the document should be the same commit — they are two faces of one change.
Length is also something you manage. The bigger it gets, the harder it is to have all of it read, so deleting sentences that are no longer true matters as much as adding new ones. Paragraphs kept “in case we need them one day” accumulate until the document quietly stops being read.
Finally, never put secrets in it. A context document is written to be read widely; credentials and API keys need the exact opposite treatment. What belongs in the document is the rule — “keys live in the environment config and are never committed”.
Managed this way, the file is a team document before it is an AI tool. When the thing a new colleague reads on day one and the thing loaded at the start of a session are the same document, it earns its keep twice.
How to carry these conventions into an individual request is covered elsewhere in the AI in practice archive, and the deployment rules such a document records overlap with the From local to production series. To have the conventions and vulnerabilities of a running site sorted out together, a diagnostic is part of our optimization program.