Documentatie als code: de directory die alles verandert

Deze zin klinkt fout maar is het niet: het meest impactvolle dat je als developer kunt doen is vijf markdown-bestanden schrijven.

Geen code. Geen tests. Geen betere CI-pipeline. Gewoon markdown-bestanden.

Klinkt absurd. Tot je de cijfers ziet. Voor we onze conventies documenteerden genereerde AI bruikbare code in zo'n 40% van de gevallen. Daarna? Zelfde AI, zelfde prompts. 90%.

Het verschil? AI kan niet gedachten lezen. Maar het kan wel je docs lezen.

De vijf bestanden die alles veranderen

In totaal kost dit zo'n 90 minuten. Die tijd heb je de eerste dag al terug.

1. ARCHITECTURE.md

Je tech stack en waarom. Welk framework, welke ORM, hoe authenticatie werkt. AI stopt met Express voorstellen zodra het ziet dat je FastAPI gebruikt. Stopt met MongoDB aanbevelen als je op PostgreSQL zit.

# Architectuur
- Backend: FastAPI + SQLAlchemy 2.0 (async)
- Frontend: React 18 + TypeScript + Vite
- Database: PostgreSQL 15+ met RLS
- Auth: JWT tokens, bcrypt hashing
- Kernpatroon: domain-driven, event-based

2. DOMAIN_PATTERNS.md

De blauwdruk voor elke feature. Directorystructuur, waar business logic leeft, hoe endpoints zijn aangesloten. AI genereert code die past in je structuur. In plaats van z'n eigen te verzinnen.

# Elk domein volgt deze structuur:
domains/{name}/
  __init__.py      # Publieke API
  models.py        # SQLAlchemy models
  schemas.py       # Pydantic schemas
  service.py       # Business logic (ALLEEN hier)
  router.py        # Dunne endpoints
  events.py        # Domein-events
  tests/           # Unit + integratie

3. API_CONVENTIONS.md

URL-patronen, statuscodes, paginatieregels, authenticatie-headers. Elk endpoint dat AI genereert volgt dezelfde regels als de endpoints die je zelf schreef.

4. DATABASE_PATTERNS.md

Naamgeving voor tabellen, standaardkolommen die elke tabel krijgt, hoe je indexes noemt, enum-handling in migraties. Nooit meer gegenereerde schema's die conflicteren met je bestaande database.

5. TESTING_STRATEGY.md

Wat je test, hoe je tests noemt, hoe fixtures eruitzien. AI schrijft tests die echt thuishoren in je suite. Niet van die generieke tests die framework-gedrag testen.

Het bewijs

Metriek	Zonder docs	Met docs
Tijd per domein	3-5 dagen	1-2 dagen
AI first-try nauwkeurigheid	40-60%	85-95%
Regels herschreven na generatie	60-70%	5-15%
Benodigde promptlengte	400-600 woorden	50-100 woorden

Houd ze levend

Docs die niet kloppen met de werkelijkheid zijn erger dan geen docs. Ze sturen AI actief de verkeerde kant op. Drie regels:

De 10-minutenregel: kost een doc-update meer dan 10 minuten? Te gedetailleerd. Kort in. Dit zijn referentiekaarten, geen handboeken.
Update-triggers: nieuwe architectuurbeslissing, patroonwijziging, nieuw domein, bug door inconsistentie, verwarring bij onboarding.
PR-checklist: verandert deze PR een architectuurpatroon? Dan moeten de docs mee.

Probeer dit

Maak een .claude/ directory in je huidige project. Begin met ARCHITECTURE.md. Beschrijf je stack, je belangrijkste beslissingen, je patronen. Kost 20 minuten. Vraag daarna AI om een nieuw endpoint te genereren. Vergelijk het met wat het eerder genereerde.

Je ziet het verschil meteen.