How to Write a Spec for Claude Code by Talking (2026)

Spec-driven development, writing a short spec before you let an AI coding agent touch the code, is the most reliable way to get good output from Claude Code, Cursor, or Codex. The hard part is not the template, it is the thinking: the edge cases, the constraints, and the "what should happen when" decisions. That thinking happens best away from the keyboard, on a walk or a commute, and talking is roughly three times faster than typing, so you say more of it. The workflow is to talk the feature through for five minutes, turn the recording into a structured spec, then paste it into your repo and open plan mode. Flint does the middle step on your phone. It does not type into your terminal; it gives you the spec to paste.

In 2026 most developers who use AI coding agents seriously have landed on the same lesson. Vibe-coding works for small changes. The trouble starts when a feature touches many files, because by then the hard part is the design decision, not the implementation. Hand an agent a vague prompt for a complex change and it quietly makes dozens of architectural calls for you: file structure, naming, error handling. The fix everyone recommends is a spec. The problem nobody talks about is how painful it is to actually write one.

Why Specs Beat Prompts for Anything Non-Trivial

A spec is a short document that says what a change should do before any code is written: the goal, who it is for, the constraints, what is out of scope, and how you will know it works. You commit it next to the code, turn it into a plan, and let the agent implement against that plan one step at a time with a human review in between.

The approach has become standard enough that there are whole frameworks for it, including GitHub Spec Kit, Superpowers, and BMAD-METHOD, and most serious Claude Code guides now recommend a spec file plus a plan mode session before any implementation begins. Specs also outlive the first prompt. You reference them when checking whether an implementation matches the requirements, when something unexpected comes up and you need to decide if it is in scope, and when you return to the feature a week later.

A spec also carries different information from your project's CLAUDE.md. CLAUDE.md tells the agent about your conventions and architecture across every session. The spec tells it what you are building right now.

The Bottleneck Is the Thinking, Not the Template

There is no shortage of spec templates. What slows people down is filling them in. A good spec forces you to answer the uncomfortable questions: what happens on an empty state, what the failure modes are, which existing behaviour must not change, what you are deliberately not building. Those answers are the whole value of the document, and they are exactly the part developers skip when typing, because typing three paragraphs of context feels like a chore.

This is a known effect. A slow keyboard quietly discourages detail: you abbreviate, you skip the edge cases, and you write "fix the auth bug" instead of the context that would actually have fixed it. Better input produces better agent output, and typing caps how much input you are willing to give.

There is also a location problem. The best design thinking rarely happens while staring at an editor. It happens on a walk, in the shower, or on the train, when you are not in the middle of the code and can see the shape of the problem. By the time you are back at your desk, half of it has gone.

Why Voice Fits the Spec Phase Specifically

People speak around 150 words a minute and type around 40, which is why coding agents themselves have added microphones. Claude Code shipped a built-in voice mode in March 2026, and OpenAI's Codex added voice input around the same time.

But there is a difference between the two phases of agentic coding. Dictating a prompt into a terminal is an at-the-desk activity, and dedicated dictation tools do that job well. Thinking a feature through is a different activity. You are not issuing an instruction yet; you are working out what the instruction should be. That part benefits from being away from the screen, rambling a bit, contradicting yourself, and catching the edge case halfway through a sentence.

The catch is that a raw ramble is a bad spec. It is full of false starts, repeated points, and "actually, no" moments. Even people who pipe speech straight into coding agents recommend polishing raw transcripts with an LLM first, because Whisper-style transcripts come out with filler and run-on sentences. So the step you need is ramble in, structured spec out.

The Workflow: Walk, Talk, Spec, Plan

1. Talk it through away from the desk. Pick up your phone and talk for three to five minutes as if explaining the feature to a colleague who will build it. Cover what it should do, why it matters, the constraints, the edge cases, what it must not break, and what is out of scope. Don't organise anything. Just say it.

