Why AI Needs Better Requirements Than Humans

The previous article made the case that detailed requirements matter more than ever when working with AI agents. This article takes the next step: how to turn those requirements into specs that agents can execute precisely, and how to build a workflow where specs are the central artefact.

Spec-driven development is not new. What is new is that AI agents make it essential rather than optional. With human developers, a rough spec and a conversation could produce good results. With AI agents, the spec IS the conversation. There is nothing else.

The spec is the single source of truth for the agent. Everything the agent does traces back to what the spec says. Everything the spec omits, the agent guesses.

What a Spec Contains

A spec for AI-assisted development is more detailed than a typical technical design document. It must contain everything the agent needs to make correct decisions without human intervention. At minimum:

1. Functional Requirements

What the system should do. Written as specific, testable statements. Not "the user should be able to log in" but "the login endpoint accepts email and password, validates against the user store, returns a JWT with a 24-hour expiry on success, and returns a 401 with error code AUTH_INVALID_CREDENTIALS on failure."

2. Technical Constraints

The boundaries the agent must operate within. Language, framework, architecture patterns, naming conventions, file structure, dependency rules. If the project uses Express.js, not NestJS, the spec says so. If exports go at the bottom of the file, the spec says so. If there is a specific error handling pattern, the spec includes an example.

3. File Structure

Where the code should go. Which files to create, which files to modify, which directories to use. The agent should not have to guess where a new service lives or what to name a test file. The spec maps the implementation to the codebase.

4. Testing Requirements

What tests to write and what they should cover. Unit tests for which functions. Integration tests for which flows. Expected test patterns (describe/it blocks, mock patterns, assertion style). Minimum coverage expectations.

5. Acceptance Criteria

The conditions that must be true when the work is complete. These are not vague bullet points. They are specific, verifiable statements that a review agent can check mechanically:

  • All existing tests pass.
  • New tests cover the happy path and all documented error paths.
  • No lint errors.
  • Type checking passes.
  • The implementation follows the project's coding conventions.
  • The PR description includes a summary of changes and testing instructions.

6. Persona Context

Who this feature is for and how they will use it. Personas give the agent the judgment context that humans get from experience. Without persona context, the agent makes generic decisions. With it, the agent makes decisions appropriate for the actual user.

The Planner Agent Workflow

Writing detailed specs is time-consuming if you do it manually. This is where the planner agent comes in. The planner is a dedicated agent (or skill) whose only job is to read requirements and produce specs. It does not write code. It does not run tests. It plans.

The separation of concerns is critical:

  • The planner reads requirements and writes specs. It understands the project architecture, the coding conventions, the file structure, and the ticket format. It produces a spec that is ready for execution.
  • You review the spec. This is the human checkpoint. You verify that the planner understood the requirements correctly, that the technical approach is sound, and that no edge cases were missed.
  • The builder agent executes from the spec. The builder reads the spec and implements exactly what it says. It does not interpret vague requirements. It does not make architecture decisions. It follows the spec.

This separation prevents a common failure mode: the same agent interpreting vague requirements AND implementing them. When one agent does both, mistakes in interpretation become mistakes in implementation, and they are much harder to catch.

The planner agent's output is the spec. The builder agent's input is the spec. Your job is the review in between.

The GitHub Spec Format

For teams that use GitHub (or similar platforms) for project management, the spec can live directly in the issue or ticket. Here is a format that works well for AI-assisted development:

Title

A concise, descriptive title that includes the domain and action. Not "Fix login" but "Auth: Handle expired JWT refresh with graceful session extension."

Description

The context paragraph. Why this work matters, what problem it solves, and what the expected outcome is. This is for human reviewers, not the agent — but it helps the agent understand priority and intent.

Acceptance Criteria

A numbered list of specific, testable conditions. Each criterion should be verifiable without subjective judgment. "The code is clean" is not an acceptance criterion. "All functions have JSDoc comments with parameter descriptions" is.

Technical Approach

The implementation plan. Which files to create or modify. Which patterns to follow. Which existing code to reference. Which dependencies to use (or avoid). This section is the agent's roadmap.

Testing Requirements

What tests to write, what patterns to follow, what coverage to achieve. Include example test structures if the project has an established pattern.

The Full Flow

When you put requirements, specs, agents, and hooks together, you get a complete development workflow:

1. Requirements are airtight.

Detailed functional requirements with happy paths, error paths, personas, edge cases, and validation rules. No ambiguity. No gaps for the agent to fill with guesses.

2. The spec is agent-ready.

The planner agent (or a human) translates requirements into a spec with functional requirements, technical constraints, file structure, testing requirements, acceptance criteria, and persona context. You review and approve.

3. The builder agent executes.

The builder reads the spec and implements. It writes code, writes tests, creates the PR. It follows the spec precisely because the spec is precise.

4. Hooks enforce the quality gate.

PostTask hooks run automated checks. A review agent (different from the builder) validates the implementation against the acceptance criteria. PostToolUse hooks gate destructive actions. The work does not move forward until quality checks pass.

5. Learnings compound.

PostApproval hooks capture what was learned: configuration quirks, API behaviour, architecture decisions, pitfalls encountered. This knowledge feeds back into the system. The next spec is better informed. The next build is more accurate.

Requirements airtight. Spec agent-ready. Build agent executes. Hooks quality gate. Learnings compound. This is the full cycle.

Why This Matters

The relationship between spec quality and output quality is not linear — it is exponential.

  • Vague spec = vague result. The agent fills gaps with assumptions. Some assumptions are wrong. You spend time debugging, correcting, and re-running. Net time saved: minimal.
  • Decent spec = decent result. The agent gets the main flow right but misses edge cases. You catch issues in review. Net time saved: moderate.
  • Airtight spec = precise result. The agent builds exactly what was specified. Tests pass. Edge cases are covered. The PR is ready for merge with minimal review. Net time saved: significant.

The shift happens at Levels 4 and 5 of AI-assisted development. At Level 4, you start writing specs intentionally. At Level 5, you have a planner agent that produces specs from requirements, hooks that enforce quality, and a learning loop that makes every cycle better.

Below Level 4, most developers are prompting ad hoc — writing a description of what they want and hoping the agent figures it out. This works for simple tasks but breaks down for anything with complexity, edge cases, or multi-file changes.

The Rule

The order is non-negotiable:

Requirements first. Spec second. Build third.

Skip the requirements, and the spec is incomplete. Skip the spec, and the build is unpredictable. Follow the order, and you get a system where AI agents produce reliable, high-quality output consistently.

This is not about adding process for the sake of process. It is about recognising that AI agents are extremely capable executors but poor interpreters. They will build exactly what you tell them to build. The question is whether what you told them is what you actually wanted.

Write it down. Make it specific. Let the agent execute. That is spec-driven development.