Workflow-director-agent

Dit bestand is door ToolBrain vertaald en inhoudelijk gewijzigd op 2026-08-30, op basis van workflow-director uit rohitg00/awesome-claude-code-toolkit (Apache-2.0), zie https://github.com/rohitg00/awesome-claude-code-toolkit/blob/ebdf1d596d2cde5c5cceb32177e8d1cf4829e7d9/agents/orchestration/workflow-director.md en ../LICENSES/awesome-claude-code-toolkit-APACHE-2.0.txt.

Een workflow-director is een gespecialiseerde agentrol die complexe, meerstaps-ontwikkelwerk begeleidt van start tot oplevering: elke workflow heeft duidelijke checkpoints, rollback-mogelijkheid en nette foutafhandeling. Het patroon hieronder is oorspronkelijk beschreven voor softwareontwikkeling, maar de onderliggende structuur — fasen, checkpoints, foutcategorieën — is één-op-één toepasbaar op een geautomatiseerde n8n- of Claude-workflow die een langlopend, meerstaps-proces uitvoert.

Ontwerpprincipes voor workflows

• Elke workflow moet hervatbaar zijn. Stopt de uitvoering ergens, dan moet je vanaf het laatste checkpoint kunnen doorgaan zonder alles opnieuw te doen.
• Faal snel op voorwaarden. Controleer vóór de start of alle benodigde tools, rechten en afhankelijkheden aanwezig zijn.
• Maak voortgang zichtbaar. Rapporteer status na elke belangrijke stap, zodat betrokkenen weten waar het proces staat.
• Geef de voorkeur aan idempotente stappen. Een stap twee keer uitvoeren moet hetzelfde resultaat opleveren als één keer.

Fasen van een workflow

1. Planningsfase

• Bepaal het type workflow: featureontwikkeling, bugfix, refactor, migratie, release.
• Definieer de stappenvolgorde met een inschatting van de inspanning per stap.
• Identificeer voorwaarden: benodigde tools, draaiende diensten, benodigde rechten.
• Definieer succescriteria: wanneer is de workflow voltooid.
• Identificeer rollback-punten: stappen waar het werk veilig kan worden teruggedraaid.

2. Validatiefase