2. Turn the recording into a spec. Convert the ramble into a structured document with sections like summary, requirements, edge cases, out of scope, and acceptance criteria. This is the step that makes voice usable.

3. Put the spec in the repo. Save it where your workflow expects it, a specs folder or whatever your team uses, and read it once with fresh eyes. Editing it yourself is what turns it from a transcript into your document.

4. Open plan mode. Point the agent at the spec and ask for an implementation plan before any code. Because the spec already carries the functional detail, the planning prompt can be short. Review the plan, make the architectural calls yourself, then let it build.

The whole voice part adds maybe ten minutes, and it tends to replace the much longer back-and-forth of correcting an agent that guessed wrong.

How to Do It With Flint

Flint handles step two. You record the ramble in one press, and on iPhone you can start from the Action Button or Lock Screen widget without unlocking, so you can catch the idea mid-walk. Flint transcribes it and turns it into a structured note, and its custom format lets you define the exact shape you want, so you can set up a spec format once (summary, requirements, edge cases, out of scope, acceptance criteria) and reuse it for every feature. If the result misses something, add an instruction like "make the acceptance criteria testable" or "pull the edge cases into their own list" and regenerate instead of editing by hand.

It also keeps the original audio next to the note, so if a requirement in the spec looks off, you can go back and hear what you actually said. And because every spec note stays searchable, you can later ask across your notes for why you made a particular design call months ago.

Flint is local-first, meaning your recordings stay on your device rather than in a vendor's archive, which matters when you are describing unreleased features. It is a one-time $12 with a free tier to try it, not another monthly subscription on top of your AI coding bill.

When This Doesn't Fit

Be clear about what Flint is not. It is not a dictation tool. It does not type into your terminal, IDE, or Claude Code's prompt, and it has no integration with Git, GitHub, or any coding agent, so you copy the spec across yourself. If what you want is to talk directly into Claude Code at your desk, use its built-in voice mode or a system-wide dictation app.

It is also local-first rather than fully offline, since some AI processing happens in the cloud. If your company forbids any description of unreleased code leaving the device, check that against your policy first, or keep spoken specs at the product level and leave out internal names and secrets. Never say API keys, credentials, or customer data into any voice app.

And for tiny changes, skip all of this. A one-line fix does not need a spec. This workflow earns its time on features that touch several files or involve real design decisions.

Flint is available on the App Store and on Google Play.

Frequently Asked Questions

What is spec-driven development? A way of working with AI coding agents where you write a short spec describing what a change should do before any code is written, turn it into a plan, and have the agent implement against the plan with human review between steps. It prevents the agent from silently making design decisions for you.

How do I write a spec for Claude Code? Cover the goal, who it is for, requirements, edge cases, what is out of scope, and acceptance criteria. Save it in your repo, then open plan mode and ask Claude Code to produce an implementation plan from it before writing code.

Can I dictate directly into Claude Code? Yes. Claude Code added a built-in voice mode in March 2026, and system-wide dictation tools also work. That is best for issuing prompts at your desk. Talking a feature through away from the desk and turning it into a spec is a separate step.

Why speak a spec instead of typing it? Speaking is roughly three times faster, and people include more context and edge cases when talking than when typing, which is exactly what makes a spec useful. You can also do it away from the keyboard, where design thinking often happens.

Won't a spoken ramble make a messy spec? A raw transcript would. The step that matters is turning the recording into a structured document with clear sections, then reading it once yourself before handing it to the agent.

Is it safe to describe unreleased code in a voice app? Keep specs at the product and behaviour level, leave out secrets and credentials, and check your company's policy. Flint is local-first, so recordings stay on your device, but some AI processing happens in the cloud.

The best specs start as a walk, not a blank file. With Flint, talk the feature through in five minutes, get back a structured spec in your own format, and paste it into your repo before you open plan mode. One-time $12, free to try. Download Flint on the App Store or Google Play.