AI Workflow & Regels¶

Instructies voor AI assistenten (Warp Agent) die werken aan het Voedingsgeneeskunde project.

Projectcontext¶

Locatie: /var/www/sites/docs.voedingsgeneeskunde
Technologie: Zensical (Material for MkDocs)
Taal: Nederlands
Doel: Technische documentatie en dagboek voor ontwikkeling van voedingsgeneeskunde.nl
Platform: Drupal 10 met Commerce 2.x

Sessie-afsluitingsprocedure¶

Aan het einde van elke sessie MOET je de volgende stappen uitvoeren IN DEZE VOLGORDE:

1. Sessie-verslag aanmaken¶

Maak een blogpost in docs/sessies/:

Bestandsnaam: YYYYMMDD-korte-beschrijving.md
Format: Markdown met YAML frontmatter

Verplichte frontmatter:

---
title: Korte beschrijvende titel
date: YYYY-MM-DD
tags: [Tag1, Tag2, Tag3]
---

Verplichte structuur: - H1: Volledige sessietitel met datum (bijv. "Sessie 2 januari 2025: Hosting Setup") - Sectie "Doel": Wat was het hoofddoel van deze sessie - Inhoud: Gedetailleerde technische beschrijving van wat er is gedaan - Subsecties: Gebruik H2/H3 voor verschillende onderwerpen - Resultaat/Oplossing: Wat is bereikt of opgelost - Tags: Relevante categorisering (zie lijst hieronder)

2. Overzichtspagina's bijwerken¶

Update de volgende bestanden:

docs/sessies/index.md:
Voeg nieuwe sessie toe in chronologische volgorde (nieuwste bovenaan)
Groepeer per maand en week
Formaat: - [YYYYMMDD-beschrijving](YYYYMMDD-beschrijving.md) - Tags: Tag1, Tag2
docs/index.md:
Update de sectie "Laatste Updates" met korte samenvatting
Voeg datum en 2-4 bullet points toe met hoofdpunten
docs/project-traject.md:
Alleen als de sessie een belangrijke mijlpaal of nieuwe fase vertegenwoordigt
Voeg toe aan de timeline met tags
Groepeer per fase en week
docs/everlasting-todo-lijst.md:
Markeer voltooide taken als DONE
Voeg nieuwe taken toe indien nodig
Houd de lijst actueel

3. Bestaande documentatie bijwerken¶

Als de sessie een specifiek onderwerp behandelde, update de relevante technische documentatie:

docs/documentatie/commerce.md - Voor webshop/commerce wijzigingen
docs/documentatie/user-profiles.md - Voor user management
docs/documentatie/integraties.md - Voor externe diensten (Mollie, Mailchimp, etc.)
docs/documentatie/vgbc.md - Voor VGBC ticket systeem

Voeg nieuwe secties toe of update bestaande met de nieuwe inzichten/wijzigingen.

4. Validatie¶

Voordat je de build draait:

Controleer of alle links werken
Controleer of frontmatter correct is
Controleer of code blocks syntax highlighting hebben

5. Zensical build uitvoeren¶

Na het bijwerken van alle documentatie:

zensical build

Als de build faalt: - Lees de error output zorgvuldig - Los het probleem op (meestal YAML syntax of markdown formatting) - Run opnieuw

Markdown Documentatie-eisen¶

Opmaak¶

GEEN emojis of icoontjes - Pure tekst en structuur
Duidelijke koppenstructuur: Gebruik H1-H6 logisch en consistent
Code blocks: Altijd met taalaanduiding voor syntax highlighting
Lijsten: Voor opsommingen en stappen
Geen markdown tabellen - Gebruik lijsten of geneste structuren

AI-vriendelijke structuur¶

YAML frontmatter voor metadata (title, date, tags)
Beschrijvende kopjes - Geen vage titels zoals "Probleem" maar "Race Condition in Mollie Webhook"
Consistente terminologie - Gebruik dezelfde termen voor dezelfde concepten
Expliciete links - Link naar gerelateerde documenten waar relevant
Code voorbeelden - Volledig en werkend, niet fragmentarisch
Technische details - Bestandspaden, functienamen, class names expliciet vermelden

Schrijfstijl¶

Toon: Technisch maar toegankelijk
Perspectief: Gebruik "we" voor gezamenlijke acties, beschrijvend voor technische details
Tijd: Gebruik verleden tijd voor sessieverslagen, tegenwoordige tijd voor documentatie
Structuur: Begin met context, dan probleem, dan oplossing

Doorzoekbaarheid¶

Schrijf specifieke termen en concepten volledig uit
Gebruik tags voor categorisering
Vermijd afkortingen zonder uitleg bij eerste gebruik
Gebruik volledige paden en bestandsnamen (bijv. web/modules/custom/vgbc/src/EventSubscriber/PaymentWebhookHandler.php)

Communicatie en Werkwijze¶

Destructieve handelingen¶

ALTIJD EERST OVERLEGGEN voordat je: - Bestanden verwijdert - Bestanden overschrijft (tenzij expliciet gevraagd) - Database-wijzigingen doorvoert (DROP, TRUNCATE, DELETE zonder WHERE) - Config-wijzigingen uitvoert op productie - Git commits maakt of pusht - Composer packages verwijdert - Drupal modules uninstalled

Vraag: "Mag ik [actie] uitvoeren?" en wacht op bevestiging.

Werk tempo¶

Werk niet te snel door - neem tijd voor belangrijke beslissingen
Leg uit wat je gaat doen bij complexe of onomkeerbare operaties
Vraag bevestiging bij twijfel
Geef updates tijdens langdurige operaties

Sessie workflow¶

