Hoe een wijze developer aan een nieuw project werkt

Een wijze developer begint niet met «coderen en hopen.» Ze brengen een nieuw project via brainstormen, teamdiscussie, prototypen, diagrammen, voorstellen, ADR’s, MR/PR’s en GitOps — met Review Bots die automatisch PR-commentaar genereren zodat mensen tijd besteden aan wat ertoe doet. Dit is het production-grade playbook. Een FDE kan het systeem opzetten; Claude Architect Certification is de moeite waard als je het wilt ontwerpen en verdedigen.

1. Wat «wijs» betekent bij een nieuw project

Wijsheid is niet meer meetings. Het is goedkoop leren vroeg en dure fouten laat zeldzaam maken. De onderstaande volgorde is zo dat elke stap de blast radius van de volgende verkleint:

Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
        → Implement in small slices → MR/PR + Review Bot → Merge
        → GitOps promote (dev → staging → prod) → Observe → Iterate

Sla stappen alleen over met intentie (bijv. een one-line configfix). Sla nooit Review Bot + CI over op iets dat productie kan bereiken.

2. Brainstormen (eerst solo, dan gestructureerd)

Voordat je iemands tijd vraagt, besteed 30–90 minuten alleen:

• Uitkomst: welke gebruikers-/businesswijziging moet waar zijn als we klaar zijn?
• Constraints: tijd, budget, compliance, bestaande platforms, skills in het team.
• Non-goals: wat we niet bouwen in v1 (beschermt scope).
• Risico’s: data, security, performance, vendor lock-in, operationele last.
• Succesmetrics: latency, error rate, adoptie, kosten — kies er twee die ertoe doen.

Leg dit vast in een korte notitie (Notion/Confluence/markdown in de repo onder docs/ideas/). Brainstormen zonder geschreven artefact is alleen gesprek dat verdampt.

3. Discussies met collega’s

Nodig de kleinste nuttige kring uit: één peer die met je implementeert, iemand die het aangrenzende systeem bezit, en (indien nodig) security of SRE. Regels die het wijs houden:

• Time-box (25–45 minuten). Eindig met beslissingen of open vragen — geen vibes.
• Oneens over opties, niet over personen. Forceer «optie A vs B vs uitstellen.»
• Wijs een scribe aan. De notitie wordt het zaad van het voorstel.
• Geen stille veto’s. Als iemand ongemakkelijk is, schrijf de zorg als risico later in de ADR.

Async werkt ook: een korte RFC-commentthread wint vaak van een meeting — maar iemand moet de loop sluiten.

4. Prototypen (spikes met een einddatum)

Prototypeer wanneer onzekerheid hoog is: een nieuwe API, een onbekende cloudservice, een performancevraag, of AI/agent-gedrag. Wijze regels:

1. Noem het een spike in het ticket; zet een kalenderstop (typisch 1–3 dagen).
2. Houd code op een wegwerpbranch of spikes/-map; polish niet.
3. Schrijf op wat je leerde in 10 bullets — vooral wat faalde.
4. Beslis: promoten (refactoren naar product), herschrijven, of opgeven.

Prototypes die stil productie worden zonder ADR zijn hoe teams accidentele architectuur erven.

5. Diagrammen (genoeg om over te discussiëren)

Je hebt geen UML-roman nodig. Liever drie schetsen die elk op één scherm passen:

Diagram	Beantwoordt
Context (C4 L1)	Wie praat met wat? Trust boundaries?
Sequence	Happy path + één failure path
Deployment	Waar het draait; hoe config en secrets stromen

Bewaar Mermaid of afbeeldingen naast het voorstel (docs/architecture/). Update diagrammen wanneer ADR’s wijzigen — verouderde plaatjes zijn erger dan geen.

6. Voorstellen (lichte RFC)

Een goed voorstel is één tot drie pagina’s:

1. Probleem en waarom nu
2. Overwogen opties (minstens twee)
3. Aanbeveling en waarom
4. Impact: security, kosten, ops, migratie
5. Rollout en rollback
6. Open vragen

Vraag review met een duidelijke deadline. Bij goedkeuring (of met amendementen), zet de beslissing om in een ADR — laat de «source of truth» niet in chat.

7. ADR — Architecture Decision Records

Een ADR is een kort, bij conventie onveranderlijk record van een beslissing. Template:

