Right before I went to sleep on Wednesday night, I asked a question that ended up mattering more than anything we built that evening: "Are you tracking the steps of this project somehow? I want to make sure you know where to start if we continue in a new session."
I ask because of how I build things these days. I pair with an AI agent on my side projects, and the agent's memory resets between sessions. Every new conversation starts from zero. If the state of the project lives only in chat history, then chat history is my project management tool — and chat history is a terrible database.
That night we had just scaffolded a new private side project. Let me tell you what got built, and then why the most valuable file in the repo contains zero lines of code.
The midnight scaffold
The project is a private side project I've been shaping for a couple of weeks. The technical decisions were locked: one codebase strategy for web and mobile, local-first with sync later. The one open question was React Native or Flutter.
I went with Expo (SDK 57) React Native plus Next.js 16 in a TypeScript monorepo, and the reasoning was boring in the best way:
- Web is a first-class citizen for this project, not an afterthought. Flutter web exists, but Next.js is where I already live.
- I write TypeScript and React every day. Context-switching to Dart for one app is a tax I'd pay forever.
- The app is mostly lists, sync, notifications, and forms — not a custom-rendered animation showcase where Flutter's pixel control earns its keep.
By about 1 AM the monorepo stood up:
project/
apps/mobile/ Expo SDK 57 app
apps/web/ Next.js 16 app
packages/core/ domain logic — 24 passing tests
packages/ui-tokens/ shared design tokens
packages/api-client/ store interfaces, no backend yet
Both apps import the shared domain package, typecheck is clean across the workspaces, and the test suite is green. Portability is baked in from the start: the domain code knows nothing about any hosting platform, the web app has a Dockerfile exit path, and the data layer sits behind an interface so the backend can be swapped later. Nothing glamorous. Just decisions that won't need to be un-made.
The amnesia problem
Here's the thing about building with an agent: the code is cumulative, but the context is not.
A human teammate who worked on a repo last week walks in on Monday with a head full of state — what's done, what's half-done, which decision was tentative, what annoyed them. An agent walks in with nothing. Every session is a cold boot. Whatever it "knows" about the project has to be reconstructed from what it can read.
I've hit the failure mode on earlier projects, and it's subtle: the agent doesn't refuse to help, it guesses confidently. It re-decides decisions that were already made. It re-explores dead ends. It writes code that contradicts an architectural choice from three sessions ago because nothing told it that choice existed. You end up spending the first twenty minutes of every session re-briefing your own project — and you become the bottleneck in your own side project.
STATUS.md: the file with no code
So before sleeping, I got my answer in the form of a file. The repo now has a STATUS.md at the root, and it's the most important thing in there.
The contents are deliberately unsexy:
- What's done — a short progress table, in plain language
- The build-order checklist — what gets built in what sequence, and why
- The exact next step — not "continue mobile work" but the next small user-visible loop, written plainly enough that a cold session can start without a briefing
- Sanity-check commands —
git pull,npm test, the dev commands, so the first action of any session is verifiable - The rule — update this file at the end of every working session. Non-negotiable.
That last bullet is what makes the whole thing work. A status file that goes stale is worse than no status file, because it lies confidently. The rule makes freshness part of the definition of done.
And because one signpost can rot quietly, there are three. The planning folder's index names the current stage. My projects overview file points at the repo. The repo root has STATUS.md. Any entrance leads to the same place.
Why not something fancier?
I considered the grown-up options. A real project management tool. An issues board. Some kind of structured memory layer for the agent. All of them lose to a markdown file at the repo root, for the same reason README files won twenty years ago:
- It travels with the code. Clone the repo and the state comes with it. No external service, no login, no export step.
- It's versioned.
git log STATUS.mdis a project history. The diff of the status file tells the story of the work. - It's the first thing anything reads. Humans open repos at the root. Agents get pointed at the root. The file sits exactly where the cold boot starts.
- It works for me too. I'm the other amnesiac in this collaboration. Two weeks from now, well-rested daytime-me will be nearly as lost as the agent is.
The insight I keep circling: building with an AI agent doesn't remove the need for engineering hygiene — it raises the stakes on it. Tests, interfaces, and written-down decisions used to be things you did for teammates and future-you. Now they're the interface between sessions. The repo has to carry the context, because the collaborator can't.
The takeaway
The scaffold took one evening. The discipline that makes it continue-able took ten minutes: one file, three signposts, one rule.
If you're building anything with an agent — or honestly, with your own intermittently available future self — the question worth asking before you close the laptop isn't "does it run?" It's this: could a stranger with amnesia pick this up tomorrow and take the right next step?
If the answer is yes, you wrote it down. If the answer is no, your project state is stored in the worst database of all: your memory of a chat window.
