AI Spec-Driven Development (AI-SDD) in 2026: Why SDD Is Back and Docs Become Code

Hello, this is Ryuta Hamamoto from TIMEWELL. This is Part 3 of the AI-native new business development series. I spent more than ten years building new businesses inside large companies, led "CHANGE by ONE JAPAN", a challenger-support programme with over a hundred large companies, and now run WARP ENTRE, an AI-driven development programme for founders and intrapreneurs. This article is a complete rewrite, six months on, of the piece I published in March 2026 under the title "AI Spec-Driven Development (AI-SDD)".

Series: An AI-native methodology for new business development

1. Building the mock while you interview
2. Lean Canvas, 7 Powers and design concept in a single day
3. Spec-driven development is back, and documents are becoming code (this article)
4. Growing organisational context with AGENTS.md, Skills, Hooks and cron

Have you ever thrown "build me an e-commerce site" at a coding agent, cold? I have. Something respectable appeared in minutes, I was impressed, and three days later it fell apart. The agent had filled in the details from imagination, the imagination did not match my intent, and the mismatch got built on. Like starting to build a house with no drawings. A great many people had that experience in 2025, and in reaction an old discipline came back in 2026 under a new name: fix the documents before you write code. Spec-driven development. SDD.

I am writing this for people in new-business teams, including those who do not write code. The reason is simple: the "write the documents" step at the heart of SDD is not an engineer's job. It is the job of whoever decides the business. For a read on where your team stands, the AI literacy check takes a few minutes.

Summary: In September 2025 GitHub released Spec Kit and AWS released Kiro, and SDD, having an agent implement from a spec treated as the source of truth, became standard in the major tools. Andrej Karpathy wrote in 2023 that "the hottest new programming language is English", coined "vibe coding" and endorsed "context engineering" in 2025, proposed "agentic engineering" in 2026, and in March's autoresearch showed a setup where the agent edits the code and the human edits the Markdown. The four documents, requirements, specification, basic design and detailed design, differ only in abstraction and can each be written by "draft, review harshly, revise". Beyond the spec, progress records and agent memory have also become things to version and review: something close to code.

From then (March 2026) to now (September 2026): what changed

When I wrote the first version in March 2026, I described SDD as "a concept beginning to spread as a reaction to vibe coding". Six months later, "beginning to spread" has become "standard".

The timeline. On September 2, 2025, GitHub released the open-source Spec Kit. The launch post diagnosed the failure this way: we treat coding agents like search engines when we should treat them like literal-minded pair programmers; they excel at pattern recognition but need unambiguous instructions. So specifications should be rethought, not as static documents but as living, executable artifacts that evolve with the project. Specs become the shared source of truth¹. As of September 12, 2026 the Spec Kit repository has more than 135,000 stars².

Around the same time, AWS shipped Kiro. A Kiro spec consists of three files: requirements.md (user stories and acceptance criteria), design.md (technical architecture and diagrams) and tasks.md (a breakdown into trackable units of work)³. Thoughtworks placed SDD in the Assess ring of its Technology Radar in November 2025, comparing Kiro, Spec Kit and Tessl, whose radical version makes the spec itself the maintained artifact, and adding a caution: the workflows remain elaborate and opinionated, long spec files are hard to review, and "we may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn't scale"⁴.

That reservation is fair. I also think reading SDD as "thicker documents solve it" is a mistake. But as of September 2026, almost every major coding agent has built a "write the spec first" stage into its workflow in some form. How thick to write is still debated. "Don't write one" has disappeared from practice.

Karpathy's three years: from "English" to "agentic engineering"

The quickest way to understand why SDD came back is to follow Andrej Karpathy's statements in order. A founding member of OpenAI and the former head of AI at Tesla, he has spent the last few years coining the words for how to work with AI.

In January 2023 he posted: "The hottest new programming language is English"⁵. It sounded provocative then; it reads like a prophecy now. In February 2025 he coined "vibe coding": give in to the vibes, forget the code exists, let the LLM write it. The implication was that it was great for fun throwaway projects, and not much more⁶. In June 2025, after Shopify's Tobi Lütke wrote that "context engineering" described the core skill better than prompt engineering, "the art of providing all the context for the task to be plausibly solvable by the LLM", Karpathy replied "+1" and continued: people associate prompts with short task descriptions, but in every industrial-strength LLM app, context engineering is "the delicate art and science of filling the context window with just the right information for the next step". Too little, or the wrong form, and it fails; too much, or too irrelevant, and cost rises while performance falls⁷.

Then February 2026. On the first anniversary of vibe coding he wrote a retrospective. Back then LLMs were weaker, so vibe coding was for fun throwaway projects. A year on, programming via LLM agents is increasingly becoming the default workflow for professionals, except with more oversight and scrutiny. The goal is to claim the leverage of agents with zero compromise on software quality. His preferred term for this: "agentic engineering". "Agentic" because the new default is that you are not writing code directly 99% of the time; you are orchestrating agents that do, and acting as oversight. "Engineering" to emphasise that there is an art, a science and expertise to it, something you can learn and get better at⁸.

