Spec-driven development for agentic software engineering: why the spec is the contract between team and agents

Why more code per developer can mean less output per team

Coding got fast. Coordination didn't. If you want to understand spec-driven development for agentic software engineering, start with this number: teams with high AI use completed 21 per cent more tasks and merged 98 per cent more pull requests, but review time rose 91 per cent, pull-request size 154 per cent and defects per developer 9 per cent. That is Faros AI's finding across 10,000 developers in 1,255 teams.³

The other sources show the same pattern. In 2024 DORA found delivery stability falling as AI adoption rose, and in 2025 summarised it this way: AI does not fix a team, it amplifies what is already there. METR measured in a randomised trial that experienced developers took 19 per cent longer with AI while believing they were 20 per cent faster. And across 211 million changed lines GitClear saw the share of refactoring fall from 25 to below 10 per cent, with eight times more duplicated blocks.^4,5,6

A paper from the Universidad Politécnica de Madrid, submitted to ACM and on arXiv since the end of August 2026, draws a clear diagnosis: the limiting factor is not model capability but the absorption capacity of the socio-technical system around it. Accelerating one phase of the lifecycle (code production) does not accelerate the system while review, verification and integration keep their old capacity. That is Amdahl's law applied to the software lifecycle, and the same lesson Scrum teams learned when their sprints overran operations.¹

I have been reading the paper with a pen for weeks. Not because it brings new numbers, but because it puts the loose practitioner discussion about harnesses, specs and agents into a frame a product team can actually operate. In this piece you will learn what the authors mean by spec-driven development, which eight mechanisms make up their methodological harness, how the roles of product managers and engineers shift, and where that lands in the PM Grader and the AI Product Playbook.

What vibe coding destroys at team scale: accountability, auditability, transferability

The authors compare four development paradigms along five dimensions: unit of work, primary artefact, locus of cognition, accountability and team topology. Agile and DevOps: the user story, working software, the individual developer, individual accountability, the cross-functional squad. AI-augmented engineering with Copilot-style assistants changes little; it speeds up sub-tasks and the human remains the author. Vibe coding, named by Karpathy in early 2025, shifts cognition into the chat window instead: the unit of work becomes the whole feature, the artefact is AI-written code, and accountability blurs because the developer signs a pull request they did not write.¹

Locally that works. A good developer gets done in hours what used to take days. At team scale it breaks in five places the paper names precisely. Non-reproducibility: the same prompt in the same context produces different code, and nobody can answer «why is this code here?» without reconstructing a conversation that is rarely saved. Non-auditability: the reasoning sits in a transient chat log; the reviewer only has the code. Non-transferability: whoever leaves the team takes the conversational context with them; the successor has to infer from code what was once explicit.¹

Add review saturation, because a reviewer cannot recover the intent behind an agent-generated pull request and has to reconstruct it from the diff, and noise scaling, because several developers with their own AI dialogues let the codebase drift apart in naming, structure and architecture. The authors stress: these are failures of methodology, not of practitioners. Vibe coding is the natural exploration phase of a new tool. The productivity paradox is the visible symptom of missing team-level discipline.¹

Agentic software engineering, the fourth stage, delegates goals instead of prompts: the unit of work is the technical goal («rate limiting for the orders API»), cognition is distributed between humans (intent, oversight, strategy) and agents (execution, parallel exploration), and the topology becomes N-to-N. This is exactly where the spec becomes the precondition: agentic engineering without spec discipline reproduces the weaknesses of vibe coding at larger scale, faster, broader, worse coordinated.^1,7

The thesis: the spec is the contract, the harness belongs to the team

My thesis, resting on the paper: the productivity paradox is a governance gap, and it does not close with better models but with a spec that serves as a versioned contract between people and agents, and with a harness that belongs to the team rather than the tool. This is not a return to the requirements tome. It is the step that restores accountability, auditability and transferability in a form that works with agents: accountability becomes contractual against the spec, verification audits evidence instead of reconstructing intent, onboarding reads specs instead of code.¹

The paper justifies the need for specs through a chain: specs enable contracts, contracts enable coordination, coordination enables trust at a scale where direct human inspection is no longer feasible. Three problems hang on it. The contract problem: an agent with a vague ticket produces plausible code that is not what was wanted, and review pays the cost. The coordination problem: if the shared artefact is the code, agents write conflicting code. The trust problem: humans cannot inspect agent output at agent volume line by line; trust needs evidence of conformance, and evidence needs a referent.¹

