Getting started with Github Spec Kit

Software development with AI assistants often feels like a game of telephone—you describe what you want, the AI generates something that looks right, and then you spend hours fixing the gaps between intention and implementation. GitHub’s Spec Kit paired with Claude Code changes this dynamic entirely. This post walks you through setting up Spec Kit and experiencing specification-driven development firsthand.

What is Spec Kit

Spec Kit is an open-source toolkit from GitHub that structures how you communicate with AI coding assistants. Instead of vague prompts that produce inconsistent results, you create specifications that serve as the source of truth for code generation. Think of it as turning your requirements into executable documentation—the AI doesn’t guess what you want; it implements exactly what you’ve specified.

For .NET developers, this is particularly powerful. You can specify architectural patterns, coding standards, and technical constraints once, then have the AI consistently apply them across your entire codebase.

Installation and Setup

To take advantage of Spec Kit you need an AI client that can run in agent mode. I the example below we use Claude Code as the agent

1. Install Claude Code

# Windows (PowerShell as Administrator)
Invoke-WebRequest -Uri https://github.com/anthropics/claude-code/releases/latest/download/claude-code-windows-x64.exe -OutFile claude-code.exe
# Add to PATH or move to a directory in PATH

# macOS/Linux
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-$(uname -s)-$(uname -m) -o claude-code
chmod +x claude-code
sudo mv claude-code /usr/local/bin/

# Verify installation
claude-code --version

2. Install UV (packagemanager from python)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Initialize Spec Kit

# Install with Python's uv (recommended)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Or use pipx
pipx install git+https://github.com/github/spec-kit.git

# Restart your terminal / console so the path / environment vars are picked up.

# Verify installation
specify --version

Time to create your first project

When you initialize a Spec Kit project, you’re creating a structured conversation framework between you and the AI:

mkdir CustomerPortal
cd CustomerPortal
specify init . --ai claude

This creates a .specify directory—think of it as your project’s DNA, containing everything the AI needs to understand your vision. the --ai claude defines that you use the claude code agent to run the command. In this case we use the claude agent. This will create a .claude folder containing all the files we need to start using Spec Kit with our agent

Understanding the Spec Kit Workflow

The power of Spec Kit lies in its structured approach. Instead of throwing requirements at an AI and hoping for the best, you build up context layer by layer, each one informing the next.

1. Constitution: Your Project’s DNA

The constitution is where you establish the unchangeable laws of your project. These aren’t suggestions—they’re requirements that every line of generated code must follow. Think of it as encoding your senior architect’s wisdom into the project from day one.

When you run /speckit.constitution in Claude Code, you’re not just listing preferences. You’re establishing architectural boundaries, security requirements, and quality standards that become part of the AI’s understanding:

/speckit.constitution

This .NET 8 web API project must follow these principles:
1. Use Clean Architecture with clear separation of concerns
2. All public APIs must have OpenAPI documentation
3. Minimum 80% unit test coverage for business logic
4. Security-first: JWT authentication, HTTPS only

What happens behind the scenes? Claude Code takes these principles and creates a detailed constitution document that becomes the lens through which all future code generation is filtered. Every subsequent command references back to these principles.

2. Specification: What You’re Building

The specification phase is where you describe functionality, but unlike traditional requirements documents that gather dust, these specifications directly drive code generation. You’re not writing documentation—you’re writing the blueprint for your application.

/speckit.specify

Build a customer portal API with user management,
product catalog, shopping cart, and order processing.

The key insight here is that specifications in Spec Kit aren’t just descriptions—they’re contracts. The AI treats them as promises about what the system must do, not suggestions about what it might do.

3. Clarification: Eliminating Ambiguity

This is where Spec Kit truly shines. Instead of the AI making assumptions about your requirements, it systematically identifies ambiguities and asks for clarification. This isn’t a chatbot asking random questions—it’s a structured process that ensures nothing is left to chance.

/speckit.clarify

The AI will identify areas needing clarification and present them as structured choices:

Should the API use REST or GraphQL?
What authentication method should be implemented?
Should data be stored in SQL Server or PostgreSQL?

Each answer becomes part of your project’s specification, eliminating the “I assumed you meant…” conversations that plague traditional development.

4. Planning: The Technical Blueprint

With clear requirements, the planning phase translates your business needs into technical decisions. This is where your tech stack, architectural patterns, and implementation strategies are defined:

/speckit.plan

Use .NET 8 minimal APIs with Entity Framework Core,
MediatR for CQRS, and xUnit for testing.

The plan isn’t just a list of technologies—it’s a coherent technical strategy that ensures all parts of your application work together harmoniously.

5. Task Breakdown: Executable Steps

Spec Kit transforms your specifications and plan into concrete, actionable tasks. These aren’t vague user stories—they’re specific implementation steps with clear dependencies:

/speckit.tasks

The generated tasks follow a logical progression:

Set up project structure and dependencies
Implement domain models and business logic
Create API endpoints and wire up services
Add validation and error handling
Write comprehensive tests