Lay those statements side by side and SDD's place becomes clear. English became a programming language; the vibe era passed; the skill of designing context was named; and now the way of working, oversight, has a name. To oversee, you must decide in advance what is to be built. The document that records that decision is the spec. SDD is the substance of agentic engineering.

The four documents differ only in abstraction

So what do you write? The pattern I teach in the programme is four documents: requirements, specification, basic design, detailed design. They differ only in the abstraction of what they contain. The left end is readable by an executive; the right end is implementable by an AI as is. In restaurant terms: the requirements document is the business plan, the specification is the menu and the service manual, the basic design is the floor plan and traffic flow, and the detailed design is the kitchen recipe.

Document	Question	Who can read it	What it contains
Requirements	Why and what	Executives, your family	Background and purpose, target, problem, features, what we will not do, success criteria
Specification	How it behaves, from the user's side	Business staff, sales	Screen list, fields per screen, input validation, behaviour on action, behaviour on error, transitions
Basic design	How it is built, from the outside	Builders	Overall structure, screen design, data design, external services, environment separation
Detailed design	How the inside is built	AI, engineers	Database detail, processing flow, validation logic, error handling, environment variable list, security notes

For the same restaurant booking form, the four documents say completely different things. Requirements: "to reduce missed phone bookings; success is twenty bookings a month through the form". Specification: "fields for name, phone, date and time, party size; a confirmation email after submission". Basic design: "three screens, input, confirm, done; where booking data is stored". Detailed design: "the columns and types of the reservations table; the phone number validation rule".

For a new-business team, the first two matter most. Requirements and specification contain no code and no technical vocabulary. And if those two are vague, writing the last two produces a beautiful blueprint for something nobody uses. The most important item in the requirements is "what we will not do". Deciding what not to do matters as much as deciding what to do. If the exclusions are not written, the agent, being helpful, does everything.

The method is the same three-step set for all four: draft, review harshly, revise. Do not skip the middle. That is where precision is decided. The prompt pattern for requirements:

You are an expert supporting product design for a new business. We are going to write a requirements document.
Do not write it yet. Ask me questions first.

# Business context
[Lean Canvas summary and the problems found in customer interviews, with quotes]

# Rules
- At most seven questions. They must cover "who", "what they struggle with", "what counts as success" and "what we will not do"
- If my answer is vague, offer three options and make me choose
- No technical vocabulary. Write at a level my family could read
- When done, write it out as requirements.md with six sections: Background and purpose / Target / Problem / Features / What we will not do / Success criteria

Once written, have it reviewed harshly: "Review this requirements document as a blunt product manager. Point out vague words, unmeasurable success criteria, contradictory requirements, and anything that belongs under 'what we will not do' but is missing. No praise needed." Fold in the findings and finish. The specification, basic design and detailed design follow the same three steps. One rule is absolute: the detailed design lists environment variables by name and purpose only, never the actual API keys or passwords. The documents may end up on GitHub.

Development docs, progress docs and memory docs are code too

Here is what the first version lacked. SDD discussions concentrate on the spec, but once you actually work with an agent, you notice that documents other than the spec matter just as much. I sort them into three kinds.

The first is development documentation: coding conventions, directory conventions, how tests are run, how deployment works. The "operating manual for the project" that the agent reads every time, filed under names like AGENTS.md or CLAUDE.md. AGENTS.md, read by many agents including OpenAI's Codex, Google's Jules and Cursor, bills itself as "a README for agents" and, as of September 2026, is used by more than 60,000 open-source projects⁹.

The second is progress documentation: what is done, what remains, what was decided, what was deferred. Kiro's tasks.md and Spec Kit's task breakdown belong here. Agents carry no memory across sessions. Without a progress document, tomorrow's agent repeats yesterday's deliberation.

The third is memory documentation: the record of "things learned" that the agent writes itself, such as Claude Code's auto memory. In its September 2025 engineering post on context engineering, Anthropic calls context "a critical but finite resource" and lists structured note-taking, saving information outside the context window, as a technique for long tasks¹⁰.

Why call these "code"? Two of Karpathy's 2026 projects show it most clearly. autoresearch, released in March, is a repository in which an AI agent runs language-model training experiments all night. The README says: you do not touch the Python files the way you normally would as a researcher; instead you program the program.md Markdown files that provide context to the agents. train.py is edited by the agent; program.md is edited by the human. program.md is "essentially a super lightweight skill"¹¹. What the human edits directly has moved from code to Markdown.

