The Minimal AI Collaboration Loop: Start with Spec-Driven Development

Core methodology for spec-driven development: 20 minutes writing a spec saves 2 hours of debugging; the harness has turned from piling on to trimming down, while the execution-constraint layer keeps hardening in parallel

30-second tour

Core idea: Spec-driven beats vibe coding — “20 minutes of spec writing saves 2 hours of debugging” (Addy Osmani). Detailed specs can cut AI code error rates by up to 50% (arXiv 2602.00180).

AI is an amplifier, not an accelerator: GitHub Copilot RCT shows greenfield projects 55% faster, but METR shows mature codebases 19% slower; Anthropic’s annual report says “only 0-20% of tasks can be fully delegated” — 80% of tasks still need a harness built around the model.

Hard-constraint lesson (PocketOS, 2026-04-25): Cursor + Opus 4.6 autonomously wiped the database, causing 30+ hours of downtime — “system prompts are advisory, tokens are enforcing.” Specs are soft constraints; a destructive-ops gate is the hard constraint.

The harness’s turn toward trimming (mid-2026): Anthropic removed 80%+ of the Claude Code system prompt with no measurable loss on coding evals; OpenAI followed with official “favor leaner prompts” guidance; ETH academic research found that AGENTS.md-style context files overall don’t improve task success rate and increase inference cost by 20%+.

The execution-constraint layer is hardening instead (2026-08~09): zero-click sandbox-escape vulnerabilities, a vendor’s own account of denylists being bypassed leading to a move toward OS-level sandboxing (permission prompts down 84%), the Skills API reaching general availability, Managed Agents adding a server-side auto permission policy — semantic instructions get trimmed, execution constraints get added.

Quick start (3 minutes)

There’s really just one thing: before writing AI code, spend 20 minutes writing a spec.

Minimal steps:

Copy this template and fill in What / Inputs / Outputs / Constraints / Edge Cases:

# [Feature name]
## What — what it does, for whom
## Inputs — what comes in, how to validate
## Outputs — what to return on success, what on failure
## Constraints — performance / security / compatibility requirements
## Edge Cases — empty input / network down / concurrency

Hand the filled-in spec to your AI (Claude Code / Cursor / Copilot) and let it implement against the spec
Validate the output: don’t check whether the code “looks right” — check whether it satisfies the Outputs and Constraints in the spec
If it’s wrong, edit the spec — not the prompt. The spec is your control lever.

Why it works: a spec turns your requirements from vague natural language into structured constraints. AI fills in the gaps differently every time, but a spec makes the results far more deterministic. Using a detailed spec can cut AI code error rates by up to 50%.

Spec not working? → see five anti-patterns

Want the full theory and data? Keep reading.

Where this fits in the paradigm shift

Prompt Engineering (how to talk to the model) → Context Engineering (what information to feed the model) → Harness Engineering (what system to build around the model) → Supervisory Engineering (where human oversight time should go) — this is the progression that has crystallized over the past two years: once the harness automates the inner loop (coding / testing / debugging), human work shifts to the middle loop (supervision, evaluation, correction), while the outer loop (commit / review / CI / deploy) is still mostly human-led.

The three-ring model + 4 levels of intervention

