#github spec kit

Introduction 

We have entered the "Integration Tax" era of AI coding. Developers using chat-based assistants (Copilot, ChatGPT) are generating code faster than ever, but they are also generating technical debt at record speeds—creating "orphan" functions, mismatched types, and logic that drifts from business requirements. 

Spec-Driven Development (SDD) is the senior engineering answer to this chaos. Instead of prompting for code directly ("Write a user auth function"), you define a rigid, rigorous specification first. You treat the spec as the Source of Truth, and the code as a derived artifact.  

With the release of Amazon Kiro (the spec-first IDE) and GitHub Spec Kit (the SDD toolkit), this workflow is no longer theoretical. It is the only scalable way to build production systems with AI. This guide moves you from "Vibe Coding" (casual prompting) to "Spec Coding" (engineering). 

Definitions & Diagnostic: The Core Shift 

Vibe Coding (Junior): You ask the AI to "build a feature." It guesses the architecture, libraries, and error handling. Result: It works once, breaks often. 

Spec-Driven (Senior): You provide a Constitution (rules), a Spec (requirements), and a Plan (architecture). The AI implements only what is defined. Result: Deterministic, documented, maintainable software. 

Diagnostic: Are you suffering from "Prompt Drift"? 

[ ] do you have to re-explain your tech stack in every third prompt? (e.g., "Use Tailwind, not Bootstrap")  

[ ] Does your AI generate code that conflicts with existing database schemas? 

[ ] Do you spend >40% of your time debugging AI-generated logic errors? 

[ ] Is your documentation consistently 2 weeks behind your code? 

If you checked ≥2, you need SDD immediately. 

The Toolkit (Minimal Viable Setup) 

You don't need a complex enterprise platform. You need a Steering Layer. 

Amazon Kiro: The IDE wrapper (VS Code fork) that natively understands "Spec Mode" vs "Vibe Mode". It uses agents to generate plans before code. 

GitHub Spec Kit: A CLI and template set that standardizes your prompts into spec.md, plan.md, and tasks.md. 

Installation (Spec Kit CLI): 

# Install the Spec Kit CLI (via uv/pip)  uvx --from git+https://github.com/github/spec-kit.git specify init my-sdd-project    # Initialize a Kiro project (if using Kiro IDE)  kiro .   # (Kiro will auto-generate steering files: product.md, tech.md)   

Step-by-Step SDD Workflow 

Phase 1: The Constitution (The Non-Negotiables) 

Before writing a single feature, define the "Constitution". These are rules the AI cannot break. 

Action: Create .spec/constitution.md (or tech.md in Kiro). 

Copy-Paste Template: 

# Project Constitution    ## 1. Tech Stack  - Frontend: React 19 (Server Components), TypeScript 5.5  - Styles: Tailwind CSS (no custom CSS modules)  - State: Zustand (avoid Redux)  - API: tRPC for type safety    ## 2. Coding Standards  - All functions must have TSDoc comments explaining 'Why', not 'What'.  - No `any` types allowed. Use `unknown` with Zod validation.  - All async operations must handle errors using the `Result` pattern, not try/catch blocks.    ## 3. Security  - Never expose env vars on the client side.  - All API inputs must be sanitized via Zod schemas.   

Phase 2: The Specification (The "What") 

Do not ask for code. Ask for a Spec. 

Command (Spec Kit): 

@spec-kit /specify "We need a 'Refund Order' button for admins. It should only be visible for orders < 30 days old." 

Outcome: The AI generates a structured spec.md. Review this manually. 

Example Output (Condensed): 

# Spec: Admin Refund Feature    ## User Story  As an Admin, I want to refund orders so that I can resolve customer complaints.    ## Constraints  1. Order age must be < 30 days.  2. User must have `role: 'admin'`.  3. Refund amount cannot exceed original total.    ## Edge Cases  - Partial refunds (Out of Scope for v1).  - Payment gateway timeout (Must implement retry mechanism).   

Phase 3: The Plan (The "How") 

Command: 

@kiro /plan based on spec.md 

The AI will generate: 

Files to touch: src/server/routers/order.ts, src/components/RefundButton.tsx. 

Data changes: Update Prisma schema for refundStatus. 

Dependencies: Stripe API SDK. 

> Critical Step: If the plan looks wrong (e.g., modifying the wrong controller), correct the PLAN, not the code. 

Phase 4: Implementation (The Code) 

Only now do we generate code. Because the context (Constitution + Spec + Plan) is pinned, the AI has "tunnel vision" on the correct solution. 

Command: 

@kiro /implement task-1 "Scaffold the database schema changes" 

Examples & Patterns 

Pattern: The "Linter-Driven" Correction 

When the AI generates code that violates the Constitution, don't argue. Use a linter to force compliance. 

Config (.cursorrules or Kiro .steering/rules.md): 

# Rules for AI Agent  - ALWAYS run `npm run lint` after generating a file.  - If the linter fails on `no-explicit-any`, REWRITE the code to use Zod schemas.  - Do not ask for permission to fix linter errors; just fix them.   

Pattern: The "Living" Spec 

Pitfall: The code evolves, but the spec dies. 

Fix: Use "Reverse Spec Generation". Before starting a new sprint on legacy code, run: 

@kiro /analyze src/legacy-module --output spec-current.md 

This creates a baseline spec from existing code, ensuring you don't break hidden logic. 

Conclusion 

Spec-Driven Development turns AI from a "coding intern" into a "software architect." By enforcing the Constitution → Spec → Plan → Code pipeline using tools like Amazon Kiro and GitHub Spec Kit, you eliminate the ambiguity that causes 90% of AI-generated bugs. 

Your Next Step: 

Don't rewrite your whole platform. Pick one complex feature (e.g., a new API endpoint) for your next sprint. Install the Spec Kit CLI, write a 10-line "Constitution" defining your styling and error handling preferences, and force yourself to generate a plan.md before writing a single line of code.