Agentic coding with spec-driven development: why your AI agent needs structure before it writes code

Most developers optimize the wrong thing when it comes to AI coding tools. They want faster code generation. So they write longer prompts, add more context and hope the output lands closer to what they need. When it does not, they fix it by hand and try again. The problem is not the model, it is the missing structure around the model.

After 20+ years of backend development, from legacy PHP monoliths to cloud-native Go microservices, the pattern is familiar: an undisciplined process produces unpredictable output. That holds for human developers just as much as for AI agents. This article is about a Claude Code plugin called Superpowers and about how to combine it with a spec-driven workflow to get reliable output from the AI agent that respects your architecture, consistently and repeatably.

The failure mode nobody talks about

Here is what actually happens when you skip structure and go straight to generation: Claude produces working code, the tests pass, the linter is clean. You merge. Three weeks later a domain object imports directly from the infrastructure layer. A payment handler makes database calls it should know nothing about. A module boundary your team worked on for six months has a silent hole in it. No single commit was obviously wrong. The cumulative drift is the problem.

That is the failure mode better prompts do not fix. The AI has no memory of last quarter's architecture decisions. It has no way of knowing that "clean code" means something specific in your codebase: hexagonal architecture, strict domain isolation, no nullable types. It optimizes for the immediate task, not for the long-term system. The fix is not a better prompt, it is a better workflow.

What Superpowers actually is

Superpowers is an open-source Claude Code plugin built by Jesse Vincent and the team at Prime Radiant, available in the official Anthropic plugin marketplace since January 2026. Installing it takes one command:

/plugin install superpowers@claude-plugins-official

After restarting Claude Code you see the session start hook:

<session-start-hook>
You have Superpowers. RIGHT NOW, go read:
@~/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
</session-start-hook>

From that point on Claude has a set of skills: structured markdown files that define how certain tasks are to be approached. These are not suggestions. If a skill exists for what you are doing, Claude has to use it. Skills get loaded into the context window when they become relevant: a TDD skill is injected when implementation starts, a code review skill fires between tasks, a debugging skill activates when an error appears. Each skill carries not just instructions but pre- and post-conditions that have to be met before the agent can move on. The core workflow they enforce is brainstorm → plan → implement, and spec-driven development is what keeps that order stable.

The spec layer: three types, three templates

Not every task is the same. A new feature, a bug investigation and a dependency upgrade are fundamentally different kinds of work with different unknowns, different risks and different definitions of "done". Treating them the same way is a mistake most teams make. The fix is to differentiate at the spec level. A clean setup looks like this:

docs/
└── specs/
    ├── README.md          <- workflow documentation
    ├── _templates/
    │   ├── feature.md
    │   ├── bugfix.md
    │   └── chore.md
    ├── features/
    ├── bugfixes/
    └── chores/

The README.md documents what goes where and how the workflow runs. This file is referenced in CLAUDE.md, which means Claude reads it at the start of every session. The agent knows the structure before it touches anything.

Feature specs

Features are new behaviour. The primary risk is building the wrong thing or building too much. The spec template reflects that:

# Feature: [Name]

## Problem
What is being solved, for whom and why now.

## In Scope
- Concrete list of what this feature delivers

## Out of Scope
- Explicit list of what this feature does NOT deliver

## Architecture Constraints
- Which modules are affected
- Which boundaries must not be crossed
- Performance thresholds
- Security requirements

## Success Criteria
- Measurable outcomes that confirm the feature works

## Open Questions
- Decisions that have to be settled before implementation starts

## Milestones / Tasks
- Broken down once the open questions are resolved

The "Out of Scope" section is not optional. An AI agent will happily drift into adjacent functionality if you do not state explicitly what is not included. Writing it down forces that conversation during brainstorming, before any code exists.

Bugfix specs

Bugs are different. The primary risk is not scope: it is fixing the symptom without understanding the cause, or introducing a regression while fixing the original problem. The template reflects that:

# Bugfix: [Name]

## Problem Description
What is broken, what the observed behaviour is, what the expected behaviour is.

## Root Cause
Known cause or hypothesis that needs to be verified.

## Affected Components
Which modules, services or layers are affected.

## Reproduction Steps
Exact steps to reproduce the problem consistently.

## Fix Approach
How the fix is implemented and why this approach over the alternatives.

## Regression Tests
Which tests have to be added or updated.

## Verification
How to confirm the fix works in the target environment.

The root cause field is the most important one. An agent without a hypothesis will make changes and see whether the symptom goes away. That is not debugging, that is guessing. Requiring a root cause hypothesis before implementation forces real analysis first. That single constraint eliminates a large class of "fixed it, but broke something else" outcomes.

Chore specs

Chores are maintenance work: dependency upgrades, refactoring, CI changes, tooling improvements. The risk is scope creep in the other direction, where "update this library" turns into "and I refactored three modules along the way".

# Chore: [Name]

## Motivation
Why this has to happen now and not later.

## Scope
What exactly is being changed.

## Out of Scope
What is not being changed, even if it looks related.

## Approach
How the work is carried out.

## Definition of Done
Specific, verifiable criteria. Not "feels clean": conditions you can actually check.