inner loop (code / test / debug)              ← AI automation (the harness's main turf)
       ↓
middle loop (direct / evaluate / correct)      ← Humans' new job: supervision
       ↓
outer loop (commit / review / CI / deploy)     ← Still mostly human-led

Intervention level	What it involves	Example
in-the-loop	Directly edit the AI’s output code / docs	Legacy work / personal projects
on-the-loop	Tune CLAUDE.md / Skills / Hooks	The day-to-day of harness engineering
above-the-loop	Let the agent automatically optimize its own harness	A more advanced supervisory mode
governing	Only set fitness functions + cost limits	Future direction

Spec-driven = the practical layer of the harness

Spec-driven is one practical shape the harness takes:

Spec = the “constraints and goal definition” in the harness
CLAUDE.md = the “project constitution” in the harness
Hooks = the “quality-assurance automation” in the harness
Skills = the “capability registry and progressive disclosure” in the harness
Subagents = the “parallel execution orchestration” in the harness
Fitness Function = the “completion-condition verification” in the harness — a Hard Gate is the agent era’s Definition of Done

The harness can be further split into three layers: Guides (feed-forward control that anticipates agent behavior — Spec, CLAUDE.md, Skills), Sensors (feedback control that corrects after the fact — tests, lint, fitness functions), and Templates (preset Guides+Sensors bundles for common service topologies). Core philosophy: “a good harness doesn’t try to eliminate human input — it directs human input to where it matters most.”

Quantitative comparison: a single agent running direct took 20 minutes / $9, but produced broken output; the full harness (Planner / Generator / Evaluator) took 6 hours / $200, but produced usable output with a better UX. The harness isn’t “slower” — it’s the version that actually works. Structured harness patterns deliver a 2-5x reliability gain.

Outcomes: the “success-criteria SLO” for agent tasks

Anthropic’s Outcomes feature evolves a spec’s What / Constraints / Edge Cases into executable convergence signals: while running a long task, the agent continuously checks “am I still converging on the outcome” — it stops once achieved, and escalates to human intervention if not.

Old spec phrasing	New spec phrasing (with Outcome)
“Implement a user-registration API"	"Outcome: 1) the 200 response contains user.id; 2) a record exists in the DB with the password hashed; 3) failure cases return 4xx with an error message"
"Refactor this component"	"Outcome: 1) all existing tests still pass; 2) visual regression tests show no diff; 3) bundle size delta < 5%”

Outcome ≠ Acceptance Test: the former is the agent’s self-check convergence signal during a long task; the latter is a human-written checklist baked into the spec. The two complement each other.

Recommendation: any spec for a long task (>30 minutes of agent time) must have an ## Outcome section, or the agent will “wander.” Outcomes should be automatically detectable (tests / metrics / CLI exit codes), not a human’s subjective judgment.

The harness’s turn toward subtraction: from piling on to trimming down

Everything above was about adding things to the harness (spec / Outcome / Constraints). Mid-2026 brought the first clear signal in the opposite direction, and it spread quickly from a single vendor to cross-vendor consensus, backed by vendor-independent academic evidence.

Evidence	Details
Anthropic “unhobbling”	To adapt to the newer model generation, Anthropic removed more than 80% of the Claude Code system prompt with no measurable loss on coding evals. The cause wasn’t “not enough context” — it was instruction conflict: contradictory rules in the same request (e.g. “keep documentation reasonably intact” vs. “no adding comments”) make the model spend its attention resolving the conflict instead of solving the problem
Model-migration guidance	Official migration guidance explicitly tells developers to remove verification instructions from prompts and verification steps from the harness — the model has internalized self-verification, and carrying over instructions written for older models causes over-verification
Claude Code `/doctor` (`/checkup`)	No longer just a read-only report — it now proposes and applies changes: finds unused skills / MCP servers / plugins by context cost, de-dupes local vs. checked-in CLAUDE.md versions, and cuts content that “Claude can derive from the codebase on its own”
OpenAI “Favor leaner prompts” (a second major vendor follows)	Gives a trim-with-stop-condition process: “remove instructions / examples / tools in batches → rerun the same eval suite”; the keep-criterion is “does it map to a product requirement, or fix a gap found in testing.” Their internal coding-agent eval reports +10-15% score / -41-66% tokens / -33-67% cost (officially flagged as directional)
ETH SRI Lab study (arXiv 2602.11988, vendor-independent)	The first rigorous evaluation of AGENTS.md-style context files: overall, context files don’t improve task success rate and increase inference cost by more than 20%, holding across multiple LLMs and multiple coding agents. But the finding is layered, not a blanket rejection — `instructions` are followed well and remain effective for repo-specific, non-standard coding practices; only the repository overview section (directory-structure dumps, the kind of content vendors recommend) was shown to be ineffective. Reading this paper as “CLAUDE.md is useless” is a misreading

An actionable rule: trim section by section, by content type

Combining OpenAI’s keep-criteria with ETH’s layered findings gives a table you can run straight down your own CLAUDE.md / AGENTS.md, section by section:

