Using GitHub Spec-Kit with Claude Code: Specs as Source of Truth

Claude Code is powerful, but let's be honest: it's also maddeningly inconsistent. Ask it to build the same feature twice, and you'll get two completely different implementations. One uses classes, the other uses functions. One has error handling, the other assumes everything will work perfectly. It's exhausting.

GitHub's Spec-Kit solves this problem by flipping the relationship. Instead of code being the source of truth with vague specs somewhere in a doc, specs become the foundation. Code becomes the derivative. Claude Code reads your specs, generates implementations, and when you need changes, you update the spec, not the code.

This isn't about writing tedious requirement documents. It's about creating a system where your AI coding assistant actually builds what you specified, consistently, every single time.

Table of Contents

1. Why Spec-Driven Development Matters for AI Agents
2. What Spec-Kit Actually Is
3. Folder Structure and Setup
4. How Claude Code Reads Your Specs
5. The Iteration Loop in Practice
6. Real Results from Teams Using This Approach

Why Spec-Driven Development Matters for AI Agents

When you're writing code yourself, you hold the entire mental model in your head. You remember why you chose a certain pattern, what edge cases matter, and how pieces fit together. Claude Code doesn't have that context unless you give it explicitly.

Without specs, Claude Code operates on vibes. You say "add user authentication" and it guesses what that means. Sometimes it adds OAuth. Sometimes it adds basic auth. Sometimes it just creates a login form with no backend. All three are valid interpretations of your vague request.

Spec-Kit fixes this by making everything explicit. Your spec says exactly what authentication means: OAuth 2.0, specific providers, token storage strategy, session handling. Claude Code doesn't guess. It reads and implements.

Analogy: Think of it like cooking. Without a recipe (spec), a chef (Claude Code) might make you pasta carbonara with cream, bacon, and garlic. With a proper recipe, they make authentic carbonara with guanciale, pecorino, and egg yolk. Both are pasta dishes, but only one matches what you actually wanted.

What Spec-Kit Actually Is

Spec-Kit is an open-source toolkit from GitHub that helps you organize specifications in a way AI agents can reliably consume. It's not a framework that locks you into specific patterns. It's a folder structure, a set of conventions, and some helper commands.

The core idea: specs live in .speckit/ directory, written in markdown. Each spec describes one component, feature, or system. Claude Code reads these specs when generating or modifying code.

What makes it work:

• Structured markdown format: Specs follow a predictable pattern with sections for purpose, behavior, interfaces, and constraints
• Version control friendly: Specs are plain text files, easy to diff and review
• AI-optimized: Written specifically to be clear for LLM interpretation, not bureaucratic human processes
• Iterative: Updating a spec triggers code regeneration, keeping implementation in sync

Spec-Kit doesn't enforce heavyweight processes. You're not writing UML diagrams or filling out requirement templates. You're writing clear descriptions of what you want built.

Folder Structure and Setup

Here's what a Spec-Kit project looks like:

your-project/
├── .speckit/
│   ├── components/
│   │   ├── auth.md
│   │   └── user-profile.md
│   ├── features/
│   │   ├── dashboard.md
│   │   └── settings.md
│   └── systems/
│       └── api-architecture.md
├── src/
└── tests/

Each spec file contains:

Purpose: What this component does and why it exists

Behavior: Specific actions, inputs, outputs, and state changes

Interfaces: APIs, function signatures, data structures

Constraints: Performance requirements, security rules, error handling

Dependencies: What other specs or external services this relies on

Setup takes about five minutes:

1. Install Spec-Kit: npm install -g @github/spec-kit
2. Initialize in your project: speckit init
3. Create your first spec: speckit new component auth
4. Start Claude Code and reference the spec

That's it. No complex configuration, no build steps, no toolchain integration.

How Claude Code Reads Your Specs

When you ask Claude Code to implement something, you reference the spec directly:

"Implement the authentication component according to .speckit/components/auth.md"

