A planning workflow that works: spec, design doc, implementation plan
Best practice right now is spending 50%+ of your time planning before an agent writes a line of code. Here's the three-document structure we see working across teams.
Basically 50%+ of the work in agentic engineering right now is up-front planning. That’s a strange thing to say out loud. It feels waterfall, and we’ve all spent the last fifteen years being told waterfall is bad - we’re agile, we don’t do big up-front design, we work out the user need and start coding and see where we end up. Deliver small increments. Deploy early, deploy often. Feature-flag everything.
A lot of that is still valid. But to get the best out of coding agents, you currently need to spend a lot of time planning with them before they touch the codebase. For a reasonably-sized feature or change, we’ll spend 60-90 minutes going back and forth with the agent before it writes an implementation plan. Then we review that plan - and reviewing it properly is a huge part of the human’s job right now.
Three documents, not one
The structure that’s working best across the teams we talk to breaks planning into three distinct artifacts, each with a different job:
The spec is the goal. The agent helps flesh it out by asking questions and understanding what the product needs to do. It should land somewhere around 50-200 lines. You need to read every line of it and actually agree with it - if you don’t, you’re not engineering, you’re just watching.
The design doc is more detailed, with much heavier reference to the architecture and the existing codebase. It’s also created with the agent, but it’s a different kind of document from the spec: less “what are we building” and more “how does this fit into what already exists.”
The implementation plan is what the agent produces once the design doc is settled - the concrete, step-by-step technical plan that actually gets executed.
The reviewing problem
Here’s the part that’s still annoying: you clearly don’t want to review a big markdown file sitting in a terminal. So people move to an IDE. But then what happens when you want to discuss one specific part of the plan with the agent - quibble about a detail, ask it to reconsider one section, without re-explaining the whole thing?
That gap was annoying enough that my co-founder Chris Raethke built Discuss CLI, a small open-source tool to close it - a way to open any plan as a proper review surface (PR-style comments, in the browser) where the agent can read the exact passage you’re commenting on and reply in the margin, with full context, instead of you re-pasting chunks of markdown into a chat window. It turns plan review into a tight loop instead of a copy-paste chore, and we genuinely can’t go back to reviewing plans any other way now.
Why this is worth the time
None of this is really new advice - it’s the same argument for planning that’s existed since before “agile” was a word. What’s changed is the cost-benefit. When a human was going to write the code anyway, spending 90 minutes writing a spec before typing the first line felt like overhead you could often skip and get away with. When an agent is going to turn your spec into a full implementation in the next 20 minutes, the spec is the only lever you have left to make sure that implementation is actually what you wanted. Skip it, and you’re not saving time - you’re just moving the same conversation to after the code already exists, where it’s much more expensive to have.
Spend the time up front. Read every line of the spec. That’s the job now.