What spec-driven development means operationally: four commitments and two levels

The operational definition is short. A team works spec-driven when, first, every non-trivial planned change originates from a written specification the team treats as the contract; second, the spec is version-controlled next to the code with the same review, audit and rollback discipline; third, artefacts (code, tests, docs, infrastructure) are derived from the spec by humans, agents or both, with explicit provenance; and fourth, when spec and artefact disagree, the spec is the truth and the disagreement is resolved by re-deriving or amending the spec, never by silent edits. Four sentences, easy to say, hard to live.¹

The practical core many teams miss is the separation of two levels. System specifications describe the durable world of the project: architecture, conventions, domain model, patterns and the normative rules every change must respect. They belong to tech leads and architects, change with architectural decisions, and are increasingly materialised as a machine-readable rule file the agent loads at every session start: agent.md, CLAUDE.md, AGENTS.md or equivalent. Feature specifications describe one concrete change within that world: goal, requirements, constraints, acceptance criteria. They belong to the responsible developer, are created per task and archived once delivered.¹

Both must be in the agent's context. With only the feature spec loaded, the agent produces functionally correct but architecturally inconsistent code. With only the system spec loaded, it cannot ground the task. And conflating the two yields either rigidity (feature decisions in the system spec) or architectural drift (global constraints reinvented in every feature spec). As a third artefact the authors name skills: procedural know-how the orchestrator loads only when a task requires it. Norms are always active («what every change must respect»), skills are on demand («how to do X»). Put a convention into a skill and you will see it violated in every session that does not trigger the skill.¹

The paper clears up two misunderstandings. SDD does not mean more documentation: documenting code that already exists is retrospective and lagging; specifying behaviour before it is built is design, and in the agentic model the difference is amplified because the agent consumes the spec at execution time. A vague spec is not poor documentation but poor input that produces poor output at agent scale. And SDD is not waterfall: the proposal, apply, archive cycle (as in OpenSpec-style workflows) is iterative, just spec first and code second. That matches what I described as the define gate in the piece on dividing discovery from execution.¹

What the methodological harness looks like: eight mechanisms the team owns

In the agent community, harness is the name for everything in an agent system except the model: agent = model + harness. The technical harness (orchestration loop, tools, context management, memory, guardrails, verification loops) governs one agent in one session. It is transient: the better the models, the less scaffolding they need, and it co-evolves with the model. Investment in it depreciates quickly. The second, methodological harness consists of practices and artefacts the team owns. It encodes intent, norms and accumulated decisions and appreciates over time. The practical consequence: teams should invest in the durable harness first and treat tool selection as secondary.^1,8

Knowledge. Mechanism 1, context engineering: the team builds and maintains the agents' information environment as a shared, versioned asset. The paper's example is painfully familiar: a two-year-old architecture decision (all timestamps in UTC) lives in a wiki the agent never sees; it builds the refund function with the local timezone, tests pass in UTC, and the defect surfaces months later in reconciliation. The fix is one line in the system specification that prevents the whole class of defect for every future feature. Mechanism 2, persistent shared knowledge: a store for decisions, rationale and session summaries that is read at the start of every agent session and written at its end. Agents have no continuity between sessions; without this store each session rediscovers the project's decisions, and a sub-agent knows nothing of the decision another agent made an hour earlier. Three properties make it a team asset: it stores summaries and decisions rather than transcripts, it supports lazy retrieval, and it is agent-neutral and tool-neutral. In research language, that is the Product Brain.¹

Production. Mechanism 3, executable specifications: acceptance criteria are testable (given, when, then), constraints are checkable (a constraint no tool can enforce is a wish), decisions are explicit (POST /payments/{id}/refunds returning 201, not PUT) so conformance checks can validate them. A spec an agent consumes and tests validate stays alive; one only humans read decays into documentation nobody trusts. Mechanism 4, the N-version mindset and parallel agents: the same spec goes to three agents that return three candidates; the developer's cognitive task becomes «specify clearly enough that implementations can be compared», and the skill in demand is comparative reading rather than writing. Technically that needs working trees instead of shared branches, so conflicts move from silent active-work time to loud merge time.¹

