An AI coding tool has no memory between sessions unless something gives it one, and no house style unless something states it. Left alone, every session solves the same class of problem its own way, and every departure takes knowledge nobody wrote down with it.
None of this needs discipline. It needs four files, one habit, and a rule for when two people disagree. This is the depth layer behind the learning loop and the informed way to code with AI: what to build, in the order to build it. Click any item for the detail.
1. The files every repository carries
An instructions file, under two hundred lines. Conventions specific to this codebase.
How errors are handled, where business rules live, what never goes in a commit. Kept short on purpose: a file that has grown past a few hundred lines gets skimmed, not followed.
An architecture note. What the system is made of and why.
Re-read at the start of work rather than reverse-engineered from the code each time.
A decision log. Choices and their reasoning.
So a decision already made does not get reopened a month later by someone who was not there for it.
A one-line memory file. Patterns that worked, mistakes corrected.
Short entries, so hundreds of them cost only a few hundred tokens of context.
Done looks like: an AI session on this repo, given no other instructions, follows the codebase’s actual conventions on its first try.
2. The ritual that keeps the files honest
Read at the start of every session. Updated before it closes. And updated the moment something important is settled mid-session, not saved for the end, because a long session’s context gets summarized and the thing decided an hour ago is exactly what gets lost.
A file written once and never touched again is worse than no file. It is actively wrong and nobody has noticed yet.
Done looks like: the architecture note was last updated this month, not at the start of the project.
3. A shared vault above the repo files
The four files are per-project. A vault is the layer above them: a git repository of short notes (patterns, decisions, gotchas) with one index file listing a line per note, pulled into every AI session’s context automatically at the start. This is what makes a lesson learned on one project available on every project after it, without anyone remembering to mention it.
New repositories get the pointer to the shared vault stamped in as part of being set up, the same way they get their hosting and their environment variables. Not a step someone is trusted to remember. A default that is simply there.
Done looks like: a brand-new repository’s first AI session already references a lesson from a different project.
4. Who owns it, and how contributions come in
Once more than one person is writing to the shared vault, three things need deciding before they are needed, not during the argument.
A named owner with a monthly pass.
Merge near-duplicates, flag entries that have gone stale, keep the index lines written for a stranger rather than for the person who wrote them.
A route in for everyone, not only the owner.
A shared inbox anyone can drop raw material into, which the owner turns into a proper note. Contributing has to be easier than staying silent.
An author on every entry.
Not for credit. It is what makes the conflict rule below possible at all.
Done looks like: someone other than the owner has added something in the last month.
5. The conflict rule
Reconcile first. Two entries that look like they disagree are usually both true under different conditions. State the boundary and move on; this resolves most apparent contradictions without anyone deciding anything.
Then the author decides. When it is a genuine contradiction, the decision goes to whoever wrote the entry, because they know why they wrote it. Not to whoever is most senior, and not to whoever is in the room. If that person has left, a named fallback owner decides. Either way, the resolution is recorded, not silent: what it used to say, what it says now, why, and who decided.
Deliberately no approval step. The instinct is to add review before anything gets recorded. Do not. The moment writing something down needs someone else’s sign-off, people stop doing it in the moment, and the knowledge goes back to living only in chat history, which is the exact failure this whole system exists to fix. Conflicts should stay rare; capture has to stay frictionless.
Done looks like: a past contradiction has a dated resolution line, not two entries quietly disagreeing.
6. The other half: work that has not landed anywhere yet
Knowledge is one side of continuity. Work in progress is the other, and it is invisible to any of the above until it is pushed.
- Push daily, even unfinished. A habit, not a policy, because nothing automated can see code that only exists on one laptop.
- Keep tickets honest. Nothing sits in “in progress” overnight without a comment saying where it actually is.
- Where it is worth the setup: a scheduled process that drafts a short handoff note per active project from ticket activity and commit history, for a person to edit and push daily rather than write from scratch. The point is not the automation. It is that the habit no longer depends on anyone remembering.
Done looks like: if either person on a two-person project vanished today, the other could describe what was in flight from what is already written down.
7. The drill
None of the above is tested by anything except an actual departure, which is a bad time to find out it does not work. Run a drill: someone who was not working on a piece of it picks it up with zero help from whoever was. Wherever they get stuck is the real gap in what is written down. Not what the documentation claims to cover; what an outsider actually needed and did not have.
Keep this manual on purpose. Automating the drill would defeat the point of it as a check.
Done looks like: the last drill found something, and it has since been fixed.
What this is not
It is not a wiki, which has to be known about and searched. It is not an approval process, which would stop people writing things down in the moment. It is not a replacement for git, which already keeps the code; this is for the reasoning git never captures. And it is not only for departures: the more common payoff is two people on different projects solving the same problem twice, which happens weekly, long before anyone leaves.
Changelog
- 2026-09-05: first version.
- 2026-09-08: file and ownership items collapsed to one-liners; conflict rule and work-in-progress sections restructured; short version added.