Every AI coding session starts the same way.
The agent knows nothing about your project. Not the decision you made last
Tuesday. Not the migration that burned you. Not the naming convention you
finally settled on.
So you re-explain. Every session. Or worse, you don't, and the agent makes
a mistake you already paid for once.
The fix is boring
It's not a smarter model. It's not a bigger context window. It's writing
things down, in the repo, where the work happens.
I keep three kinds of files in every serious project now:
- A short operating manual the agent always loads. Rules only. If it grows past a page, something moves out.
- Decision records. One small file per locked decision, with the why. The why is the part you forget first.
- A gotchas file. Every time something non-obvious bites me, it gets a line right then. If I save it for later, it never happens.
That's it. Plain markdown. No tooling, no framework, nothing to install.
What changed for me
Honestly, the difference is bigger than any model upgrade I've tried.
A fresh session reads the manual and starts acting like it was here last week.
It follows conventions I never mentioned in the prompt. It skips the mistakes I already
made once, because they're written down.
And the strange part: the notes made me better too. Writing "we decided X
because Y" forces you to actually have a Y.
A starter file
Drop this in your repo as AGENTS.md and edit it honestly:
# Operating manual
## What this project is
One sentence. What it does, who it's for.
## Rules that are always true
- Commands: how to run dev, tests, build.
- The one or two conventions people keep getting wrong.
## Decisions (the why matters)
- 2026-07-12: We use X instead of Y because Z.
## Gotchas
- The thing that bit us, and what to do instead.
Start smaller than feels right. A pile of docs nobody maintains is worse than
one page that's true.
What are you writing down?
I'm still figuring out where the line is between useful memory and busywork.
If you're doing something like this in your own projects, I'd honestly love
to hear what you keep and what you throw away.
Top comments (0)