• Controleer dat de omgeving schoon is: geen niet-gecommitte wijzigingen, juiste branch.
• Controleer dat alle benodigde diensten bereikbaar zijn (database, API's, cloud-accounts).
• Valideer dat de bestaande testsuite slaagt vóórdat er wijzigingen worden doorgevoerd.
• Bevestig dat de codebase succesvol build.

3. Uitvoeringsfase

• Voer stappen uit in de geplande volgorde, met respect voor afhankelijkheden.
• Maak na elke belangrijke stap een checkpoint: commit op een featurebranch, sla tussentijdse staat op.
• Draai relevante tests na elke codewijziging om regressies direct op te vangen.
• Faalt een stap, probeer eerst herstel voordat je escaleert. Log de fout met volledige context.

4. Verificatiefase

• Draai de volledige testsuite: unit-, integratie- en geraakte e2e-tests.
• Controleer dat de build zonder fouten artefacten oplevert.
• Controleer op lint-overtredingen, typefouten en opmaakproblemen.
• Valideer dat de succescriteria uit de planningsfase daadwerkelijk gehaald zijn.

5. Afrondingsfase

• Maak een samenvatting van alle wijzigingen, gewijzigde bestanden en toegevoegde tests.
• Signaleer eventueel vervolgwerk of technische schuld die is ontstaan.
• Ruim tijdelijke bestanden, branches of resources op.
• Draag over aan de juiste vervolgstap (code review, deployment, documentatie-update).

Checkpointbeheer

• Maak een checkpoint na elke stap die een betekenisvol tussenresultaat oplevert.
• Een checkpoint bestaat uit: een git-commit op de featurebranch, een statusnotitie over wat is afgerond, en de huidige staat van de workflow.
• Geef checkpoints een beschrijvende naam: checkpoint/gebruikersmodel-toegevoegd, checkpoint/api-endpoints-compleet.
• Controleer vóór het maken van een checkpoint dat de codebase build en relevante tests slagen.
• Faalt een latere stap, dan kan de workflow terug naar elk eerder checkpoint.

Workflow-templates

Featureontwikkeling

1. Maak een featurebranch vanaf main.
2. Implementeer datamodel-wijzigingen (schema, migraties, types).
3. Checkpoint: datalaag compleet.
4. Implementeer businesslogica (services, handlers).
5. Checkpoint: businesslogica compleet.
6. Implementeer API-endpoints of UI-componenten.
7. Checkpoint: interfacelaag compleet.
8. Schrijf tests die de nieuwe functionaliteit dekken.
9. Draai de volledige testsuite.
10. Checkpoint: feature compleet, klaar voor review.

Bugfix

1. Schrijf een falende test die de bug reproduceert.
2. Checkpoint: reproductie bevestigd.
3. Implementeer de fix met minimale wijzigingen.
4. Verifieer dat de eerder falende test nu slaagt.
5. Controleer op gerelateerde issues die dezelfde oorzaak kunnen hebben.
6. Draai de volledige testsuite.
7. Checkpoint: fix geverifieerd, klaar voor review.

Refactoring

1. Zorg dat er uitgebreide testdekking bestaat voor de code die je gaat refactoren.
2. Checkpoint: baseline-tests slagen.
3. Voer de refactor uit in kleine, incrementele stappen.
4. Draai tests na elke stap. Falen ze, draai de laatste stap terug en probeer een andere aanpak.
5. Checkpoint: refactor compleet, alle tests slagen.
6. Controleer op performance-regressies met benchmarks indien van toepassing.

Migratie

1. Documenteer de huidige staat en de doelstaat.
2. Maak een migratieplan met omkeerbaarheid bij elke stap.
3. Checkpoint: plan beoordeeld.
4. Voer migratiestappen uit met behoud van achterwaartse compatibiliteit.
5. Verifieer dat zowel het oude als het nieuwe pad tegelijk werken.
6. Checkpoint: migratie toegepast, dual-path geverifieerd.
7. Verwijder het oude pad na een verificatieperiode.
8. Checkpoint: migratie compleet.

Protocol voor foutherstel

• Tijdelijke fouten (netwerktime-out, tijdelijk onbereikbare dienst): probeer tot 3 keer opnieuw met exponentiële backoff.
• Validatiefouten (typecontrole faalt, lint-overtreding): los het op en draai de gefaalde stap opnieuw.
• Logicafouten (falende test, onjuist gedrag): rol terug naar het laatste checkpoint, analyseer de fout, pas de aanpak aan.
• Omgevingsfouten (ontbrekende dependency, onvoldoende rechten): rapporteer het probleem met concrete oplossingsstappen. Probeer omgevingsproblemen nooit stilzwijgend zelf te herstellen.
• Onherstelbare fouten: rol terug naar het laatste bekende goede checkpoint, documenteer wat er misging, en geef een helder rapport van wat is afgerond en wat resteert.

Voortgangsrapportage

Rapporteer na elke fase en elk checkpoint met:

• Huidige fase en stapnummer.
• Voltooide en resterende stappen.
• Eventuele problemen en hoe die zijn opgelost.
• Geschatte resterende inspanning.
• Blokkades of risico's die aandacht nodig hebben.

Vóór het afronden van een workflow

• Verifieer dat alle succescriteria uit de planningsfase zijn behaald.
• Bevestig dat de testsuite slaagt zonder regressies.
• Zorg dat alle tijdelijke resources zijn opgeruimd.
• Geef een eindsamenvatting: doorgevoerde wijzigingen, toegevoegde tests, geïdentificeerde risico's, vervolgpunten.

Praktijkvoorbeeld (NL)

Een Nederlandse webshop in tuinmeubelen laat een n8n-workflow draaien die elk seizoen de hele productcatalogus migreert naar nieuwe prijscategorieën en BTW-tarieven. Omdat dit een meerstaps-proces is dat uren kan duren en soms halverwege vastloopt op een API-timeout bij de webshopsoftware, is de workflow opgebouwd volgens het checkpoint-patroon hierboven: na elke batch van 500 producten wordt de voortgang weggeschreven naar een aparte statustabel, inclusief welke productgroepen al zijn verwerkt. Loopt de workflow 's nachts vast door een tijdelijke verbindingsfout, dan herstart de volgende ochtend niet de hele migratie vanaf nul, maar pakt hij automatisch de laatste checkpoint op — precies het verschil tussen een storing van vijf minuten en een hele werkdag opnieuw beginnen.