Claude Code is powerful. But it needs a spec, not a paragraph. Hand it a vague prompt and you get scope creep, broken context mid-session, and a third round of rework because "that's not what I meant." Spec-driven development fixes this — but writing the spec is the hard part.
Tekk reads your codebase and generates the spec. Claude Code executes it.
[Try Tekk.coach Free →]
How Tekk + Claude Code Does Spec-Driven Development
The problem isn't Claude Code's execution ability. The problem is the input. A casual prompt leaves Claude Code to infer file structure, scope, acceptance criteria, and what "done" looks like. It guesses. Sometimes well, often not. The result is an agent that drifts — touching files it shouldn't, skipping things it should have done, asking clarifying questions three steps too late.
Tekk starts before Claude Code does. Connect your repo, describe the feature. Tekk runs a semantic search across your codebase — reading actual files, frameworks, patterns, dependencies — before asking a single question. Its questions are grounded in what it found, not generic prompts like "what's your tech stack?" It already knows. This is spec driven development applied directly to your Claude Code workflow.
From there, Tekk generates a structured spec: subtasks broken into behavioral slices, acceptance criteria per subtask, explicit file references, and a "Not Building" section that draws a hard boundary around scope. That's what Claude Code gets. Not a paragraph. A working document that tells it exactly what to build, which files to touch, and when it's done.
The spec lives in Tekk's editor — editable, versioned, yours. Review it, adjust it, then hand it to Claude Code. The planning-to-execution handoff via MCP is coming next. The planning pipeline — Tekk reading your codebase and generating the spec — is live today.
Key Benefits
Specs grounded in your actual codebase Tekk reads your repo before writing a word. Every subtask references real files, real patterns, real dependencies. No generic boilerplate that Claude Code has to interpret and guess at.
Scope boundaries that prevent runaway execution Every Tekk spec includes an explicit "Not Building" section. Claude Code knows what's out of scope before it starts. No drift, no "while I was in there I also changed..." surprises.
Acceptance criteria per subtask Each subtask has a clear definition of done. Claude Code doesn't have to infer completion — it has a concrete condition to check. Fewer clarification loops, fewer approval interruptions mid-run. When you're running multiple Claude Code sessions in parallel, ai agent orchestration manages the coordination across agents.
MCP integration for seamless handoff (coming next) Tekk extends the Claude Agent SDK with write-capable MCP tools. When execution dispatch ships, your spec moves from Tekk to Claude Code without copy-paste. The plan drives the agent.
How It Works
Step 1: Connect your repo Link your GitHub, GitLab, or Bitbucket repository. Tekk gets read access — nothing else.
Step 2: Describe the feature One or two sentences. What you're building, not how. Tekk figures out the how.
Step 3: Tekk reads your codebase Semantic search, file search, regex search, directory browsing. Tekk builds a structural understanding of your repo — languages, frameworks, services, packages — before generating anything.
Step 4: Tekk asks questions Three to six questions, grounded in what it found in your code. Not "what framework are you using?" It already knows. It asks about the decisions that actually matter for this feature.
Step 5: Choose your approach Tekk presents two or three architecturally distinct options with honest tradeoffs. Pick the one that fits. If there's an obvious path, Tekk skips this step and moves on.
Step 6: Tekk writes the spec The plan streams into a rich text editor as the actual working document: TL;DR, Building/Not Building scope, subtasks with acceptance criteria and file references, assumptions with risk levels, validation scenarios.
Step 7: Claude Code executes Take the spec into Claude Code. Give it the document as context, or wait for MCP execution dispatch (coming next) to hand it off automatically. Claude Code has everything it needs.
Who This Is For
Claude Code users who want structured, repeatable results. You've used Claude Code. You know it works when the input is good and drifts when it isn't. You've tried writing specs yourself — a CLAUDE.md, a plan.md, a requirements doc. It helps. But it's manual, it's not codebase-aware, and it doesn't scale across every feature you're building.
Developers doing spec-driven development with Claude Code professionally. You've read the guides. You know the Requirements → Design → Tasks → Implementation pattern. You want a tool that does the spec generation for you, grounded in your actual repo — not another template to fill out. For teams that also need product-level requirements before the spec, the ai prd generator covers that upstream step.
Small teams and solo founders building with AI agents. You don't have a dedicated architect. You're using Claude Code because it's fast, but the chaos is building up — specs in chat threads, context lost between sessions, rework from vague prompts. Tekk gives you the planning layer the workflow was always missing.
What Is Spec-Driven Development with Claude Code?
Spec-driven development is a workflow that separates planning from execution. Instead of prompting a coding agent directly, you produce a specification document — covering what you're building, how it fits in the existing codebase, what the acceptance criteria are, and what's explicitly out of scope — before a single line of code is written. The coding agent works from the spec, not from your prompt.
In the Claude Code context, this matters because Claude Code is a capable agentic executor that operates with significant autonomy. The better the spec it starts with, the better it executes. CLAUDE.md handles project-wide conventions. A feature spec handles the task at hand: file targets, behavioral acceptance criteria, scope boundaries, dependencies. Together, they give Claude Code a complete picture of what to do and how to do it within your codebase.
The community has settled on a clear principle: CLAUDE.md instructions get followed about 70% of the time on their own. Structured specs dramatically close that gap by making intent explicit before execution begins. The planning phase isn't overhead — it's the work that makes everything downstream faster and more accurate.
Frequently Asked Questions
What is spec-driven development with Claude Code?
Spec-driven development with Claude Code is the practice of writing a structured specification — with subtasks, acceptance criteria, file references, and scope boundaries — before Claude Code begins executing. Rather than prompting the agent with a paragraph, you give it a working document it can follow from start to finish. The result is tighter execution, fewer mid-run clarification loops, and output that actually matches what you intended.
How does spec-driven development work with Claude Code?
The standard workflow is: write the spec (requirements, design, tasks), review and approve it, then execute. Claude Code reads the spec as context — either directly in the session or via CLAUDE.md and task files — and works through it step by step. Tools like Tekk automate the spec-writing phase by reading your codebase first, so the spec is grounded in real file structure rather than generated from thin air.
How does Tekk.coach integrate with Claude Code for spec-driven development?
Tekk generates the spec; Claude Code executes it. Today, Tekk reads your codebase, runs a multi-turn planning session, and produces a structured spec you take into Claude Code. The spec includes subtasks with acceptance criteria, explicit file references, scope boundaries, and validation scenarios — the exact inputs Claude Code needs to execute well. Execution dispatch via MCP (where Tekk hands the spec directly to Claude Code without copy-paste) is the next milestone on the roadmap.
What is the difference between a CLAUDE.md file and a Tekk spec?
CLAUDE.md handles project-wide conventions: code style, common commands, architectural patterns. It's context that applies to every Claude Code session in a repo. A Tekk spec is task-specific: it defines what you're building right now, which files are in scope, acceptance criteria per subtask, and what's explicitly not being built. They work together — CLAUDE.md sets the environment, Tekk's spec defines the work.
Can I do spec-driven development in Claude Code without Tekk?
Yes. Developers write specs manually as markdown files — requirements.md, design.md, tasks.md — review them, then feed them to Claude Code. Tools like claude-code-spec-workflow and GitHub's spec-kit provide templates and slash commands to scaffold the process. The limitation is that manual specs aren't codebase-aware: you're writing from memory rather than from a read of your actual repo. Tekk automates the codebase-grounded part, which is the most time-consuming step to do well manually.
Does Tekk support spec-driven development claude workflows beyond Claude Code?
Yes. The Tekk planning pipeline works regardless of which coding agent you use to execute. The spec Tekk generates is a structured markdown document — you can take it into Cursor, Codex, or any agent that accepts context files. Claude Code is a first-class integration on the execution side (via MCP), but the spec output is agent-agnostic.
Start Planning Free
You already know spec-driven development produces better results with Claude Code. The part that slows everyone down is writing a spec that's actually grounded in the codebase.
Connect your repo, describe what you're building, and get a spec Claude Code can execute.
[Start Planning Free →]