I’ve been writing specs instead of code for most of my work lately. A markdown file describing what I want, fed to Claude Code, produces working implementations in minutes. When something breaks, I fix the spec and regenerate. The code is disposable. The spec is the product.
Sean Grove from OpenAI put it well at the AI Engineer World’s Fair:
Treating prompts as disposable while carefully version-controlling generated code is like shredding the source and then very carefully version controlling the binary.
I’ve been writing specs over code for a few months now and it’s working exceedingly well with my agent swarms.
The spec is the source code
AI coding tools got good enough this past year that writing code is no longer the bottleneck. Claude Code, Cursor, Copilot, Windsurf, Gemini CLI all translate intent into working implementations. The scarce resource now is clear thinking expressed in plain language.
Guy Podjarny from Tessl lays out three stages of adoption. Stage one is spec-assisted: you give the AI structured context like coding standards and architecture docs, and unlike a human developer who skims the README, the AI actually reads every word. Stage two is spec-driven: you modify the spec first, then apply the change to code. Stage three is spec-centric: comprehensive specs and tests make code fully disposable. You regenerate implementations without carrying forward technical debt.
Most teams I talk to are somewhere between stage one and two but the trajectory is clear.
What it looks like in practice
Alex Op documented a spec-driven workflow with Claude Code that migrated a storage layer from SQLite to IndexedDB. Fifteen files, 14 atomic commits, about 45 minutes. The AI researched the problem in parallel, consolidated findings into a spec, asked clarifying questions, then delegated individual tasks to subagents that each produced one commit.
The part that sold me: the spec survives session restarts and context window limits. When things go sideways, you open a new chat with the pinned spec and pick up where you left off. No re-explaining.
We’ve lived this building Basic Memory. Context evaporation is the core problem we set out to solve, and a well-written spec in markdown is immune to it.
Good specs leave room
A good spec doesn’t need to specify every detail. It defines what matters — business rules, constraints, success criteria — and lets the AI figure out the how. Podjarny calls the incompleteness a feature. The same spec can produce different implementations for different contexts.
Writing good specs is harder than it sounds. You’re communicating intent and constraints to an intelligent system that makes implementation decisions on your behalf. You have to think through edge cases, constraints, and failure modes before a single line of code exists. The better your spec, the better those decisions.
The tooling already exists
Multiple open-source frameworks support this today. Claude-code-spec-workflow walks you from requirements through tasks to implementation. CC-SDD brings structured requirements to Claude Code. OpenSpec provides general-purpose spec-driven development for any AI coding assistant. AGENTS.md is becoming a standard for putting project rules in one place any AI agent can consume.
Pre-commit hooks validate generated code against specs. AI spawns subagents that each handle one atomic piece. The whole thing runs on markdown files in version control, reviewed in PRs, iterated on collaboratively.
Podjarny forecasts that by end of 2027, developers using AI agents will rarely examine generated code directly. Think about how rarely you look at compiled bytecode today. The abstraction layer just moves up.
Your specs need memory
All of this works well inside a single project and a single session. But real work spans projects, sessions, and tools. Your architectural decisions from three months ago should inform the spec you’re writing today. The debugging pattern you discovered last week should be available when you hit something similar next month.
I’ve been keeping my specs, architectural decision records, and project rules in Basic Memory for months. The first draft of this blog article was written with a spec. When I start a new Claude Code session, the AI builds context from everything I’ve written, follows connections between related decisions, and produces specs consistent with past work. No re-explaining the architecture. No contradicting last month’s decisions because the AI forgot about them.
The markdown file is the product. Everything else is generated. Try it for a week. Write a spec, hand it to your AI tool of choice, and see what comes back. Fix the spec instead of the code. You probably won’t go back.
We’re building AI memory for humans. Basic Memory keeps your specs, decisions, and context in plain markdown you own, connected through a semantic knowledge graph that any AI tool can read. Basic Memory Cloud is the best way to connect your context to your own thoughts.
— Drew Cain, Basic Memory
Further Reading: