Spec-Driven Development Workflow: From Requirements to Code

The fastest fix for uncontrolled AI coding

Symptom: A request starts as a short product sentence, then an AI Coding Agent creates a large patch that is difficult to review, test, or trace back to the original need.

Fastest fix: Use a dual-track Spec-Driven Development Workflow. Keep a specification track for requirements, constraints, and acceptance criteria, then use a code track for small, verifiable implementation tasks. Connect both tracks through version references, task IDs, and test results instead of asking the agent to generate an entire feature in one pass.

This approach is for teams introducing Spec-Driven Development into an existing repository, engineering leads who need multiple people to review AI-generated code, and developers who want remote coding sessions to remain recoverable and auditable.

The key operating rule is simple:

Do not let the agent move directly from an ambiguous request to a complete code change.

The dual-track model

A reliable workflow has two connected but separate tracks.

The specification track answers:

• What problem is being solved?
• Who is affected?
• What behavior is required?
• What is explicitly out of scope?
• Which constraints and risks must be respected?
• How will reviewers decide whether the result is correct?

The code track answers:

• Which repository components must change?
• Which dependencies, interfaces, or data structures are affected?
• What is the smallest implementation task?
• Which command proves that the task works?
• What should happen if the task fails?

The connection between the tracks should be explicit. A feature might use an identifier such as AUTH-014, while its implementation tasks reference the relevant requirement, target files, test command, and pull request. The exact naming convention is yours. The important point is that a reviewer can move from a code diff back to the requirement it claims to satisfy.

GitHub’s current Spec Kit documentation follows a similar lifecycle: specification, clarification, planning, task generation, implementation, and convergence, with optional analysis and checklist gates for higher-risk work. The official repository also documents integrations that install commands or skills for supported coding agents. See the GitHub Spec Kit quickstart for the documented flow.

Experience rule: If a requirement cannot produce a clear pass or fail result, it is not ready to become an implementation task.

This separation solves several problems that appear when teams use an AI Coding Agent without a controlled handoff:

• Scope expansion: The agent fills missing details with assumptions and changes adjacent modules.
• Review overload: A single large patch mixes API changes, refactoring, migration work, and tests.
• Weak failure recovery: When a long session fails, nobody knows which decisions were confirmed and which were invented.
• Specification drift: The code evolves, but the original requirement remains too vague to explain why the behavior exists.
• Permission risk: A remote agent may access secrets, production credentials, or unrelated directories if the execution environment is not isolated.

Requirements review: turn intent into boundaries

The first handoff is not from a product owner to an AI tool. It is from an unclear request to a decision-ready requirement.

Assume a request says: “Add team sharing to the project dashboard.”

That sentence is not enough for planning. You need to resolve at least five areas:

1. Target user: Is sharing available to project owners, all members, administrators, or external guests?
2. Core behavior: Can users invite people, remove access, change roles, or only generate a read-only link?
3. Data impact: Does the feature create memberships, invitations, audit records, or access tokens?
4. Failure behavior: What happens when an invite expires, a user lacks permission, or the project no longer exists?
5. Non-goals: Is billing, public sharing, mobile support, or bulk import excluded from this release?

Record these decisions in a requirement review note before asking for a Specification. Each requirement should have an observable outcome. “The sharing system should be secure” is too broad. “A non-owner cannot change a project member’s role” is testable.

A useful requirement record contains:

• Requirement ID
• User or system actor
• Trigger or starting condition
• Expected result
• Error or exception path
• Explicit non-goals
• Risk and dependency notes
• Open decisions
• Acceptance evidence

The output of this stage is not code and should not be a technical plan. It is a bounded list of behaviors that another person can challenge.

The handoff condition is:

A reviewer can identify the user, behavior, exception path, non-goal, and acceptance condition for every requirement that enters the next stage.

Specification design: create the single source of truth

The Specification converts reviewed intent into a structured contract for implementation. It should describe system behavior without prematurely locking the team into a particular framework or directory layout.

For a dashboard-sharing feature, the Specification might define:

• An owner can invite an existing account by email.
• An invited account receives access only after accepting the invitation.
• A member with read-only access can view project data but cannot modify membership.
• An expired invitation cannot be accepted.
• Removing a member invalidates their future access while preserving required audit history.
• The release does not include public links or external guest accounts.

Each item should retain its requirement ID. This prevents a common failure: the Specification becomes a polished document, but nobody can prove which original decision each section represents.

Separate three kinds of information inside the document:

Business facts

These describe what the product must do. They should not change merely because the team chooses a different framework.

Technical constraints

These describe repository or platform limits, such as an existing authentication provider, database compatibility requirement, API version, or deployment boundary.

Pending decisions

These are unresolved items. Do not hide them inside confident prose. Mark them as open, assign an owner, and block planning when the decision could change the architecture or acceptance tests.

This distinction answers a common source of confusion: a Specification and a technical design are not interchangeable. The Specification defines the required behavior and evidence of success. The technical design defines the components, interfaces, data flow, migrations, and test strategy used to deliver that behavior.

The current Spec Kit flow reflects this separation. Its specify step focuses on requirements and user stories, while plan is where the chosen technology stack and implementation design are introduced. The Spec Kit command reference describes these stages in the context of the repository’s documented workflow.

The Specification is ready for technical planning when:

• Every requirement has an ID.
• Acceptance criteria can be converted into tests or inspection steps.
• Exceptions are described.
• Non-goals are visible.
• Technical assumptions are separated from business behavior.
• Open questions that could alter the design have an owner.
• A reviewer approves the scope.

Repository preparation: map impact before implementation

Before an agent edits code, create a technical plan that identifies the repository impact. This is where the team should resist the temptation to ask the agent to “just start coding.”

The plan should cover:

• Components and files likely to change
• Existing interfaces that must remain compatible
• New dependencies and their approval status
• Database or storage migrations
• Configuration and environment variables
• Authentication and authorization boundaries
• Test layers affected
• Rollback or migration recovery
• Observability requirements
• Documentation and operational changes

This is also the stage for identifying high-risk changes. A new read-only UI component may not need a formal architecture review. A change to authorization middleware, payment state, data migration, or public API behavior usually does.

Use a decision gate:

• If the change affects authorization, persistent data, public contracts, deployment topology, or irreversible migrations, require human approval before task generation.
• If the change stays within an isolated component with existing interfaces and reversible tests, proceed to task breakdown after normal review.

This prevents an AI Coding Agent from treating a repository-wide concern as a local implementation detail.

The technical plan should also state what it does not change. For example, “The existing session model remains unchanged” is valuable because it gives reviewers a boundary to inspect in the diff.

The official Spec Kit reference describes plan as the stage for implementation design, while later task generation creates an actionable, dependency-ordered list. Its documentation also includes optional analysis to detect conflicts and gaps across spec.md, plan.md, and tasks.md. See the Spec Kit reference overview for the relevant artifact relationship.

Task sizing: make agent work reviewable

Task generation is the point where a broad feature becomes a sequence of controlled changes.

Each task should contain five fields:

• Traceability: the requirement or Specification section it satisfies
• Scope: the target files, component, or migration
• Action: the concrete change to make
• Validation: the command, test, or inspection that proves completion
• Exit condition: the state that allows the next task to begin

A weak task says:

Implement project sharing.

A stronger task says:

Add invitation persistence for existing accounts. Update the invitation model, repository interface, and database migration. Do not add email delivery in this task. Run the invitation repository test suite and migration validation. The task is complete when an invitation can be created, queried, expired, and rejected after expiry.

The second version is easier to assign, review, resume, and reject.

Use these sizing conditions:

• If one task changes several unrelated subsystems, split it.
• If a task cannot be validated without completing an entire feature, split it or add an intermediate testable checkpoint.
• If splitting would create a permanently uncompilable repository state, keep the tasks together but define internal checkpoints.
• If the agent needs to make a new product decision during execution, stop and return to the Specification or technical plan.

For long-running remote sessions, checkpoints matter more than raw task count. Save the generated artifacts, current branch, command output, test results, and unresolved questions after each meaningful phase.

