I recently wrote about using Claude Code Subagents in real projects and how a team of specialized agents collaborates effectively: Claude Code Subagents: A Developer’s Guide to Specialized AI Assistants. Building on that, I’ve been experimenting with spec-driven development (SDD) to guide AI coding agents with clarity and control. Instead of throwing a vague prompt at an agent and hoping it “gets it,” I now work in three lightweight stages:

• Specification (the what/why): I write an explicit spec that captures intent, scope, constraints, and success criteria.
• Plan (the how at a high level): I outline architecture choices, integration points, and guardrails.
• Tasks (the executable units): In Spec Kit, /tasks auto-generates the actionable list from your spec and plan; I review and adjust as needed.

SDD turns intent into an executable spec and plan, which makes AI coding agents far more reliable: less ambiguity, clearer execution paths, and a consistent, auto-generated task list that the agent can follow systematically.

How SDD Works

SDD provides with a clear, unambiguous source of truth. The agent executes against the spec, plan, and auto-generated tasks.

Why I Integrated SDD Into My Workflow

• Less rework: Vague prompts led to “reasonable” but wrong assumptions. A concise spec up front reduces back-and-forth.
• Repeatability: I can re-run the same spec+plan across variants (e.g., different data sources) without rewriting context.
• Built-in constraints: Security, performance, and design rules live in the spec/plan, not in my memory.
• Better diffs: Changes in intent propagate to code systematically—update the spec, regenerate plan/tasks, and implement.

Getting Started: Project Initialization

Prerequisite: uv must be installed. If the uv command is not found, install it via the official guide: uv installation.

Install Spec Kit once and use everywhere (recommended):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Then use the tool directly:

specify init <PROJECT_NAME>
specify check

Or run Spec Kit directly without installing:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

When prompted during initialization, select your preferred AI assistant. In my case, I selected Claude.

For full details, see the official repo: github/spec-kit.

My Minimal SDD Template

I keep a compact template I can paste into my agent or repo. It’s fast to fill and avoids over-documentation.

# Specification (What & Why)
- Goal: <clear outcome>
- Users: <audiences and needs>
- Scope: <in/out of scope>
- Success: <measurable criteria>
- Constraints: <security, perf, platform, design system>

# Plan (High-Level How)
- Architecture: <key components & boundaries>
- Data: <schemas, sources, contracts>
- Integrations: <APIs/services/features>
- Risks: <known risks & mitigations>
- Non-Goals: <explicitly not doing>

A Concrete Example From My Workflow

Here’s a more substantial example I’m working on an invoice-generator project with SDD

Constitution (governing principles and development guidelines) 

Executed with the /constitution slash command.

Example:

/constitution
- Principles: follow spec/plan as source of truth; minimal deps; security/privacy; performance budgets.
- UX/UI: polished and accessible, consistent with the design system.
- Rendering: prefer SSR; use client components only when necessary.

Result:

• The constitution is generated automatically.

• The generated constitution is well-structured and thorough.

Specification (refined for clarity) 

Executed with the /specify slash command.

Example:

/specify
- Goal: Build a web app that generates invoices for clients.
- Users: My small business users who need to manage clients, items, and invoices.
- Scope: Provide dedicated pages to manage clients and items. Allow users to create invoices from selected clients and items, then export invoices as PDF or send them via email.
- Success: A user can create, preview, and export/send an invoice within one minute. PDF output is consistent and readable; email delivery succeeds with confirmation. Data persists reliably across sessions.
- Constraints: Keep the stack simple. Use minimal dependencies. Respect privacy; do not expose invoice data publicly.

Result:

• When the specification is generated, it also creates a Git branch 001-goal-build-a with a prefix matching the goal. 

• The specification is clear and actionable, with requirements and edge cases called out.

Plan (technology and architecture) 

Executed with the /plan slash command.

Example:

/plan
- Stack: Next.js (TypeScript), PostgreSQL for database.
- Data model: `clients`, `items`, `invoices`, and `invoice_items` (line items). Basic relations with sensible indexes.
- Pages/routes: `/clients` (CRUD), `/items` (CRUD), `/invoices` (list/create/view), `/invoices/[id]` (view/export/send).
- PDF: Server-side PDF generation with a minimal library or native rendering pipeline; prefer SSR/Edge-friendly approach.
- Email: Minimal email sender integration (e.g., SMTP or a single provider SDK) behind a server action/route handler.
- Security: Session-based auth; input validation; RBAC kept simple (owner-only for now).
- Ops: Use migrations for schema; seed minimal data; logging around invoice creation and email send.

Result:

• The plan command generates artifacts for technical decisions.

Let’s take a quick look at the generated artifacts; each file is long, so I’ll highlight the important parts.

• Provides reasoning and justification.

• Shows project structure details.

• Also lays out project phases and progress tracking.

• Summarizes technical decisions and research.

• Also outlines implementation priorities.

• Getting-started guide for environment setup.

• Also shows the user workflow.

• Also shows test coverage details and acceptance criteria.

• Data model design with relations and indexes.

Tasks (executable units) 

Executed with the /tasks slash command to auto-generate the task list from the spec and plan.

A quick look at the generated tasks:

• As you notice from the screenshot image [P], it means the tasks can be executed in parallel.

When everything is done, I can run the /analyze slash command to perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. (project structure, technical decisions, and implementation priorities)

If the analyze command finds no issues, it shows a green checkmark. To start the implementation, I can run the /implement slash command.

This structure keeps the intent clear, the architecture constrained, and the units of work small enough for an AI coding agent to implement reliably.

Practical Tips That Worked for Me

• Keep specs short: One screen of text is usually enough.
• Name the constraints: Latency budgets, access rules, style systems—write them down.
• Structure agent runs: First /specify, then /plan, then /tasks (Spec Kit auto-generates tasks from your spec and plan).
• Regenerate deliberately: When intent changes, update spec first, then plan; don’t “just tweak code”.
• Measure success: Define acceptance checks the agent can verify.

Final Thoughts

Spec-driven development turns “intent” into the source of truth. For me, it reduces ambiguity, keeps quality high, and makes AI assistance predictable. When I treat the spec as executable, the plan as architecture, and the tasks as contracts, the agent becomes a reliable partner instead of a creative guesser.