
Most AI-assisted coding workflows fail in production for a simple reason. They start with execution.
The agent is asked to "add authentication," "refactor the service," or "build the feature," and it immediately begins writing code. Decisions about scope, architecture, dependencies, and behavior are made implicitly by a probabilistic system. By the time a human reviews the output, the system has already drifted.
Production systems cannot rely on implicit decisions.
This issue introduces spec-driven AI-assisted coding. Not as a productivity shortcut, but as a control mechanism. The specification becomes the execution contract. The agent executes only what the spec allows. The human owns intent, boundaries, and constraints. The model performs bounded work.
Why Prompt-First AI Coding Breaks Down
LLMs are fast, confident, and non-deterministic. That combination is useful, but dangerous.
Without a specification, the model must guess:
- What features are in scope
- What trade-offs are acceptable
- Which libraries to introduce
- How much abstraction is appropriate
- What "done" means
Each guess compounds. The code often works once, but fails under change, review, or extension. These failures are difficult to diagnose because the original decisions were never explicit.
Example
Prompt-first request:
"Add authentication to the API."
Typical agent behavior:
- Adds password reset and email verification flows
- Introduces a new authentication library
- Modifies routing and middleware globally
- Touches files unrelated to the original change
None of these decisions were requested. They emerged from implicit assumptions.
A spec-driven workflow forces these decisions into text before execution.
Specs Are Not Documentation
In this workflow, a spec is not documentation. It is infrastructure.
A spec is a version-controlled execution contract that answers four questions unambiguously:
- Why the work exists
- What is allowed to be built
- What is explicitly forbidden
- How correctness is validated
If a decision is not written in the spec, the agent must not invent it.
Example
Instead of prompting:
"Refactor input validation."
A spec states:
This converts an open-ended instruction into a bounded execution.
What You Are Defining
This issue is not about building an application. It is about defining how AI-assisted coding is controlled.
The workflow relies on a small set of explicit artifacts:
- A specification describing intent, scope, and constraints
- A task list describing executable work units
- Agent rules defining acceptable behavior
- A human verification gate defining completion
Plain text is sufficient when boundaries are explicit.
The Execution Model
The execution model is intentionally simple.
- A specification is written or updated
- The specification is reviewed and approved
- The agent executes a single task
- Output is validated against the specification
- The specification evolves when reality requires it
The agent never plans and executes in the same step.
Planning is read-only. Execution is constrained.
Example
Incorrect flow:
- “Add rate limiting”
- Agent writes code immediately
- Human reviews a large diff and tries to infer intent
Correct flow:
- Define rate limits, scope, and exclusions in the spec
- Execute one task only
- Validate against written constraints
Anatomy of a Production-Grade AI Spec
A usable AI spec has four core sections.
1. Context
Context grounds the work. It explains why the change exists and how ambiguity should be resolved:
This prevents the agent from optimizing for unrelated goals such as abstraction or reuse.
2. Scope
Scope defines what the agent is allowed to build:
Anything not listed is out of scope. This must be treated as a hard boundary.
3. Constraints
Constraints are non-negotiable. They define how work is performed, not just what is built.
A practical structure uses three tiers:
This structure removes ambiguity when the agent encounters edge cases.
4. Tasks
Tasks are the unit of execution.
Each task must be:
- Small
- Isolated
- Verifiable
- Deterministic
Example:
If verification cannot be stated explicitly, the task is not ready.
Separation of Planning and Execution
One of the most important rules in AI-assisted coding:
The agent that plans must not execute.
Planning requires exploration. Execution requires discipline.
Example:
- Session 1: Draft and refine the spec
- Session 2: Execute Task 1 only
- Session 3: Execute Task 2 only
Each execution starts with a clean context. This prevents hidden assumptions from accumulating.
Boundaries as Control Flow
Specifications encode authority.
The agent does not decide when to cross boundaries. The specification does.
Example
If a task requires a schema change:
- The agent must stop
- The agent must ask for approval
- The spec must be updated before execution continues
This prevents silent scope expansion, one of the most common production failure modes.
Modular Specs and Context Control
Large efforts require modular specifications.
Not every task needs full context. Feeding all constraints into every execution increases instruction collision and reduces adherence.
Common patterns:
- A global spec defining rules and constraints
- A task file defining executable units
- A separate agent rule file defining behavior expectations
For example, agent rules can be as simple as:
This keeps behavior predictable across sessions.
Multi-Agent Workflows Without Loss of Control
Multiple agents are effective only when authority is explicit.
A production-aligned pattern assigns narrow roles:
- A builder agent executes tasks
- A reviewer agent checks output against constraints
- A test agent verifies behavior
Each agent reads the same specification. Each agent has a limited role. The specification remains the single source of truth.
This avoids the coordination failures common in uncontrolled agent workflows.
Human-in-the-Loop Execution Gates
Completion must be deterministic.
Before a task is considered complete, a human gate validates:
- Changed files match the task definition
- No excluded areas were modified
- Constraints were respected
- Verification criteria were satisfied
- No implicit features were added
This turns "looks good" into an enforceable standard.
The Role of the Human
The human is not removed. The role changes.
Instead of writing code line by line, the human:
- Defines intent through specifications
- Encodes constraints
- Reviews plans
- Approves boundary crossings
- Evaluates output against deterministic gates
Reliability comes from structure, not speed.
Why This Works in Practice
Spec-driven AI-assisted coding works because it:
- Eliminates implicit decisions
- Constrains probabilistic behavior
- Produces reviewable artifacts
- Makes failures explainable
- Scales across sessions and agents
- Survives model and tooling changes
The model becomes interchangeable. The specification remains stable.
Final Notes
AI coding agents are not engineers. They are execution engines.
Reliable outcomes come from constraining uncertainty, not amplifying it. Specs are the mechanism that makes AI-assisted coding viable beyond demos.
If you want predictable behavior, write the spec first.
Explore the source code at the GitHub repository.
See you in the next issue.
Stay curious.
Join the Newsletter
Subscribe for AI engineering insights, system design strategies, and workflow tips.