Why a PRD is not enough, and when a spec bundle actually helps

GitHub: agent-spec-bundle

The most boring failure in AI development does not look like a broken build. It looks like a polite question from an agent in the middle of an otherwise decent PRD.

The document is good. It has the idea, the goal, the scope, sometimes even tidy non-goals. Everything looks mature right up to the moment the agent asks: what lives in the database, what does the payload look like, what counts as done, and where exactly does this release stop being responsible?

That is usually when the unpleasant thing becomes visible: the PRD explained the product, but not the build.

That is why I put together agent-spec-bundle. It has three simple pieces: the spec-bundle skill, a scaffold script, and templates for prd.md, contracts.md, schema.sql, test-plan.md, and epics.md. Not a cult of sacred Markdown files. Just a way to remove ambiguity before someone already has a branch with code and their own interpretation of the task.

Where a PRD starts failing

The problem is not the PRD as a format. The problem is that it too often lives above the ground. It answers questions like “what are we building” and “why does this matter” well. It answers a different set of questions much worse: what the agent is not allowed to invent, and which disputed points must be closed before code.

When those artifacts are missing, the agent still moves forward. That is the catch. The error usually appears not while reading the PRD, but later, when there is already code, rough schema drift, a crooked contract, or a review where everyone suddenly learns that “done” meant different things.

So the core bug is not “the document is bad.” The core bug is that the document left too much room for an expensive guess.

What the bundle removes in practice

contracts.md matters where silent assumptions like to break work: APIs, queues, IPC, events, and background jobs. schema.sql fixes entities while arguing about them is still cheap. test-plan.md makes “done” verifiable rather than emotional. epics.md turns all of this into a clear handoff instead of a second product-discovery session on the way into GitHub.

The point of the bundle is not the number of files. If half of them are unnecessary, good, they should not be in the folder. A bundle is useful only when a specific artifact removes a specific ambiguity.

This is especially visible with agents. A person often forgives holes in a document because they wrote it and can reconstruct the missing context from memory. An agent can also reconstruct things. The cost of that “can” usually arrives later, in code.

The uncomfortable tradeoff

A spec bundle has an uncomfortable downside: for a small task, it is expensive paperwork. If the work fits into 40 minutes, is reversible, and does not touch a second layer of the system, the bundle can become a neat folder that consumed time and removed no real risk.

That is why I care less about the bundle as a ritual and more about the bundle as a tool with a very plain usefulness test. It must remove ambiguity. If it does not, it is not discipline; it is paper overheating.

The right moment for a bundle starts where the work will survive one session, cross several subsystems, hit schema, queues, or background jobs, or later move into GitHub Issues as a real execution lane.

What I would take from this

If you want to repeat the approach, I would start with three things:

• do not treat a PRD as automatically execution-ready;
• add contracts, schema, and test-plan only where they remove real ambiguity;
• measure the bundle not by file count, but by how many expensive guesses it killed before the first branch.

Everything else is a matter of scale. Sometimes a brief is enough. Sometimes a full bundle is needed. But if the bundle does not remove ambiguity, it is not an agent-ready package. It is just another Markdown folder that will also need explaining later.