Start:
Check docs/everlasting-todo-lijst.md
Lees relevante documentatie in docs/documentatie/
Vraag naar prioriteiten als er meerdere taken zijn
Tijdens werk:
Test wijzigingen waar mogelijk
Documenteer belangrijke bevindingen
Communiceer over blokkades of onverwachte problemen
Einde:
Maak sessie-verslag
Update overzichten en documentatie
Run zensical build
Vraag of gebruiker tevreden is

Git Workflow¶

Commits¶

Vraag altijd eerst voordat je commit of push.

Commit message format:

Type: Korte beschrijving (max 50 chars)

Uitgebreide beschrijving van de wijzigingen en waarom ze
nodig waren. Gebruik meerdere paragrafen indien nodig.

- Bullet points voor specifieke wijzigingen
- Verwijs naar gerelateerde issues of tickets

Co-Authored-By: Warp <agent@warp.dev>

Types: - Feat: Nieuwe functionaliteit - Fix: Bug fix - Docs: Documentatie wijzigingen - Refactor: Code refactoring zonder functionaliteitswijziging - Style: Formatting, code style - Test: Tests toevoegen of wijzigen - Chore: Onderhoudstaken, dependencies

Branches¶

Werk in feature branches voor grote wijzigingen
Beschrijvende branch names: feature/mollie-webhook-fix, docs/hosting-setup
Vraag naar branch strategie bij twijfel

Backup Procedure¶

Voor destructieve operaties of grote wijzigingen:

Database backup:

/var/www/sites/docs.voedingsgeneeskunde/docs/scripts/backup-script.sh

Config export (voor Drupal site):
```
drush config:export
```
Git status check:
```
git status
git diff
```

Vraag gebruiker of backup nodig is bij twijfel.

Testing en Validatie¶

Na code wijzigingen:¶

Syntax check: Controleer PHP syntax met php -l bestand.php
Drupal cache clear: drush cr
Test functionaliteit: Test de wijziging handmatig of met drush commands
Check logs: drush watchdog:show voor Drupal errors

Na documentatie wijzigingen:¶

Zensical build: zensical build
Link check: Controleer of interne links werken
Preview: Check de gegenereerde HTML in site/ directory

Voor deployment:¶

Volg de checklist in docs/scripts/live-migration-checklist.md

Tag Taxonomie¶

Gebruik deze consistente tags voor categorisering (combineer waar relevant):

Functioneel: - Commerce - E-commerce/webshop gerelateerd - UX - User experience verbeteringen - VGBC - VGBC ticket systeem - Users - User management en profielen - Integraties - Externe diensten (Mailchimp, Mollie, etc.)

Technisch: - Hosting - Server, MySQL, UNIX-Socket, beveiliging, Git - Migration - Deployment en migraties - Patches - Custom patches en fixes - Setup - Initiële configuraties - Scripts - Tools en automatisering

Meta: - Critical - Urgente fixes - Documentatie - Documentatie updates - Refactor - Code verbetering zonder functionaliteitswijziging

Voorbeelden: - [Commerce, Critical, Patches] - Urgente webshop fix met patch - [Hosting, Setup, Scripts] - Server configuratie met automation - [VGBC, UX, Refactor] - Ticket systeem verbetering

Bestandslocaties en Structuur¶

Documentatie¶

Sessieverslagen: docs/sessies/YYYYMMDD-beschrijving.md
Sessies overzicht: docs/sessies/index.md
Hoofdpagina: docs/index.md
Project timeline: docs/project-traject.md
Todo lijst: docs/everlasting-todo-lijst.md
Technische docs: docs/documentatie/*.md
Scripts: docs/scripts/
Project docs: docs/project/

Drupal (hoofdproject)¶

Indien je aan de Drupal site werkt (niet de docs): - Custom modules: web/modules/custom/ - Custom themes: web/themes/custom/ - Config: config/sync/ - Patches: patches/

Veelvoorkomende Taken¶

Nieuwe sessie starten¶

Lees docs/everlasting-todo-lijst.md
Lees relevante docs in docs/documentatie/
Check git status voor uncommitted changes
Vraag naar prioriteiten

Module/Code wijziging¶

Zoek bestaande code/module
Maak wijziging
Test functionaliteit
drush cr
Documenteer in sessie-verslag
Update technische documentatie indien relevant

Nieuwe feature documenteren¶

Maak sectie in relevante docs/documentatie/*.md
Beschrijf architectuur, implementatie, usage
Link vanuit sessie-verslag
Update docs/index.md indien belangrijk

Troubleshooting¶

Check Drupal logs: drush watchdog:show
Check PHP errors: tail -f /var/log/apache2/error.log
Check database: drush sqlc
Documenteer probleem en oplossing uitgebreid in sessie-verslag

Credits Beheer¶

Voorkom onnodig token verbruik: - Lees alleen relevante bestanden - Gebruik grep/search voor specifieke zoektermen - Vraag om bevestiging bij grote operaties - Gebruik efficiënte commands (bijv. head i.p.v. cat voor grote bestanden) - Batch file operations waar mogelijk

Bij twijfel: vraag "Deze operatie kan veel tokens kosten, wil je doorgaan?"

Belangrijke Drupal Concepten¶

Voor AI assistenten die minder bekend zijn met Drupal: - Entity: Drupal's data objecten (Node, User, Commerce Product, etc.) - Config: YAML bestanden in config/sync/ - Drush: CLI tool voor Drupal (drush cr, drush config:export, etc.) - Module: Uitbreidingen in web/modules/ (contrib vs custom) - Service: Dependency injection via *.services.yml - Event Subscriber: Hook into Drupal events - Commerce Order: Bestelling met Line Items, Payments, etc.

Vraag om uitleg als een concept onduidelijk is.