# Spec-kit Under the Hood

> A 20-30 minute deep dive into Spec-kit's source code. Once you know how it works in practice, reading its templates and commands shows you exactly what prompts drive the workflow and gives you a model for building your own.

- **Source:** https://ainativesoftware.engineering/roadmap/day-5/spec-kit-under-the-hood
- **Site:** AI-Native Software Engineering — https://ainativesoftware.engineering/book

- **Day:** 5 · position 4 of 4
- **Reading time:** 3 minutes
- **Day overview:** [Day 5](https://ainativesoftware.engineering/roadmap/day-5.md)

A 20-30 minute deep dive into Spec-kit's source code. Once you know how it works in practice, reading its templates and commands shows you exactly what prompts drive the workflow and gives you a model for building your own.

## Theory

Once you've used Spec-kit a few times, it's worth understanding what's actually happening when you run a command.

### The moving parts

At the surface, Spec-kit feels like a set of slash commands (`/speckit.specify`, `/speckit.plan`, etc.). Under the hood, each command triggers a small orchestration: a **shell script** runs to handle the mechanical work (creating branches, scaffolding files, numbering features), and then a carefully written **prompt template** is injected into your AI agent's context.

That prompt template is the real engine. It's not a simple instruction like "write a spec." It's a structured document that constrains what the AI can and can't do: it tells the agent to stay at the right abstraction level, flag unknowns explicitly with markers like `[NEEDS CLARIFICATION]`, and avoid jumping to implementation details before they're needed.

### The constitution as an enforcement layer

Separate from the per-command templates, Spec-kit ships a `constitution.md` that gets loaded into the agent's context as a set of non-negotiable principles. Things like "tests must be written before implementation code" or "don't wrap framework features in unnecessary abstractions." These aren't suggestions in the prompt; they're framed as hard rules the agent is expected to follow throughout the entire session.

### Why this matters

The key insight is that the quality of Spec-kit's output isn't magic. It comes from the quality of the prompts. Each template has been designed to push the AI toward a specific kind of output and away from the failure modes that show up in unconstrained generation (hallucinated details, premature decisions, vague acceptance criteria). Reading those templates gives you a direct window into how to engineer that kind of reliable, structured AI output yourself.

**Theory resources**

- [Spec-kit Commands – GitHub Source](https://github.com/github/spec-kit/tree/main/templates/commands)
- [Spec-kit Templates – GitHub Source](https://github.com/github/spec-kit/tree/main/templates)

## Practice

Run this in a repository you already know, not a toy project.

The goal of this exercise is to read the actual prompts that drive Spec-kit's workflow, understand what each one is doing, and draw lessons you can apply to your own prompts.

**Step 1: Read the command templates**

Open the [templates/commands](https://github.com/github/spec-kit/tree/main/templates/commands) directory in the Spec-kit repo. Read through each command file: `specify.md`, `plan.md`, `tasks.md`, and `implement.md`.

For each one, ask yourself:
- What is this prompt trying to constrain or enforce?
- What failure mode is it designed to prevent?
- What instructions are doing the real work here?

**Step 2: Read the spec and plan templates**

Open the [templates](https://github.com/github/spec-kit/tree/main/templates) directory and read the output templates (like `spec-template.md` and `plan-template.md`). These are the structures the AI is asked to fill in. Notice what sections are mandatory, which are optional, and where the template explicitly says "don't include implementation details yet."

**Step 3: Find the guardrails**

Look for the instructions in the prompts that set boundaries on AI behavior. Things like explicit instructions to flag uncertainty, to avoid technology choices at spec time, or to require test cases before implementation code.

Make a short list of the 3–5 guardrails you found most interesting.

**Step 4: Write your own mini-template**

Pick one task you commonly ask an AI agent to help with (reviewing a PR, breaking down a feature, writing test cases). Draft a one-page prompt template for it, borrowing the guardrail patterns you identified from Spec-kit.

**Reflect:**
- Which guardrails do you already use informally in your prompts? Which ones were new?
- How would the output change if those guardrails were removed?
- Is there a place in your current workflow where a standing template like this would save you time?

- **Previous topic:** [Spec-kit: The Open Toolkit](https://ainativesoftware.engineering/roadmap/day-5/spec-kit-the-open-toolkit.md)
- **Next topic:** [BMAD: The AI-Driven Delivery Framework](https://ainativesoftware.engineering/roadmap/day-6/bmad-the-ai-driven-delivery-framework.md)

---

_AI-Native Software Engineering by Alfonso Graziano (O'Reilly Media, Early Release; print edition February 2027). Every page of ainativesoftware.engineering is also served as Markdown: append `.md` to any URL. Index: https://ainativesoftware.engineering/llms.txt — whole site in one file: https://ainativesoftware.engineering/llms-full.txt._