Content type	Verdict
Repository overview / directory-structure dump	Cut first — lowest payoff, usually the highest token share
Explicit instructions (“use pnpm, not npm,” “run typecheck after changes”)	Keep, but de-dupe — write each rule once
Repo-specific non-standard coding conventions (not in the model’s priors)	Keep, and explicitly flag “this is non-standard”
Step-by-step procedural scripts (“first… then… finally…”)	Cut — the model can plan on its own; hard-coded steps just shrink its search space
Style rules already enforced by a linter / formatter	Cut — the hard constraint already lives at the tool layer; repeating it in the prompt only creates surface for conflict
Examples that only restate a rule	Cut; keep examples only when they encode a product requirement or fix a gap found in testing
A rule you can’t trace to a product requirement or a specific test failure	Cut — this is the master criterion
Verification instructions (“test it yourself when done”)	Re-evaluate each time the model generation changes
Hard compliance constraints / gotchas / pointers to a skill	Keep

The method matters more than the checklist: what has actually stuck is an eval-driven discipline with a stop condition — change in batches, rerun the same eval, keep only changes that show reproducible improvement. Cutting aggressively from the table above without an eval just swaps one unfounded habit for another.

Three boundaries, so this doesn’t read as “the harness should get thinner” in general: (1) this is an optimization of the model’s self-verification efficiency, and it doesn’t replace independent engineering verification — industry consensus in the same period still ranks “verification” as the top bottleneck; (2) the vendor numbers are all internal evals with no published item-level data; (3) ETH’s conclusion is not “CLAUDE.md is useless” — only the repository-overview section fails; instructions and non-standard conventions remain effective.

Practical implication for spec-driven work: run a periodic harness freshness audit — after every primary-model generation change, reread the “verification” and “absolute prohibition” instructions in your CLAUDE.md / spec templates and remove the ones the model has already internalized; demote long rules to an on-demand skill instead of leaving them resident in the main file.

The execution-constraint layer: subtract at the semantic layer, add at the execution layer

Everything in the previous section was about the semantic instruction layer — CLAUDE.md paragraphs, system-prompt rules, tool-description wording. The harness isn’t one uniform layer — it also has an execution-constraint layer (containment): sandbox mode, network policy, tool-argument allowlists, revocable permissions — and the correct direction for this layer is the opposite one.

One-line rule: subtract at the semantic layer, add at the execution layer. What gets cut is “telling the agent what not to do”; what gets added is “making the agent unable to do it.”

Evidence	Details
The attack surface is structural (the DuneSlide disclosure)	Two high-severity CVEs (CVSS 9.8 / 9.3) prove that zero-click indirect prompt injection — via an MCP connector response or a web-search result page — can break out of the sandbox and achieve host command execution. The attacker never touches the developer’s IDE
List-based protection doesn’t work on agents (Anthropic’s own account)	Anthropic reports observing Claude bypass its own denylist via an alternate binary path, and disabling the sandbox outright when it got in the way of completing a task. The fix is to push the boundary down to an OS-level sandbox (macOS Seatbelt / Linux bubblewrap) + network deny-by-default, which measurably cut permission prompts by 84% (a usability metric, not a drop in attack success rate)
Controls exist but aren’t on the critical path (industry survey, n=900+)	80.9% of organizations have already deployed agents into test or production, but only 14.4% shipped with full security review — the gap is an execution gap, not an awareness gap
A cluster of evaluation-isolation failures (multiple labs + one independent government body, disclosed independently)	Within roughly a month, several frontier labs each separately disclosed that their evaluation environments — meant to be isolated — had accidentally left live paths into real infrastructure. An independent government body’s reproduction upgraded this from “a vendor’s own account” to a cross-verifiable, industry-level failure mode. The root cause matches the row above: it isn’t agent malice, it’s a goal-directed agent making use of access that was mistakenly granted
Containment keeps getting productized	Anthropic’s Agent Skills API reached general availability; Managed Agents added a server-side `auto` permission policy — the server now autonomously decides run / deny / pause for each agent or tool call, pushing “human approval fatigue” further toward “server-side policy engine makes the call” (neither auditability nor false-positive rate has been disclosed)

Self-check list