Spec Kit’s task documentation describes dependency ordering, file paths, parallel markers, test tasks, and checkpoint validation as useful properties of tasks.md. The Spec Kit repository guidance provides the broader context for structuring implementation work.

Agent execution: controlled changes and recovery

The agent should execute tasks in dependency order, not improvise a new sequence based on whichever file looks easiest to edit.

A controlled execution cycle looks like this:

1. Load the approved Specification and technical plan.
2. Select one task or one explicitly bounded task group.
3. Confirm the target branch and clean working tree.
4. Inspect only the relevant repository context first.
5. Make the smallest change that satisfies the task.
6. Run the declared validation command.
7. Record the diff summary, test result, and unresolved items.
8. Create a checkpoint before moving to the next task.

The execution prompt should prohibit silent scope expansion. If the agent discovers that a task requires a new database migration, public API decision, or permission rule not covered by the artifacts, it should stop and report the conflict.

For failure recovery, restore from the most recent checkpoint that has both a known repository state and a passing validation result. Do not resume from an unverified half-written patch simply because it is newer.

A useful checkpoint contains:

• Commit or branch reference
• Specification version
• Task ID
• Modified file list
• Commands executed
• Test output
• Known failures
• Next permitted action

Spec Kit’s current quickstart documents a converge phase that checks the codebase against the Specification, plan, and tasks, then appends remaining work when gaps are found. This is useful for incomplete implementation, but it should not replace human review of risky behavior. See the Spec Kit quickstart and converge flow for the documented sequence.

Remote execution reminder: A persistent terminal session is not the same as an auditable workflow. You still need isolated credentials, retained logs, a known branch state, and a recovery point that another reviewer can inspect.

Code review: inspect implementation and intent together

A normal code review asks whether the code is readable, tested, secure, and maintainable. A Spec-Driven Development review adds a second question:

Does the implementation satisfy the approved Specification without silently expanding its scope?

The reviewer should inspect four evidence groups.

Requirement coverage

For each requirement ID, identify the implementation path and test evidence. Mark requirements as satisfied, partially satisfied, blocked, or not applicable with an explanation.

Exception coverage

Check denied access, invalid input, expired state, missing records, retries, timeouts, and rollback behavior. AI-generated code often handles the success path while leaving error behavior implicit.

Scope control

Compare the changed files and dependencies with the technical plan. A refactor may be valid, but it should not be hidden inside an unrelated feature patch.

Execution evidence

Require the agent output to include:

• Diff summary
• Files changed
• Commands run
• Test results
• Known warnings
• Unresolved items
• Any deviation from the Specification or plan

If the implementation conflicts with the Specification, do not solve the conflict by editing the document after the fact. Decide whether the requirement changed, the design was wrong, or the implementation must be corrected. Then update the relevant artifact with a review record.

Spec Kit also documents analyze as a read-only cross-artifact consistency check before implementation. That makes it a useful gate for detecting mismatches before a large patch is created. The Spec Kit analysis workflow explains how the check relates to the other artifacts.

Git integration: preserve traceability without replacing existing practice

You do not need to discard your current Git workflow. Add traceability fields to the branch, issue, commit, and pull request process you already use.

A practical mapping is:

• Branch: feature/AUTH-014-project-sharing
• Specification directory: linked to AUTH-014
• Task list: each task references the same requirement IDs
• Commit: includes the task ID
• Pull request: includes the Specification version and test evidence
• Review checklist: confirms behavior, exceptions, scope, and migration safety

Keep specification artifacts versioned with the feature when they explain the implementation. Avoid storing temporary agent chatter that has no decision value. Retain the final decisions, rejected alternatives when important, validation output, and unresolved risks.

For larger initiatives, split the roadmap into bounded slices. GitHub’s Spec Kit documentation describes each sub-feature as an independent feature with its own spec.md, plan.md, and tasks.md, while the roadmap preserves the relationship between slices. The Spec-of-specs guidance covers this organization pattern.

The result is a repository where a reviewer can answer:

• Which requirement caused this change?
• Which task authorized this file edit?
• Which test proves the behavior?
• Which decision changed during implementation?
• Can the change be reverted without losing unrelated work?

Continuous delivery: update the specification after release

