Journal · The AI Architect · 2026-07-26
Give your project a memory: write the rule you learned the hard way into a notes file so you never relearn it.
Give your project a memory: write the rule you learned the hard way into a notes file so you never relearn it.
There’s a particular kind of tired that comes from fixing the same bug twice. Not a similar bug — the same one, in the same file, for the same reason, six weeks apart. You sit there with the fix half-typed and a creeping sense of déjà vu, and then it arrives: you’ve been here before. You even remember the conversation you had with yourself last time about how you should write this down. You didn’t. The tension isn’t that mistakes happen. It’s that your project, unlike you, has no way to hold on to what you learned unless you build one.
Most of us treat memory as something that happens automatically, in our heads, because that’s where thinking feels like it lives. But projects outlast the moods and context that produced our insights. Six weeks from now you won’t remember why you avoided that library, only that something felt off about it. The knowledge decays into a vague unease, which is useless to your future self and completely invisible to anyone else on the project.
The rule is smaller than the story
When people try to write these things down, they usually write too much. They want to capture the whole saga — the three hours of debugging, the false leads, the moment of realization. That’s a nice story, but it’s not a rule, and stories don’t get read twice. What you actually need is the compressed version: the one sentence that would have saved you the three hours if you’d read it at the start.
Try this: the next time you solve a problem that made you say “oh, of course” out loud, stop and write one line in a file called notes.md or lessons.md at the root of your project. Not the explanation. The rule. “Don’t run migrations before the cache is cleared.” “The API returns nulls for deleted users, check for that.” “This library silently truncates strings over 255 characters.” One line. If you feel the urge to write a paragraph, that’s a sign you haven’t fully understood the lesson yet — the real rule is still hiding somewhere in your explanation.
Make it a habit, not a project
The temptation, once you see the value of this, is to go build an elaborate knowledge base — categories, tags, a search function, maybe a whole wiki. Resist that for now. An elaborate system is a project of its own, and projects you have to maintain are projects you eventually abandon. A single flat file that you actually open is worth more than an ambitious system that intimidates you into never touching it.
The habit that works is boring: after you fix something non-obvious, before you move on to the next task, add the line. It takes fifteen seconds. The discipline isn’t in the writing, which is trivial — it’s in remembering to pause at the exact moment you’re most eager to move forward. That pause is the whole practice. You’re trading a few seconds of friction now for hours of friction you’ll never have to feel later.
And read the file before you start work each day, or at least each week. This part gets skipped constantly, and it’s the part that makes the whole thing worth doing. A notes file nobody rereads is just a diary. A notes file you check before touching the code is a second brain that never forgets and never gets tired.
Let it grow honest, not tidy
Don’t worry about the file getting messy or repetitive. If you write the same rule twice because you forgot you’d already learned it, that’s not failure — that’s the file doing its job, showing you exactly where your memory keeps failing you. Those repeated entries are data. They tell you which parts of the system are genuinely counterintuitive and deserve more than a note — maybe a comment in the code itself, or a change to the design so the mistake becomes impossible rather than just documented.
Over time the file becomes less about individual bugs and more about the shape of your own blind spots. You’ll notice patterns: you keep forgetting to handle time zones, you keep trusting an API that lies about its own state. That’s the real payoff. Not a list of trivia, but a mirror.
I think about this as one small habit in a much larger practice of building projects that remember things so people don’t have to. It’s not glamorous, and it won’t feel important the day you start it. But there’s more on how this fits with the rest of how a project holds knowledge over time in the book, if you want to go further with it than a single file.
Go deeper. The full method is in The AI Architect. New here? Start with the free companion pack, or explore the series.