Spec-Driven Development With Cloud Coding Agents

In spec-driven development with cloud coding agents, the versioned specification takes the prompt’s place as the control layer between what the team wants and what the agents build. Replicas runs Claude Code or Codex in isolated cloud VMs, letting teams delegate work without managing the execution infrastructure themselves. The platform supplies the environment, but the spec supplies the durable instructions that keep different agents building the same thing.

Why cloud coding agents fail without a control layer

The central failure is plausible code that quietly solves the wrong problem. Loosely prompting an agent and accepting whatever returns can work for throwaway prototypes, but maintained software exposes the gaps in that approach. An underspecified prompt invites intent drift because the agent fills missing requirements with reasonable defaults. Context decay weakens earlier decisions as the codebase grows, while missing acceptance criteria leave the output unverifiable.

Parallel execution compounds this problem. When several agents work across tasks and harnesses, their small interpretations can diverge into incompatible results. Faster implementation does not resolve that divergence because speed says nothing about whether the agents share the same understanding. Trust requires an anchor that each agent reasons against throughout its run.

What spec-driven development actually is, and what it is not

Spec-driven development makes the specification the primary, versioned artifact and treats code as an output that can be rebuilt or modified when requirements change. A workable spec defines observable behavior, explicit exclusions, interfaces, acceptance criteria, and constraints. Those constraints include performance, security, and project conventions. The spec lives with the code, typically under specs/, and changes first when a bug or feature request changes the intended behavior. This reverses the familiar pattern in which requirements become stale while implementation becomes the only reliable account of the system.

The distinction is not simply that documentation comes earlier. TDD begins with tests, and BDD expresses behavior in business language, whereas spec-driven development defines behavior, architecture, edge cases, and constraints before an agent produces code, tests, and documentation. The spec can be executable when its acceptance criteria are clear enough to turn into tests. A per-feature spec defines a bounded change, while a project-wide constitution establishes architecture conventions, testing rules, security baselines, and framework choices. The feature document has a finite life, but the constitution applies across runs.

The method also permits different levels of commitment. Spec-First governs initial generation but allows code to drift afterward, making it suitable for prototypes and AI-assisted features. Spec-Anchored keeps the specification and code in step as they change, with automated tests checking that they match, and works well for most production systems. Spec-as-Source allows humans to edit only the specification and generates all code from it. That final model demands trusted generation tooling and remains aspirational for most teams.

The five-phase loop that turns a spec into a pull request

GitHub Spec Kit organizes the process into Constitution, Specify, Plan, Tasks, and Implement. Other tools vary in their phase counts and sequences, but the shared pattern separates intent, planning, decomposition, and execution. A human review gate between phases keeps a mistake in one phase from becoming the basis for the next. Constitution establishes the rules loaded into every session. Specify then defines the feature’s user stories, acceptance criteria, non-goals, interfaces, and constraints without making technology choices.

Before planning, clarification can expose ambiguities that would otherwise become implementation decisions. Plan maps the approved specification onto the existing codebase, identifying files, modules, execution order, and risks. This is the point at which architectural errors are cheapest to catch. Tasks then divides that plan into atomic, independently reviewable units small enough to test on their own. Implement executes those units against both the feature spec and the constitution.

The essential discipline is to review the plan before task decomposition and the tasks before implementation. Approving an unread, agent-generated specification merely creates a longer prompt with more room for plausible mistakes. Acceptance criteria must also precede implementation because tests derived from the spec express what the code should do. Tests derived only from the implementation describe what it already does. The resulting pull request is trustworthy only to the extent that the agent can verify its work against those independent expectations.

How the major tools implement this loop differently

Tool choice determines how much of this discipline is enforced and where engineers review the work. GitHub Spec Kit provides a model-agnostic workflow without requiring a particular IDE, using .specify/ for tooling such as scripts and templates. AWS Kiro gives each feature spec three artifacts, namely requirements.md, design.md, and tasks.md, with human review between phases and code. Its autopilot hooks run checks against the spec when events occur, including when files are saved, tests fail, and pull requests are opened. That automation comes with adopting an IDE on AWS’s roadmap.

Cursor takes an IDE-first approach through Plan Mode and Composer 2.5, with project rules under .cursor/rules/. Inline diff review suits rapid feature development, while MCP support permits Spec Kit integration. OpenCode instead offers an open-source, model-agnostic option for teams that want to bring their own models without proprietary workflow tooling. BMAD-METHOD distributes the phases across role-based agents that hand files to one another, allowing teams to customize responsibilities. Claude Code can support spec-driven practices through skills and community plugins, but commands such as /sdd:specify are not native built-in commands.

These are different workflow commitments. IDE integration may matter most to one team, while another needs open tooling or configurable agent roles. The cloud execution platform is a separate choice from those authoring and review tools.

Why a spec-driven team should stay harness-agnostic

A durable specification makes the executing agent replaceable without making the task ambiguous. Practitioner patterns place Claude Code in architecture and debugging work, Cursor in rapid feature development, and Codex in automated workflows and background delegation. Those roles need not become permanent assignments. As models and harnesses improve, the team can choose a different executor and keep the same approved requirements. The constitution and feature spec go with the task instead of being stuck in a tool’s conversation history.

