Ga naar inhoud

Werken met agents

Agents (Claude Code e.d.) werken aan onze repos onder vastgelegde guardrails, zodat herhaalde runs convergeren in plaats van driften (openspec: add-agent-guardrails).

Het operatie-cataloog

Elke deelnemende repo heeft docs/agents.md: een cataloog van operaties in dit vaste formaat — daardoor per component reviewbaar én zichtbaar in dit handboek:

Operatie Autonomie Idempotentie Verificatie
(wat) autonoom / mens-vereist / verboden waarom een herhaalde run niets wijzigt welke check succes bewijst

Autonomie-niveaus:

  • autonoom — de agent voert uit zonder te vragen; altijd gedekt door de verify- en docs-gates.
  • mens-vereist — de agent bereidt voor (bestand, diff, commando) en een mens voert uit of keurt expliciet. Pushes en álle cluster-mutaties zijn per definitie mens-vereist.
  • verboden — nooit, ook niet op verzoek in een sessie; wijziging van het verbod gaat via PR op het cataloog.

De creatie-regel (aangescherpt 2026-07-10, na de eerste livetest)

Operaties die nieuwe infrastructuur-entiteiten aanmaken (een tenant, een component, een frontend) zijn nooit autonoom-schrijvend, ook niet als het "maar" een lokaal bestand is: de agent toont eerst het volledige voorstel (bestand of diff) en schrijft pas na een expliciet akkoord in de sessie. In catalogen heet dit niveau voorstel-eerst. Wijzigingen aan bestáánde entiteiten kunnen wel autonoom zijn — dat bepaalt het cataloog per operatie.

De escalatieregel

Niet in het cataloog = mens-vereist. Een agent die een operatie niet in docs/agents.md vindt, zegt dat en vraagt — improviseren is geen optie. Uitbreiding van het cataloog is zelf een PR.

Grondwaarheid

Agents gebruiken het handboek als bron boven modelkennis, via de MCP-server conduction-docs (zie de hub-sectie). Spreekt modelkennis een handboekpagina tegen, dan wint de pagina; de agent mag de discrepantie flaggen.

Standaardblok voor CLAUDE.md

Elke deelnemende repo neemt dit blok (of equivalent) op:

## Agent-guardrails
- Operatie-cataloog: docs/agents.md — niet gecatalogiseerd = eerst vragen.
- Grondwaarheid: MCP `conduction-docs` (handboek) boven modelkennis.
- Vóór afronden: ./scripts/verify.sh groen; docs mee in dezelfde wijziging.
- Push en cluster-mutaties doet een mens. Nooit --no-verify.

Zelf aansluiten (elke collega, lokaal — geen hosting nodig)

git clone https://codeberg.org/Conduction/hub.git ~/CONDUCTION/hub
cd ~/CONDUCTION/hub && uv sync
claude mcp add --scope user conduction-docs -- \
  uv run --directory ~/CONDUCTION/hub python -m docs_mcp.server

Daarna heeft élke Claude-sessie op die machine de handboek-tools. Content komt live van Codeberg (max 1 uur oud); voor de private KeyCloak-docs is een leestoken nodig (DOCS_READ_TOKEN). Een gehost endpoint (voor gebruik zonder checkout, achter SSO) komt met de interne toegangslaag — zie openspec change add-portal-access-split.

Semantische docs-review

Vrij proza kan geen gate toetsen — daarvoor bestaat de maandelijkse semantische review: een agent-pass (skill semantische-review in de hub) die per component de docs naast code/config legt, drift fixt of meldt via de docs-drift-routing, en toetsbare beweringen promoveert naar doc-assertions of verify-blokken. Twee componenten per maand, langst-niet-gereviewd eerst.

De importlijst als trust root

De repos:-lijst in handbook's mkdocs.yml bepaalt wélke content het portaal, de hub-MCP én de agents als grondwaarheid zien — het is een trust root. Daarom: CODEOWNERS dekt de lijst, wijzigingen alleen via review, en (forge-config, menselijk aan te zetten) branch protection op handbook main. Spiegelbeeldig geldt: docs-PR's in geïmporteerde repos verdienen code-review-rigueur — een pagina die agents als waarheid lezen is een mogelijk prompt-injectie-kanaal. Hetzelfde import_url-formaat wordt door twee consumenten geparsed (de multirepo-plugin en hub's content.py, beide strak gepind): een formaatwijziging breekt er twee tegelijk.

Nieuwe component onboarden

  1. Repo voldoet aan het docs-contract én heeft een verify-gate.
  2. Schrijf docs/agents.md (begin klein: de 3–5 vaakst gevraagde operaties; de escalatieregel vangt de rest).
  3. Voeg het standaardblok toe aan CLAUDE.md en registreer conduction-docs in .mcp.json.
  4. Bewijs idempotentie: draai de kernoperatie twee keer — de tweede run hoort "geen wijziging" op te leveren.