What Is GitHub Spec Kit and Where It Fits in the SDD Workflow

In Topic #1, we talked about the mindset of SDD — the new way of thinking about building software with AI. In this Topic #2, we shift focus to the tooling that automates that mindset, and for a Go developer the entry point is github spec kit.

GitHub Spec Kit is the answer.

It’s not a new framework to learn from scratch. Not a library to import into every project. It’s a CLI tool that automates the six stages of the SDD cycle — from a hazy business need, all the way to Go code that’s ready to review and merge.

One command. One cycle. The entire workflow orchestrated.

01.1 Context: Where Does Spec Kit Fit?

If you just finished Topic #1, you know SDD has components that must be executed in sequence: write spec, clarify, create plan, break down tasks, generate code, review. The problem is that all of that is normally done by hand — opening different files, keeping references consistent, remembering where everything lives, and feeding Claude Code the right context at each stage. The comparison below shows the manual grind next to the Spec Kit flow.

 1Without Spec Kit:
 2Developer → [open terminal] → [open editor] → [write spec manually]
 3         → [switch to Claude Code] → [paste context] → [generate plan]
 4         → [copy plan to file] → [write tasks manually] → [implement]
 5
 6With Spec Kit:
 7Developer → specify feature product-service
 8         → specify clarify product-service
 9         → specify plan product-service
10         → specify tasks product-service
11         → specify implement product-service --phase=1

The takeaway is that Spec Kit isn’t a replacement for SDD — it’s the conductor orchestrating every instrument in the SDD orchestra, collapsing a dozen manual steps into five predictable commands.

01.2 The Philosophy Behind Spec Kit

GitHub Spec Kit was born from a very specific frustration: developers who had adopted SDD found that the manual process — creating .specify/ folders, maintaining consistency across files, ensuring Claude always had the right context — consumed almost as much time as the implementation itself.

Spec Kit’s philosophy can be summarized in one sentence:

“Specification is the source of truth. Code is the output. AI is the executor. Spec Kit is the conductor.”

Three direct implications follow from that sentence:

1. Spec is written before code — enforced by tooling, not just discipline.
2. Constitution defines all architectural decisions — before a single line of code.
3. AI context is always consistent — Spec Kit ensures complete context at every command.

Together these implications explain why Spec Kit feels opinionated: the tool refuses to let you skip the discipline that makes SDD work in the first place.

01.3 The Six Commands That Form One Cycle

Everything Spec Kit does is built on six commands, each mapping to exactly one stage of the SDD cycle. The listing below names them in the order they must run.

1specify constitution init    → Define project principles that cannot be broken
2specify feature [name]       → Write business requirements without tech stack
3specify clarify [name]       → Structured Q&A to clarify spec ambiguities
4specify plan [name]          → Generate technical plan from clarified spec
5specify tasks [name]         → Break plan into actionable tasks
6specify implement [name]     → Generate and execute code from tasks sequentially

The key point: these six commands are designed to run in sequence — you can’t run specify plan before a spec exists, because Spec Kit enforces the ordering. That enforcement is what turns “spec-first” from a good intention into a guarantee.

01.4 The File Structure Spec Kit Creates

Running those commands doesn’t just talk to Claude — it materializes files on disk that you can commit and review. The tree below shows the shape of a project after one feature has been driven through Spec Kit.

 1santekno-shop/
 2├── .specify/
 3│   ├── constitution.md              ← Principles for all features
 4│   ├── features/
 5│   │   └── product-service/
 6│   │       ├── spec.md              ← Business requirements (no tech details)
 7│   │       ├── plan.md              ← Technical plan (files, SQL, API)
 8│   │       └── tasks.md             ← Task breakdown with estimates
 9│   └── history/
10│       └── 2025-07-01-product-service.log
11├── CLAUDE.md                         ← Project memory (still needed)
12└── internal/
13    └── product/

What to remember here: everything under .specify/ is part of your source of truth — reviewable via PR, discussable, and versionable — so these files belong in git, not in a scratch folder.