Each task builds on the previous ones, ensuring a smooth development flow.

6. Implementation: Where Magic Happens

Finally, when you run /speckit.implement, Claude Code generates your entire application based on all the context you’ve built up. This isn’t template code or boilerplate—it’s a complete, working implementation that follows your specifications exactly.

The generated code includes:

Clean Architecture structure with proper separation between layers
Domain models that capture your business logic
API endpoints with proper validation and error handling
Unit and integration tests ensuring code quality
Configuration files for development and production
Docker support for containerization

Understanding the Power of Specifications

Why This Approach Works

Traditional AI coding assistance fails because it lacks context. You ask for a feature, the AI generates code based on generic patterns, and you spend hours adapting it to your specific needs. Spec Kit inverts this—you build up context first, then generate code that fits perfectly into your architecture.

Think of it like building a house. Traditional AI assistance is like asking someone to build a room without telling them about the house it’s going into. Spec Kit ensures the AI understands the entire blueprint before laying a single brick.

The Compound Effect

Each phase of the Spec Kit process compounds on the previous:

Constitution establishes the rules
Specification defines the game within those rules
Clarification removes ambiguity from the game
Planning chooses the right tools to play
Tasks break down the game into moves
Implementation executes all moves consistently

By the time you reach implementation, the AI has such rich context that the generated code often requires minimal adjustments.

Best Practices for .NET Development

1. Leverage Your Existing Patterns

Don’t reinvent the wheel in your constitution. If your team follows specific patterns, encode them:

Constitution: All repositories must follow the pattern in 
CompanyName.Common.DataAccess. Use our standard BaseEntity
class for all domain models.

2. Start with Bounded Contexts

For larger applications, use Spec Kit to build one bounded context at a time:

First iteration: User Management context
Second iteration: Product Catalog context  
Third iteration: Order Processing context

Each context gets its own specification cycle, but they all share the same constitution.

3. Version Your Specifications

Treat your .specify folder as source code:

bash

git add .specify/
git commit -m "Initial customer portal specifications"

This creates a history of how your requirements evolved, invaluable for understanding why certain decisions were made.

4. Use Templates for Common Scenarios

Create constitution templates for different project types:

webapi-constitution.md for REST APIs
blazor-constitution.md for Blazor applications
microservice-constitution.md for microservices

This ensures consistency across projects and speeds up initialization.

Common Pitfalls and Solutions

Over-Specifying Too Early

Problem: Trying to define every detail in your first specification.
Solution: Start with core functionality. Use Spec Kit iteratively—build, test, then specify the next layer. The AI excels at adding features to existing codebases when given proper context.

Conflicting Requirements

Problem: Your constitution says “use minimal APIs” but your specification describes MVC-style controllers.
Solution: Review your constitution and specification together. They should align like a symphony—the constitution sets the key, and the specification provides the melody.

Trusting Without Verifying

Problem: Assuming all generated code is production-ready.
Solution: While Spec Kit produces high-quality code, always review critical components—especially authentication, data access, and external integrations. The generated tests are your friend here; run them and review what they’re actually testing.

When to Use Spec Kit

Perfect Scenarios

Prototyping: Quickly validate ideas with production-quality code
Greenfield Projects: Start with best practices from day one
Modernization: Generate modern implementations alongside legacy code
Learning: See how experienced developers would structure solutions

Consider Alternatives When

Highly Specialized Domains: If your domain requires deep expertise (e.g., real-time trading systems), human expertise remains crucial
UI-Heavy Applications: While Spec Kit can generate APIs brilliantly, complex UI interactions still benefit from human creativity
Performance-Critical Code: Generated code is good, but hand-tuned optimization might be necessary for hot paths

Conclusion

GitHub Spec Kit with Claude Code transforms AI-assisted development from a hit-or-miss experiment into a predictable, specification-driven process. By establishing clear constitutions and specifications, you ensure that generated code meets your architectural standards, follows your coding conventions, and implements your exact requirements.

The key insight is that specifications aren’t documentation—they’re executable contracts. When you define your project through Spec Kit’s structured approach, you’re not just telling the AI what to build; you’re establishing the constraints, patterns, and principles that ensure the result fits seamlessly into your broader architecture.

For .NET developers, this combination is particularly powerful. You can encode enterprise patterns, security requirements, and architectural decisions into your specifications, then have Claude Code consistently apply them across your entire codebase. The result isn’t just faster development—it’s better, more consistent code that aligns with your team’s standards from day one.

Ready to dive deeper? The next posts in this series explore how Spec Kit aligns with Scrum methodologies, accelerates prototyping, and even modernizes legacy codebases. But first, try building something with Spec Kit yourself. Start small—perhaps a simple API for a proof of concept. You’ll quickly discover that when your specifications drive the implementation, the gap between vision and code virtually disappears.

Share the Post:

AI for developers

The Developer Skill That AI Can’t Fake

Everyone’s talking about what AI is going to take from developers. I want to talk about what it’s exposing. Over