When AI Miswrites Code, Try a Spec‑Driven Development Workflow

Problems when using AI coding tools

Common issues observed in teams using Codex, Cursor, Claude Code, etc.:

Overly simple prompts give the model insufficient context, leading to hallucination.

Providing too much information without a clear focus or acceptance criteria causes unfocused output.

Generated code may violate team conventions or unintentionally expand the change scope.

Key business terms and background often exist only in the current session and must be re‑explained later.

Spec‑Driven Development (SDD)

SDD follows the long‑standing engineering principle “define rules first, then implement”. The high cost of writing and maintaining specifications historically limited adoption, but rapid AI coding advances in 2024‑2025 make the approach practical again.

GitHub’s Spec Kit formalises the AI workflow as Specify – Plan – Tasks – Implement, shifting human effort to requirement definition, architecture design, constraints and acceptance criteria.

SDD vs. traditional development

Document reader: Human vs. AI + Human.

Document granularity: Readable enough vs. structured for AI parsing.

Acceptance criteria: Relatively vague vs. preferably verifiable and decidable.

Doc‑code relationship: Tends to drift apart vs. spec‑driven implementation keeps them aligned.

Tool selection – OpenSpec

OpenSpec offers a lightweight entry point with minimal intrusion. After installing, initialise a project: openspec init The command creates the following directory layout:

openspec/</code>
<code>├── specs/              # Source of truth (system behaviour)</code>
<code>│   └── <domain>/</code>
<code>│       └── spec.md</code>
<code>├── changes/            # Proposed updates (one folder per change)</code>
<code>│   └── <change-name>/</code>
<code>│       ├── proposal.md</code>
<code>│       ├── design.md</code>
<code>│       ├── tasks.md</code>
<code>│       └── specs/      # Delta specs (what’s changing)</code>
<code>│           └── <domain>/</code>
<code>│               └── spec.md</code>
<code>└── config.yaml         # Optional project configuration

Key files and their purposes: spec.md – defines requirements, boundaries, behaviour, constraints and acceptance criteria; serves as the long‑term AI context. design.md – records concrete technical solutions and implementation design. proposal.md – describes background, goals, impact and rationale. tasks.md – breaks requirements into executable, verifiable tasks.

For Codex users the shortcut /opsx enters the OpenSpec workflow.

Workflow core

The SDD process starts with a spec, not code. The spec is iteratively refined, then AI generates code based on it.

Spec – answers “what to do and what not to do” by stating user scenarios, functional boundaries, edge cases and acceptance criteria.

Design – answers “how to do it” by describing technical solutions, module impact, data flow, interface dependencies and compatibility.

Tasks – answers “which part first and to what extent” by splitting the requirement into small, executable, verifiable units, making each AI iteration focused and easier to review or roll back.

Supporting mechanisms

Skills

Skills encode reusable rule layers, reducing the need to repeat soft constraints via prompts.

Bottom‑level Skill – long‑term habits for the model (e.g., “think before coding”, “make small changes”, “self‑check impact”, “confirm uncertain points”). Applied globally across projects.

Top‑level Skill – project‑specific knowledge such as request‑handling layers, naming conventions, domain terminology and historical pitfalls. Stored per project and evolves with the codebase.

Skills provide context; Specs focus on “what”, while Skills focus on “how”.

AGENTS.md

Many AI coding tools read an AGENTS.md file at session start. It acts as an “entry‑manual” containing project structure, rule priority, protected directories, etc. If the format is unknown, AI can generate the file for verification.

Hooks

Hooks enforce hard constraints at specific lifecycle nodes, preventing the model from “going rogue”. Typical Codex hook points: UserPromptSubmit – after the user prompt is submitted, before the model receives it. PreToolUse – before a tool is invoked; can block high‑risk actions. PostToolUse – after tool execution, before results return to the model. Stop – before session ends; can run checks, tests or code‑review flows.

Example Bash hook that aborts if Chinese characters appear in generated code:

#!/bin/bash

FILE="$1"

# Detect Chinese characters
if grep -nE '[\u4e00-\u9fa5]' "$FILE"; then
  echo ""
  echo "Detected Chinese hard‑coding"
  echo "Please replace with:"
  echo "t('xxx')"
  exit 2
fi

exit 0

Corresponding hook configuration:

{
  "Hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "Hooks": [
          {
            "type": "command",
            "command": "./scripts/check-i18n.sh $CLAUDE_FILE"
          }
        ]
      }
    ]
  }
}

Spec synchronization

When code changes without updating the spec, the spec becomes stale. Keep spec and code aligned by:

Running /opsx:sync + description of change to modify the spec, then applying with /opsx:apply.

If code was edited manually, still run /opsx:sync + description to bring the spec up‑to‑date.

Archiving and knowledge‑base building

After all tasks are verified, execute /opsx:archive. Archiving solidifies the experience into reusable project context.

Artifacts to archive:

Confirmed functional boundaries.

Adopted design decisions and rejected alternatives.

Historical issues discovered during implementation.

Rules worth promoting to the main spec, Skills or AGENTS.

Reusable tests and acceptance methods.

Applicable scenarios

SDD is beneficial for:

New business modules.

Complex feature development.

Multi‑person collaborative projects.

Long‑term maintenance projects.

Large‑scale refactoring.

Rule of thumb: if a requirement is expected to span more than two days, building a spec usually pays off.

Less suitable scenarios include trivial changes, pure style tweaks, one‑off proof‑of‑concepts or temporary scripts where the overhead outweighs benefits.

Practical tips

Generate an initial spec as a workable draft; refine iteratively during verification.

Start by clearly stating user scenarios and goals before diving into technical details.

Advance one minimal closed loop at a time (e.g., add a page capability or fix a config link) to avoid scope creep.

If requirements are unstable, list uncertainties explicitly before implementation.

Split tasks into “commit‑able, verifiable, rollback‑able” units.

After each sub‑task, perform a minimal validation (e.g., page render, request parameters, type checks).

Conclusion

Current AI models are powerful but still rely on human‑defined rules and judgments for quality. Spec‑Driven Development provides a structured, repeatable workflow that reduces AI‑induced errors and lowers long‑term collaboration costs. The approach is supported by tools such as OpenSpec (https://github.com/Fission-AI/OpenSpec) and can be extended as AI capabilities evolve.