Governance. Mechanism 5, normative specifications: the team's standing norms (conventions, patterns, prohibitions) are an explicit, versioned, reviewed part of the system specification, not tacit knowledge in the senior engineer's head. The example: after the third identical review correction («service methods must not catch generic exceptions») the correction becomes a rule in the rule file via pull request, paired with a lint sensor, and the agent self-corrects before a human sees the code. Mechanism 6, structured consultation: the agent stops at a decision it may not make and raises a scoped request with the question, the options, the affected spec clauses and the consequences; the answer is recorded against the spec so the same question is never asked twice. Mechanism 7, evidence-backed acceptance: «done» is not «PR merged» but an evidence pack that discharges every spec clause: executed acceptance tests, CI output, a short rationale, links to the spec version and the norms in force. The reviewer audits evidence and drills down only where it is weak. Mechanism 8, graduated autonomy: autonomy is set per class of task, explicitly and revisably (dependency updates fully autonomous, feature work with mandatory consultation, auth changes with an approved plan and stepwise review), as a team decision in artefacts, not an individual habit.^1,7

The eight mechanisms reinforce each other, and that is the paper's most important sentence for product teams: a team that adopts the harness in fragments, say writing feature specs but neither encoding norms nor persisting decisions, obtains a fraction of the benefit while paying most of the discipline cost. Partial, ungoverned adoption can degrade team outcomes. That matches DORA's finding that AI amplifies dysfunction. In Teklens vocabulary: the Product Brain is mechanisms 1 and 2, the quality gates are mechanisms 6 to 8, and the Playbook Activities are where mechanisms 3 to 5 become concrete: Write a PRD and Write a good ticket for feature specs with executable criteria, Record an architecture decision for norms and decisions, Review a code change for acceptance against evidence.^1,4

How the human role changes: five interaction patterns and six competences

The harness has a corollary: the team itself changes. The authors distil five recurring interactions, all operations on the shared spec. Briefing: the human conveys intent through a structured spec and must think in properties («the operation must be idempotent»), not examples. Consultation: the agent requests a scoped decision; this demands rapid context loading from the human and routing rules from the team, because an unanswered consultation blocks parallel agents. Review: the human audits an evidence pack against the spec; this demands the ability to read evidence rather than re-derive correctness, and the cultural acceptance some senior engineers experience as loss of control. Norm encoding: recurring corrections are generalised into rules. Orchestration: the human composes workflows of agents with autonomy levels and evidence requirements but does not write code, so their own context stays free of execution detail.¹

Taken together, the patterns describe what the human's primary work is: briefs, rules, workflow definitions, consultation resolutions and evidence judgements. Code production is largely delegated. The cognitive centre moves upstream (clarity of intent, architectural judgement) and sideways (comparative evaluation of candidates). The authors name six competences: specification literacy, architectural reasoning as a daily competence, comparative reading, norm articulation, cost-aware orchestration and strategic patience, meaning the resistance to «just code it» when the situation calls for specifying. That is the cultural inversion the whole agentic model demands.¹

For product teams one sentence matters most: «The product manager becomes a co-author of product specifications in a tighter loop than under Agile, because ambiguity at the product level now propagates directly into agent output.» The tech lead becomes the primary author of the system specification, whose impact scales across all features. QA inverts from after-the-fact testing to before-the-fact specification of testability. Ops and security shift from gatekeeping to authoring the operational and security specs that govern their agents. The topology becomes N-to-N: multiple humans, multiple specialised agents, connected through the shared spec substrate. The authors name three cultural shifts as the truly hard part: seniority moves from coding to specification (the deference shift), accountability spreads across brief author, orchestrator and evidence reviewer (the accountability shift), and juniors can no longer become senior through code alone (the skill investment shift).¹

What this means for the PM Grader and your Playbook

The PM Grader asks in six situations how your team works with AI today, and four of them are harness mechanisms directly. The situation «An agent picks up a story tomorrow. What does it find?» measures mechanism 1 and the technical harness (docs, permissions, test environment, CI, release controls). «A new team member or an agent needs to understand your initiative. Where does it find the truth?» is mechanism 2, persistent shared knowledge, in one question. «The agent says: done. Who signs off the result, and against what?» is mechanism 7, evidence-backed acceptance. And «Which rules apply to data, providers and actions of your AI?» is mechanism 8, graduated autonomy, plus the normative rules of mechanism 5.

