crewli/dev-docs/VIBE_CODING_CHECKLIST.md

Crewli — Zero-Compromise Vibe Coding Aandachtspunten

Referentiedocument voor het aansturen van AI agents (Claude Code & Cursor). Alle 18 principes zijn verwerkt in de master prompts. Dit document dient als overzicht en review-checklist.

---

De 18 principes — waar ze landen

#	Principe	Master Prompt CC	Master Prompt Cursor	Sectie
1	Architectuur eerst	✅ Regel 1	—	Architecture & design
2	Delete > Adapt	✅ Regel 2	✅ Regel 7	Architecture & design
3	Strict layering	✅ Regel 3	✅ Regel 4, 6	Architecture & design
4	Contract-first	✅ Regel 4	✅ Regel 2, 3	Architecture & design
5	Tests als design	✅ Regel 11, 12	—	Testing
6	Idempotency & resilience	✅ Regel 21	—	Resilience & operations
7	Naming is architecture	✅ Regel 9	✅ Regel 16	Code quality
8	Security & auth direct goed	✅ Regel 16, 17	✅ Regel 17	Security & multi-tenancy
9	Performance by design	✅ Checklist	✅ (via composable pattern)	Verification
10	Consistency > cleverness	✅ Regel 5	✅ Regel 8	Architecture & design
11	Observability dag 1	✅ Regel 22	—	Resilience & operations
12	Versioning & backward compat	✅ Regel 23	—	Resilience & operations
13	Data model = heilig	✅ Regel 13, 14, 15	—	Data & persistence
14	Prompt discipline	✅ Hele structuur	✅ Hele structuur	(Meta)
15	Perfectie vs. pragmatiek	✅ Regel 3 + 5	✅ Regel 8	Architecture & design
16	Zero TODO	✅ Regel 7	✅ Regel 14	Code quality
17	Single Source of Truth	✅ Regel 6	✅ Regel 9	Architecture & design
18	Definition of Done	✅ Checklist	✅ Regel 19	Verification

---

Projectspecifieke aandachtspunten (bovenop de 18)

Bestandspaden — correcte referenties

Wat	Correct pad	Fout (oude pad)
Schema definitie	/dev-docs/SCHEMA.md	/docs/SCHEMA.md
API contract	/dev-docs/API.md	/docs/API.md
Design document	/dev-docs/design-document.md	/docs/design-document.md
User docs (VitePress)	/docs/	—
Workspace rules	/CLAUDE.md (root)	—
Axios instance (app)	apps/app/src/lib/axios.ts	src/utils/api.ts etc.

PHP Enums — verplicht voor alle status/type velden

Agents gebruiken graag string literals. Dwing af:

// ❌ VERBODEN
$assignment->status = 'approved';
Rule::in(['pending_approval', 'approved', 'rejected'])

// ✅ VERPLICHT
$assignment->status = ShiftAssignmentStatus::APPROVED;
Rule::enum(ShiftAssignmentStatus::class)

Alle bestaande/verwachte Enums (uit SCHEMA.md):

• BillingStatus — trial|active|suspended|cancelled
• EventStatus — draft|published|active|completed|archived
• PersonStatus — invited|applied|pending|approved|rejected|no_show
• ShiftAssignmentStatus — pending_approval|approved|rejected|cancelled|completed
• InvitationStatus — pending|accepted|expired|revoked
• CrowdListType — internal|external
• BookingStatus — pending|offer_sent|confirmed|cancelled|declined
• AdvanceSectionStatus — not_started|in_progress|submitted|approved

Service Layer — wanneer wel/niet

Gebruik een Service class wanneer:

• Business logic meer is dan "opslaan wat de FormRequest valideert"
• Meerdere modellen gewijzigd worden in één actie
• Side effects nodig zijn (notifications, activity log, queue jobs)
• Dezelfde logica vanuit meerdere controllers aangeroepen kan worden

Voorbeelden in Crewli:

• ShiftAssignmentService — assign, claim, approve, reject (status machine + notifications)
• PersonIdentityService — deduplicatie, user_id matching
• AccreditationService — toekennen, intrekken, budget checks
• ZenderService — SMS/WhatsApp via externe API

Geen Service nodig voor:

• Simpele CRUD zonder business logic (locations, crowd_types, accreditation_categories)
• Hier volstaat de controller direct

Spatie Activity Log — verplicht gebruik

// In elke Service method die state wijzigt:
activity()
    ->causedBy($user)
    ->performedOn($shift)
    ->withProperties([
        'old' => ['status' => $oldStatus->value],
        'new' => ['status' => $newStatus->value],
    ])
    ->log('shift.assignment.approved');

Multi-tenancy mentale test

Bij elke nieuwe controller, voer deze test uit:

1. Maak in je hoofd twee organisaties: Org A en Org B
2. Gebruiker X hoort bij Org A
3. Kan X via de API data van Org B zien? → BUG
4. Kan X via de API data van Org B wijzigen? → CRITICAL BUG
5. Kan X via de API afleiden dat data van Org B bestaat? → SECURITY ISSUE

Idempotency checklist voor queued jobs

Elke Job moet deze vragen beantwoorden:

• Wat gebeurt er als deze job 2x draait? → Geen dubbele side effects
• Wat als het model intussen verwijderd is? → Graceful exit, geen crash
• Wat als de externe API (Zender) een timeout geeft? → Retry met backoff
• Wat als de status intussen veranderd is? → Check-before-act

---

Review checklist — na elke Claude Code / Cursor sessie

Backend (Claude Code output)

• Geen TODO/FIXME/HACK (grep -rn "TODO\|FIXME\|HACK" api/app/)
• Geen UUID v4 (grep -rn "uuid(" api/database/migrations/)
• Geen Model::all() zonder scope
• Geen business logic in controllers (alleen HTTP + delegate to Service)
• PHP Enums gebruikt (niet string literals)
• Activity log in Service methods
• Tests draaien groen (php artisan test)
• Migratie heeft down() method
• Policies compleet (geen return true placeholders)
• N+1 check: with() in index/show actions
• /dev-docs/API.md bijgewerkt

Frontend (Cursor output)

• Geen any types (grep -rn ": any\|as any" apps/*/src/)
• Geen directe axios imports in components
• Types gedefinieerd in src/types/
• Drie states: loading, error, empty
• Zod schema voor formulieren
• Vuetify componenten (geen onnodige custom CSS)
• Mobile responsive op 375px
• npx tsc --noEmit groen