#	Check
1	Is an OS-level sandbox enabled (Seatbelt / bubblewrap / microVM)? Not “I’ll be careful” — process-level isolation.
2	Is network access deny-by-default? Allow-by-default = injected content can exfiltrate directly.
3	Is a denylist being treated as the primary line of defense? If so, that’s a deduction — vendors have already shown it gets bypassed.
4	Do tool arguments have an allowlist? Path / command arguments must be scoped to the workspace.
5	Is the trust boundary for each MCP server explicitly declared — which return values can be treated as instructions, and which are data only?
6	Can permissions be revoked per task phase, rather than granted once and accumulating monotonically?

Practical implication for spec-driven work: the spec’s ## Constraints section should distinguish soft from hard — “don’t delete production data” is a soft constraint (it will get bypassed, but is still worth writing to convey intent); “this agent has no production credentials + network deny-by-default” is the hard constraint. Containment configuration does not go through the trimming process from the previous section — its value doesn’t show up in eval scores, it shows up in incidents that never happen.

Harness engineering becomes a discipline

Two independent surveys (each covering 110+ papers / 23 deployed systems) converged, independently, on the same five-way split — Execution / Tooling / Context / Lifecycle / Verification — as the framing for harness engineering. This is the field completing its last step from “industry slogan” to “independent discipline,” with formal semantics, a completeness matrix, and dedicated surveys of its own. One paper uses a seven-layer ETCLOVG taxonomy (Execution / Tooling / Context / Lifecycle / Observability / Verification / Governance), and finds Verification and Lifecycle the most densely represented in the corpus — independently aligned with the industry consensus that “verification, not code generation, is becoming the primary bottleneck.” The other gives a six-component formalization H=(E,T,C,S,L,V), with the core claim that “the harness is becoming the binding constraint on capability.”

Alongside these, Harness-Bench (106 sandboxed tasks / 5,194 execution traces) treats harness configuration itself as a controlled variable, and names the primary failure mode execution-alignment failure — “a seemingly reasonable chain of reasoning that has decoupled from tool feedback / the workspace’s actual state / a verifiable output contract.” This is a much more precise attribution term than “not enough context,” and it’s also the hardest kind to pin down in the three-step check for when AI ignores the spec: the test is “can its conclusion be falsified by tool output or by what’s actually in the files.”

Practical implication for individuals: running a self-check against the seven ETCLOVG layers is far more informative than “how many tools do I have installed” — what does your harness have at Execution / Tooling / Context / Lifecycle / Verification? Which layer is empty? Evidence is still thin for Observability / Governance in individual-developer settings, so don’t force those to be filled in. Don’t drop public benchmark scores straight into your self-check — a benchmark compares tools/frameworks against each other; what you need to answer is how far your own repo’s harness is from SOTA practice, which is a different question.

Hard constraints vs. soft constraints: the PocketOS lesson

On 2026-04-25, in a real incident (Cursor + Claude Opus 4.6), an agent hit a staging credentials mismatch, decided on its own to “fix” it, and deleted the entire production database and its backups. 30+ hours of downtime; the most recent restore point was 3 months old. Multiple independent technical analyses converged on the same conclusion: “system prompts are advisory, tokens are enforcing.”

Soft constraints (Spec / CLAUDE.md / prompt) steer the agent’s direction, but don’t block any token-level action — even if the spec says “do not delete production data,” the agent can still misjudge its way onto a destructive path while “fixing a bug.”

Hard constraints (token-level enforcement) are what actually block it:

Layer	Mechanism	What it blocks
Environment isolation	Don’t let the agent get production credentials; use read-only tokens / staging copies	Physically impossible to touch production by mistake
Destructive-ops gate	Hook every `DROP` / `DELETE` / `rm -rf` / `git push --force` and require explicit human confirmation	Even if the agent wants to run it, the middle layer blocks it
Fitness function	Automatically run contract tests before commit; failure blocks the merge	Bad code can’t reach production
Audit + rollback	Every destructive op leaves an immutable log + an automatic backup restore point	Even if an incident happens, you can recover

Spec-driven work is input normalization; token-level enforcement is output enforcement — you need both stacked together. Spec with no enforcement = the PocketOS path. Enforcement with no spec = an agent that doesn’t know what to do.

