A field note from a dev who inherited Alice's codebase and lived to tell the tale.
Aight dev, let's stop the pretentious dance here.
No matter what color your taekwondo belt is — junior, senior, staff, principal, "10x ninja rockstar" on your LinkedIn — at some point you will get absolutely smacked by a legacy codebase you inherited from Alice. Alice who left 8 months ago. Alice who had her own "system". Alice who swore the docs were "basically up to date".
You, me, and whatever AI agent we're hyping this sprint are equally clueless. Like an ape standing in front of that gas stove.
The Social Contract Nobody Keeps
We've all sat in that standup. You know the one.
Bob promises to keep the Postman collection updated. He does it twice, then a refactor happens and the collection quietly becomes historical fiction.
Karen promises to keep the feature docs evergreen. Noble. Genuinely noble. But docs written after the fact have no soul — they're always 2 sprints stale, always missing the weird edge case, always slightly wrong in the way that matters most at 2am during an incident.
Nobody's lying. Nobody's lazy (well, maybe Bob). It's just that documentation is always an afterthought and afterthoughts die.
So we got fed up. If we want it done right, we do it ourselves. And now — we do it with the agent.
The Epiphany: Your AI Isn't a Oracle, It's a New Hire
Here's where most devs get the AI workflow completely backwards.
They treat the LLM like a vending machine — put prompt in, get code out, ship. When it breaks something they yell "AI is useless" and go back to Googling Stack Overflow.
But think about how you'd actually onboard a new developer to a gnarly codebase:
You wouldn't hand them the repo URL and say "fix ticket #247, LFG."
You'd say:
- here's the architecture and why we did it this way
- here's the table that looks simple but is actually varchar instead of enum because of a decision made in 2019 that nobody wants to touch
- here's where the bodies are buried
- now tell me back what you understood
That last part is the one everyone skips. With humans and with AI.
The Pattern: READ_BEFORE_CODE.md
Here's the actual workflow. No buzzwords, no prompt engineering certification required.
Step 1: Drop a READ_BEFORE_CODE.md in your repo root.
Step 2: When starting any task, give the AI:
- Absolute paths of the relevant files (no ambiguity, no hallucinated locations)
- The goal or issue in plain language
- A standing instruction to dump its comprehension into the markdown before writing a single line of code
Step 3: Read what it wrote. Course correct. THEN say LFG.
That's it. That's the whole thing.
What you're asking the AI to produce isn't code — it's an externalized mental model:
Files: [/absolute/path/to/service.ts, /absolute/path/to/types/core.d.ts]
Goal: Fix the building category filter returning wrong results
Before writing any code, update READ_BEFORE_CODE.md with:
1. Your understanding of each file's role
2. How they relate to this bug
3. What you think needs to change and why
4. Any assumptions or blind spots you have
Do NOT write any code yet.
The markdown review is your vibe check. You're not just fact-checking the AI — you're calibrating shared context before any real work happens.
It surfaces two things:
- What it actually understands — "oh it gets our auth pattern, we're good"
- What it confidently got wrong — which is the dangerous one. Same as the new hire who never asks questions but has completely wrong assumptions baked in from day one
The Secret Sauce: Make It a Living Diary
Here's where it gets interesting.
Don't let the markdown be a one-shot thing. Add this standing rule:
"After everything you do, update this file. This is your diary so that you can have long-term memory which survives across sessions, model updates, etc. Update: your current understanding of the project, quirks and gotchas you found, things that looked simple but were actually complex, anything important the user might not have known or mentioned."
And here's the part I'm most proud of — add this:
"Don't assume I, the user, am omniscient about this project. I also inherited this codebase and I'm still learning. If you find something important, tell me by updating this file. Let's be honest — we're in the same boat."
Now you've done something wild. You've turned a stateless token completion engine into a collaborative pair programmer with persistent institutional memory.
Every session, it reads the diary. Every session, it adds to it. Quirks, gotchas, "this table is varchar not enum and that's weird but it is what it is", recent changes, things that looked one way but turned out another.
The AI's amnesia problem? Solved with a markdown file and a git commit.
Why This Works (The Slightly Nerdy Part)
LLMs aren't copy-paste machines. They're not retrieving your code — they're reconstructing the most statistically coherent response given everything in their context window.
The failure mode of agentic coding isn't the AI being dumb. It's misaligned assumptions that snowball. It assumes auth lives in one module, starts editing, 15 tool calls later everything's on fire and you can't trace where it went wrong.
The READ_BEFORE_CODE.md pattern kills the assumption problem at the root. The diary review step is you manually steering the probability distribution before it goes wide with code generation. You're reducing variance before the high-stakes step.
Also — current context windows are sitting at 1M tokens at the floor, with some models hitting 10M+. That's your entire feature branch. That's cross-file relationship tracking. That's "this bug in UserService.ts is caused by a type mismatch defined 40 files away in types/core.d.ts" — found in a single pass.
Humans read code serially. We build mental models that degrade as we go. We forget what we saw at the top of the file by the time we hit the bottom. The model holds it all simultaneously.
Use that.
The Gut Punch Ending
Here's the thing though.
None of this works if you don't commit the file.
READ_BEFORE_CODE.md is only as immortal as your git history. It survives model updates, session resets, team turnover — but only if you push it. It's Alice-proof. It's Bob-proof. It's the doc that actually stays current because the AI itself is incentivized to keep it current as part of doing its job.
Whether your senior thinks it's genius or calls it clutter in code review — that's a conversation about engineering culture. Have it.
But for the devs who inherited the gas stove, don't fully understand the gas stove, and are trying to not blow anything up?
The diary is the move. 💪
Top comments (1)
The READ_BEFORE_CODE.md pattern is brilliant — essentially giving the AI externalized long-term memory through git. That last bit about the AI being "incentivized to keep it current" is the key insight most people miss.
This maps to something I've been thinking about: the output side of AI workflows is just as broken as the input side. You do the research in Gemini, the AI synthesizes something brilliant, and then... you copy-paste it into chaos.
The diary pattern solves context persistence for coding. But for research/architecture outputs — the stuff you generate in Gemini before you even get to the code — most people are still screenshotting long chats and losing the structure entirely.
Great piece. The "treat it like a new hire, not a vending machine" framing is something I'm going to steal for every AI onboarding conversation I have.