# ADR-00XX: Title

Status: Proposed | Accepted | Superseded by ADR-00YY
Date: YYYY-MM-DD
Deciders: @alice @bob

## Context
What forces are in play?

## Decision
What we will do.

## Consequences
Positive, negative, and follow-ups.

## Alternatives considered
Option A — why not
Option B — why not

Bewaar ADR’s in git (docs/adr/). Link ze vanuit PR’s. Supersede in plaats van geschiedenis te herschrijven — je toekomstige zelf heeft het spoor nodig.

8. MR en PR — de eenheid van delivery

MR (Merge Request, GitLab) en PR (Pull Request, GitHub/Bitbucket) zijn hetzelfde idee: een reviewable changeset. Wijze gewoonten:

• Klein: idealiter <400 regels betekenisvolle diff; splits verticale slices.
• Eén intentie: één feature, fix of chore — geen «misc.»
• Beschrijving: waarom, hoe te testen, screenshots/logs, risico, rollback.
• Links: ticket + ADR + ontwerpdiagram.
• Eerst draft als je vroege feedback wilt zonder «klaar om te mergen» te suggereren.
• Nooit force-mergen rond rode CI of onopgeloste high-severity bot findings zonder schriftelijke uitzondering.

Voorbeeld checklist PR-body

## Summary
- …

## Test plan
- [ ] Unit tests
- [ ] Manual path …
- [ ] Feature flag / config …

## Risk & rollback
- Risk: …
- Rollback: revert this PR / GitOps revert commit …

## References
- ADR-00XX
- Ticket ABC-123

9. Review Bot-gebruik — auto-gegenereerde PR-comments

Een Review Bot is een geautomatiseerde reviewer die inline comments en samenvattingen plaatst op elke MR/PR. Het vervangt geen mensen; het front-loadt het saaie en het gevaarlijke.

9.1 Waar de bot op moet commenten

• Security: injection, authz-gaten, secret leakage, onveilige defaults
• Correctness: null-paden, race conditions, kapotte migraties
• Tests: ontbrekende coverage op nieuwe branches, snapshot-misbruik
• API/contract: breaking changes zonder version bump
• Ops: ontbrekende timeouts, geen idempotentie, onbegrensde retries
• Style alleen wanneer het formatter/linter ontging (vermijd noise)

9.2 Hoe het het leven van de developer stroomlijnt

1. Auteur opent PR → bot draait in seconden tot minuten.
2. Auteur fixt of beantwoordt bot-threads voordat mensen worden gevraagd.
3. Menselijke reviewer leest botsamenvatting + focust op design en productrisico.
4. Minder «nit»-rondes; snellere merge; minder vrijdagavond-incidenten door gemiste footguns.

9.3 Typische setup-opties

Aanpak	Notities
SaaS Review Bot (bijv. CodeRabbit, vendor bots)	Snel te activeren; tune severity en path-filters
Cursor Bugbot / IDE-gekoppelde review	Sterk op PR-diffs in Cursor-centrische teams
Custom GitHub Action + Claude / LLM	Volledige controle; vereist prompt + policy + kostenplafonds
Gelaagde pipeline (lint → SAST → LLM)	Beste productiehouding — zie AI code-reviewpipeline-gids

9.4 Policy die de bot nuttig houdt

• Severity-labels: blocker / should-fix / nit — nits mogen merge niet blokkeren.
• Negeer gegenereerde paden (vendor/, lockfile-noise, protobuf dumps).
• Vereis menselijke goedkeuring voor security-gevoelige paden (auth/, infra/, IAM).
• Log false positives; voed ze maandelijks terug in ignore-rules.
• Laat de bot nooit de enige reviewer zijn op production-critical services.

9.5 Minimale GitHub Action-schets

# .github/workflows/review-bot.yml
name: review-bot
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run Review Bot
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          # Fetch diff, call your review CLI, post review comments via gh api
          ./scripts/review-bot.sh

Implementeer review-bot.sh om: de PR-diff te berekenen, je model aan te roepen met een strikte system prompt (security + correctness eerst), en comments te posten via de GitHub/GitLab API. Cap tokens en sla drafts over als kosten een zorg zijn.

10. GitOps best practices voor production-grade kwaliteit