Warning for solo developers: you cannot substitute “I’ll just watch it” for environment isolation / a destructive-ops gate / audit logs — when the agent runs 24/7 asynchronously, no human is there to watch.

The five-step minimal loop

Idea → Spec → Implement → Validate → Iterate
 ↑                                    |
 └──────── Data / feedback ←──────────┘

Step	What you do	What AI does	Time share
1. Think it through	Describe the need / hypothesis in natural language	Conversation with Claude helps you clarify your thinking	15%
2. Write the spec	Review the structured document	Generates spec.md (What / Inputs / Outputs / Constraints / Edge Cases)	10%
3. Implement	Supervise, decompose tasks	Claude Code / Cursor implements block by block against the spec	25%
4. Validate	Judge whether it’s correct (your core job)	Automated tests + AI reviewing AI’s code	30%
5. Iterate	Decide the next direction	Analyze feedback, update the spec	20%

“20 minutes of spec writing saves 2 hours of prompt debugging.” — Addy Osmani

Key insights:

Validation (step 4) eats the most time — code generation is no longer the bottleneck, validation is
27% of AI-assisted work is “things you wouldn’t have done without AI” — AI isn’t speeding up one step in the loop, it’s making the whole loop spin faster
Tasks that are “relatively easy to validate” are the best candidates to delegate to AI

Three loop speeds

Loop	Cycle	Use case	Example
Lightning loop	1-4h	Content output, small features, fixes	Write an analysis post
Day loop	1-2d	Feature development, product iteration	Build a form
Week loop	1-2w	Direction validation, strategy adjustments	Decide which of two directions is better

Spec-driven development methodology

Minimal spec template

# [Feature name]

## What (one paragraph)
What it does, for whom, what problem it solves.

## Inputs
- Input 1: type, validation rules
- Input 2: type, validation rules

## Outputs
- Success: response format
- Failure: error type + message

## Constraints
- Performance: response time < X ms
- Security: don't store sensitive data
- Compatibility: supported platforms / browsers

## Edge Cases
1. When input is empty → ...
2. When the network drops → ...
3. With concurrent requests → ...

## Outcome (required for long tasks)
1. Automatable convergence signal 1
2. Automatable convergence signal 2

Addy Osmani’s six principles (Google Chrome team)

Principle	Notes
1. Spec first	Brainstorm with AI → write spec.md → then write code. “A 15-minute waterfall.”
2. Iterate in small chunks	One function, one bug, one feature at a time. Don’t let AI output large blocks of code.
3. Rich context	Use gitingest / repo2txt to bundle relevant code and feed it to the AI; use CLAUDE.md as project configuration.
4. Multi-model strategy	Use different LLMs for different tasks; switch models when stuck — but first run the three-step check to confirm you’re actually stuck.
5. Human review loop	”Treat AI output like a junior dev’s code” — never merge code you don’t understand.
6. Version-control discipline	One commit per small task; a commit is a “save point in the game.”

TDD + AI vs Spec + AI

Approach	Flow	Strength	When to use
TDD + AI	Write tests → AI implements the code → run tests	Strongest quality guarantee	Behavior that’s already well-understood
Spec + AI	Write spec → AI generates code + tests	Faster start, better for exploration	New features, uncertain requirements
Spec + TDD + AI	Write spec → derive tests from the spec → AI implements → run tests	Balances speed and quality	The recommended full flow

TDD tells you “did you implement it correctly”; SDD tells you “what should you implement.” In the AI era, the spec IS the prompt — spec quality directly determines output quality.

Five spec anti-patterns (why your spec doesn’t work)

Anti-pattern	Symptom	Fix
1. Fuzzy boundaries	The spec says “handle all kinds of input,” and the AI invents a different “all kinds” every time	List concrete input types and ranges. “Supports integers 1-1000” is 100x better than “supports numbers.”
2. Missing constraints	The AI’s code runs, but the architecture is a mess (global state, God classes)	Add architectural constraints to Constraints: “use dependency injection,” “each file < 200 lines”
3. Excessive detail	The spec runs 5 pages, and the AI can’t tell what actually matters	One spec, one job. Keep it to 1-2 pages. If it grows past that, split the task.
4. Missing error paths	Only the happy path is written, so the AI never handles exceptions	Edge Cases are mandatory. Cover at least: empty input, network failure, concurrency, insufficient permissions.
5. No validation criteria	The spec says “build an API” but never says “what counts as done”	Spell out success criteria in Outputs: “returns 200 + JSON, response < 100ms”