The grader's maturity levels follow the paper's logic. Levels 1 and 2 are vibe coding at team scale: context gets copied together, results are nodded through informally. Level 3 has the artefacts (a project document, a named review rule) but not the loop. Level 4 has the contract: linked evidence with an owner, checks against explicit criteria, rules for data and providers. Level 5 closes the loop: contradictions are visible, review decisions traceable, rules adjusted after incidents. If the grader puts you at level 2 on context or sign-off, your next step is exactly the Activities that establish mechanisms 1 to 3; at level 4 you get those for mechanisms 6 to 8. The deep dive with six more situations sharpens the same dimensions, and the report orders the three priorities into a 30/60/90-day plan.

And the Playbook? In the paper's language the 43 Activities are feature specs for product work: each has a trigger, required context, steps with skills, quality criteria and a human approval. The Product Brain is the shared knowledge store from which people and agents pull the right context per task. That the authors explicitly name product specs as a second spec type beside code specs confirms, for me, that spec-driven development does not stop at engineering: the ambiguity that flows into agent output mostly arises one level up, in discovery and define.

Where the limits are: four predictions, five risks, one research agenda

The strongest evidence for the thesis is that the authors do not overstretch it. They predict four benefits and call them testable hypotheses: consistency (shared context and norms reduce drift), absorption (evidence-backed acceptance addresses the review bottleneck Faros and Qodo identify as the main brake), transferability (onboarding reads specs and the knowledge store instead of code) and organisational compounding (the context asset grows with every feature, the marginal cost of supervision falls). Five risks sit beside them: talent bifurcation between those who learn orchestration and those who do not; cultural fracture among experienced engineers; cost spirals from uncounted agent invocations; spec drift when spec and code silently diverge; and platform lock-in through proprietary spec formats.^1,3

Methodologically the paper is a multivocal literature review: 94 included works from IEEE Xplore, ACM, Scopus and arXiv plus grey literature from DORA, Faros, METR, GitClear, Stack Overflow, Martin Fowler, LangChain and practitioners such as Karpathy; the replication package is on Zenodo. The authors say unmistakably that the constructs (agentic SE, vibe coding, harness, specification) are young and contested, that the synthesis is coherent but not empirically validated, and that the motivating evidence skews toward web, SaaS and platform engineering; for embedded, safety-critical or heavily regulated software the transfer is plausible but unproven. The research agenda they set out matches the questions I know from conversations with teams: how teams reorganise around the orchestrator role, which human-to-agent ratios emerge, how engineers acquire the new competences, how organisations sequence the eight mechanisms, and how to measure spec quality, evidence completeness, consultation latency and agent portfolio cost where DORA metrics were built for human-authored software.^1,2

That closes the loop to the first number. 98 per cent more pull requests are no progress if they produce 91 per cent longer reviews and more defects. The paper explains why: the acceleration dissolved the contract that makes teamwork possible. Spec-driven development restores it in agentic form. Automate bad input and you just ship the mess faster; make the spec the contract and you ship evidence. The deeper insight is uncomfortable for everyone waiting for the next model: the harness that counts is not the technical one around the agent but the methodological one around the team. And the team has to build that one itself.³

Frequently asked questions

Recommendations

• Separate the two spec levels this week. Create a system specification as a rule file in the repository (architecture, conventions, prohibitions, a few hundred lines at most) and a template for feature specs with goal, constraints, acceptance criteria and a verification step. Activity: [Record an architecture decision](/playbook/record-an-architecture-decision) for the norms, [Write a good ticket](/playbook/write-a-good-ticket) for the feature spec.
• Make acceptance criteria executable. For the next non-trivial change: every criterion as given, when, then, every constraint with a tool that checks it, every decision explicit. What no tool can check is a wish, not a constraint. Activity: [Write a PRD](/playbook/write-a-prd).
• Replace «PR merged» with an evidence pack. Require from every agent pull request executed acceptance tests, CI output, a three-paragraph rationale and the link to the spec version. Reviewers audit evidence against clauses and drill down only where it is weak. Activity: [Review a code change](/playbook/review-a-code-change).
• Persist decisions and consultations in one place. Every agent consultation and its answer is recorded against the spec; every session ends with a summary in the shared store the next session reads. That is the difference between a collection of sessions and a team. In Teklens vocabulary: the Product Brain.
• Calibrate autonomy per class of task and write it down. Three classes are enough to start: fully autonomous (dependency updates with the test suite as judge), autonomous with mandatory consultation (ordinary feature work), plan approval plus stepwise review (auth, payments, data). Revise the calibration quarterly after incidents. Activity: [Run a blameless incident postmortem](/playbook/run-a-blameless-incident-postmortem).
• Measure what DORA does not. Spec quality (how often a consultation was needed), completeness of evidence packs, consultation latency, review time per pull request and agent cost per feature. If review time rises with pull-request count, you have vibe coding at team scale, not SDD. Activity: [Define and use KPIs](/playbook/define-and-use-kpis).