Claude Code reads the spec and uses it as the instruction manual. It doesn't improvise. It follows the structure you defined.

Here's what a basic auth spec looks like:

# Authentication Component

## Purpose
Handle user authentication using OAuth 2.0 with Google and GitHub providers.

## Behavior
- Users click login button, select provider
- Redirect to provider OAuth flow
- Receive callback with authorization code
- Exchange code for access token
- Store token in httpOnly cookie
- Create session with 7-day expiration

## Interfaces
```typescript
interface AuthService {
  login(provider: 'google' | 'github'): Promise<void>
  logout(): Promise<void>
  getCurrentUser(): Promise<User | null>
}

Constraints

• Must use PKCE for security
• Tokens never exposed to client JavaScript
• Failed auth shows user-friendly error, logs details
• Rate limit: 5 login attempts per IP per hour

Claude Code reads this and generates exactly what you described. No surprise dependencies, no architectural decisions you didn't approve, no creative interpretation.

## The Iteration Loop in Practice

The real power shows up when you need changes. Traditional development: you modify code, hope you didn't break anything, write tests, deploy. With Spec-Kit:

1. **Update the spec**: Change the markdown file to reflect new requirements
2. **Regenerate code**: Ask Claude Code to update implementation
3. **Review changes**: See exactly what changed based on spec diff
4. **Commit both**: Spec and code changes go together in version control

This creates a traceable history. Six months later, you can look at your spec history and understand exactly why code evolved the way it did.

Let's say you need to add Microsoft as an OAuth provider. You don't tell Claude Code "add Microsoft login." You update the spec:

```markdown
## Behavior
- Users click login button, select provider (Google, GitHub, or Microsoft)

Then ask Claude Code to sync the implementation. It reads the updated spec and makes the minimal changes needed. No refactoring, no creative improvements, just the change you specified.

Spec-Kit Development Loop

Real Results from Teams Using This Approach

Developers who switched to Spec-Kit report concrete improvements:

One team building a SaaS platform reported that their biggest win wasn't speed. It was predictability. They could look at a spec, estimate effort accurately, and trust that Claude Code would deliver what they specified. No more "well, the AI did something weird" excuses.

Another developer mentioned that specs became their documentation. They stopped maintaining separate docs because the specs were always current, always accurate, and actually enforced by the code generation process.

When Spec-Kit Makes Sense

This approach works best when:

• You're building features with clear requirements
• Multiple people or AI agents work on the same codebase
• You need consistency across similar components
• You want documentation that stays synchronized with code
• You're tired of Claude Code's creative interpretations

It's less useful for:

• Exploratory prototyping where you don't know what you want yet
• One-off scripts where consistency doesn't matter
• Projects where you're the only developer and keep everything in your head

Spec-Kit adds structure. Structure helps when coordination matters. If you're working alone on experimental code, the overhead might not be worth it.

Making It Work for Your Team

Start small. Pick one feature, write a spec, have Claude Code implement it. See if the result matches your expectations better than your usual approach.

Don't try to spec everything at once. Add specs incrementally as you build new features or refactor existing ones. Your codebase will have a mix of spec-driven and traditional code for a while. That's fine.

Treat specs as living documents. Update them when requirements change. The goal isn't to write perfect specs upfront. It's to maintain a clear source of truth that evolves with your project.

Review spec changes in pull requests just like code changes. When someone updates a spec, you're reviewing the intent, not just the implementation. This catches misalignment before code gets written.

Conclusion

Spec-Kit turns Claude Code from an inconsistent assistant into a reliable builder. Your specifications become the authoritative source of truth. Code becomes the generated artifact that implements those specs.

This doesn't mean more bureaucracy or slower development. It means less rework, fewer surprises, and code that actually matches what you asked for. When you need changes, you update the spec and regenerate. The spec history shows you exactly why your system works the way it does.

If you're tired of Claude Code making up its own interpretation of your requests, give Spec-Kit a try. Write clear specs, let the AI handle implementation details, and spend your time on problems that actually matter.