TL;DR: Your AI coding assistant keeps forgetting what you're working on? This
TODO.mdstructure fixes it. Takes minutes to set up, saves hours of re-explaining context. Jump to the quick-start or see the template.
The Problem: Groundhog Day Development
Picture this. You're building a game, planning an app, vibe-coding something cool with AI assistance. End of day, you close your laptop feeling productive. Next morning, you type your next prompt and see the dreaded "Summarising conversation" spinner ... and the groove you had last night just evaporates.
So you open a new chat. Pluck a duck, where was I? Where were we?
You: "Read the project files and continue where we left off."
AI: [Scans your 50-item TODO list] "I see you're building the diving system! I also notice you have 'giant squid encounters' in your backlog. While we're in the diving code, we could add creature attack hooks that would later support—"
You: "No. Just the diving system."
AI: "Got it! I also see 'sound design' is listed. Should we add placeholder audio triggers while—"
You: [internal screaming]
Every. Single. Session.
It's Groundhog Day again. Same routine every time, burning the same precious minutes each development session:
- Re-explaining what we were building
- Redirecting away from backlog items
- Establishing (again) what was in scope
- Gently but firmly saying "not that, THIS"
But the AI wasn't broken. My documentation was.
The Fastest Way to Try This
Want to skip the explanation and just experience it?
- Download this article (use your browser's save/print to PDF)
- Open your repo
- Start a new chat with your AI assistant
- Probably select a thinking model
- Drop in this prompt:
read this article and design a TODO.md structure with supporting markdown documentation for my project that implements the Session Protocol
The AI will read this entire post, understand the pattern, and generate a customised TODO.md for your actual project. You can iterate from there.
Seriously. Try it right now. I'll wait.
(Or keep reading if you want to understand why this works before you implement it.)
The Root Cause: TODOs Designed for Humans
My TODO.md was born out of necessity to help me record all the ideas swirling around my head.
It looked like every other TODO list:
# TODO
## Current Tasks
- [ ] Build diving system
- [ ] Add captain's log UI
- [ ] Implement oxygen consumption
## Future Ideas
- Multiple ocean depths
- Port trading mechanics
- Crew morale system
- Giant squid encounters
- Sound design
[...30+ more items]
To a human, this is fine. Your brain has context. You know what you're working on. The backlog is just a parking lot for ideas that you are unconsciously sorting.
But to an AI assistant? This is a buffet of equally-valid options. Everything looks like a suggestion waiting to happen. There's no signal saying "focus HERE, ignore THAT." The AI reads it literally and treats your 3 current tasks and 30 future ideas with equal weight.
The result? Constant distraction, repeated context restoration, and burning time.
And here's the thing. If you don't give the AI a TODO structure, it'll invent one and stubbornly latch onto it like a dog with a bone.
The AI's version will be aiming for what it thinks you might want, not what you're actually building.
At least with a bad TODO you control the chaos. Without one, the AI's making up priorities on the fly every session.
The Session Protocol isn't about adding structure where none existed. It's about taking control of the structure the AI's going to use anyway.
The Solution: A Session Protocol
Over time I restructured my TODO.md into what my AI assistant dubbed the Session Protocol — a document designed specifically to help AI assistants focus.
The key insight here is that the document isn't for task tracking. It's for programming your AI collaborator's attention.
Here's what changed:
1. Quick Context (The 30-Second Bootstrap)
## Quick Context (For New Chats)
**Read these docs to understand the project:**
- [DESIGN_PHILOSOPHY](./docs/DESIGN_PHILOSOPHY.md) — Core principles
- [AESTHETIC.md](./docs/AESTHETIC.md) — The vibe we're aiming for
**One-line pitch:** "Command your own Nautilus" — a Victorian submarine simulation where you manage pressure, oxygen, and crew through uncharted depths.
**Tech:** Godot 4.x (GDScript). Prototype phase.
Why it works: When I start a new chat with "Read TODO.md and the linked docs", the AI hits this section first and knows:
- What the project is
- Where to look for depth
- What tech we're using
- Where we are in the lifecycle
No preamble. No back-and-forth. Just instant orientation.
2. Completion Log (The Breadcrumbs)
## Completion Log
- **Nov 30** — First playable loop (navigation, save/load)
- **Dec 1** — Captain's Log UI (message list, pagination)
- **Dec 2** — Pressure system (physics, hull stress, depth gating)
Why it works: The dates (I think!) give the AI temporal context. When it sees "we're three weeks in and have shipped X, Y, Z," it understands project maturity.
Without this, AI sometimes suggests "should we set up the save system?" when you built that three milestones ago. With it, suggestions align with where you actually are.
3. Current Milestone (The Focus Laser)
## Current Milestone: Electric Engine
**Goal:** Propulsion system controlled by navigation computer.
### What We're Building
- Engine power curves
- Battery consumption mechanics
- NemoOS status messages
### Success Criteria
- [ ] Engine responds to throttle commands
- [ ] Battery drains during operation
- [ ] NemoOS logs engine state changes
### Deferred (Not This Slice)
- Emergency surface procedures (future complexity)
- Engine damage mechanics (not yet)
- Backup propulsion systems (out of scope)
Why it works: The Deferred section is the magic. By explicitly listing what we're NOT doing, we create visible boundaries. The AI can't suggest what it sees we've deliberately parked.
Before this section: Constant nagging about tackling backlog suggestions per session.
After this section: Zero backlog suggestions unless I ask for it.
The AI learns: "This isn't forgotten, it's just not now."
4. Backlog (De-emphasised, At The Bottom)
## Backlog (Not Prioritised)
- Crew morale system
- Giant squid encounters
- Multiple depth zones
- Port trading mechanics
[...brief list]
Why it works: Ideas need a home, but not prominence. By putting the backlog:
- At the bottom (encountered last)
- Under a "Not Prioritised" header
- Kept brief (truncate if >20 items)
The AI reads the current work first, absorbs the boundaries, and by the time it hits the backlog, knows those items are background noise.
5. Handover Prompt (Copy-Paste Continuity)
## How to Continue in a New Chat
**Prompt to use:**
> Read TODO.md and the linked docs. Current milestone: Electric Engine.
> We just finished the pressure system. Pick up from engine physics.
Why it works: Zero friction. I literally copy-paste this into a new chat. The AI gets exactly the context it needs: what to read, where we are, what just finished, where to continue.
No thinking. No reconstruction. Just ... paste and go. It's delightfully satisfying!
The Before and After
Before (many early sessions)
[10:15] Me: Read project and continue where we left off
[10:16] AI: [Reads TODO] I see diving system. Also notice port
trading. Should we add cargo hooks while—
[10:17] Me: No, just diving
[10:17] AI: Got it! About sound design in backlog—
[10:18] Me: Just. Diving. Please.
[10:20] AI: Right! For diving, should we start with physics or UI?
[10:21] Me: Physics. We discussed this yesterday.
[10:22] AI: Let me start on the pressure model...
[10:25] [Actual work finally begins]
Session startup: valuable minutes of re-explaining
After (every session now)
[10:15] Me: Read TODO.md and linked docs.
[10:16] AI: Got it. Diving system — pressure physics ✓, UI (not yet),
depth gating (not yet). Emergency ascent explicitly deferred.
Continue with UI?
[10:16] Me: Yes
[10:16] [Productive work begins immediately]
Session startup: seconds ... straight to coding
The difference isn't subtle. It's the difference between frustration and flow.
The Copy-Paste Template
Here's the structure you can steal:
# [Project Name]: Development TODO
## Quick Context (For New Chats)
**Read these docs:**
- [Doc 1](link) — What it covers
- [Doc 2](link) — What it covers
**One-line pitch:** [What is this project?]
**Tech:** [Stack/framework]
**Status:** [Prototype/MVP/Production]
---
## Completion Log
- **[Date]** — [Milestone name] ([brief description])
- **[Date]** — [Milestone name] ([brief description])
---
## Current Milestone: [Milestone Name]
**Goal:** [One sentence describing success]
### What We're Building
- Specific feature 1
- Specific feature 2
- Specific feature 3
### Success Criteria
- [ ] Measurable outcome 1
- [ ] Measurable outcome 2
- [ ] Measurable outcome 3
### Deferred (Not This Slice)
- Thing we're explicitly NOT doing right now
- Another feature we've parked
- Explicit boundary / scope protection
---
## Backlog (Not Prioritised)
- Future idea 1
- Future idea 2
- Future idea 3
---
## How to Continue in a New Chat
**Prompt to use:**
> Read TODO.md and linked docs. Current milestone: [name].
> Context: [one line about what just finished]. Continue from [specific point].
What Makes This Different
Traditional TODO: Designed for human brains with implicit context and persistent memory.
Session Protocol: Designed for AI assistants that read literally and start fresh every session.
The key differences:
- Explicit boundaries (Deferred section) vs. implicit priorities
- Temporal orientation (dates + completion log) vs. flat task lists
- Embedded handover prompts vs. hoping the AI figures it out
- Attention shaping through structure vs. assuming the AI knows what matters
Your AI assistant can't remember between sessions (well, unless you're using Projects, but even then...). Your documents can remember for it.
Make them count.
What This Isn't (Scope Check)
Before the comments fill with "but how does this scale to my 50-person org?" — let me save you the typing.
This is a personal workflow pattern. It's optimised for you working with your AI assistant.
It works for:
- Solo devs building passion projects
- Engineers working individual tickets within a squad
- At a stretch, pair programming handoffs if both people use the same structure
It does not replace:
- Jira, Linear, Trello, or any team coordination tool
- Sprint planning, backlog grooming, or standups
- Your tech lead's opinion on story points
Asking "how does this scale to a team?" is like asking how your personal notebook scales to 50 people. It doesn't. That's not a bug—it's the point.
This is about your focus. Your flow. Your AI assistant's attention.
The scaling question assumes this is a planning tool. It’s not. Use a tool designed for that. This is an alignment tool for a single human-to-AI feedback loop. It’s what you use when you sit down, open a chat, and want to immediately get back into flow instead of re-explaining your life story to a goldfish with a very expensive education.
Pro Tips
Update at session end, not session start. When you're wrapping up for the day, spend 2 minutes updating the TODO. You have context. Future you will thank you.
Make the AI do the work. End sessions with: "Update TODO.md with what we just accomplished and write the handover prompt for next time." Offload the admin to the tireless assistant.
Keep the completion log short. Once it hits ~10 items, archive older ones to a CHANGELOG.md. The log is for orientation, not history.
Test the deferred section. If you're still getting backlog suggestions, your Deferred section isn't explicit enough. Name specific features and why they're parked.
Move the backlog if it grows. Once you hit ~20 items, consider a separate BACKLOG.md. What the AI doesn't see, it can't get distracted by.
When This Breaks (And How to Fix It)
The temporal orientation might be placebo. I think dates help the AI calibrate to project maturity, but I haven't proven it. Test it yourself: try removing dates for a week and see if behaviour changes. If it does, keep 'em. If not, they're just clutter.
Long contexts might truncate the bottom. I put behavioural notes at the end, but some models might deprioritise them. If your AI starts ignoring constraints, move the critical ones to the Quick Context section at the top.
Human discipline is required. This only works if you actually update the TODO before closing your laptop. If you code for 4 hours and forget to update... next session starts with stale context. Solution: make it a habit, or make the AI do it.
The Bigger Pattern
The Session Protocol works because documents shape AI behaviour.
A sprawling TODO makes an AI scattered.
A focused TODO makes an AI focused.
Traditional documentation assumes smart readers who can infer intent. AI assistants are powerful but literal—they need explicit instruction.
This isn't just about TODO files. The same principle applies to:
- Architecture Decision Records (add "Alternatives we rejected and why")
- API docs (add "Usage patterns we don't support")
- Design docs (add "What we're NOT building in V1")
When collaborating with literal-minded machines, make your boundaries as visible as your goals.
Go Try It
This structure emerged from frustration, got refined through iteration, and now saves me a lot of time. It might work for you. It might not. But it costs 5 minutes to try.
Fastest path: Drop this article into your AI assistant and ask it to generate a Session Protocol TODO.md for your project. Iterate from there.
DIY path: Copy the template. Fill in your project details. Use the handover prompt in your next session. See if it helps.
If it works, brilliant. If it doesn't, tweak it. The structure isn't sacred — the principle is: teach your AI assistant what to focus on by showing it explicitly in your documentation.
Now go build something cool.
This pattern emerged vibe-coding a simulation game, POC originally in React (which I know well), then pivoting to Godot 4.x (which is completely new to me). The structure was proposed and refined by Claude Opus 4.5 during meta-discussions about project documentation.
Comments? Questions? Improvements?
What documentation patterns are you using with AI assistants? Found something that works better? Hit the comments — I'm curious what's working for other devs.
Top comments (0)