The LLM Wiki, published in April, goes further. Instead of RAG, retrieving from raw documents on every query, the LLM ingests what it reads and maintains an interlinked Markdown wiki over time. He describes the arrangement as "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." The CLAUDE.md or AGENTS.md that defines the wiki's structure and conventions he calls "the key configuration file", and he recommends a periodic "lint": checking the wiki for contradictions, stale claims and orphan pages¹². Lint is a word for static analysis of code. Running lint on documents is what "documents are code" concretely means.

What has been demanded of code is now demanded of documents. Version them. Review the diffs. Generate tests from the spec and verify. Delete what is stale. Check for contradictions. In practice it comes down to four things.

For code	For documents
Version in git; review diffs	Put specs, AGENTS.md and progress in git; review changes via pull request
Verify correctness with tests	Generate tests from the spec's acceptance criteria to detect drift between spec and code
Delete unused code	Periodically prune "done" items in progress docs and stale learnings in memory
Catch convention violations with lint	Have the agent check documents for contradictions, stale statements and orphans

In new-business terms: the "order form" you used to hand to vendors or engineers lived in someone's head and in meeting minutes. Now it is written as requirements and a specification, handed straight to the agent, and becomes the basis for implementation. If you cannot write it, it cannot be built. If you can, something working appears the same day. The ability to write the documents became the ability to build the business.

The "thick document" trap, and a common corporate misunderstanding

Having read this far, you might think: so write everything, and thickly. No. Thoughtworks' reservation again: long spec files are hard to review, and handcrafting detailed rules for AI does not scale⁴. Karpathy's context engineering post says outright that too much, or too irrelevant, degrades performance⁷. A document's value is decided not by thickness but by whether the staircase of abstraction is built correctly.

Two misunderstandings are common in large companies. One is trying to write the "requirements document" in the several-hundred-page template used by the existing IT department. The requirements document you hand to an agent has six sections a family member could read. The thickness of the template reflects the thickness of the approval process, not precision. The other is treating the document as "written once, done". Like code, documents are updated every time something changes. Fix the code and leave the spec, and the next time the agent reads the old spec it makes a backwards fix. The minimum condition for the spec to remain the single source of truth is that changes start from the spec.

There is also an advantage specific to business development teams. The top two of the four documents double as tools for internal alignment. Show "what we will not do" and "success criteria" from the requirements at the management meeting, and the discussion moves from "sounds interesting?" to "are these the right success criteria?" Show the specification's screen list to sales and you get concrete reactions: "I can explain this screen to customers", "this field will never get filled in on site". The documents are instructions to the agent and explanations to people at the same time.

In WARP we write the four documents on participants' own themes, have the agent implement, and get to something that runs. The methodology continues in Part 4, Growing organisational context with AGENTS.md, Skills, Hooks and cron, which takes documents from a personal discipline to an organisational operation. The programme structure is on the WARP page.

Wrapping up

SDD is not a new technology. The obvious discipline of deciding what to build before writing code simply became mandatory in the age of agents. The four documents, requirements, specification, basic design and detailed design, differ only in abstraction and can be written with "draft, review harshly, revise". And beyond the spec, development docs, progress docs and memory docs have also become things to version, review and check: something close to code. In Karpathy's words, what the human edits is program.md, and the wiki is the codebase.

If you do one thing tomorrow, write just the six sections of a requirements document for the new business you are working on now. Especially "what we will not do" and "success criteria". Any section you cannot write is where you go to interview, per Part 1. If you want to write the four documents on your own theme and take them through to implementation with us, let's talk through a consultation.

Footnotes

1. Spec-driven development with AI: Get started with a new open source toolkit (GitHub Blog, Den Delimarsky, September 2, 2025) ↩

2. github/spec-kit (GitHub, retrieved September 12, 2026; 135,839 stars) ↩

3. Specs — Kiro Documentation (requirements.md / design.md / tasks.md) ↩

4. Spec-driven development — Technology Radar (Thoughtworks, November 5, 2025, Assess) ↩ ↩²

5. Andrej Karpathy (X, January 24, 2023): "The hottest new programming language is English" ↩

6. Andrej Karpathy (X, February 2, 2025): "There's a new kind of coding I call "vibe coding"…" ↩

7. Andrej Karpathy (X, June 25, 2025): "+1 for "context engineering" over "prompt engineering"…" (replying to tobi lutke's June 19 post) ↩ ↩²

8. Andrej Karpathy (X, February 4, 2026): the vibe coding anniversary retrospective and "agentic engineering" ↩

9. AGENTS.md — A simple, open format for guiding coding agents ("used by over 60k open-source projects", retrieved September 12, 2026) ↩

10. Effective context engineering for AI agents (Anthropic Engineering, September 29, 2025) ↩

11. karpathy/autoresearch README (GitHub, March 2026: "you are programming the program.md Markdown files", "train.py — edited by the agent / program.md — edited by the human") ↩

12. LLM Wiki — A pattern for building personal knowledge bases using LLMs (Andrej Karpathy, GitHub Gist, April 4, 2026) ↩