That portability also matters when agents work in parallel. Shared specifications let separate runs base their choices on the same requirements, though each task still needs a clear scope. Among cloud execution options, Replicas supports Claude Code, Codex, Cursor, or Opencode and accepts work from Slack, Linear, or GitHub. This separates the place where work begins from the harness that carries it out. A spec-defined task also supplies the reference needed to attribute output to the specification, harness, and model that produced it.

What the agent environment must provide for specs to hold

The spec says how the code should behave, but it cannot enforce machine boundaries. Agents need to install packages, run services, drive browsers, and execute tests to validate their work. Those activities require a real computer with the codebase, dependencies, tooling, and test infrastructure available. In a shared environment, one run’s side effects can corrupt another’s state.

Each run needs its own sandbox, and it needs the correct version of the constitution and feature spec loaded as context. Reading the latest shared document is not equivalent if that document changes during execution. Separate environments also matter for event-triggered checks because hooks in shared environments can race on state. The sandbox limits what an agent can affect, while the acceptance criteria are the test of whether its changes do what the task calls for. Neither control provides the other’s guarantee.

With Replicas, each agent runs in its own sandboxed VM pre-loaded with the team’s dependencies and tooling. Its analytics account for every minute by source, harness, model, and credential, providing execution detail that can be connected to spec-defined tasks. These tools do more than make runs easier to manage because the work must be checked before it reaches human review. An agent that can run the full test suite has a stronger basis for self-correction than one that leaves validation to the reviewer. Isolation and attribution make that process manageable across concurrent runs.

Where specs connect to the developer tools teams already use

A task can begin in an issue or conversation without making that surface the final authority on implementation. Linear Agent’s Coding Sessions read an issue and its discussion, investigate the codebase, propose an approach, write code, and open a pull request in the cloud. A spec in the repository gives each step a set of requirements to follow beyond what is in the conversation. The issue expresses the request, the spec defines the approved change, and the pull request exposes the result for review.

GitHub’s Agent HQ roadmap similarly places coding agents within GitHub through paid GitHub Copilot subscriptions and extends connections to existing work surfaces. Groundcover’s Agent Mode lets engineers direct agents to recommend code, open pull requests, and manage tasks inside Slack, Linear, and GitHub. Its actions run under the permissions of a specific authorized user. The spec sets the scope of the code changes allowed, while user permissions control who has the right to act. Keeping those roles distinct makes the handoff auditable without treating a requirements document as an access-control system.

What teams that have run this at scale report back

Production accounts show meaningful throughput gains, but they also reveal where the work moves. Ramp’s internal agent system, Ramp Inspect, runs in sandboxed virtual machines, and people took it up without being told they had to. As agents produced more work, code review became more of a bottleneck for its engineers. That account shows the pressure that comes with cloud-agent throughput, but it does not prove that specification alone led to the gains. Once implementation accelerates, reviewer capacity becomes a constraint.

AWS reports faster delivery from teams using Kiro and spec-driven development. Its engineering team completed a substantial rearchitecture with a smaller team than originally planned, while Amazon.com shipped “Add to Delivery” ahead of schedule. The Kiro IDE team also used Kiro to build the IDE itself and shortened feature builds. These outcomes support the method’s practical value, but they do not establish that every task becomes faster. The defensible conclusion is that explicit specifications reduce drift and rework, while the difficulty of changing mature software remains.

Teams should therefore plan for how much work will need review instead of judging success by how much code is generated or how many pull requests are opened. Well-scoped tasks limit large code dumps and help produce reviewable diffs. Useful measures include lead time from first commit to production, change failure rate, review time from PR opening to approval, and median lines changed. Rework includes reverts and code rewritten within three weeks, while security findings per PR and cost per merged PR show other costs of shipping the work. These measures should be attributed to the specific spec, harness, model, and credential responsible for the work.

How to start: applying spec-driven practices to your next agent task

Start with two artifacts, keeping your existing framework in place. Commit a constitution.md that lists the language, frameworks, testing conventions, and security requirements that every run must load. Before the next agent task, write a version-controlled markdown spec covering behavior, exclusions, interfaces, acceptance criteria, and constraints. Write those criteria before asking for a plan. Then review the plan before task decomposition and review the tasks before implementation begins.

Choose tooling that fits how the team already works instead of changing interfaces just for the sake of a change. Spec Kit suits model-agnostic workflows, Kiro suits teams seeking automated enforcement within its IDE, and Claude Code skills suit command-line-first practices. Cursor Plan Mode supports IDE-first work, while OpenCode combines open-source tooling with model choice. For cloud execution, use isolated, pre-configured environments and preserve attribution to the task, harness, model, and credential.

Begin at Spec-First, then move to Spec-Anchored when automated tests enforce alignment in CI. Treat Spec-as-Source as a later target once generation is trusted enough to stop hand-editing code. The durable investment is the specification committed to the repository that keeps present and future agent runs building the same thing as agents, harnesses, and environments change with better options.