01.5 Spec Kit vs CLAUDE.md: You Need Both

A common question is whether Spec Kit makes CLAUDE.md obsolete. It doesn’t — the two operate at different scopes, as the table below makes clear.

The conclusion: Spec Kit reads both CLAUDE.md and .specify/constitution.md when generating plans and code, so keep both — one describes who you are, the other describes what you’re building right now.

01.6 Spec Kit vs Other SDD Tools

Spec Kit is not the only spec-first tool in 2026, so it helps to see what actually distinguishes it from the alternatives:

vs. Kiro (Amazon): YAML-based steering files vs Markdown. More AWS-integrated vs more agnostic.

vs. Manual SDD: Maximum flexibility but high mental overhead. Spec Kit reduces that overhead by automating the repetitive cycle.

vs. Browser-based AI: No codebase access. Spec Kit integrates AI directly into the development workflow with full codebase context.

Spec Kit’s unique characteristics:

• Enforces ordering (can’t skip stages)
• All output as committable files
• Direct Claude Code integration (not browser)
• Constitution as a consistent “law” across all features

The differentiator to hold onto: Spec Kit trades some flexibility for enforced structure, which is exactly the trade you want once a team depends on the discipline.

01.7 Who Should Use Spec Kit

Spec Kit is not for everyone or every task, so match it to the situation:

Best fit:

• Developers who’ve adopted SDD but find the overhead large
• Small teams (2-10 people) who want to enforce SDD consistently
• Go developers who want to start SDD but don’t know where to begin

When Spec Kit might not be the best choice:

