AI coding agents have moved the bottleneck. Writing code used to be the slow part. Now an agent can generate thousands of lines while you make coffee — and the slow part is deciding what to build.
That shift catches a lot of teams off guard. They point an agent at a vague idea, get a working feature in an afternoon, and then spend a week undoing it because the feature was built on a slightly wrong assumption. The code was fast. The thinking was skipped. And as one developer put it recently, if your starting opinion is slightly wrong, no amount of automation will save you — the automation just gets you to the wrong place faster.
The fix is unglamorous, cheap, and older than the AI hype: write down what you think before you automate it.
The teams getting the most out of coding agents tend to share one habit. Before any code is generated, they debate the feature — what it should do, what it should deliberately not do, who it is for, and what "done" looks like — and they capture that debate in plain markdown files inside the repo.
Not a wiki nobody reads. Not a ticket that goes stale. Small, versioned text files, right next to the code:
docs/decisions/001-checkout-guest-mode.md`` docs/decisions/002-pricing-in-cents.md``docs/product/why-we-built-X.md
The agent then reads those files as its source of truth. You are no longer asking it to guess your intent from a one-line prompt. You are handing it your judgement, in writing, and asking it to execute.
This is the part people skip because it feels like slowing down. It is slowing down — for about an hour. It saves days.
A good decision file is short. Five sections are usually enough:
## Context
40% of checkouts are abandoned at the sign-up wall.
Support gets weekly complaints about forced accounts.
## Decision
Keep guest checkout. Accounts are optional, offered
*after* payment succeeds, never before.
## Alternatives considered
- Forced accounts (rejected: kills conversion)
- Social login only (rejected: not all users have one)
## Consequences
- We store orders by email, not user ID.
- Password reset flow must handle guest orders.
- Marketing loses some sign-up funnel data.
## Status
Accepted — 2026-11-10. Revisit if abandonment
drops below 15% for a full quarter.
Notice what this file does for an agent: it tells it the why, the rejected alternatives, and the trade-offs. Without it, an agent asked to "improve checkout" might helpfully add a sign-up wall — the exact thing you decided against. With it, the agent works inside your judgement instead of against it.
This is the same idea behind Architecture Decision Records (ADRs), a practice that predates AI coding tools by years. The AI era just raised the stakes: before, a forgotten decision cost a confused new hire an afternoon. Now it costs an agent an afternoon of confidently building the wrong thing at machine speed.
Here is a simple version of the workflow, end to end:
1. Debate before you type. Get the people who own the feature in a room (or a call) and argue about it. What problem are we solving? What are we explicitly not doing? Capture the discussion as notes or a transcript — even a rough one.
2. Distill it into markdown. One decision, one file. Keep it under a page. Write the context, the decision, the alternatives you rejected, and the consequences. If you cannot write the "alternatives considered" section, you have not thought hard enough yet.
3. Put it in the repo. Decision files live with the code so they get reviewed in pull requests like everything else. A decision that nobody reviewed is a rumour, not a decision.
4. Point the agent at the file. When you ask your coding agent to build the feature, reference the decision file explicitly: "Implement this following docs/decisions/001-checkout-guest-mode.md." Now the agent is executing a decision, not inventing one.
5. Update the file when reality changes. Decisions go stale. When a pivot happens, do not just change the code — supersede the old file with a new one that says what changed and why. The history of why things are the way they are is the most valuable documentation a codebase can have, and it is exactly what agents need to avoid re-litigating settled questions.
"But what if we change our minds?" You will. That is the point. A decision file is not a contract carved in stone; it is a snapshot of your best thinking at a point in time. Changing your mind is cheap when the old reasoning is written down — you can see exactly which assumption broke and update just that part.
The expensive version is the team with no written decisions, where every pivot means re-arguing everything from scratch, and where every agent session starts from zero context and re-invents choices you already made six months ago.
There is a temptation to measure AI productivity in lines of code per minute. That metric is already meaningless — agents will win it by orders of magnitude, and the code will still be wrong if the thinking was.
The scarce skill is now judgement: knowing what is worth building, what to leave out, and why. Judgement that lives only in someone's head cannot be automated. Judgement written down in a markdown file can be — by you, by your teammates, and by the agent working at 2 a.m. while you sleep.
So before your next agent session, try this: spend thirty minutes writing down what you actually think. One file, one decision, five sections. Then hand it to the agent and watch how much less rework comes back.
Slow down. Write it down. Then let the machine be fast.
— Written by Davis George · zhuan.xyz