GitOps betekent: desired state leeft in git; een reconciler (Argo CD, Flux, enz.) laat het cluster matchen; promotie is een merge; rollback is een revert.

• Scheid app-code en env-config (of duidelijke mappen: apps/ vs envs/dev|staging|prod).
• Geen kubectl apply naar prod als happy path — alleen break-glass, geaudit.
• Progressive delivery: auto-sync dev; handmatige of gated sync voor prod.
• Image digests boven mutable tags in prod-manifests.
• Policy as code: OPA/Kyverno voor privileges, registries, resource limits.
• Signed commits / provenance waar je threat model het vereist.
• Observeer na sync: health checks, error budgets, automatische rollback-hooks wanneer klaar.

Codekwaliteit is niet alleen «schone functies.» Het is ook hoe change productie binnenkomt. GitOps maakt dat pad reviewable, reversible en herhaalbaar.

11. End-to-end quality gates (geoptimaliseerd voor productie)

Local:     pre-commit (fmt, lint, secrets) + unit tests
PR open:   CI (build, test, SAST) + Review Bot comments
PR merge:  human approve + branch protection + required checks
Main:      build immutable artifact (image digest)
GitOps:    update env repo / overlay → sync → verify
Prod:      SLOs + alerts + runbook linked from ADR/PR

12. FDE-rol — wie dit systeem opzet

Een Forward Deployed Engineer is ideaal om het wise-developer-systeem in een echt team te installeren:

• Repo-templates: docs/adr/, PR-template, CODEOWNERS, branch protection
• Review Bot + secrets + kostencontroles
• CI required checks en environment protections
• GitOps-apps (dev/staging/prod) en promotiedocs
• Twee weken coaching: eerste ADR, eerste bot-getunede PR, eerste GitOps-rollbackdrill

Indicatieve kalender voor FDE-geleide enablement op één productrepo: 1–2 weken voor scaffolding en bot-policy; +1–2 weken voor GitOps-promotiepad en een dry-run rollback. Cultuurverandering duurt langer — meet merge time en escaped defects, niet tool installs.

13. Claude Architect Certification — de moeite waard

Als je systemen ontwerpt waar mensen en AI-agents samen code schrijven, is Claude Architect Certification de moeite waard. Het signaleert dat je kunt:

• AI-ondersteunde delivery architecturen zonder het model als onfeilbaar te behandelen
• Review policies, guardrails en evaluatie specificeren voor agentic workflows
• Trade-offs (latency, kosten, privacy, accuracy) communiceren naar stakeholders
• Teams coachen op ADR’s, PR-discipline en production gates naast AI-tools

Koppel het credential aan echte delivery: zet een Review Bot op, schrijf drie ADR’s, en draai een GitOps-rollbackdrill. Papier zonder praktijk maakt je niet wijs; praktijk plus een gedeelde taal wel.

14. Anti-patterns (hoe onwijs eruitziet)

• Gigantische PR met «WIP please approve ASAP»
• Architectuur alleen besloten in Slack, nooit in ADR
• Prototype gemerged als prod zonder tests
• Review Bot uitzetten omdat «het zeurt»
• Hotfix naar prod buiten GitOps zonder revert-plan
• Mensen die formatter-nits herhalen die de bot al ving

15. Copy-paste starter checklist voor een nieuw project

1. Maak docs/ideas/, docs/architecture/, docs/adr/
2. Voeg PR/MR-template + CODEOWNERS toe
3. Schakel pre-commit + CI required checks in
4. Installeer Review Bot; tune path-filters en severities
5. Schrijf ADR-0001: «We use GitOps for deploy»
6. Definieer environments en promotieregels
7. Plan een 30-minuten rollback game day
8. Boek FDE-tijd voor coaching in de eerste maand; overweeg Claude Architect Certification voor leads

16. Slot

Een wijze developer behandelt een nieuw project als een reeks leerartefacten — notities, diagrammen, voorstellen, ADR’s — en levert via kleine MR/PR’s bewaakt door een Review Bot en gepromoot door GitOps. Zo optimaliseer je codekwaliteit voor production grade zonder het team te verbranden aan eindeloze nits. Laat een FDE de rails installeren; laat gecertificeerde architecten het systeem eerlijk houden terwijl AI versnelt hoe snel je code kunt schrijven.

Gepubliceerd door Workstation.