The Missing Link in AI Coding: Why Specs Beat Prompts Every Time

A practical guide to specification-driven development with AI assistance.

Artwork: “The Raft of the Medusa” (1819) by Théodore Géricault.

As developers, we’ve all been there: a stakeholder describes a feature, we nod along thinking we get it, we spend days coding… and then comes the dreaded line — “That’s not quite what I meant.” Sound familiar?

After spending some time experimenting with GitHub’s Spec Kit and Claude Code, I think we’ve found a powerful new way to bridge the gap between ideas and implementation — without slowing down development.

It’s not about replacing the tools we already use; it’s about adding a lightweight methodology that helps us build the right thing the first time.

The Problem I’m Solving

Translating business requirements into working code remains one of the biggest challenges in software development. Small misinterpretations early on can cascade into costly rework and missed deadlines. Whether I’m developing test frameworks, web applications, or integrating C# backends with JavaScript frontends, I consistently see how the gap between what the business envisions and what developers deliver impacts both quality and timelines.

Traditional approaches – lengthy PRDs that never get updated, architecture diagrams that drift from reality, or the infamous “let’s just start coding and figure it out” – all have their limitations. There’s a need for something better.

Enter Spec-Driven Development with AI

Spec-Driven Development (SDD) flips our traditional workflow. Instead of specifications being thowaway documents,they become living, executable artifacts that drive the actual implementation. When combined with AI assistants like Claude Code, this approach can dramatically improve our accuracy and reduce rework.

Here’s the key insight: specifications don’t serve code – code serve specefications.

The Tools: Claude Code and Spec Kit

Note on AI Tool Flexibility: While this article uses Claude Code as the primary example, the Spec Kit methodology works equally well with other AI coding assistants like GitHub Copilot, Cursor, Windsurf, or even ChatGPT. The principles of spec-driven development remain the same regardless of which AI tool you choose – the key is having a structured specification that any AI assistant can interpret and implement.

Claude Code

Think of Claude Code as your AI pair programmer on steroids. Unlike GitHub Copilot’s inline suggestions, Claude Code operates at a project level, understanding context across files and making architectural decisions. It integrates with VS Code and can:

Generate entire features from specifications
Refactor complex code while maintaining business logic
Write comprehensive test suites
Update documentation automatically

Key differentiator: Claude Code excels at understanding nuanced requirements and maintaining consistency across a codebase—crucial for our mixed C#/JS environment.

Spec Kit

GitHub’s Spec Kit is the methodology and toolkit that makes specifications executable. It provides:

Structured templates for specifications, technical plans, and tasks
CLI tools for project initialization
Integration with multiple AI agents (Claude Code, Copilot, etc.)
A four-phase workflow that ensures quality at each step

Key differentiator: Spec Kit isn’t just documentation—it’s an active workflow that generates and validates code against requirements.

The Four-Phase Workflow

Phase 1: Specify (What & Why)

markdown

/specify Create a customer feedback widget that collects ratings 
and comments, integrates with our existing auth system, and 
stores data in our SQL database

This phase focuses purely on business requirements, user journeys, and success criteria. No technical implementation details yet.

Phase 2: Plan (How)

markdown

/plan Use ASP.NET Core API with Entity Framework for backend,
React components for frontend, SignalR for real-time updates,
Azure SQL for persistence

Now we make technical decisions: architecture, frameworks, data models, API contracts. This is where our senior developer expertise shines.

Phase 3: Tasks (Breaking It Down)

markdown

/tasks Generate detailed implementation tasks with acceptance criteria

The system generates numbered, actionable tasks:

TASK-001: Set up database schema and Entity Framework models
TASK-002: Implement feedback submission API endpoint
TASK-003: Create React feedback component
TASK-004: Add SignalR hub for real-time updates

Phase 4: Implement (Execute with TDD)

markdown

/implement TASK-001

Claude Code executes each task following Test-Driven Development:

Writes failing tests
Implements the feature
Ensures tests pass
Refactors if needed

Practical Workflow Example: Building a Test Results Dashboard

Let me walk through a real scenario our team might face:

Initial Setup (One-time per project)

bash

# Install Spec Kit
uvx --from git+https://github.com/github/spec-kit.git specify init test-dashboard --ai claude

# This creates the project structure:
test-dashboard/
├── .claude/           # Claude Code commands
├── .specify/          # Templates and scripts
├── specs/            # Specifications will go here
└── memory/
    └── constitution.md  # Project principles

Step 1: Define Project Constitution

Before any coding, we establish our non-negotiables:

markdown

# constitution.md

## Core Principles
- All APIs must follow our company REST standards
- Use dependency injection for all services  
- Minimum 80% code coverage for business logic
- All database access through Entity Framework Core
- Frontend components must be accessible (WCAG 2.1 AA)

## Technical Standards
- C# backend: .NET 8, nullable reference types enabled
- JavaScript: TypeScript strict mode, ES modules only
- Testing: xUnit for C#, Jest for JavaScript
- No direct SQL queries except for read-only reports

## Architecture Patterns
- Repository pattern for data access
- CQRS for complex business operations
- Feature folders structure, not layer folders

Step 2: Create the Specification

markdown

/specify Build a test results dashboard that aggregates results from 
multiple test frameworks (NUnit, xUnit, Jest), displays trends over time, 
identifies flaky tests, and sends alerts when test pass rates drop below 
thresholds. Must integrate with existing Azure DevOps pipelines.

Claude Code generates a detailed specification including:

User personas (developers, QA engineers, managers)
User journeys
Success criteria
Edge cases
Non-functional requirements

Step 3: Technical Planning

markdown

/plan 
Backend: ASP.NET Core 8 Web API with:
- Hangfire for background test result processing
- EF Core with Azure SQL 
- MediatR for CQRS pattern
- Polly for resilient Azure DevOps API calls

