My AI log remembers so I do not have to
Every feature session on Buildom ends the same way: I write a log entry. One markdown file per session in docs/ai-log/, named YYYY-MM-DD-<topic>.md. There are 36 of them by now, and honestly, this folder does more for the project’s velocity than any architecture decision I have made.
What goes into an entry
The template is deliberately boring. Date, tool, feature area. Then a Goal section, an Outcome section, and two sections most people skip but that carry all the value: Decisions and Failed approaches.
The outcome part documents what actually changed and how it was verified. Not “implemented torches”, but “torch light is a radial gradient composited in the fog pass, verified with tsc, biome and by placing torches at chunk borders in a dev world”. The difference matters the next time someone asks whether torch light is in the render loop or the fog pass.
The failed approaches section is my favorite. When I tried something and it did not work, that goes in with a sentence about why it failed. That sounds negative, but it is the cheapest bug repellent I own: the same dead end cannot be walked a second time, because the second walker reads the log first.
The README is the manual for the agent
The log folder itself starts with a README.md, and I write those READMEs for the AI, not for me. Mine explains the purpose in three bullet points, continuity, institutional memory, hand-off, and then defines the exact entry format with the template inline. When an agent is asked to write a log entry, it does not guess the structure. It reads the README and produces a file that looks like every other file in the folder.
This has become a general habit in the project: every docs folder I create gets a README whose first job is to instruct the next agent session. What lives here, how to name files, when to read it, when to write it. A human needs a hint, an agent needs a contract. The template in the ai-log README is the reason my thirty-six entries are consistent enough to be greppable and scannable instead of thirty-six diaries with thirty-six styles.
The rule that makes it work
My AGENTS.md has one instruction that does the heavy lifting: before working on a feature or area, scan the ai-log for relevant entries. Past sessions may contain decisions, failed approaches, and open items. The agent reads before it writes, and suddenly every session starts with full context instead of archaeology.
A concrete example. Two weeks ago a URL race let a builder session write into the player’s persistent store. The fix itself was small, but the log entry captured the why: the gate existed, it was just fed a wrong value at the wrong time. That entry then spawned a follow-up note in my refactoring folder, because the root cause was structural: the “adventure only” rule lived in one component and in the discipline of future callers, not in the store itself. When I flipped the persistence hook defaults to fail-safe this week, the log entry was the receipt explaining why.
One more rule: agents are not allowed to write log entries on their own. I write them, or I explicitly ask for one. Otherwise you get fifty identical “did the thing, tests pass” files that nobody reads, and the log dies of noise.
Logs are aids, not specs
There is a caveat baked into my guidelines: where a log entry contradicts the code, the code is right. Logs describe intent at a point in time. Code is what actually ships. That single sentence keeps the folder honest, because nobody is tempted to treat an old entry as law.
The template also has a promotion path. Pitfalls that apply to every session, not just one, get promoted out of the log and into AGENTS.md itself. The log is the incubator, the guidelines are where durable rules end up.
Why I will not automate this
I could have the agent auto-generate these entries. I tried the mental version of it and dropped the idea. The value is not in recording what happened, it is in deciding what was worth recording, and that judgment is mine. A five minute write-up that captures the why beats an auto-generated transcript of the what.
If you are working with AI agents on a codebase that needs to survive longer than one session, start the folder. Name the files after dates, keep the template boring, record your failures louder than your wins. Your future sessions will thank you, usually within the first five minutes.