Scope & caveats

• The paper by Díaz, Gayoso, Cimminio and Pérez (Universidad Politécnica de Madrid, arXiv 2609.00252, 31 August 2026, submitted to ACM) is a conceptual synthesis from a multivocal literature review, mostly grey literature. The authors themselves stress that it is not a validated framework and that whether SDD resolves the productivity paradox remains empirically open. I adopt their terms, not their evidential weight.
• The paradox figures come from external sources and are cited as the paper reports them: Faros AI (2025, telemetry from 10,000+ developers in 1,255 teams, vendor data), DORA 2024 and 2025 (correlations, self-reported), METR 2025 (16 developers, 246 tasks, since described as out of date by METR itself) and GitClear (211 million lines, 2020 to 2024). None of them is a statement about your team.
• Mapping the Product Brain, quality gates and Playbook Activities to the eight mechanisms is my interpretation, not a statement by the authors. Teklens is not mentioned in the paper. The PM Grader's maturity levels are a Teklens practice model, not a validated measurement of the harness.
• SDD is a governance discipline, not a universal prescription. The authors themselves say that for exploratory work with genuinely unknown requirements a deliberately lighter discipline with throwaway artefacts may be more appropriate. The degree of specification depends on uncertainty, stability and the expected lifetime of the work product.

Sources

Every external figure and quote in this piece – linked so you can verify it.

1. 1.Díaz, J., Gayoso, J., Cimminio, A., Pérez, J. (2026). Spec-Driven Development for Agentic Software Engineering: Harnessing Human–Agent Teamwork. Universidad Politécnica de Madrid, arXiv:2609.00252, manuscript submitted to ACM ↗ – Multivocal literature review; socio-technical model of SDD, eight harness mechanisms, five interaction patterns.
2. 2.Replikationspaket zum Paper, Zenodo, DOI 10.5281/zenodo.22151221 ↗ – Source selection and extraction matrix of the synthesis.
3. 3.Faros AI (2025), The AI Productivity Paradox Report ↗ – Telemetry from over 10,000 developers in 1,255 teams: +21% tasks, +98% PRs, +91% review time, +9% defects.
4. 4.Google Cloud / DORA (2024, 2025), Accelerate State of DevOps Report und State of AI-assisted Software Development ↗ – 2024 falling stability with AI adoption; 2025 «AI amplifies what is already there».
5. 5.METR (2025), Measuring the Impact of Early-2025 AI Tools on Experienced Open-Source Developer Productivity ↗ – RCT with 16 developers: 19 per cent slower, perceived 20 per cent faster.
6. 6.GitClear (2025), AI Copilot Code Quality: 2025 Data Suggests 4x Growth in Code Clones ↗ – 211 million changed lines 2020 to 2024; refactoring share from 25 to below 10 per cent.
7. 7.Hassan, A. E., Li, H., Lin, D., Adams, B., Chen, T.-H., Kashiwa, Y., Qiu, D. (2025). Agentic Software Engineering: Foundational Pillars and Research Roadmap. arXiv:2509.06216 ↗ – SE for humans and SE for agents, briefing documents, consultation request packs, merge-readiness packs.
8. 8.Böckeler, B., Fowler, M. (2026). Harness Engineering for Coding Agent Users. martinfowler.com ↗ – Practitioner article: agent = model + harness.

Keep reading in the PM Lab

Related deep dives – from the same pillar and the adjacent phases.

Matching Activities from the Playbook

From the article straight into practice: these Activities put the concepts to work with Teklens.