Je hebt elf lessen gelezen. Je kent de patronen. Je hebt types, domeinen, events, quality gates en documentatie.
Nu de vijf manieren waarop developers dit allemaal saboteren. Meestal met de beste bedoelingen.
Valkuil 1: premature abstraction
Je ziet vergelijkbare code op twee plekken en je extractt meteen een gedeelde utility. Het DRY-principe, toch?
Verkeerde timing. Wacht op de derde keer. De eerste twee voorbeelden delen zelden zoveel als je denkt. Je eindigt met een abstractie die een beetje bij beide past maar nergens perfect. En nu moet je een gedeelde utility onderhouden die lastiger te wijzigen is dan de duplicatie die het verving.
Drie regels gedupliceerde code is beter dan de verkeerde abstractie.
De Rule of Three bestaat niet voor niets. Bij de derde keer snap je het patroon goed genoeg om het correct te extracten. Daarvoor ben je aan het gokken.
Valkuil 2: blinde AI-trust
AI genereert nette, goed geformatteerde, zelfverzekerde code. Het leest alsof iemand het schreef die weet wat hij doet. Die zelfverzekerdheid is precies het probleem.
AI kent je business rules niet. Het weet niet dat "gearchiveerde" projecten nog steeds in rapporten moeten verschijnen. Het weet niet dat je Europese gebruikers datums als DD/MM verwachten. Het genereert wat er goed uitziet op basis van patronen. Niet wat correct is voor jouw domein.
De oplossing: review elke gegenereerde functie zoals je een pull request van een junior zou reviewen. Stel drie vragen:
- Doet het wat ik vroeg? (Niet wat het aannam dat ik vroeg)
- Volgt het onze patronen? (Niet zijn eigen verzonnen patronen)
- Kan het stil falen? (De gevaarlijkste bugs zijn degene die niet crashen)
Valkuil 3: big-bang refactoring
"Laten we twee weken nemen om alles op te schonen."
Klinkt verantwoordelijk. In de praktijk gebeurt dit: het team stopt twee weken met features shippen. Ze introduceren 40+ bugs door grote wijzigingen. De refactoring duurt drie weken in plaats van twee. Feature requests stapelen zich op. En als ze eindelijk weer gaan shippen, is de codebase binnen een maand weer rommelig.
De oplossing: kleine verbeteringen elke dag verslaan geplande herschrijvingen. De Boy Scout Rule (laat elk bestand iets schoner achter) telt op over tijd. Je hebt de cijfers gezien: 40 features geshipt met slechts 45 uur refactoring verspreid over 6 maanden.
Valkuil 4: documentatie overslaan
"Ik documenteer het later wel."
Dat ga je niet doen. Niemand doet dat. En elke dag zonder documentatie gokt je AI-partner in plaats van patronen te volgen. Je gooit de investering weg die het meeste oplevert.
Negentig minuten om je .claude/ directory op te zetten. Meer is het niet. AI-nauwkeurigheid springt van 40% naar 90%. Prompt-lengte daalt van 500 woorden naar 50. Je verdient die tijd binnen een dag terug.
De oplossing: schrijf de docs voordat je ze nodig hebt. Vijf bestanden, 90 minuten. Doe het vandaag.
Valkuil 5: perfection paralysis
De code werkt. Tests slagen. Maar je blijft zitten tweaken. Die variabelenaam kan beter. Die functie kan schoner. Misschien als je dit nog een keer herstructureert...
Ondertussen gebruikt niemand de feature. Nul gebruikers halen er waarde uit. Je perfecte code zit in een branch. Perfect aan het zijn voor een publiek van een.
De oplossing: time-box je verbeteringen. Fase 2 krijgt 30 minuten. Timer af? Ship wat je hebt. Het is goed genoeg. "Goed genoeg en gedeployd" verslaat "perfect in een branch." Elke keer.
Dat is het complete systeem
Architecture First is geen filosofie. Het is een praktijk. Begin met de .claude/ directory. Voeg types toe. Trek domeingrenzen. Je eerste feature gaat 5x sneller. Bij de vijfde vraag je je af hoe je ooit anders werkte.
De developers die floreren met AI zijn niet de snelste coders. Het zijn de helderste denkers. Zij nemen de architectuurbeslissingen die AI veranderen van een fancy autocomplete in een echte force multiplier.
Ga nu iets bouwen.