The Saddest Thing in Coding Right Now
You've done this. I've done this. Most people I work with have done this.
You sit down with Claude or Cursor or whatever your agent of choice is. You hit a tricky bug, or you're designing something non-obvious, or you're refactoring a system that has 14 reasons it works the way it does. You and the agent go back and forth. You explore three dead ends. You finally figure out why the migration was failing. You ship the fix.
You close the tab.
The next week, you (or worse, a teammate) hit the same problem. The agent has no memory of the previous session. You have a fuzzy recollection. The code looks the same as it always did. You start the whole investigation over.
You just lit 80,000 tokens on fire and got nothing back except the fix itself. The understanding that produced the fix is gone.
Tokens Are Cheap. Understanding Is Not.
It's an old idea in new clothes: if you're going to do the work, leave something to show for it. With an agent, a long session produces two artifacts, not one. There's the code change, which everyone sees. And there's the understanding that led to it, which usually evaporates the moment your context window resets.
The code is what you shipped. The understanding is why it works, what almost worked instead, what you tried and rejected, and what assumptions are baked into the design. That second artifact is more valuable than the first, and almost nobody saves it.
If you're going to spend the tokens anyway, you might as well use that context to make the codebase deeper. Not just functional. Deeper. The next person who reads it (including future-you, including the next agent session) should be able to absorb what you learned without having to learn it again from scratch.
A Simple Question Before You Close the Tab
Before you close the tab on a long agent session, it's worth asking one question:
"If I came back to this code in three months with no memory of this conversation, would I understand why it looks the way it does?"
Often the answer is no. The fix is cheap: spend the last few minutes encoding the understanding before it's gone.
What to Actually Leave Behind
📝 Takes 10-15 minutes per session. Less than the time you'd spend re-discovering it later.
Pick what fits. Not every session needs all of these. But every long session needs at least one.
1. The "Why Not" Comment
Code shows what you did. Code does not show what you almost did and rejected. That's where most of the misunderstanding comes from later.
// We process payments before sending the receipt email, even though
// async-first would feel more natural here. The processor sometimes
// returns a partial success that we need to confirm before telling
// the user "you're paid." Tried the parallel version — it created
// a race where users got receipts for failed charges. See PR #482.
processPayment(order)
sendReceipt(order)The comment isn't about what the code does. It's about what the code doesn't do, and why. That's the part the agent helped you figure out. Save it.
2. The Architecture Decision Record (ADR)
If your session produced a real design decision (chose Postgres over DynamoDB, picked event sourcing over CRUD, decided to denormalize a table), write a short ADR. It can be a markdown file in /docs/decisions/ or just a section in your README. The format doesn't matter. The capture matters.
# ADR-007: We Use Optimistic Locking on Inventory
## Context
Multiple warehouse workers can update the same SKU at the same time.
## Decision
Optimistic locking with a version column. Pessimistic locking
caused workers to block each other during the morning rush.
## Consequences
Conflicts are rare but possible. Worker UI shows a "refresh and
retry" message. We logged 4 conflicts in the first month.You and the agent already worked through the alternatives. Just write down what you picked and why, in five sentences. Future-you will thank present-you.
3. The Test That Encodes the Constraint
This is my favorite. If your agent session uncovered a non-obvious constraint, write a test that fails when someone violates it. The test name itself becomes documentation.
def test_user_emails_are_lowercased_before_storage():
# We discovered the hard way that case-sensitive emails
# caused duplicate accounts when users typed differently
# on mobile vs desktop. See incident-2026-03-14.
user = create_user(email="Justin@Example.com")
assert user.email == "justin@example.com"The test guards the behavior. The comment explains the why. The next person to refactor this code can't accidentally break it without the test screaming.
4. The Commit Message That Explains the Investigation
One-line commit messages are fine for trivial changes. They are malpractice for changes that took 80K tokens to figure out. Use the body of the commit message to capture what you learned.
fix: race condition in inventory update during concurrent orders
We were seeing intermittent oversells when two orders for the
last unit of a SKU arrived within ~50ms of each other. The
optimistic locking was correct but the version check was
happening AFTER the inventory decrement instead of as part of
the same transaction.
Fixed by wrapping the decrement and version check in a single
UPDATE with a WHERE clause on the version. Tested by hammering
the endpoint with 100 concurrent requests in the staging env.
The agent session that figured this out is in my notes if anyone
needs the full trace.This commit message will outlive the codebase. git blame is the most-read documentation in any project. Make it carry weight.
5. The README Section You Keep Putting Off
If your session involved explaining how a system works to the agent before you could even start fixing it, that explanation is gold. Paste it into the README. Clean it up a little. Done.
You wrote a 200-word system overview to give the agent context. That overview is exactly what a new contributor needs. Stop writing it twice.
6. The "Gotchas" File
Every codebase has them. The third-party API that returns 200 with an error in the body. The cron job that has to run before the other cron job. The environment variable that has to be set in two places. Every agent session that hits one of these is a chance to write it down.
# GOTCHAS.md
## Stripe webhooks
- Always verify the signature BEFORE parsing the body.
Parsing first changes the raw bytes and breaks verification.
- The `payment_intent.succeeded` event can fire twice. Idempotency
key on our end is the payment_intent ID.
## The `legacy_users` table
- DO NOT add columns. The migration locks for ~40 minutes
on prod-size data. Use the `user_metadata` JSONB column instead.This file pays for itself the first time it saves someone an outage.
Especially If You're Vibe Coding
If you're a vibe coder — and I mean that with love, I vibe code half my side projects — this matters more for you, not less.
The reason is simple: vibe coders often don't carry the full mental model of their own codebase. The agent does the heavy lifting. That's fine when the agent is in the conversation with you. It's a disaster the moment the conversation ends and you (or a new agent session) try to extend the code without that context.
The artifacts above are how you keep the codebase legible to your next session. Without them, every session starts from zero. With them, every session builds on the last one. That's the difference between a vibe-coded project that grows for six months and one that collapses under its own weight in three weeks.
If you're not going to hold the context in your head, hold it in the repo.
The Bigger Picture: Codebases as Memory
Agents are the best collaborator most of us have ever had for the actual act of writing code. They're terrible at one thing: remembering. Every session is a fresh brain. Every context window has an end.
The codebase itself is the only persistent memory you and your agents share. Comments, tests, ADRs, README sections, gotchas files, commit messages — these aren't busywork. They're the substrate that lets every future session pick up where the last one left off.
Treat your repo like a notebook you're sharing with a brilliant collaborator who has amnesia. Because that's exactly what it is.
Do This Before Your Next Commit ⚡
Three things. Takes 5 minutes.
- Look at the last meaningful change you made with an agent. Find one decision in that change that wouldn't be obvious to a stranger. Add a comment explaining the "why not."
- If you wrote a paragraph of context for the agent at the start of the session, paste it into the README or a relevant doc. You already wrote it. Just save it.
- For your next session, end it by asking the agent: "What did we figure out today that isn't captured anywhere in the code? Suggest where to put it." Then actually put it there.
Tokens spent producing fixes are tokens spent. Tokens spent producing fixes and understanding that lasts are tokens invested. Same burn, very different ROI.
Publish over perfect. A scrappy comment is worth more than a beautiful doc you never write.
Header image by Cooper Hofmann on Unsplash
Content on this blog was created using human and AI-assisted workflows described here. Original ideas and editorial decisions by Justin Quaintance.