The workflow does not end when the pull request merges. Production feedback is new evidence about the behavior described by the Specification.

When a defect appears, first classify it:

• The code violates an existing requirement.
• The Specification omitted an exception.
• The product requirement changed.
• The technical plan failed to account for an operational constraint.

Then update the correct artifact before generating a new implementation task. This prevents the team from repeatedly fixing symptoms while the underlying contract remains incomplete.

Before release, confirm that:

• The approved Specification version is known.
• Every implementation task has a completion state.
• Tests cover the acceptance criteria and important exceptions.
• Migration and rollback steps are documented.
• The pull request contains agent execution evidence.
• Remaining gaps have owners and explicit risk acceptance.

After release, connect incidents and new requests to the affected requirement ID. Over time, this creates a useful record of where the product contract is stable and where it repeatedly needs clarification.

Decision conditions for adopting the workflow

Use the following branch when deciding how much process to introduce:

• If the feature changes authentication, persistent data, public APIs, billing, or deployment behavior, use the full dual-track workflow with clarification, plan review, task review, implementation checkpoints, and convergence.
• If the feature is isolated, reversible, and covered by existing tests, use a shorter path: Specification, plan, tasks, implementation, and review.
• If the request is still ambiguous, do not generate tasks. Return it to requirements review.
• If the agent cannot state a validation command and exit condition, the task is not ready.
• If the remote environment cannot isolate the repository, retain logs, restore snapshots, and restrict credentials, do not use it for unattended implementation.
• If the team cannot assign a reviewer for the Specification and code diff, keep the change smaller or delay agent execution.

This is the procurement decision that matters: you are not buying faster code generation alone. You are choosing whether the surrounding workflow can contain, verify, and recover the generated changes.

FAQ

How do you turn a product request into a Specification?

Start by separating the requested outcome from the implementation idea. Record the user, trigger, expected behavior, data changes, failure cases, constraints, and acceptance conditions. Give each requirement a stable identifier, then mark unresolved decisions explicitly. A Specification is ready for planning only when another reviewer can determine whether the future implementation passes or fails each requirement.

What is the difference between a Specification and a technical design?

A Specification defines externally observable behavior: what the system must do, for whom, under which conditions, and how success is checked. A technical design explains how the repository will deliver that behavior through components, interfaces, dependencies, migrations, and tests. Mixing both too early can make an accidental architecture decision look like a business requirement.

How large should each AI Coding Agent task be?

A task should produce one reviewable change with a clear file scope, dependency position, validation command, and exit condition. If the agent needs several unrelated decisions, multiple subsystem changes, or a long unverified session, split the work. Keep related tasks together only when separating them would make the repository impossible to test or compile.

How can Spec-Driven Development fit an existing Git workflow?

Keep the specification artifacts in version control beside the feature branch or change request. Link the Specification ID to the branch, issue, task list, pull request, and test report. Add review gates before planning and implementation, and require the pull request to show both code evidence and specification coverage. Existing Git practices stay in place; the artifacts add traceability.

Choosing the execution environment

A local workstation is often the best choice for small changes, sensitive repositories, and work that depends on physical devices or private network access. A shared cloud runner can be convenient for repeatable CI tasks, but it may offer limited interactive recovery and less control over long agent sessions.

A remote Mac environment becomes more attractive when your team needs a persistent development machine for Apple-platform builds, isolated repository access, retained execution logs, snapshot-based recovery, or a consistent environment that reviewers can enter without sharing a developer’s laptop. Before adopting one, verify the kvmboot help center and confirm that the environment matches your repository isolation, access-control, and handoff requirements. For regional availability, review the US East Mac checkout option rather than assuming every workflow has the same delivery conditions.

The current approach is not automatically the best long-term option: a local machine may be unavailable during unattended execution, ordinary CI runners may not provide an interactive recovery point, and a shared workstation can make logs, credentials, and branch state difficult to separate. If your team only needs short-lived experiments, local execution remains the sensible choice. If you need temporary remote coding capacity with controlled handoffs, retained logs, snapshot recovery, and safe reviewer access, renting a Mac from kvmboot can provide a cleaner operational boundary than extending an already overloaded developer machine.