• For one-off tasks under 30 minutes (overhead not worth it)
• For teams completely unfamiliar with SDD (read Topic #1 first)
• For proof-of-concept projects that will be thrown away

In short, Spec Kit pays off when the same disciplined cycle repeats often enough that automating it saves real time.

01.8 Before and After Spec Kit

The clearest way to feel the value is to compare the wall-clock cost of one small feature — “Get Product by SKU” — with and without the tool.

 1Before (manual SDD):
 2- Create folders and files manually
 3- Open Claude Code, paste context manually
 4- Generate plan, save manually
 5- Write tasks manually
 6- Implement with repeated context pasting
 7- Total setup time: ~45 minutes before first line of code
 8
 9After (with Spec Kit):
10- specify feature get-product-by-sku      (10 min Q&A)
11- specify clarify get-product-by-sku       (5 min)
12- specify plan get-product-by-sku          (60 seconds)
13- specify tasks get-product-by-sku         (30 seconds)
14- specify implement get-product-by-sku --phase=1
15- Total setup time: ~15 minutes

The point isn’t only that Spec Kit is faster — it’s more consistent: nothing is forgotten and no context is lost between stages, which is where manual SDD quietly accumulates errors.

01.9 Spec Kit + Go: A Powerful Combination

Go is an opinionated language. go fmt, go vet, interface-based polymorphism, explicit error handling — all conventions that must be followed.

The problem: an AI that isn’t configured properly tends to generate Go code that “works but isn’t idiomatic” — using patterns borrowed from other languages that feel unnatural in Go.

Spec Kit solves this through the constitution. When the constitution defines error-handling patterns, interface strategies, package naming, and testing approach, Claude Code consistently generates idiomatic Go that matches your existing codebase — the same reason we invested so heavily in conventions in Topic #1.

01.10 The Santekno Shop Project

Throughout this series, we use Santekno Shop — a B2C Indonesian e-commerce platform — as our concrete example, so every abstract concept lands on real code. The stack it runs on is listed below.

1- Go 1.22+, Echo v4, pgx/v5, go-redis/v9
2- confluent-kafka-go v2, testify/suite, gomock

Because every article builds on this same codebase, you’ll see how a single feature evolves from zero to production-ready rather than juggling disconnected toy examples.

01.11 Series Roadmap: 20 Articles, 4 Parts

Before we install anything, it’s worth seeing the whole journey at once so you know where each article fits. The map below lays out all four parts of this topic.

 1PART 1 — INTRODUCTION & SETUP (Articles 1–4)
 201. What Is GitHub Spec Kit ← you are here
 302. Installing specify CLI: Persistent vs One-time Setup
 403. .specify Folder Structure: Anatomy of Generated Output
 504. Spec Kit + Claude Code Integration: End-to-End Go Project Setup
 6
 7PART 2 — SIX CORE COMMANDS (Articles 5–10)
 805. speckit.constitution: Project Constitution
 906. speckit.specify: Write Requirements Without Tech Stack
1007. speckit.clarify: Structured Q&A for Spec Clarity
1108. speckit.plan: Functional Spec to Technical Plan
1209. speckit.tasks: Actionable Task Breakdown
1310. speckit.implement: Execute Code from Tasks
14
15PART 3 — REAL WORKFLOWS (Articles 11–15)
1611. Case Study: CRUD API from Spec Kit End-to-End
1712. Branching Strategy: One Feature = One Branch
1813. Git Workflow: Auto-Commit and PR from Spec Kit
1914. Auto-Updating CLAUDE.md
2015. Debugging Workflow: When Claude Ignores Instructions
21
22PART 4 — SCALE & INTEGRATION (Articles 16–20)
2316. Spec Kit for Teams: Onboarding and Shared Constitution
2417. Spec Kit in Go Monorepos
2518. Validating Implementation Against Specification
2619. Spec Kit + GitHub Actions: Lightweight Validation CI
2720. [Bridge →] Spec Output as Contract in AI Pipeline

Keep this roadmap handy: the four parts move from setup, to the six core commands, to real workflows, and finally to scaling Spec Kit across a team.

01.12 What Spec Kit Doesn’t Do

It’s just as important to know the boundaries so you don’t expect magic:

Spec Kit does NOT replace:

• Engineering judgment — you still decide if the spec is correct
• Business knowledge — you must know what users need
• Code review — Spec Kit output still needs human review
• Testing strategy — Spec Kit generates tests, but you decide coverage targets

Spec Kit is NOT:

• A CI/CD tool (doesn’t deploy to production)
• An application monitor
• A tech stack selector (constitution is written by humans first)

The bottom line: Spec Kit is a multiplier for developers who already have good judgment — not a replacement for that judgment.

01.13 Position in the 2026 AI Tools Ecosystem

To place Spec Kit precisely, picture the modern AI-coding stack as a set of “slots,” each occupied by a different class of tool. The diagram below shows where Spec Kit lives.

1Slot 1: AI Editor (you write, AI helps) → Copilot, Tabnine
2Slot 2: AI Chat Coding (you prompt, AI generates) → Claude Code, ChatGPT
3Slot 3: Agentic Coding (AI runs tasks autonomously) → Devin, Claude Code plan mode
4Slot 4: Workflow Orchestration → GitHub Spec Kit ← here

The insight: Spec Kit doesn’t compete with your editor or your chat assistant — it sits one level above them in Slot 4, orchestrating when and how each of those tools is used within the SDD context.

01.14 Prerequisites

Before Spec Kit is useful, a few things need to be in place — split here into what you must install and what you should already understand:

Technical:

• Go 1.22+ installed
• Node.js 18+ (for specify CLI via npm)
• Claude API key (from console.anthropic.com)
• Initialized Git repository

Knowledge:

• Familiarity with SDD concepts (ideally Topic #1)
• Understanding of clean architecture in Go
• Basic Claude Code usage

If all of these are ready, the installation in the next article will be a five-minute exercise rather than a debugging session.

01.15 A Day in the Life with Spec Kit

Concepts stick better when you see them in a normal working morning. The timeline below traces a single feature from Jira ticket to committed code.

108:30 — Check Jira: SHOP-789 "Add product variant support"
208:35 — $ specify feature product-variants (10 min Q&A)
308:45 — $ specify clarify product-variants (5 min clarification)
408:50 — $ specify plan product-variants (60 seconds)
508:52 — $ specify tasks product-variants (30 seconds, 12 tasks ready)
608:55 — Review plan and tasks (10 min), one correction
709:05 — $ specify implement product-variants --phase=1 (5 min)
809:10 — Review output, commit
909:15 — $ specify implement product-variants --phase=2...

Notice what the rest of the day looks like: it’s spent on code review and testing, not on “setup” and “admin” — the repetitive orchestration has been handed to the tool.

01.16 Why “GitHub” Spec Kit?

The name can mislead. GitHub Spec Kit is not an official GitHub product — it’s an open-source project hosted on GitHub, inspired by how GitHub uses spec-driven workflows internally, and designed to work natively with GitHub repositories and Actions.

You don’t strictly need GitHub, though — any Git hosting works, and Spec Kit even runs locally with no remote at all. We use GitHub in this series simply because it’s the most common choice.

01.17 Full End-to-End Picture

Before installation in the next article, it helps to hold the entire pipeline in your head at once. The flow below traces one feature from a vague business need to committed spec-plus-code.

 1Business need ("we need product variants")
 2  ↓ specify feature
 3Business requirement documented (spec.md)
 4  ↓ specify clarify
 5Ambiguities resolved, spec updated
 6  ↓ specify plan
 7Technical plan created (file structure, SQL, API endpoints)
 8  ↓ specify tasks
 912 actionable tasks with time estimates
10  ↓ specify implement --phase=1
11Domain types generated
12  ↓ Review + commit
13  ↓ specify implement --phase=2
14Repository layer generated
15  ↓ ... (repeat per phase)
16  ↓ Feature complete: spec + code both committed

The property that matters: every step is a command and every output is a file — which is what makes the whole process structured, transparent, and reproducible rather than a one-off chat session.

01.18 Tips & Gotchas

A few field-tested lessons will save you time before you even start:

💡 Tip 1: Start with an existing project, not from scratch — Spec Kit can be adopted incrementally.

💡 Tip 2: Constitution is your most important investment — time spent here pays dividends on every subsequent feature.

💡 Tip 3: Treat .specify/ like source code — commit every change, review spec via PR.

💡 Tip 4: Spec Kit works best with an existing codebase — more reference code means better-quality output.

⚠️ Gotcha 1: Don’t use the --all flag initially — always use --phase=N and review after each phase.

⚠️ Gotcha 2: The API key must be set before the first command — Spec Kit fails immediately without it.

⚠️ Gotcha 3: Ambiguous constitution = ambiguous code — invest time in making rules clear and explicit.

⚠️ Gotcha 4: Spec Kit output is a starting point — human code review is still required before merge.

The common thread across all four gotchas: Spec Kit rewards preparation and punishes shortcuts, so front-load the discipline.

01.19 Comparing Spec Kit to Manual SDD

The value of Spec Kit over manual SDD isn’t just speed — it’s consistency and context preservation. When you’re on your fifth feature of the week, manual SDD starts accumulating small inconsistencies: slightly different folder structures, subtly different spec formats, forgetting to update CLAUDE.md after adding a library.

Spec Kit eliminates these by making the consistent path the easy path. The convention is baked into the tooling, so doing the right thing costs no extra effort.

01.20 Summary

GitHub Spec Kit is a CLI tool that automates the six stages of the SDD cycle — from business requirements to merge-ready Go code. It’s not a replacement for engineering judgment, but an amplifier that makes the process faster, more consistent, and more structured.

Six core commands: constitution, feature/specify, clarify, plan, tasks, implement — each enforcing one stage of the SDD cycle.

Position in the ecosystem: Not an AI editor, not an AI chat — a workflow orchestrator that manages how all tools are used within the SDD context.

Keys to success: A good constitution, familiarity with Go clean architecture, and the discipline to review each output before merging.

In the next article, we install the specify CLI and perform a complete setup for the Santekno Shop project — including the configuration that makes Spec Kit work persistently across all your Go projects.