One Plan Doc for Humans and Agents

The PRD vs. spec debate misses the point

People keep arguing about whether PRDs are dead, whether specs should replace them, and whether spec-driven development is the new default.

That debate misses the real issue. The problem is not whether the top-level document is called a PRD, a spec, or a plan. The problem is that most teams create too many planning artifacts and then stop maintaining them.

We replaced that stack with one living plan document.

It is short enough that a human will actually read it. It is structured enough that an agent can use it. And it stays close enough to the work that it can remain current as the feature moves from idea to implementation.

What goes in the document

Our plan starts with the parts of a good PRD that matter most, but stripped down and written plainly:

• Goals
• Use cases
• Jobs to be done
• Differentiators
• Strategy
• Success criteria

Then, in the same document, we add the things that usually get scattered across separate files.

• Architecture diagrams in Mermaid or Excalidraw
• The implementation approach, but not code
• Key constraints, decisions, and tradeoffs

That gives us one document that explains why we are building something, what it should do, and roughly how we expect to build it.

What stays outside the document

We do not force everything into one file.

The code is still the code. The tests are still the tests. We usually keep a dedicated testing plan as a separate artifact because test cases often need more detail and more churn than the main plan.

But the plan becomes the backbone. Agents use the plan, the testing plan, and the codebase together. That combination produces much better results than throwing an agent into a repo with only a vague prompt and some source files.

How we use it

The workflow is simple.

First, we draft the plan with the team. Product, engineering, and design iterate on the same document instead of handing off separate interpretations.

Then we enrich that same document with diagrams and implementation approach. We are not writing code yet. We are making the shape of the solution clear enough that both humans and agents can reason about it.

Then agents use that plan to build. Because the goals, constraints, diagrams, and approach live together, the agent has a much better chance of making coherent decisions.

After implementation, the plan gets updated to reflect what was actually built.

That last part matters. Most docs die because nobody wants to update five different files after the work is done. Updating one document is realistic. Updating many is not.

Why one plan works better

Humans will read a few pages. They will not reliably read a bloated packet of planning docs that each tell part of the story.

Agents also do better when the important context is unified. They do not need to infer product intent from one file, architecture from another, and success criteria from a third. They can read one coherent narrative and then cross-check it against tests and code.

The result is less drift.

You get fewer contradictions between product intent and technical implementation. You spend less time re-explaining the same feature in different formats. And you end up with a planning artifact that is actually useful after the first week.

Keep it short enough to survive

The goal is to be as short as possible while still being thorough. Usually that means a few pages, not twenty.

If the document is concise, the team will read it. If the structure is clear, the agent will use it. If it stays attached to the work, it will remain accurate.

One plan document that humans will use, agents can build from, and both can keep up to date.