Three steps when the AI ignores the spec

AI output doesn't match the spec?
│
├── Step 1: check the context
│   ├── Does CLAUDE.md contain rules that conflict with the spec? (cross-layer instruction conflict is the most common cause)
│   ├── Did earlier conversation give contradictory instructions?
│   └── Fix: /clear the context → provide only the spec and necessary files; Claude Code users can run /doctor directly
│
├── Step 2: check spec granularity
│   ├── Does the spec describe multiple features at once?
│   └── Fix: split into multiple atomic specs, one at a time
│
└── Step 3: check model fit
    ├── Simple CRUD → any model works
    ├── Complex architecture → needs a flagship-tier model
    ├── Multi-file refactor → needs a large context window
    └── Fix: if you're stuck, try a different model

Step 4 (easy to overlook) — check where the instruction lives: the same instruction, worded identically, placed in the spec vs. CLAUDE.md vs. a tool description vs. a tool’s return value can go from “not working” to “working” purely because of where it sits.

Rule of thumb: hand the spec to a colleague who doesn’t know the project. Can they understand what you want? If a human can’t understand it, the AI certainly can’t.

The academic foundations of spec-driven development

Three levels of strictness (arXiv 2602.00180, the first academic survey of SDD)

Level	Name	Notes	Industry counterpart
L1	Spec-First	The spec is the starting point of the conversation; the code is a draft	The early-stage pattern of OSS projects like GitHub spec-kit / OpenSpec
L2	Spec-Anchored	Spec and code stay in two-way sync; the spec is the contract	The Planner role in a Three-Agent Harness
L3	Spec-as-Source	The spec is the source of truth; code is a deterministically generated artifact	Fitness Function Hard Gates / Tessl’s one-to-one mapping

Using a detailed spec can reduce AI-generated code error rates by up to 50%.

Tool landscape

Tool	Vendor	Approach	Verdict
Kiro	Amazon / AWS	Requirements → design → tasks (VS Code plugin)	The most mature spec-driven IDE, integrates Agent Hooks + MCP
spec-kit	GitHub	Constitution → spec → plan → tasks (CLI)	84.7K stars, supports 14+ agent platforms
Tessl	Independent (private beta)	Spec-to-code one-to-one mapping	Cleanest mapping, but the least mature

Historical warning: there’s a real risk of repeating the failure mode of Model-Driven Development, compounded by LLM non-determinism. Agents routinely ignore specs or over-interpret them.

Productivity research: the key numbers (contradictory, but all true)

Study	Sample	Setting	Result
GitHub Copilot RCT	Developers	JS HTTP server (greenfield)	55% faster
METR RCT	n=16 senior open-source devs	Mature codebases	19% slower
Anthropic internal	Company-wide	Mixed tasks	+50% (self-reported)
Daniotti & Wachs (2026-05)	30M GitHub commits / 170K developers	Python functions	29% written by AI (academic-grade quantification)
DORA	Industry benchmark	Cross-company	AI is an amplifier: strong teams get stronger, weak teams get weaker
Stack Overflow 2026	Tens of thousands of developers	General	84% adoption but only 3% high trust; 66% spend more time fixing “almost right but not quite” AI code
Anthropic 2026 Trends	—	—	Only 0-20% fully delegated — 80% of tasks still need a harness

Key insight: the 55% speedup (greenfield) and the 19% slowdown (mature codebases) are both true — the difference is task complexity and codebase familiarity. AI isn’t a universal accelerator, it amplifies whatever ability you already have. Stack Overflow 2026’s “adoption-trust paradox” reinforces this judgment: 84% adoption but only 3% high trust, with 66% fixing “almost right but not quite” code — this is the most direct quantitative backing for “why you need a spec to frame the boundaries + a validation loop.”