The definition of done field is what separates a chore from an open-ended refactoring session. The agent knows when to stop, and more importantly, it knows that stopping is the correct behaviour.

Connecting specs and Superpowers

The spec files do not just sit in docs/specs/, they are the input for the Superpowers workflow. When a new Claude Code session starts, CLAUDE.md tells the agent where specs live, how they are structured and what each type means. The specs/README.md carries the workflow documentation. That context is loaded before any task begins. For a new feature Claude opens _templates/feature.md, works through the questions the template demands and fills in the spec together with you. Nothing moves forward until the spec is complete and the open questions are settled. For a bug report the documented root cause hypothesis is the gate. For a chore the definition of done is fixed from the start.

Once the spec is finished, the agent creates a branch before anything else happens. The branch name derives from the spec type: feature/, bugfix/ or chore/ as a prefix, followed by a normalized version of the spec title. This happens automatically, before the plan exists, so work never starts on the wrong branch. The planning skill then breaks the spec down into tasks of two to five minutes with exact file paths and verification steps, and the finished plan is committed immediately. From there every completed implementation task gets its own commit, with a message that references the task. The result is a git history that reads as a narrative. The review skill checks each task not against general best practices but against this specific spec: does this code do what the feature spec says, does this fix address the documented root cause, does this chore stay inside the defined scope?

TDD enforcement: not a preference, a constraint

The Superpowers TDD skill enforces the red/green/refactor cycle as a hard constraint.

RED: a failing test exists. The agent implements only what the error message demands: the minimal code to make exactly that test pass. Not the clean version, not the extensible version, the minimum. If the agent writes implementation code before a test exists, the skill tells it to delete that code and start over. No exceptions.

GREEN: the test passes, lint is clean and types are valid. All three. The agent cannot declare GREEN until it produces the actual test runner output as evidence. A claim is not enough: the literal output has to be there.

REFACTOR: code gets improved, behaviour stays unchanged. Tests have to stay green throughout.

For backend systems with real business logic this has concrete meaning. A payment calculation that is mostly correct is not correct. A security boundary that is probably enforced is not enforced. TDD enforcement treats correctness as binary, because it is binary in production.

The spec connection makes TDD more precise than usual: tests are written against the acceptance criteria in the spec, not against the implementation. A test that passes but does not verify what the spec demands is a test that checks the wrong thing.

Architecture constraints belong in the spec, not in the prompt

One of the persistent problems with AI-generated code is architecture drift. The agent does not know your module boundaries unless you tell it, and telling it in the prompt means telling it again in the next session.

The architecture constraints section of the feature spec changes that. When constraints are documented in the spec and loaded as part of the workflow, they are active for the entire implementation. The review skill checks against them. The plan respects them. They do not drift, because the spec prevents drift.

For a PHP codebase with a strict separation between domain and infrastructure, the constraints go into the spec:

## Architecture Constraints
- PaymentGateway interface must be used for all external provider calls
- No provider-specific types may be exposed outside the payment module
- Retry logic belongs in the gateway layer, not in the application layer
- All currency values are integers (cents), never floats

Claude reads this before it writes the first test. The review checks for violations after every task.

On legacy modernization work, where architectural intent is often undocumented, writing these constraints down during the brainstorming phase is valuable independently of the AI workflow. It forces you to articulate what you want to protect before you start changing things.

The limits worth knowing

Superpowers is not a universal fix. Environment debugging is outside its scope: platform-specific problems, differences between CI and local environments, infrastructure issues all require leaving the workflow, because the structured approach does not help when the problem is not a coding problem. Bad specs produce bad implementations: the brainstorming phase is where the leverage is, a rushed spec with vague success criteria will produce an implementation that is technically correct relative to the spec but wrong relative to what you actually needed. The workflow makes the problem more organized, it does not make the wrong decision right. Custom architecture rules have to be encoded: specific module boundaries, naming conventions and error handling contracts belong in personal skills under ~/.config/superpowers/skills/ or in the architecture constraints sections of your specs. Superpowers ships a skill-authoring skill that helps with exactly that.

Getting started

Install the plugin:

/plugin install superpowers@claude-plugins-official

Create the spec structure in the repository:

docs/specs/_templates/feature.md
docs/specs/_templates/bugfix.md
docs/specs/_templates/chore.md
docs/specs/README.md

Write the workflow documentation in specs/README.md: which kind of work goes where, what each template requires, what the review process looks like, and reference that file in CLAUDE.md so it gets loaded at the start of every session. Then start a new Claude Code session, describe what is to be built, and the brainstorming skill activates automatically. Claude opens the matching template and works through the questions before a single line of code is written. The full sequence from there is predictable and repeatable:

1. The spec is finished and saved in the right subdirectory
2. A branch is created from the spec name with the correct prefix (feature/, bugfix/, chore/)
3. The plan is written and committed
4. Every implementation task is executed and committed individually

The discipline experienced developers apply naturally. Know your boundaries, write tests first, commit in coherent steps, review against requirements instead of conventions: all of it becomes the agent's default behaviour. Not because you prompted for it, but because the workflow requires it.