Werkwijze en regels

Dit project wordt grotendeels gebouwd met AI-agents (Cursor, Claude Code) die onder begeleiding taken uitvoeren. De afspraken hieronder gelden voor mens en agent. De agent-versie ervan staat in AGENTS.md in de repo-root; wijk je hier af, werk dan beide bij.

Eén issue per sessie

Open werk staat in Linear, team Okhema. Taken is het historische werklog per fase, geen opdrachtlijst.

• Begin bij de Linear-issue (inclusief parent en blockers), niet bij het volgende open vinkje in Taken. Respecteer blockedBy en begin geen taak uit een volgende fase voordat de huidige fase in Linear af is.
• Geen Linear-issue en geen expliciete opdracht: vraag na. Is Linear onbereikbaar, zeg dat en stop — val niet stilzwijgend terug op Taken.
• Een grotere taak begint met een plan: vastgestelde versies, keuzes met reden, stappen, “klaar wanneer” en wat bewust buiten scope blijft. Zie Taakplan 2.1 als voorbeeld.
• Na uitvoering: Linear-issue bijwerken (status, commentaar met bewijs en afwijkingen). Is het een genummerde fasetaak, werk dan óók Taken bij. Alleen afvinken in Taken is niet klaar.
• Werk op een eigen branch en merge via een pull request naar main.

Blijf binnen de scope

Zie je buiten de taak iets dat beter kan, meld het dan in plaats van het te wijzigen. Voeg geen dependencies toe die niet gevraagd zijn: geen linters, testrunners, CI-configuratie of Git-hooks tenzij daar expliciet om is gevraagd.

Verifieer versies

Astro 7.2 verscheen op 6 augustus 2026 en zit niet in de trainingsdata van de meeste modellen. Configuratiesyntaxis verschilt tussen majors van Tailwind, Drizzle, Turborepo en Starlight. Controleer daarom vóór je configuratie schrijft:

npm view <pakket> dist-tags
npm view <pakket> engines
npm view <pakket> peerDependencies

Verzin geen versienummers of API-velden. Kon je iets niet verifiëren, zeg dat dan.

De harde regels

Volledig uitgeschreven in Architectuur; hier de kern.

1. Huisstijl komt uit data. Geen kleuren, fonts, radii of spacing in componenten of blokken. Alles via CSS-variabelen uit site.theme.
2. Een pagina is een geordende reeks blokken, opgeslagen als jsonb en gevalideerd met Zod bij schrijven én lezen.
3. Types nooit dupliceren. Raakt een type klantsite én dashboard, dan staat het in @platform/contract.
4. Tenant-context is expliciet. TENANT_ID, DATABASE_URL en SITE_DOMAIN via astro:env (in Nuxt: useRuntimeConfig()). Nooit process.env, nooit een globale databaseconnectie.
5. Engels voor code: bestandsnamen, tabellen, kolommen, variabelen, commit-berichten. Commentaar en documentatie mogen Nederlands.
6. De route-cache is opt-in per publieke pagina en wordt nooit vanuit een CMS-pagina aangeroepen. Geen routeRules.

Twee gewoontes die daarbij horen: een nieuw blok is altijd drie dingen tegelijk (schema, renderer, registry-entry), en vermijd gereserveerde Postgres-woorden in namen (testimonials, niet references; sort_order, niet order).

Documentatie hoort bij de taak

Verandert het gedrag van het systeem, werk dan in dezelfde wijziging de documentatie bij: Architectuur, Datamodel of Contract bij structurele wijzigingen, en het runbook onder Beheer en deploy bij operationele. Bij een afwijking tussen code en document wint de code, maar dan wordt het document bijgewerkt. Hoe je een pagina toevoegt staat in Documentatie uitbreiden.

Rapportage aan het eind

Meld na een taak: welke versies je hebt vastgesteld, wat je anders hebt gedaan dan gevraagd en waarom, en waar je twijfelde over een ontwerpkeuze.