Facundo Uferer
A reference for teams bringing AI agents into large, long-lived projects with several people involved.
Why a layered scheme
The problem is not that agents write bad code. They write reasonably well. The problem shows up three months in, when nobody can reconstruct why the system does what it does, and the architectural decisions are buried in chat sessions that no longer exist.
The cause is always the same: one tool ended up covering responsibilities that should have been separate. The tracker holds the specification, the specification holds the task plan, the agent writes its own acceptance criteria, and the result is a system with no auditable source of truth.
This scheme separates four responsibilities and defines coupling rules between them. It is independent of which agent, which model, or which framework you use — those are details of a single layer, the most replaceable one.
Part 1 — The four layers
Layer 1 · Intent
What it is: the contract. What the system must do and why.
Two distinct artifacts:
- Current state — what the system does today. Descriptive and always true.
- Change proposal — the delta you want to introduce. Prescriptive and temporary.
Confusing them is the most common mistake. Mix both into one document and in six months you will not be able to tell what the system does from what somebody once proposed it should do.
Where it lives: in the repository, versioned, reviewed by PR like any code change.
Who owns it: one person. Always. An agent can draft it, but acceptance is human.
Authority: maximum. No other layer can contradict it without an explicit review.
Layer 2 · Coordination
What it is: who does what, in what order, blocked by what.
Minimum content of a work unit: an identifier, a reference to the corresponding contract (not a copy), a human owner, and a status.
Where it lives: outside the repository. Who is working on what changes far faster than the code, and versioning it across branches produces permanent conflicts while adding nothing.
Critical rule: the work unit references the contract, never contains it. If the technical substance migrates into the tracker, you lose the ability to reconstruct the project from the repository.
Layer 3 · Execution
What it is: translating contract into diff.
Artifacts it produces: task plan, diff, session log.
Where it lives: nowhere permanent. It is deliberately disposable.
Design test: if all of this layer’s output were lost tomorrow, no information should be lost with it. If something produced here becomes indispensable to understanding the system, that is a sign it belonged in layer 1 and needs promoting.
Its limit: the agent cannot modify the contract on its own. Faced with an ambiguity, it stops and asks. It does not guess. This is the hardest rule to hold and the one that most defines long-term quality — an agent that guesses right 90% of the time leaves you 10% of architectural decisions made by nobody and documented nowhere.
Layer 4 · Verification
What it is: proof that the diff satisfies the contract.
Artifacts: acceptance tests derived from layer 1’s criteria, unit tests, the automation that runs them, and the gates that block the merge.
Where it lives: in the repository, next to the code.
Authority: veto power. It is the only layer that cannot be talked around.
Critical rule: the acceptance criterion is written before layer 3 starts, and by someone other than the implementer. If whoever implements also defines what counts as success, verification stops verifying.
The four coupling rules
| Rule | Statement | What it prevents |
|---|---|---|
| Directionality | Each layer references upward, never duplicates | Four versions of the truth, none authoritative |
| Judge/executor separation | The criterion is written by a person, beforehand, in layer 1 | A loop closed on itself |
| Asymmetric persistence | Layers 1 and 4 outlive the project; 2 outlives the sprint; 3 the session | Critical knowledge trapped in ephemeral artifacts |
| Aligned granularity | One contract = one unit = one reviewable diff = one evidence set | Review made impossible, traceability lost |
The cycle
Outbound: a delta is proposed → humans agree on it → it becomes a work unit → an agent executes it → the evidence validates it.
Closing: the delta is absorbed into the current state and the proposal is archived. This is the step nearly everyone skips, and it is what stops layer 1 from becoming a graveyard of contradictory proposals.
Return: there are two return paths.
- From verification — if the evidence contradicts the contract, the evidence wins and the contract is corrected. Never the other way around.
- From execution — if the agent finds an ambiguity, it escalates. It does not resolve.
Part 2 — Tools by layer
Tools change fast; layers do not. This section will go stale before the rest of the article, and that is exactly the point: if your process depends on a specific tool, migrating costs you the whole process.
Layer 1 · Intent
Category: versioned specification frameworks.
| Tool | Profile | Notes |
|---|---|---|
| OpenSpec | Brownfield, lightweight | Separates current state from proposals using delta markers (ADDED/MODIFIED/REMOVED). Produces compact, easily reviewable artifacts. Its stores allow specs shared across repos. |
| GitHub Spec Kit | Greenfield, structured | More exhaustive and more verbose — roughly three times the content OpenSpec produces for the same change. Requires Python. |
| BMAD-METHOD | Multi-team, ceremonious | Simulates a full agile team with 12+ specialized agents. Only justified at large scale. |
| Kiro | Full IDE | Integrates all four layers in one environment. Less initial friction, more lock-in. |
| Your own documents | Any | A markdown directory with clear conventions covers 80% of the value. Do not underestimate this option. |
Minimum requirement, tool-independent: a conventions file at the repository root (AGENTS.md or CLAUDE.md) that any agent reads on startup. That is what makes the rest portable.
Layer 2 · Coordination
Category: trackers with agent support.
| Tool | Strength | Limit |
|---|---|---|
| GitHub Issues | Short loops between idea, code, review, and merge; highly programmable via Actions and GraphQL | It is a developer-native coordination layer, not a work system that spans the whole organization |
| Linear | Treats agents as first-class participants: direct assignment, issue context when launching the coding tool, MCP support | Lives outside the repository, with no native access to the code |
| Jira | Administrative model and governance for large organizations | Considerable configuration weight |
The choice criterion is not features but who else has to take part. If it is only developers, Issues is enough. If design, product, or management are involved, a developer-native tracker shuts them out.
Layer 3 · Execution
Category: agent harness.
- CLI: Claude Code, Codex CLI, Gemini CLI, Aider
- IDE: Cursor, Cline, Roo Code, Copilot
- Cloud/async: agents that take an issue and hand back a PR
This is the fastest-churning layer and the one where deep integration is least worth investing in. Pick it for team ergonomics, not benchmarks. The best agents today solve between 60% and 70% of SWE-bench Verified, but that benchmark uses curated issues with explicit acceptance criteria — conditions real tasks almost never have. The number says more about the quality of your layer 1 than about the agent.
Layer 4 · Verification
Category: test frameworks and automation.
| Level | Typical tools | Derives from |
|---|---|---|
| Acceptance | Cucumber, Behave, Playwright, contract testing | Layer 1 criteria |
| Unit | pytest, Vitest, JUnit, Go testing | Layer 3 design |
| Static | linters, type checkers, security analysis | Repo conventions |
| Orchestration | GitHub Actions, GitLab CI, and merge gates | — |
Configuration rule: gates must be blocking, not informational. A check you can merge past in red is not verification, it is decoration.
Part 3 — How the methodologies fit together
No methodology covers all four layers. Each one concentrates on one or two and assumes the rest. Understanding where each one puts its weight is what lets you combine them with neither overlap nor gaps.
Coverage matrix
| Methodology | Layer 1 | Layer 2 | Layer 3 | Layer 4 |
|---|---|---|---|---|
| Vibe coding | — | — | ●●● | — |
| Issue-driven | ○ | ●●● | ●● | ○ |
| SDD (spec-driven) | ●●● | ○ | ●● | ● |
| TDD (test-driven) | — | — | ●● | ●●● |
| BDD / ATDD | ●● | — | ● | ●●● |
| SDD + TDD | ●●● | ○ | ●● | ●●● |
| EDD (evaluation-driven) | ● | — | ● | ●●● |
●●● main focus · ●● strong involvement · ● partial involvement · ○ marginal · — does not cover
Vibe coding
What it is: describing in natural language what you want, letting the agent generate the code, and accepting the result if it “works”, iterating through conversation without reading the code in detail. There is no prior contract and no success criterion fixed in advance: the criterion is the impression of whoever tries it. Andrej Karpathy popularized the term in early 2025 to describe that mode of working where you forget the code even exists.
Where it lives: layer 3, exclusively.
It works well for prototypes, exploration, and throwaway scripts — contexts where the cost of being wrong is zero and the artifact has no future.
Why it fails at scale: all the knowledge stays in the most ephemeral layer. When the session ends, the information is gone. With several people, each one builds a different mental model of the system and nobody can reconcile them.
When to use it anyway: inside a work unit already bounded by a contract. Vibe coding is a valid layer 3 technique; the problem is using it as a methodology.
Issue-driven development
What it is: organizing work around a tracker’s issues. Every change is born as an issue, is discussed, prioritized, and assigned there, and is closed when the associated PR merges. It is the default practice of almost any team using GitHub, GitLab, or Jira, which is why many apply it without naming it.
Where it lives: layer 2, spilling into layer 3.
The issue is the work unit and the agent’s entry point. In its pure form, the agent reads the issue, navigates the code, and hands back a PR.
Strength: zero adoption friction. It does not change how the team works, it just adds an actor.
Structural weakness: with no layer 1, the issue ends up absorbing the specification. It starts as three lines and ends up a design document buried in comments. Six months later you have a tracker with thousands of closed issues and no coherent description of the system.
How to integrate it well: keep the issue thin and pointing at the contract. Issue-driven is an excellent layer 2 and a terrible layer 1.
SDD — Spec-driven development
What it is: writing and approving a specification — what the system must do, at what scope, under what constraints — before generating code, and using that spec as the agent’s direct input instead of a loose prompt. It is the methodology behind the layer 1 tools from Part 2 (OpenSpec, Spec Kit, Kiro): each is a different way of structuring the spec and chaining it to the plan and the tasks.
Where it lives: layer 1, with strong influence over layer 3.
It inverts the traditional relationship: the specification stops being documentation written afterwards and becomes the source that drives generation, checklists, and task decomposition.
Key difference from a traditional PRD: a design document is written for human readers, who interpret ambiguities and fill gaps with organizational context. Agents fill gaps too — but not the way you would want. Without explicit scope, they move fast in the wrong direction.
Its blind spot: SDD alone is weak on layer 4. It produces documents describing expected behavior, but the translation into executable evidence stays implicit. On top of that, proposals are static: in long implementations, contract and code drift apart with nothing catching it.
Three levels of spec authority over code:
- Spec-first — the spec precedes and constrains, the code is still the main deliverable
- Spec-anchored — governance layers and supervision checkpoints are added
- Spec-as-source — the spec is the primary artifact and the code is derived
Most teams should start at level 1.
TDD — Test-driven development
What it is: writing an automated test that fails first, because the functionality does not exist yet, then the minimum code to make it pass, and finally refactoring with the test as a safety net. That cycle — red, green, refactor — repeats in small increments at the unit level. Kent Beck formalized it within Extreme Programming, and it is as much a design technique as a verification one: it forces you to define a component’s interface before implementing it.
Where it lives: layer 4, with strong influence over layer 3.
With agents, there are three variants depending on where the human sits:
| Variant | Who writes the test | Risk |
|---|---|---|
| Human writes the tests | A person | Low — but it is the bottleneck |
| Review checkpoint | Agent writes, human approves before implementing | Medium |
| Everything inside the loop | Agent writes both test and implementation | High |
The third variant’s risk is concrete, not theoretical. Kent Beck documented agents deleting failing tests instead of fixing the underlying implementation. The agent optimizes the criterion you gave it — if the criterion is “keep the suite green” and the agent controls the suite, you have a misaligned incentive.
Its blind spot: TDD says nothing about what to build. It verifies you did well what you decided to do, not that you decided the right thing. A system with 100% coverage can be solving the wrong problem.
BDD / ATDD
What it is: two names for the same idea, with different emphases.
- BDD (Behavior-Driven Development) — an evolution of TDD proposed by Dan North. Instead of unit tests, the system’s expected behavior is described in structured natural-language scenarios (Given-When-Then: given an initial state, when an action occurs, then a result is expected), written jointly by business, development, and testing, and automated with tools like Cucumber or Behave.
- ATDD (Acceptance Test-Driven Development) — the same practice seen from the test side: acceptance criteria are agreed with whoever requests the change and turned into executable tests before implementing.
In practice they are used almost interchangeably. BDD puts the weight on shared language; ATDD, on the acceptance test as a contract.
Where it lives: a bridge between layer 1 and layer 4.
The scenarios work simultaneously as readable specification and as executable test. It is the methodology that naturally connects intent with evidence.
Its specific advantage in this scheme: it resolves the translation SDD leaves implicit. The acceptance criterion stops being interpretable prose and becomes an artifact that runs.
Its risk with agents: when the agent generates the scenarios from a domain description, those scenarios tend to reflect the model’s training distribution rather than your domain’s specific edge cases. AI-generated scenarios need human review focused on completeness, not correctness — the problem is rarely that a scenario is wrong, but that the three that matter are missing.
SDD + TDD — the recommended combination
What it is: not a new methodology but the explicit combination of the two above: SDD to fix the contract and scope before starting, and TDD — with BDD scenarios as the bridge — to turn that contract into failing tests before the agent writes any code. Each one covers the other’s blind spot.
Where it lives: layers 1 and 4 simultaneously, which is exactly what neither covers alone.
The two methodologies operate at different architectural levels, which is why they integrate rather than compete: TDD drives interface design through red-green-refactor cycles at the unit level, while SDD stacks on top to impose architectural constraints.
The concrete flow, layer by layer:
- Layer 1 — the change contract is written: expected behavior, scope, and the acceptance scenarios in Given-When-Then format. A person reviews and approves it.
- Layer 2 — the contract becomes one or more work units with an assigned owner.
- Layer 4 (first step) — the scenarios are translated into executable acceptance tests that fail. This happens before execution, and it is what makes judge/executor separation real rather than declarative.
- Layer 3 — the agent implements the minimum needed to pass the tests, using unit-level TDD for the internal design.
- Layer 4 (closing) — CI runs acceptance and unit tests. The gates block the merge if anything fails.
- Layer 1 (archiving) — the delta is absorbed into the current state.
Why this combination specifically: the spec is the rein; TDD is the mechanism that holds it. Without a spec, TDD verifies the wrong thing well. Without TDD, the spec drifts silently during implementation. Code shipped with neither spec nor test suite looks fine until the third sprint, when behavioral drift accumulates and refactoring turns into archaeology.
The rule that keeps it from collapsing: the step 3 acceptance tests are written by a person, or by an agent different from the one implementing and reviewed by a person. If the same agent does 3 and 4, you are back to the closed loop.
EDD — Evaluation-driven development
What it is: adapting the test-driven cycle to components whose behavior is non-deterministic, such as an LLM or an agent. Instead of binary asserts, you define evals: sets of representative cases with metrics — accuracy, instruction adherence, quality judged by another model or by people — run continuously, before and after each deployment, to catch regressions when the model, the prompt, or the data changes.
Where it lives: layer 4, extended beyond the merge.
Only relevant if what you are building includes AI components. TDD and BDD assume that once software passes its tests it stays reliable — a valid assumption for deterministic systems. LLM-based components evolve with model changes, knowledge updates, and context variations, and exhibit emergent behaviors no static test case anticipates.
What it adds: continuous post-deployment evaluation, with metrics on dimensions asserts do not capture — reasoning coherence, constraint adherence, output quality.
When to bring it in: if your product has an agent inside it, layer 4 needs this component in addition to traditional tests. If you only use agents to build deterministic software, you do not need it.
Adoption guide
Coming from vibe coding: add layer 4 first. Acceptance tests before specs. It is the change with the best effort-to-benefit ratio and the one that makes the problem visible.
Coming from issue-driven: add layer 1 and slim the issues down. Migrate the technical substance from the tracker to the repo.
Already doing SDD: check whether your acceptance criteria are executable or prose. If they are prose, you have a nominal layer 4.
Already doing TDD: add layer 1 for the decisions tests do not capture — scope, architectural constraints, design rationale.
Suggested implementation order: layer 4 → layer 1 → layer 2 → optimize layer 3. Layer 3 is last because it matters least and will change most.
Diagnosis
Four failures, each identifiable by which layer slipped out of place:
| Symptom | Displaced layer | Correction |
|---|---|---|
| Project knowledge lives in the tracker | Substance migrated from 1 to 2 | Move content to the repo, leave references |
| Tests always pass, bugs always ship | Layer 3 writes layer 4 | Separate who writes the criterion |
| The spec says one thing, the system does another | Layer 1 is never archived | Institute the cycle’s closing step |
| PRs get approved without reading | Broken granularity | Reduce the size of the work unit |
Health indicator, in one sentence: if a newcomer can understand what the system does by reading only layers 1 and 4, the scheme is working.