Why a project falls apart at the third revision, and what spec coding is
The first attempt is a delight, the third a dead end: fixing the form breaks the menu, fixing the menu breaks the block from the second attempt. The cause is structural: the project has no description, only a history of requests. Below is a different order of work and the six points that set it.
The first attempt is a delight, the third a dead end: fixing the form breaks the menu, fixing the menu breaks the block from the second attempt. The cause is structural: the project has no description, only a history of requests. Below is a different order of work and the six points that set it.
---
Day one delight, day three a dead end
A familiar curve for anybody who has tried building something with AI.
The first attempt. You described the idea and got a working page. In an evening. Delight.
The second. You asked for a block to be added — it got added and everything works. More delight.
The third. You asked for the form to change — it changed, but the menu stopped working. You fix the menu and the block from the second attempt breaks.
The fifth. You no longer remember what was there originally, and neither does the model. Easier to start again.
And plenty of people do start again — for the third time.
The cause is not that the model is getting stupider. The cause is that the project has no description, only a history of requests.
Why this happens
Let us go through the mechanics, because without them it is unclear what to fix.
The model does not remember your project. It sees what you showed it in this conversation. Everything decided earlier and left in your head does not exist for it.
Every request is a new task with no context. You say "change the form" and the model changes the form. It does not know that three attempts ago you agreed the form's data goes to a particular place in a particular shape. It will redo that, because nobody told it.
Decisions accumulate; the description does not. By the fifth revision the project has two dozen implicit rules, none of them written down. Every new request has a chance of breaking any of them.
That is not a problem with a particular model and not a problem of bad prompts. It is a structural problem of working "by request".
What spec coding is
A different order of work. One phrase instead of the whole explanation: the description first, the build second.
Not "make me a landing page" followed by twenty clarifications, but first a document saying what has to come out — and then the build from it.
The difference looks like this.
*Working by request:* request → result → revision → result → revision → chaos.
*Working from a description:* description → build → change to the description → rebuild of the necessary part.
The key thing in the second scheme: what gets corrected is the description rather than the project. The project gets brought into line. So changes do not accumulate as a layer of patches — they are always consistent with one source.
What goes in the description
Not a forty-page specification. Six points are enough.
What this is and who for. One or two sentences. Who needs it and what problem it solves. Without that the model makes something "in general" rather than "for this".
The screens and what is on them. A list of pages or states with the content of each.
What happens on actions. A button gets pressed — what happens. A form gets submitted — where it lands. Wrong data gets entered — what gets shown.
Where the data lives. What has to be saved and what only lives in the session.
What must not exist. The most skipped point and the most useful: a list of explicit prohibitions. Do not collect extra data, do not change the structure of what exists, do not add features nobody asked for.
What already works and must not be touched. A list of what is finished. That is exactly what saves you from the third revision breaking the second.
How this works in practice
Step 1. Describe it before the first request. The six points above. Twenty minutes of work, and they pay for themselves on the second revision.
If phrasing it is hard, ask the model to draft the description from your idea: you describe the task in words and get a structured document, then correct it. Correcting something finished is faster than writing from scratch.
Step 2. Build from the description. Hand over the document whole rather than a summary.
Step 3. Change the description rather than the project. Something new is needed — put it in the document first, then ask for the change with a reference to the updated text.
Step 4. Keep a list of untouchables. Every revision request ends with a sentence on what must not be changed. That is one line, and it prevents most breakages.
Step 5. After every revision, check more than the new part. What worked before has to be checked too. Five minutes against an hour of untangling.
Why this matters especially when you are not writing the code
A programmer who wrote it by hand holds the project in their head: they remember why something was done that way and will not break it accidentally.
You do not remember, because you did not write it. And the model does not remember, because it does not store it.
The description replaces what neither of you has — the project's shared memory.
Hence a non-obvious conclusion: the less you understand code, the more important the description is for you. It is not for the model, it is for you.
What this gives you with a client
The description is the specification. The same document gets shown to a client before the start: this is what will come out. Agreed, then built.
It closes off endless revisions. "Addressing comments to the client's full satisfaction" is the phrasing that has freelancers working for months unpaid. Comments get accepted within the agreed description; everything else is separate work for separate money.
It protects you on handover. A project with a description can be passed to somebody else. A project with no description cannot be passed at all — and that is your problem when you want to pass it on.
And it justifies the price. A client looking at a document of six sections argues with the items rather than the total.
What is available on the platform
Website templates — 343 prompts, and they are built exactly on this principle. Each card is not "make a landing page" but a full specification: structure, typography, colours, how animation behaves on hover and scroll. Around 10 000 characters on average, the most detailed up to 75 000.
So the description has already been written for you, by somebody who knows what belongs in one. The preview is visible before you run it.
The prompts are not tied to a particular service: they paste into any environment that can write code. The Plus plan.
Skills for Claude Code — more than 10 000. A skill is a chain of agents where a task is split into parts and each gets passed on — the same logic as spec coding, only inside one tool. The catalogue is open to everyone, the files come with Basic.
The engineering assistants — from Basic. They will help draft a description from your idea.
Registration is free and opens three days of full Basic access.
Where to start today
One action. Take a project that is falling apart and write the six points for it retrospectively. Particularly the last: what already works and must not be touched.
Twenty minutes. Then make your next revision request with a reference to that document and an explicit list of untouchables.
Usually the project stops breaking immediately after that — not because the model got cleverer but because it finally has what it never had: a description of what it is fixing.
---
Why a description works: the mechanics of cascades
Spec coding is a particular case of a general principle, and module 3 covers it separately.
Cascading prompts. A large task gets broken into a chain of small requests and the model goes through them step by step.
Why that is needed — the phrasing from the lesson: each individual request is precisely focused, the model does not spread itself thin and solves one specific sub-question. You control every step, check the intermediate answers and direct what comes next.
The example straight from the lesson is building a landing page: first work out the structure, second write the headlines, third the block copy, fourth the detail.
The conclusion that explains the whole article: you lead the model along a clear plan, like a scriptwriter. A project description is exactly such a plan, only written once and reusable.
Module 3 — the Basic plan.
---
What to read next
[App architecture as a building](/en/blog/app-architecture-as-building) — so revisions go to the right address.
[A 30 000-character brief](/en/blog/prompt-30000-characters) — what a real description looks like.
[From prototype to product](/en/blog/prototype-to-product) — what to add once it has stabilised.
[Skills for Claude Code](/en/blog/claude-code-skills-guide) — chains instead of a single request.