Van idee naar specificatie: zo bouwt AI wat je echt bedoelt

Wie Claude Code vraagt om een boekingssysteem te bouwen, heeft al snel iets dat werkt. Alleen werkt het zoals Claude dacht dat je het wilde. Mag een klant op de dag zelf nog afzeggen? Duurt een eerste afspraak even lang als een vervolgafspraak? Over al zulke dingen heeft Claude dan een keuze gemaakt, meestal de keuze die je in andere systemen het vaakst ziet. Een specificatie voorkomt dat. Het is een kort document waarin staat wat je bouwt en voor wie, en ook wat er bewust niet in zit. De snelste manier om er een te maken, is Claude jou eerst te laten interviewen.

Waarom een vage opdracht duur uitpakt

Anthropic zegt het in zijn adviezen voor Claude Code zonder omwegen: Claude kan je bedoeling afleiden, maar geen gedachten lezen. Elke keuze die jij niet maakt, maakt Claude voor je, en een keuze die niet past, zie je pas terug als iets dat net anders werkt dan je verwachtte. Een ontbrekende keuze vinden in een gesprek kost je een minuut. Dezelfde keuze herstellen in een platform dat al draait, kost een avond, omdat er code en gegevens aan vastzitten.

Een specificatie maakt die keuzes zichtbaar voordat er iets gebouwd is. Hij is daarna ook het ijkpunt voor alles wat volgt. Claude leest hem voor elke bouwstap, en jij legt het resultaat ernaast om te zien of het klopt. Hoe je in het algemeen een vraag stelt waar AI iets mee kan, lees je in Een goede vraag stellen aan AI.

Laat Claude de vragen stellen

Zelf een specificatie schrijven is lastig, omdat je niet weet wat je vergeet. Daarom laat je de rollen wisselen: Claude vraagt, jij geeft antwoord. Anthropic raadt dat zelf aan voor grotere klussen. Begin met een korte beschrijving en vraag Claude om je uitgebreid te interviewen met AskUserQuestion. Dat is een functie in Claude Code waarmee Claude je meerkeuzevragen stelt. Je klikt een antwoord aan. Past er geen, dan schrijf je zelf een antwoord. Anthropic adviseert Claude te laten doorvragen op de moeilijke punten in plaats van op de voor de hand liggende, en pas te stoppen als alles besproken is.

Vrij vertaald naar het voorbeeld van Anthropic ziet zo’n opdracht er zo uit:

Ik wil een boekingssysteem voor mijn praktijk. Nog geen code: eerst wil ik
een specificatie. Interview me uitgebreid met je vraagfunctie AskUserQuestion.
Sla de voor de hand liggende vragen over en vraag door op de lastige
punten waar ik zelf nog niet aan heb gedacht. Als alles besproken is,
schrijf je een volledige specificatie in specificatie.md, in eenvoudig
Nederlands.

Zet het interview er uitdrukkelijk in. Staat Claude Code in auto mode, dan werkt Claude anders liever door dan dat hij tussendoor vragen stelt.

Zeg gerust dat je iets niet weet. Juist daar zit vaak de belangrijkste keuze. Laat Claude de opties dan naast elkaar zetten, met de gevolgen voor jou en je klanten, en beslis daarna.

Een voorbeeld: de praktijk van Fatima

Fatima is fysiotherapeut en werkt alleen, vier dagen per week. Nu maken klanten een afspraak per telefoon of app, en die beantwoordt ze in de pauzes tussen twee behandelingen. Ze wil dat klanten voortaan op haar site zelf een tijd uitzoeken. Het interview bracht vragen boven die ze nog nooit had uitgedacht.

Moet een intake langer duren dan een gewone behandeling? Ja, dus het systeem moet weten om wat voor afspraak het gaat. Mag een klant zelf verzetten, of alleen annuleren? Alleen annuleren, en tot een dag van tevoren; daarna belt de klant de praktijk. Hebben klanten een account nodig? Nee, een bevestiging per mail met een link om te annuleren is genoeg. Vraagt het formulier naar de klacht? Nee, want dat zijn gegevens over iemands gezondheid, en voor het inplannen heeft ze die niet nodig. En online betalen bewaart ze voor een latere versie.

Elk van die antwoorden had Claude anders kunnen invullen. Nu staan ze in de specificatie, en weet Fatima wat ze krijgt voordat er één regel code bestaat.

Wat erin moet staan

Een bruikbare specificatie past op een paar schermen. Iemand die je idee niet kent, moet na het lezen kunnen uitleggen wat er gebouwd wordt. Loop hem na op deze punten:

• waarvoor het platform is en wie het gebruikt;
• wat elke soort gebruiker kan zien en mag doen, en wat juist niet;
• de belangrijkste handelingen, beschreven als een reeks stappen;
• elk gegeven dat je opslaat, met de reden en hoe lang je het bewaart;
• afspraken over de randgevallen, zoals afzeggen of een agenda die vol zit;
• wat bewust pas in een latere versie komt;
• hoe je aan het eind van begin tot eind controleert dat alles werkt.

Anthropic noemt onder meer twee dingen die een specificatie bruikbaar maken: dat erin staat wat buiten de opdracht valt, en dat hij eindigt met een controle van begin tot eind. Lees hem door de ogen van een buitenstaander. Wat niet klopt, laat je aanpassen of verbeter je zelf in het bestand. Leg hem vast met git, en laat in je CLAUDE.md zetten dat Claude de specificatie leest voordat hij iets bouwt.

Van specificatie naar bouwplan

Met een specificatie op papier begint het bouwen nog niet meteen. Eerst laat je Claude een bouwplan maken, het liefst in plan mode, de stand waarin Claude onderzoekt en plannen schrijft zonder iets te veranderen (zie Plan mode, auto mode en toestemming). Vraag om een handvol stappen, zeg vijf tot acht, die elk een zichtbaar resultaat hebben. Bij Fatima begon dat met de database en een paar verzonnen afspraken, en kwam daarna haar eigen beheerscherm, voordat er iets voor klanten was. Na elke stap draaien de tests en kijk je zelf. Pas als het klopt, legt Claude de stap vast met een commit.

Anthropic raadt aan om het bouwen in een nieuwe sessie te beginnen als de specificatie af is. Dat gesprek start dan zonder al het heen en weer van het interview, met de geschreven specificatie als houvast. Typ daarvoor /clear, of start Claude Code opnieuw.

Wil je eerst zien hoe het eruit kan zien, laat Claude dan een paar sterk verschillende schetsen maken als losse HTML-pagina’s, zonder database erachter. Anthropic doet het in zijn workshop How We Claude Code ook zo, met de materialen op GitHub: eerst van interview naar specificatie, dan vier uiteenlopende ontwerprichtingen als losse pagina’s, en pas daarna de app zelf. Kiezen tussen vier schetsen is makkelijker dan één ontwerp beoordelen.

Heb je een idee voor een platform, begin dan niet met bouwen maar met het interview. Trek er een uur voor uit en zeg eerlijk wat je niet weet. Lees de specificatie die eruit komt een dag later nog eens met frisse ogen, en schrap wat niet in de eerste versie hoeft. Wat er verder bij een eigen platform komt kijken, lees je in Zelf een app of platform bouwen zonder programmeerervaring. In de leerlijn Platformen van het online programma doe je dit met je eigen idee.