Specs as the Language of Handoff

The skill is the spec, not the prompt

When teams talk about working effectively with AI coding assistants, the conversation almost always lands on prompting. Better prompts. Longer prompts. More context-rich prompts. There are now playbooks, frameworks, and entire roles organized around prompt craft.

We think this is the wrong center of gravity. Prompting is a skill, but it’s a local one. It produces a single useful exchange. The skill that produces a useful system — software that works in production, that survives across sessions and developers, that gets better as the team learns — is something else. It’s spec writing.

A prompt is an instruction. A spec is a contract. The instruction is consumed and gone. The contract persists. And the durable artifacts of an AI-assisted codebase — the ones that compound in value — are the contracts, not the instructions.

What writing a spec actually forces

The thing nobody warned us about: writing a good spec is a real cognitive lift, and that’s the whole point. The lift is doing the work that’s otherwise invisible until something breaks.

When you have to write down what you want as a numbered list of functional requirements, you discover the seams in your own thinking. Two requirements that sounded compatible turn out to contradict each other. A “simple” feature reveals four edge cases you hadn’t named. A data model you assumed would be straightforward needs a column you hadn’t accounted for, and that column changes how three downstream services behave.

This is not new. Anyone who has built non-trivial software knows the “writing the design doc” phenomenon: the act of writing surfaces the things the act of prototyping concealed. What’s new is the leverage. Once the spec exists, implementation moves at a pace that used to be reserved for trivial features. So the value of the spec — the cognitive lift you did up front — pays off across everything that follows.

The spec is what survives the session

Here’s a pattern we have watched repeatedly in teams adopting AI coding assistants: a developer has a productive day-long session, ships meaningful work, and closes the conversation. A week later, someone else picks up the thread. The productive day-long session is gone. The chat history is somewhere — maybe — but the architectural decisions, the rejected alternatives, the “why” that shaped what got built, all live inside that conversation. They are functionally lost.

The spec is what carries that information across. The conversation gets distilled into something portable. The next person — human or AI — reads the spec and walks into the same context the original author walked out of.

This is the most under-discussed property of spec-driven development: it solves the institutional memory problem that long-running AI collaboration creates. The session ends; the spec stays.

The conversation is where you discover what to build. The spec is what makes that discovery survive the conversation.

What makes a spec good

Three properties matter more than length, format, or polish.

Grounded in the actual codebase. A spec that references real module names, real conventions, real prior decisions is implementable. A spec written in the abstract — about a system the AI imagines you have, rather than the one you actually have — produces confidently wrong code. The pre-flight audit, the step before spec writing, is what makes a spec grounded. Skip that step and the spec becomes a wish list.

Decisions made explicit. Specs that read like a list of features are not specs — they’re wish lists. A real spec captures the decisions that were made: the alternatives considered, the tradeoffs weighed, the rationale chosen. When someone — a teammate, an AI session six months later, a new hire — encounters the spec and asks “why is it this way?” the answer is in the document. Specs without rationale produce code that’s easy to undo by accident.

Phased and verifiable. A spec that says “build the feature” is too coarse. A spec that breaks the feature into independently verifiable phases — schema first, then ingestion, then API, then UI — is something an AI can execute against and a human can review against. Each phase is a checkpoint. The spec is right when the phases are right.

Reading specs is becoming a skill of its own

The flip side of spec writing is spec reading. As AI-generated specs become normal, the ability to critique a spec — to see what it’s missing, where it’s overconfident, where the requirements are too coarse to be useful — becomes a load-bearing skill on engineering teams.

In our practice, the spec review is becoming arguably more important than the code review. If the spec is wrong, the implementation will be wrong in a well-structured, hard-to-spot way. If the spec is right, the implementation becomes a verification exercise rather than an open-ended judgment call.

This shifts where senior engineering judgment shows up. It used to be in the code — in the elegant abstraction, the well-named function, the right comment in the right place. Now it’s upstream — in the audit that grounds the spec, the numbered requirement that admits no ambiguity, the design decision that names a tradeoff someone else would have left implicit.

Why this is the durable answer

Models will keep getting better. So will the tooling around them. Today’s prompting techniques will be quaint inside a year. The convention-encoding files, the agent harness configs, the specific scaffolding rituals — all of it is a moving target.

What stays put is the discipline of writing down what you want, why you want it, and how you’ll know it’s right. That practice is durable across model generations and tool ecosystems. The medium shifts; the skill doesn’t.

For teams investing in AI-assisted delivery, the highest-leverage thing to invest in isn’t a better prompt library. It’s the spec writing — and spec reading — practice that will outlive whatever tool you’re using to consume the specs today.

At Kairoi, we structure every engagement around this practice. The spec is what we deliver before we deliver code. It’s how we keep small, senior teams moving fast without losing the institutional context that makes the work compound.