Blog Post
Requirements Driven Development for Coding Agents
- requirements-driven-development
- ai
- software-engineering
- testing

Requirements Driven Development (RDD) is a workflow I’m building for coding agents. You maintain the required behavior and constraints; agents derive the design, implementation plan, code, and verification from that baseline. The reference implementation, rdd-harness, organizes this work into specification, preparation, and implementation, with acceptance evidence tied to the code being checked.
The goal is to make a long implementation run easier to direct and inspect. Requirements describe what success means, contracts give parallel implementors stable boundaries, and the controller checks whether the evidence supports accepting each increment.
Motivation
Consider a Todo application that reports a task as saved before its database transaction commits. The interface appears responsive, the new row is visible, and a test checking that row passes. If the write subsequently fails, the application has acknowledged something it never preserved.
A specification containing “optimistic updates” and “reliable persistence” has not necessarily settled this behavior. An interface agent might assume immediate success, a storage agent might return before commit, and a test agent might verify only the visible result. Their implementations can agree with one another while missing the owner’s durability requirement.
The same ambiguity appears when the starting point is an outcome such as “build a useful personal Todo application.” That is useful input for exploration, but it leaves important choices open. Browser storage, a cloud account, and memory-only state could each support a plausible interpretation. Before implementation, those choices need explicit acceptance conditions.
Spec driven development already provides a more durable basis for work than isolated prompts. GitHub Spec Kit separates what and why from implementation planning, while Kiro separates requirements, design, and tasks. RDD builds on that separation by making the authority chain and acceptance gates explicit.
I want agents to have room to solve the engineering problem without inventing the product’s meaning of success. Once that meaning is agreed, a generated design document, task list, or implementation should preserve it. If the requirement changes, the workflow should expose the effect on the solution and its evidence.
Requirements as the source of truth
Requirements define the behavior and constraints. Specifications describe the selected solution. Contracts, plans, tests, code, and validation reports connect that solution to an acceptance decision. Stable identifiers, shared definitions, and observable outcomes make those connections inspectable; Markdown is sufficient when it expresses them precisely.
The supplied example is a desktop Todo application using Rust, Tauri 2, and a persistent local embedded Turso database. These are owner-selected constraints. Domain boundaries, database structure, frontend framework, and API operations are resolved during specification. The current requirements baseline targets macOS 26.x on Apple silicon with at least 32 GB RAM, including qualifying macOS VMs. That application scope is separate from the platforms on which the harness tooling can run.
For instance, FR-016 requires mutations and restores to commit to persistent storage before the application acknowledges success. Its acceptance conditions include pausing a commit and checking that the UI reports a pending operation. The design can use an actor, a serialized command executor, or another suitable mechanism, provided it preserves that observable behavior.
The search, filter, and ordering requirement adds a different kind of obligation: p95 latency within 250 milliseconds under a defined workload and measurement protocol. An evaluator must assess the recorded samples for each required operation class. A pooled result could conceal a slow operation, so the protocol matters as much as the threshold. These are proposed product targets, not measured performance claims.
Together, these examples show why functional behavior and quality constraints belong in the same design discussion. A persistence decision affects error handling and responsiveness; a latency target affects data access and UI scheduling. The resulting tests need to demonstrate both the behavior and the relevant limits.
The baseline also distinguishes offline availability from zero outbound traffic. An application can work offline and still send telemetry when connectivity returns. Giving those obligations separate acceptance conditions prevents a general promise of local operation from hiding a different privacy decision.
A useful trace follows a requirement through its solution, scenario, implementation task, and result on a particular revision. If a later artifact contradicts the requirement, the disagreement needs resolution before acceptance. Human review remains essential: precise requirements can still describe the wrong product.
Architecture and technical overview
The harness combines agents that research, design, implement, and review with a repository-local Python controller. Agents author the solution and assess its meaning. The controller validates declared structure, ownership, source identities, evidence, and state transitions. Independent review checks whether the declared relationships reflect the actual engineering problem.
The three workflows and their accepted outputs, adapted from the harness’s conceptual architecture diagram.
View the architecture diagram at full size
| Workflow | Input | Accepted output |
|---|---|---|
| Specification | Requirements and resolved product decisions | Frozen solution, contracts, scenario definitions, and qualified execution prerequisites |
| Preparation | Committed, frozen solution | Implementation plan and materialized baseline accepted by gate preparation |
| Implementation | Accepted preparation baseline | Sealed phase PRs and application evidence accepted by gate project |
The Architecture and artifact responsibilities guide maps the workflow to repository files, while the workflow guide defines the operational gates.
Specification workflow
Specification turns the requirements into a solution that can be implemented and verified. It starts with unresolved behavior, domain ownership, failure cases, and feasibility questions. For the Todo example, this includes qualifying the native runtime, frontend, embedded database, generated boundaries, and packaging in the required environment.
The coordinator brings consequential choices back to the owner through specification refinement. Accepted decisions are recorded durably and published by the specialist responsible for the affected artifact. This gives later agents a canonical decision to follow without requiring them to reconstruct it from a conversation. Routine coding choices remain with the implementor.
Modules are organized around coherent capabilities and the invariants they own. A user journey can cross several modules, and several requirements can belong to one module. The specification identifies the owner of each operation, its consumers, and the behavior of the boundary between them.
Scenario definitions make those decisions testable. They cover the main user journeys alongside invalid inputs, storage failures, interruption, recovery, accessibility, and performance. Each scenario needs an observable result. Benchmark protocols also define the workload, samples, and evaluator that will establish whether a threshold is met.
For example, a restart scenario can show that committed data is loaded again, but it does not establish what happens when a write is interrupted. Recording the expected outcome for each case gives the test author an independent answer to check. The production implementation cannot supply its own answer key or weaken a threshold when it fails.
These definitions precede executable application tests. Disposable providers and consumers can qualify a proposed contract during specification, but the real application still needs implementation evidence. Two independent final perspectives review the candidate: one assesses whether the solution satisfies the requirements, and the other assesses whether its execution design is viable. The accepted solution and contracts are then frozen.
Contracts for parallel implementation
Protobuf defines the data and operations exposed across module boundaries. An illustrative task command could begin with:
syntax = "proto3";
package example.tasks.v1;
message CompleteTaskRequest {
string task_id = 1;
}
message CompleteTaskResponse {
string task_id = 1;
}
service TaskCommands {
rpc CompleteTask(CompleteTaskRequest)
returns (CompleteTaskResponse);
}
This reduced example leaves response details and error semantics for the actual specification. The harness’s Rust generator produces message types and local unary service traits, giving providers a compiler-checked surface without requiring a gRPC server or separate processes.
Generated boundaries support parallel implementation; separate checks establish their use and behavior.
View the contract diagram at full size
Compilation establishes that the method surface matches. Architecture checks assess whether callers use the approved boundary, and behavioral tests assess what the operation actually does. Private domain types can still enforce internal invariants, with adapters translating boundary messages where necessary. Those mappings serve a different purpose from duplicate business rules.
Frozen contracts let implementors work from stable assumptions. A missing operation or insufficient response requires a specification amendment, including an otherwise compatible additive change once that run’s contract baseline is frozen.
Preparation workflow
Preparation turns the solution into tasks with exact file changes, dependencies, and acceptance conditions. For a search feature, the work might connect a latency assertion, query implementation, application command, and visible result. The plan identifies who produces each prerequisite and when its consumers need it.
Those ordered paths through the dependency graph are task verticals. Shared prerequisites retain one task identity. Phases group the work so that each accepted outcome is complete: a phase promising responsive search must include its required data path and measurement, rather than defer them to unspecified hardening work.
The graph validator checks declared dependencies; the reviewer checks whether those declarations match the design. Later phases can extend previously touched files while preserving their accepted guarantees. Sealing a phase fixes its acceptance decision, not every file forever. If that decision turns out to have been wrong, the correction follows the amendment process described below.
The implementation matrix connects requirements and solution elements to scenarios, checks, tasks, and phases. It is a generated view of the canonical plan. A reuse analysis also records where existing owners can be extended and why a new capability is necessary when an addition is proposed.
Preparation places task packets beside their intended work sites. A marker uses the phase, category, verticals, task, and site:
// RDD:P01:tests:V01+V03:T001:A01
Commentable source files can receive comment-only shells. Noncommentable files and deletion targets use adjacent sidecars; absent JSON, binary, and lock files remain absent. The controller verifies the packets against the plan and removes them as tasks complete. Deleting a comment cannot complete the canonical task.
Materialization is only part of preparation. The baseline must be committed and pushed, preparation CI explicitly dispatched, and the actual evidence imported. Readiness checks and independent semantic and execution reviews precede ./rdd gate preparation. A push alone does not run that CI, and a materialized baseline remains preparing until the gate accepts it as prepared.
Implementation workflow
Implementation begins at the accepted preparation commit and proceeds one phase at a time. Within each phase, tasks follow this order:
- Tests: implement the approved assertions and demonstrate behavioral failure.
- Deletion: remove obsolete code within the planned scope.
- Modification: extend existing implementations.
- Addition: introduce capabilities justified by the reuse analysis.
- Documentation: explain the resulting behavior and verified usage.
This order makes additions deliberate, but it also constrains planning. An adapter migration may need a replacement before consumers can switch and the old adapter can be removed. Those dependencies span separate phases, each with a useful intermediate outcome.
Phase boundaries accommodate real dependencies, including migrations that need addition before deletion.
View the phase diagram at full size
For FR-016, an executable scenario follows the behavior already agreed during specification:
Given a valid task submission and a deliberately paused commit
When the user saves the task
Then the UI reports a pending operation
And it does not report the task as successfully saved
When the commit succeeds
Then success is acknowledged and the committed result is visible
A useful RED result means that an assertion executed and exposed missing behavior. An unresolved import or unavailable database does not establish that result. Minimal scaffolding may make the assertion executable, but it cannot contain the production behavior disguised as test setup. Rejection and uncertain outcomes need their own approved scenarios.
The coordinator assigns bounded work to implementors in separate Git worktrees. Each assignment carries a lease defining its permitted writes, and integration checks the submitted changes against that scope. A separate reviewer follows progress continuously; formal acceptance occurs at phase completion, without adding a review gate to every task. The runtime configuration defines the specialist roles and current model choices.
Evidence and completion
A long run needs completion conditions that remain clear after an interruption. The controller binds check results to the source revision, frozen inputs, execution environment, and raw logs. Changing the candidate invalidates affected evidence, so a previous pass cannot silently accept new code.
For the latency requirement, a successful command exit is only the beginning. The harness evaluates recorded samples, sample counts, units, statistics, and thresholds against the frozen benchmark definition. Review checks whether the workload represents the required operation. Required native, manual, and reference-machine observations remain pending until they are actually available.
This matters for the desktop example: a browser test can assess part of the interface, but it cannot establish the behavior of the packaged Tauri application. Likewise, mock storage cannot prove database durability. The accepted platform and workload determine which evidence is relevant, even when the harness’s own tests pass elsewhere.
At phase completion, cumulative checks and independent review assess the committed candidate before its PR is published, verified, and sealed. Each later PR targets the preceding sealed phase branch. The result is a ready stack of open, non-draft PRs representing accepted increments. Merging and releasing remain separate developer actions.
The final decision is exposed through:
./rdd gate project
Acceptance requires status=passed and application_complete=true: completed canonical tasks, no outstanding task packets, sealed phases, a verified PR stack, resolved findings, and all required cumulative evidence. Every required golden scenario must explicitly execute and pass. An aggregate green result cannot cover missing, filtered, skipped, or duplicate scenarios; the evidence guide defines that accounting.
The gate writes readable and machine-readable validation reports plus a completed-run checkpoint under .rdd/evidence/. Together they connect the accepted requirements to the code and observations used to accept them.
These records also make a blocked run inspectable. A missing native observation is a specific unmet obligation, rather than a vague claim that testing remains. Preserve the reports and raw evidence with the relevant source and worktrees; the checkpoint does not replace the implementation it describes.
Changing and improving the process
Amendment and regeneration
An amendment traces a changed requirement through the affected solution, contracts, consumers, tests, and documentation. Valid unaffected work can remain, while affected evidence is regenerated. A small text edit may have a large implementation impact, so the requirements diff alone cannot establish the scope.
Regeneration derives a fresh solution and plan from the current requirements, retaining earlier baseline history. Replacing existing implementation is explicit planned work; user data, migration obligations, and external consumers still need consideration.
A frozen specification or sealed phase can also prove defective even when the requirements were correct. That is a failure of the earlier acceptance process. The harness records the failure and requires a preventive repair with a reproducing regression before a fresh trial. The amendment route preserves accepted history instead of changing the requirement to excuse the defect.
Interruptions have a separate recovery path. Native session recovery and controller reconciliation restore different parts of the run. An unavailable environment can be resolved before continuation, but resume cannot reset an exhausted execution budget. The recovery procedure explains what to preserve and when a new reviewed baseline is needed.
Keeping context useful
The workflow can create its own documentation problem if every artifact repeats the project. Stable IDs and links let a task packet include the relevant requirements, solution sections, allowed paths, and verification instructions without reproducing every decision. Repository skills provide specialized guidance when needed, keeping the goal focused.
The same principle applies to code. New modules and dependencies need a requirement-backed purpose. Review looks for duplicated rules and unnecessary layers while preserving useful domain types and boundary adapters. Fewer lines alone do not establish a better design.
These controls also have limits. Worktrees separate Git state, not processes running as the same operating-system user. Hashes establish identity and freshness, not the truth of an observation. Independent verification and repository protections remain part of the trust model.
Running the reference harness
Start with your own repository or fork and a writable GitHub remote. Python 3.11+ and Git support initialization; full workflows also need authenticated Codex, GitHub CLI, Rustup, Buf, and the required native tools. The README maintains the setup details.
From a fresh clone, create the dedicated baseline branch and inspect the environment:
git switch -c codex/todo-baseline origin/main
./rdd init
./rdd status
./rdd doctor --full
main is merge-only. Setup does not begin development, and source-writing workflows reject main. Once the baseline is clean, launch specification:
./rdd workflow specification --mode regenerate
Complete its decisions, qualification, and independent reviews, then commit the frozen outputs before launching preparation:
./rdd workflow preparation
Follow the preparation journey through materialization, baseline publication, dispatched CI, evidence import, reviews, and its acceptance gate. Only after it reports prepared should implementation begin:
./rdd goal
./rdd workflow implementation
In the interactive session, activate native /goal with the exact printed objective. Launching the session alone does not activate Goal. Detailed policy lives in versioned files and skills, allowing the objective to stay short. Treat these commands as stage entry points; the linked workflow guide supplies their acceptance and recovery procedures.
For later requirement changes, commit the authorized edit and begin specification with --mode amend. After project acceptance, preserve the phase stack and use the separate release procedure for a PR into main.
Current status and next steps
This overview reflects harness commit 4824d81, reviewed on October 29, 2026. The repository includes the controller, workflow skills, role configuration, schemas, Rust contract generator, CI integration, and regression tests. The Todo application has not yet been implemented or accepted through a complete run.
The repository’s runtime observations record Rust/Buf native and WASM qualification proofs and native Codex launch/resume smoke. They also record hosted CI observations with both passing and failing jobs. These are bounded observations, not complete application validation: the native smoke did not activate Goal or execute an application workflow, and it does not establish backend-model identity or child-process isolation.
I also plan to add a retrospective skill inspired by Matt Pocock’s retro. It would review run evidence, recurring blockers, and review findings to suggest better checks, clearer navigation, and simpler instructions for future runs. Changes to requirements or contracts would still follow the amendment workflow. The existing specification-refinement skill already credits Pocock’s work; this retrospective is planned, not a fourth implemented workflow.
The next useful evaluation is independently verified completion on the same requirements baseline. I would compare defects after acceptance, failed acceptance decisions, attempts to weaken checks, duplicate implementations, human interventions, elapsed time, and model cost. That would show where the extra planning pays for itself and where the process should be simpler.
If you try the harness, I’d be interested in the requirement, boundary, or acceptance decision that gives it trouble. A reproducible failure on a small baseline is useful evidence for improving the workflow.