Second post of Season 1. Monday I told you about the moment a decision only ever lived inside a prompt, gone the second I closed the chat window. This one's the fix, and it doesn't ask you to become a technical writer.
The Idea Is Smaller Than It Sounds
Before I ask an agent to build something now, I write down what I’m actually asking for, in plain language, in a file that sits in the project next to the code. Not a spec. Not a doc nobody reads. Just a place the decision lives, so it’s still there next week, and so the agent can be pointed back to it instead of guessing again.
I didn’t come up with this because it sounded like good practice. I came up with it because I got tired of asking an agent why it built something a certain way and getting an answer that was really just “because you never told me otherwise,” which is a fair answer, and also not one I wanted to keep hearing. The file isn’t about being thorough. It’s about having somewhere to put a decision the moment I make it, instead of trusting myself to remember it existed three prompts later.
The File Itself
I copy this into a file called BUILD-NOTES.md at the top of the project:
markdown
# Build Notes: [name of the feature or app]
## What we're building
One or two sentences. Plain language, no code.
## Why
What problem this solves, or what breaks without it.
## What's included
The parts that need to exist when this is actually done.
-
-
-
## What's NOT included
Things you're deliberately leaving out for now, so the agent doesn't add them on its own.
-
-
## Edge cases we've already decided
If X happens, do Y. This is the part that usually only lives in someone's head.
- If
- If
## How we'll know it's done
Things you can actually check, not "it feels right."
- [ ]
- [ ]
- [ ]
## Still undecided
Anything you haven't figured out yet. The agent should ask about these, not guess.
-
---
*Last updated: [date]*I don’t fill in every line perfectly, not even close some weeks. Half-answered is still miles ahead of not written down at all. I’ve shipped plenty of these with two sections left mostly blank, and it still beat having nothing.
The Line That Makes It Stick
Once the file exists, here’s what I hand the agent, every time I’m about to build or change something:
Before you write any code, ask me anything below that I haven’t already answered. Once I answer, write my answers into a file called
BUILD-NOTES.mdusing this structure: [paste the template above]. Use that file as the source of truth for what we’re building. If I ask for a change later, updateBUILD-NOTES.mdfirst, then write the code. Don’t just make the change and leave the notes stale.
That last sentence matters more than it looks like it should. It’s the difference between a file that’s accurate on day one and useless by day ten, and one that actually stays trustworthy as the project moves. I skipped it the first few times I wrote this prompt, figured the agent would naturally keep the file current on its own, and watched the notes drift out of sync with the actual code within about a week. Once they’re wrong, they’re worse than nothing, because now I’m trusting a document that’s lying to me without knowing it.
What This Actually Buys Me
Two things, and I notice both of them almost every week now. First, the next time I ask myself why something got built a certain way, the answer is sitting in a file instead of buried in a conversation that’s already gone. Second, when I come back in two weeks to add something small, the agent reads the notes before it reinterprets the whole feature from scratch, which is exactly the mess I used to walk back into.
The section that pays for itself fastest is “edge cases we’ve already decided.” The first time I filled it out, for a file upload feature, I wrote “if the file already exists, ask before overwriting” almost as an afterthought, one line I typed without thinking too hard about it. That line has saved me from clobbering something twice since, both times on days I was moving fast enough that I wouldn’t have caught it in review. I didn’t get smarter between the first version and the second. I just had somewhere to put the thought the first time it crossed my mind, instead of losing it the second I moved on to the next request.
Try it on whatever you’re building right now. Paste the template in, run the prompt, and see what the agent asks you that you hadn’t actually decided yet. That question is usually the useful part, it’s the one you’d have skipped past on your own.
One more thing. If keeping a file like this updated by hand feels like one more chore on top of everything else, reply and tell me. I’m trying to get a real read on how many people would rather have something do this automatically versus doing it themselves. Either answer is useful to me.