Frontend: React 18 with:
- Recharts for visualizations
- SignalR for real-time updates
- React Query for data fetching
- Tailwind CSS for styling

Testing:
- xUnit with WebApplicationFactory for integration tests
- Jest and React Testing Library for frontend
- Playwright for E2E tests

Step 4: Review and Execute Tasks

The system generates ~15 specific tasks. Here’s how we’d implement one:

markdown

/implement TASK-003
# "Create test result aggregation service"

Claude Code would:

Create ITestResultAggregator interface
Write xUnit tests for aggregation logic
Implement the service with proper DI registration
Add error handling and logging
Update documentation

Best Practices

1. Start Small, Think Big

Don’t try to specify everything upfront. Start with core functionality and iterate:

markdown

Version 1: Basic test result display
Version 2: Add trend analysis
Version 3: Add flaky test detection
Version 4: Add predictive analytics

2. The Constitution is Sacred

Invest time in your constitution.md file. This prevents AI from making inconsistent technical decisions:

markdown

## Never Do This
- Don't use var for implicit typing in C#
- Don't use any type in TypeScript
- Don't skip unit tests for "simple" code
- Don't access database from controllers

3. Specification Quality Determines Output Quality

❌ Bad specification:

markdown

"Build a dashboard for test results"

✅ Good specification:

markdown

"Build a dashboard that displays test results from our CI/CD pipeline,
showing pass/fail rates per test suite, execution time trends over the 
last 30 days, and highlighting tests that failed in the last 3 runs.
Users should be able to filter by project, test type, and date range.
The dashboard should refresh automatically every 5 minutes and send
Slack notifications when pass rate drops below 95%."

4. Use the Clarify Step

Before jumping to technical planning, use /clarify to identify gaps:

markdown

/clarify

Claude Code will ask:
- How should the system handle concurrent test runs?
- What happens when Azure DevOps API is unavailable?
- Should historical data be retained indefinitely?
- Who can configure alert thresholds?

5. Leverage for Cross-Stack Consistency

For our C#/JS stack, create shared specifications:

markdown

/specify Create DTOs that can be used by both C# backend and 
TypeScript frontend with automatic code generation and validation

This ensures contract consistency between backend and frontend.

6. Version Control Your Specs

bash

git add specs/
git commit -m "feat: Add specification for test dashboard v1"

Specifications are code. Review them in PRs, track changes, and maintain history.

Governance and Team Workflows

For New Features

Product Owner creates initial specification with business requirements
Tech Lead reviews and adds technical constraints
Team uses /clarify to identify edge cases
Senior Dev creates technical plan
Developers implement tasks with AI assistance
QA validates against original specification

For Bug Fixes

Create a mini-spec describing the bug and expected behavior
Generate targeted fix plan
Implement with tests
Update main specification if behavior changes

For Technical Debt

Specify the refactoring goals without changing functionality
Plan the approach with minimal risk
Execute with comprehensive test coverage

Integration with Current Workflow

Azure DevOps Integration

yaml

# azure-pipelines.yml
- task: Bash@3
  displayName: 'Validate Specifications'
  inputs:
    targetType: 'inline'
    script: |
      specify validate --spec specs/
      specify check-implementation --coverage 80

GitHub Actions Alternative

yaml

name: Spec Validation
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate Specs
        run: |
          uvx specify validate --spec specs/
          uvx specify check-implementation

Pull Request Template

markdown

## Specification Changes
- [ ] Updated relevant specs in `/specs` folder
- [ ] Ran `/analyze` to verify consistency
- [ ] Updated constitution.md if adding new patterns
- [ ] Technical plan reviewed by senior dev

## Implementation
- [ ] All tasks from spec completed
- [ ] Tests written and passing
- [ ] Documentation updated

Measuring Success

Track these metrics to validate the approach:

Requirements Accuracy: Reduction in “that’s not what I meant” moments
Rework Rate: Less code thrown away after review
Onboarding Time: New developers productive faster
Documentation Freshness: Specs stay current with code
Test Coverage: Automatic test generation improves coverage

When NOT to Use This Approach

Be pragmatic. Skip the full workflow for:

Emergency hotfixes (but document after)
Spike/proof-of-concept work
Simple configuration changes
UI-only cosmetic updates

Getting Started Tomorrow

Ready to try this? Here’s your action plan:

Week 1: Personal Experiment

Install Claude Code and Spec Kit
Try it on a small, isolated feature
Document what works and what doesn’t

Week 2: Pair Programming

Pair with a colleague using the approach
Build something together
Gather feedback

Week 3: Team Pilot

Choose a new feature for team pilot
Run through complete workflow
Retrospective on the process

Week 4: Refine and Scale

Adjust constitution based on learnings
Create team-specific templates
Plan broader rollout

The Bottom Line

Spec Kit with Claude Code isn’t magic—it’s a disciplined approach to ensuring we build what’s actually needed. For our team dealing with complex requirements across multiple tech stacks, this methodology offers:

Clarity: Requirements become unambiguous
Consistency: AI follows our established patterns
Velocity: Less rework means faster delivery
Quality: TDD by default, comprehensive tests
Knowledge Transfer: Specs serve as living documentation

The learning curve is real, but the payoff—building the right thing the first time—makes it worthwhile for any feature taking more than a few days to implement.

Resources and Next Steps

Official Spec Kit: https://github.com/github/spec-kit
Claude Code Setup: Available through Claude.ai or VS Code extension

Remember: this isn’t about replacing developer creativity or decision-making. It’s about augmenting our capabilities and ensuring that when we do create, we’re creating exactly what’s needed.

Let’s build with clarity, not chaos.

Vasyl’s Dev Notes