Without code journals, your AI will fail you.

Everyone who ships with an AI coding assistant learns the same lesson twice. The first time, the tests catch a regression and you feel clever for having written them. The second time, the tests pass, the build is green, and the assistant confidently rewrites a decision you made three weeks ago for a reason you can no longer remember. The second lesson is the expensive one, and it is the one nobody warns you about.

A test encodes what the system must do. It verifies behavior, and it is genuinely valuable. But a test is silent on the only question that matters when a person or a machine reopens the code later: why. Why this timeout and not a longer one. Why you abandoned the obvious approach. Why the ugly branch has to exist. Tests preserve the answer and throw away the reasoning, and the reasoning is where the knowing actually lives.

It is not a code comment and it is not documentation. It is a short, dated record of a decision and the constraint that forced it, kept in the repo next to the work. Here is a real one:

# Token refresh: proactive, not reactive
Decision: refresh the auth token 5 minutes before expiry, on a timer.
Rejected: refresh reactively on a 401. Simpler, but it double-fires
  every in-flight request during the refresh window.
Constraint: the auth provider rate-limits refresh to 1 per second
  per user. The June load test returned 429s at 200 concurrent users.
The knob: the 5-minute lead. Shorten it only if the provider
  raises the refresh limit.

Four lines of prose. It cost the ninety seconds at the end of a session it took to write. Watch what it is worth.

Give the assistant the codebase but not the journal, and ask it to do the reasonable thing:

Nothing stopped it. No test failed, because the cost does not show up until the system is under load. It shipped. Three weeks later it fell over at two hundred concurrent users, and by then no one remembered that “simpler” had already been tried and rejected for exactly this reason. The assistant was not reckless. It was blind, and blind is worse, because it overwrote a load-bearing decision with total confidence and left no mark.

Now give it the same prompt with the journal in the repo. It does not silently obey, and it does not silently overrule you. It surfaces what it found and hands the decision back:

The journal did not catch the mistake on its own, and it did not turn the machine into an oracle. It gave the assistant something to notice, and gave you the moment to decide with the reason in front of you instead of rediscovering it in production. Same model, same prompt: one silently overwrites a load-bearing decision, the other stops and asks.

An AI assistant is a brilliant idiot with no memory of your intent. Point it at a well-tested codebase and it will keep every test green while quietly undoing the judgment that produced them, because nothing in the repo ever told it that judgment was there. It is not being reckless. It is doing exactly what you would do with a codebase whose history had been erased: guessing, confidently, and passing the tests while it does.

A test tells the machine the code still works. Only a journal tells it why the code is shaped this way, and the why is the one thing it cannot safely guess.

The structure is not sacred. A decision, the option you rejected, the constraint that forced your hand, and the knob to turn if the world changes. Dated, plain text, in the repo. That is the whole discipline, and almost no one keeps it.

Scale the problem up and it stops being a coding tip. A team is a codebase whose tests are its outcomes and whose journal is, usually, nothing at all. When the person who knew why walks out the door, the outcomes keep passing for a while, and then one day they do not, and no one can reconstruct the reasoning because it was never written anywhere it could survive. The org kept the what and threw away the why, exactly like the green test suite, just slower and more expensive.

Your AI will fail you for the same reason your last senior engineer’s code became unmaintainable the day they left. Not because the work was wrong, but because the knowing behind it was never moved anywhere it could outlast the person who held it. Write the journal. Move the knowing. The machine, and the next human, are both counting on a record that you are the only one who can leave.