Two companion notes trace where the delivery constraint moved once AI made writing code cheap: Code Review Tooling Market - GitHub, GitLab, and the PR Review Bottleneck downstream at review, and Rebuilding Review and Deployment for the AI Era at the ship path. This note goes the other direction, upstream, to the planning artifacts that exist before any code: product requirements documents, design docs, RFCs, architecture decision records, and the newer agent-facing specs. The claim under examination: when a model writes the implementation, the quality of the plan feeding it becomes the thing that most determines the output.
The planning artifact becomes an input, not a memo
A PRD or design doc was historically a coordination device: it aligned humans before they went off to build. In an AI workflow it becomes something more literal, a direct input to a generator. Spec-driven development (Spec-Driven Development) treats the spec as the source of truth and code as a regenerable artifact downstream of it, which means ambiguity in the spec is not smoothed over by an engineer’s judgment. It is compiled into the output.
The practical consequence is that PMs and engineers report reviewing planning docs more critically, not less. The common framing is that the competitive edge is no longer writing speed but thinking clarity: a sharp problem statement and validated concept produce a good result fast, a vague brief produces confident garbage fast. The skill shifts from drafting to spotting what a generated spec left out: edge cases, cross-team dependencies, launch risks.
Why models punish ambiguity that humans absorb
The mechanism behind “specs matter more now” is concrete, not motivational. Human implementers infer missing context from experience; models fill gaps with plausible defaults that may be wrong, and they degrade as instructions accumulate. Addy Osmani, summarizing a GitHub analysis of 2,500+ agent files, reports that most fail because they are too vague. He separately cites a “curse of instructions” finding: model adherence drops as requirements pile up, so even strong models struggle to follow many directives at once. The fix is deliberate modularization, not longer documents.
That analysis converged on six areas a working spec covers: exact commands, testing setup, project structure with explicit paths, code style shown by example, git workflow, and boundaries expressed as tiers (always / ask-first / never). The single most common constraint across specs was “never commit secrets.” The failure modes are equally concrete: “build me something cool” gives no anchor, and a monolithic 50-page document without hierarchical summaries overloads the attention budget as badly as too little context does.
A new document layer: agent-facing context
The genuinely new artifact is the context file: AGENTS.md, CLAUDE.md, and kin, checked into the repo to steer any agent that touches it. It occupies a different slot than the classic docs. Where an Architecture Decision Records entry answers “what did we decide and why,” the agent file answers “given that decision, what must always and never happen when changing this code.” The pitch is that decisions stop being merely recorded and start being enforced, on the reasoning that code is now generated faster than anyone records decisions by hand.
This is one instance of Context Engineering: the discipline of systematically supplying an agent with the intent, plans, and repository-specific detail it needs, through persistent artifacts rather than one-off prompts. Empirical work on these files is early. A study of context files across GitHub repos catalogs what they contain (project structure, dev instructions, tool specs, code guidelines) but the quantified effect on agent performance is not yet well established. Adoption is running ahead of measurement.
What the old formats do and don’t survive
Not everything upstream is being rewritten. Three patterns are visible in current discourse:
- Prototypes displace prose. “Demos before memos”: rather than describe behavior, use AI to generate an interactive prototype that shows error and success states. The written PRD shrinks toward a problem statement plus a working artifact. This is fast alignment but weak on the invariants a prototype does not exercise.
- ADRs are having a revival. The argument is that AI scaling makes recorded, enforceable decisions load-bearing infrastructure rather than documentation hygiene, precisely because an agent will otherwise re-decide settled questions inconsistently across a codebase.
- Probabilistic products need different specs. A PRD for an AI feature cannot assume deterministic output. The reframing is that quality is a distribution, so the spec defines acceptable behavior in aggregate (eval sets, thresholds) rather than a pass/fail per input.
Where the evidence is thin: almost all of this is practitioner framing and vendor writing from 2025-2026, not controlled study. The direction (planning gets more leverage, specs get more structured, a new agent-facing layer appears) is consistent across sources, but the magnitude is asserted, not measured. Treat the “how much” as open.
Moving leverage upstream also moves the risk upstream
The framing above treats better planning as pure upside, which understates the trade. Cheap regeneration cuts both ways. When the spec is the source of truth, a confidently wrong spec compiles a wrong system fast, at scale, with the error laundered through plausible-looking code that reads as intentional. A single bad line in a CLAUDE.md or a wrong assumption in a PRD now propagates further than a single bad function ever did, and it is harder to spot because the artifact that carries it looks like planning, not like a bug. This is why the downstream defenses in Rebuilding Review and Deployment for the AI Era are the other half of the same system: concentrating decisions upstream raises the value of catching a bad decision before it is generated, and of catching a bad generation before it ships.
Try it
Spec-diff a small feature (1-2 hours, any coding agent). Write two specs for the same small feature: a one-line vague brief (“add user tagging”) and a structured one with explicit boundaries, acceptance criteria, and an example of the data shape. Generate an implementation from each with the same agent and model. Compare what the vague run invented (naming, storage, edge-case handling) against what the structured run pinned down. The mechanism predicts the gap shows up as unrequested decisions the model made for you, which is exactly the ambiguity a human implementer would have absorbed silently.
Test the curse of instructions (1 hour, any LLM API). Take one generation task and give the model a growing list of constraints: 3, then 8, then 15. Hold everything else fixed and check adherence to each constraint at each level. If the finding holds, you will see adherence to individual rules fall as the list grows, and the failures cluster in the middle of the list. That degradation is the mechanical argument for modular specs over one monolithic document.
See also
- AI SDLC Bottleneck — the constraint-relocation frame this series runs on.
- Definition of Done — the downstream cousin of a spec: agreed criteria that gate completion rather than initiation.
- Async Coding Agents — where well-specified, enforceable context files pay off most: agents working without a human in the loop.
- Writing Code vs. Shipping Code: AI Productivity Across Tool Generations — why upstream leverage matters when downstream gains get swallowed.
Sources
- How to Write PRDs in the AI Era (Aakash Gupta) — the “clarity over speed” reframing of the PM role.
- How to Write a Good Spec for AI Agents (Addy Osmani) — the six-area structure, the curse of instructions, and concrete failure modes, drawn from a 2,500+ agent-file analysis.
- AGENTS.md vs Architecture Decision Records — the record-vs-enforce distinction between ADRs and agent context files.
- Agent READMEs: An Empirical Study of Context Files for Agentic Coding (arXiv) — what context files contain, and how early the measurement still is.