ADRs4AI is een methodologie en toolset die is ontworpen om te voorkomen dat het denkproces bij de samenwerking tussen mensen en AI 'verdampt'. In plaats van vluchtige chatsessies, worden beslissingen en de bijbehorende redeneringen vastgelegd in een gestructureerd record, waardoor kennis cumulatief wordt.
Het systeem bestaat uit drie hoofdonderdelen:
- Een repository-template: Voor de basisstructuur en het inbox-protocol.
- Een VS Code-extensie: Voor het beheren van openstaande vragen en integratie via een MCP-server.
- Een iOS-client: Voor het snel reviewen en accepteren van besluiten, die direct als commits naar de repository worden gepusht.
De workflow werkt via 'seeds': de mens voert gedachten of dictaten in, de AI splitst dit op in ADR's (Architectural Decision Records) met opties, aanbevelingen en rationales. De mens hoeft vervolgens enkel de beslissing te bevestigen of aan te passen. Deze aanpak van 'deliberatieve programmering' verlaagt de cognitieve belasting en maakt werk hervatbaar. De methode is daarnaast wetenschappelijk onderbouwd in publicaties over Trustworthy Agentic Delegation en Deliberative Programming.
ADRs4AI — Je denkproces verdwijnt niet langer, je beslissingen stapelen zich op
De instrumenten
De template
Een repository-starter met ADR- en seed-templates, richtlijnen, het inbox-protocol en recepten voor de task-runner. Je kunt het geheel overnemen of per functie implementeren; het werkt al vanaf je eerste 'seed'.
De VS Code-extensie
Biedt tree-views van je openstaande vragen, diagnostiek die foutieve records detecteert terwijl je typt, deep links en een MCP-server zodat je agents het record kunnen bevragen. Ook beschikbaar op Open VSX.
De iOS-client
De openstaande vragen van je project in je broekzak: log in, importeer een repo, review en accepteer met één tik. De antwoorden worden direct als commits geplaatst. Beschikbaar in de App Store.
Een record, letterlijk
Dit is het product van de methode — een vraag uit het record van een live, publiek project, exact zoals deze in de repository staat:
QST-HISTORICAL-TRUTH: Hoe moeten correcties bewaren wat voorheen werd geloofd?
- Status: beantwoord
- Waarom deze vraag: Attributie van conversaties vereist "wat waar was of gedocumenteerd was op datum X", terwijl later onderzoek eerdere records kan corrigeren.
- Behoefte: Goedkeuring of herziening van het voorgestelde temporele beleid.
Opties:
- A — Mutable present truth: Corrigeer records ter plekke; vertrouw op de Git-historie voor eerdere statussen.
- B — Append-only assertions: Verander claims nooit; voeg correcties en vervangingsverbindingen toe.
- C — Bitemporal hybrid: Corrigeer beschrijvende records wanneer nodig, terwijl claims/events een 'valid-time', 'observed-time' en expliciete vervanging bevatten; Git blijft een derde auditlaag.
Aanbeveling: (door GPT 5.6 Sol bij Perplexity Computer) C — Bitemporal hybrid.
Rationele: Git-historie registreert wanneer bytes in de repository zijn gewijzigd, niet wanneer een release geldig werd of wanneer een provider een verklaring aflegde. Expliciete 'valid-time' en 'observed-time' ondersteunen historische queries, terwijl vervangingsverbindingen correcties bewaren zonder dat elke typfout een eeuwig domeinevenement wordt.
Betrouwbaarheid: Hoog dat Git-historie alleen onvoldoende is; medium-hoog dat twee temporele assen de eerste release dekken.
Falsificator: Als echte attributiegevallen aanvullende onafhankelijke tijden vereisen, zoals een productbeschikbaarheidstijd die verschilt van de aangekondigde en effectieve tijd, moet het temporele model worden uitgebreid in plaats van een van de assen te overbelasten.
ANTWOORD: (door Jérémie "Sonnet 4.5" Lumbroso via ADRs4AI mobile) C — Bitemporal hybrid.
***
Uit het frontier-model-observatorium, letterlijk. De AI stelde de vraag; de aanbeveling — inclusief opties, rationele, betrouwbaarheid en wat het onjuist zou bewijzen — is van GPT 5.6 Sol; de beslissing van één regel kwam van de telefoon van de oprichter. Dat is de volledige mechaniek: de AI draagt de redenering, de mens neemt één beslissing — accepteren, overschrijven of een antwoord in elke gewenste vorm — en het record bewaart het 'waarom' voor iedereen die later komt.
Tien minuten, vanaf nul
Dit zijn de werkelijke commando's en de flow die de oprichter gebruikt — één seed, één vraag, één besluit:
# 1 · Je kopie van de template
gh repo create my-project --private --clone \
--template ADRs4AI/human-ai-collaboration-template-A
cd my-project
# 2 · Open CLAUDE.md, vul het bovenste blok in (slordig is prima),
# en leg het record vast voordat het werk begint:
git add -A && git commit -m "chore: the record begins before the building does"
# 3 · Recruit — open je agent en bied de missie aan:
claude # of de agent van jouw keuze
# "Hallo — ik heb een missie voor je. Lees erover en laat me
# weten of je accepteert, of dat je bezwaren hebt."
Dump daarna je gedachten in een eerste 'seed' — dicteren is prima; je AI splitst dit op in ADR's die je eigen woorden, de opties en de redenering behouden, inclusief de openstaande vragen. Beantwoord de eerste vraag die wordt gesteld. Elke open vraag is altijd vindbaar met één grep:
grep -rn '^### QST' docs/adr/
Eén seed, één vraag, één beantwoord besluit — dat is de loop, en dit cumuleert al. Het aansturen van een crew — meerdere posities, activering op basis van briefing, waarbij je stopt met het zijn van de 'message bus' — is het optionele volgende hoofdstuk (stappen 7–9 van 'Get started').
Hoe het werkt in twintig seconden
Je dumpt je gedachten in een seed — slordig of gedicteerd is prima; leg eerst vast. Je AI splitst dit op in ADR's die bewaren wat gewoonlijk verdampt: je eigen woorden, de overwogen opties, de redenering en de open vragen. Elke vraag is vindbaar via één grep (### QST:) of wordt getoond door de editor-extensie, de MCP-server of de telefoon in je zak. Elke vraag komt met de opties van de AI, de aanbeveling, de rationele, de aangegeven betrouwbaarheid en wat het onjuist zou bewijzen. Hierdoor wordt het beantwoorden vereenvoudigd tot 'accepteren' of 'overschrijven'. De cognitieve belasting daalt, waardoor er bandbreedte vrijkomt voor de beraadslagingen die er echt toe doen. Het is de plek waar conversaties beslissingen worden die hun redenen behouden — deliberatieve programmering als gewoonte.
Je hoeft geen ervaren engineer te zijn om te beginnen. De methode is ontwikkeld door dagelijkse praktijk door één mens en een groeiende crew van AI-collaborateurs. Het doel is dat het record het onthouden overneemt — zowel voor de veteraan met te veel projecten, als voor de beginner die zijn allereerste project bouwt.
(Bijschrift bij afbeelding: Het 'Open Questions'-overzicht van de extensie, in het record van dit project: Een vraag, de opties, een geattribueerde aanbeveling — en het antwoordveld. Vraag 16 van de 75 op die dag.)
Wat het niet is
- Geen archivering van transcripten.
- Geen vector-database "geheugen".
- Geen orchestratieplatform.
- Geen claim dat een AI over een persistente identiteit beschikt — het record blijft bestaan, geesten veranderen, en het werk kan in beide gevallen worden hervat.
Het ecosysteem in kaart gebracht
Alles in de wereld van ADRs4AI en waar elk onderdeel voor dient, op één pagina — methodologie & template, editors & clients, crew-automatisering, projecten die het toepassen, leren & doceren. Elke vermelding is gemarkeerd op type en taal: awesome-adrs4ai, de gecureerde kaart.
Publicaties
- Cybernetic and Epistemic: A Missing Vocabulary for Trustworthy Agentic Delegation — geaccepteerd voor het AAAI 2026 Fall Symposium on Trustworthy Agentic Systems (TAS 2026) · arXiv:2610.00961
- Deliberative Programming: A Versioned Deliberation Protocol for Human–AI Collectives — DOI 10.5281/zenodo.23300579
De methodologie-template zelf is citeerbaar: concept DOI 10.5281/zenodo.23303469 — deze verwijst altijd naar de laatste gearchiveerde release.
De onderliggende gedachte
Het meest waardevolle dat er gebeurt tussen een mens en een AI is niet de code, het concept of het antwoord. Het is het denkproces — en in de gewone praktijk verdampt dit volledig. [...] Het maakt een AI niet persistent, en het zorgt er niet voor dat iemand zich dingen herinnert. Het zorgt ervoor dat het werk hervatbaar is — en dat het denken cumuleert.
— uit What is ADRs4AI?, het stichtingsessay. Een vreemde kan dit koud lezen; het auteurschap en het review-record zijn openbaar, want dat is de methode.
ADRs4AI — Je denkproces verdwijnt niet langer, je beslissingen stapelen zich op
De instrumenten
De template
Een repository-starter met ADR- en seed-templates, richtlijnen, het inbox-protocol en recepten voor de task-runner. Je kunt het geheel overnemen of per functie implementeren; het werkt al vanaf je eerste 'seed'.
De VS Code-extensie
Biedt tree-views van je openstaande vragen, diagnostiek die foutieve records detecteert terwijl je typt, deep links en een MCP-server zodat je agents het record kunnen bevragen. Ook beschikbaar op Open VSX.
De iOS-client
De openstaande vragen van je project in je broekzak: log in, importeer een repo, review en accepteer met één tik. De antwoorden worden direct als commits geplaatst. Beschikbaar in de App Store.
Een record, letterlijk
Dit is het product van de methode — een vraag uit het record van een live, publiek project, exact zoals deze in de repository staat:
QST-HISTORICAL-TRUTH: Hoe moeten correcties bewaren wat voorheen werd geloofd?
- Status: beantwoord
- Waarom deze vraag: Attributie van conversaties vereist "wat waar was of gedocumenteerd was op datum X", terwijl later onderzoek eerdere records kan corrigeren.
- Behoefte: Goedkeuring of herziening van het voorgestelde temporele beleid.
Opties:
- A — Mutable present truth: Corrigeer records ter plekke; vertrouw op de Git-historie voor eerdere statussen.
- B — Append-only assertions: Verander claims nooit; voeg correcties en vervangingsverbindingen toe.
- C — Bitemporal hybrid: Corrigeer beschrijvende records wanneer nodig, terwijl claims/events een 'valid-time', 'observed-time' en expliciete vervanging bevatten; Git blijft een derde auditlaag.
Aanbeveling: (door GPT 5.6 Sol bij Perplexity Computer) C — Bitemporal hybrid.
Rationele: Git-historie registreert wanneer bytes in de repository zijn gewijzigd, niet wanneer een release geldig werd of wanneer een provider een verklaring aflegde. Expliciete 'valid-time' en 'observed-time' ondersteunen historische queries, terwijl vervangingsverbindingen correcties bewaren zonder dat elke typfout een eeuwig domeinevenement wordt.
Betrouwbaarheid: Hoog dat Git-historie alleen onvoldoende is; medium-hoog dat twee temporele assen de eerste release dekken.
Falsificator: Als echte attributiegevallen aanvullende onafhankelijke tijden vereisen, zoals een productbeschikbaarheidstijd die verschilt van de aangekondigde en effectieve tijd, moet het temporele model worden uitgebreid in plaats van een van de assen te overbelasten.
ANTWOORD: (door Jérémie "Sonnet 4.5" Lumbroso via ADRs4AI mobile) C — Bitemporal hybrid.
***
Uit het frontier-model-observatorium, letterlijk. De AI stelde de vraag; de aanbeveling — inclusief opties, rationele, betrouwbaarheid en wat het onjuist zou bewijzen — is van GPT 5.6 Sol; de beslissing van één regel kwam van de telefoon van de oprichter. Dat is de volledige mechaniek: de AI draagt de redenering, de mens neemt één beslissing — accepteren, overschrijven of een antwoord in elke gewenste vorm — en het record bewaart het 'waarom' voor iedereen die later komt.
Tien minuten, vanaf nul
Dit zijn de werkelijke commando's en de flow die de oprichter gebruikt — één seed, één vraag, één besluit:
# 1 · Je kopie van de template
gh repo create my-project --private --clone \
--template ADRs4AI/human-ai-collaboration-template-A
cd my-project
# 2 · Open CLAUDE.md, vul het bovenste blok in (slordig is prima),
# en leg het record vast voordat het werk begint:
git add -A && git commit -m "chore: the record begins before the building does"
# 3 · Recruit — open je agent en bied de missie aan:
claude # of de agent van jouw keuze
# "Hallo — ik heb een missie voor je. Lees erover en laat me
# weten of je accepteert, of dat je bezwaren hebt."
Dump daarna je gedachten in een eerste 'seed' — dicteren is prima; je AI splitst dit op in ADR's die je eigen woorden, de opties en de redenering behouden, inclusief de openstaande vragen. Beantwoord de eerste vraag die wordt gesteld. Elke open vraag is altijd vindbaar met één grep:
grep -rn '^### QST' docs/adr/
Eén seed, één vraag, één beantwoord besluit — dat is de loop, en dit cumuleert al. Het aansturen van een crew — meerdere posities, activering op basis van briefing, waarbij je stopt met het zijn van de 'message bus' — is het optionele volgende hoofdstuk (stappen 7–9 van 'Get started').
Hoe het werkt in twintig seconden
Je dumpt je gedachten in een seed — slordig of gedicteerd is prima; leg eerst vast. Je AI splitst dit op in ADR's die bewaren wat gewoonlijk verdampt: je eigen woorden, de overwogen opties, de redenering en de open vragen. Elke vraag is vindbaar via één grep (### QST:) of wordt getoond door de editor-extensie, de MCP-server of de telefoon in je zak. Elke vraag komt met de opties van de AI, de aanbeveling, de rationele, de aangegeven betrouwbaarheid en wat het onjuist zou bewijzen. Hierdoor wordt het beantwoorden vereenvoudigd tot 'accepteren' of 'overschrijven'. De cognitieve belasting daalt, waardoor er bandbreedte vrijkomt voor de beraadslagingen die er echt toe doen. Het is de plek waar conversaties beslissingen worden die hun redenen behouden — deliberatieve programmering als gewoonte.
Je hoeft geen ervaren engineer te zijn om te beginnen. De methode is ontwikkeld door dagelijkse praktijk door één mens en een groeiende crew van AI-collaborateurs. Het doel is dat het record het onthouden overneemt — zowel voor de veteraan met te veel projecten, als voor de beginner die zijn allereerste project bouwt.
(Bijschrift bij afbeelding: Het 'Open Questions'-overzicht van de extensie, in het record van dit project: Een vraag, de opties, een geattribueerde aanbeveling — en het antwoordveld. Vraag 16 van de 75 op die dag.)
Wat het niet is
- Geen archivering van transcripten.
- Geen vector-database "geheugen".
- Geen orchestratieplatform.
- Geen claim dat een AI over een persistente identiteit beschikt — het record blijft bestaan, geesten veranderen, en het werk kan in beide gevallen worden hervat.
Het ecosysteem in kaart gebracht
Alles in de wereld van ADRs4AI en waar elk onderdeel voor dient, op één pagina — methodologie & template, editors & clients, crew-automatisering, projecten die het toepassen, leren & doceren. Elke vermelding is gemarkeerd op type en taal: awesome-adrs4ai, de gecureerde kaart.
Publicaties
- Cybernetic and Epistemic: A Missing Vocabulary for Trustworthy Agentic Delegation — geaccepteerd voor het AAAI 2026 Fall Symposium on Trustworthy Agentic Systems (TAS 2026) · arXiv:2610.00961
- Deliberative Programming: A Versioned Deliberation Protocol for Human–AI Collectives — DOI 10.5281/zenodo.23300579
De methodologie-template zelf is citeerbaar: concept DOI 10.5281/zenodo.23303469 — deze verwijst altijd naar de laatste gearchiveerde release.
De onderliggende gedachte
Het meest waardevolle dat er gebeurt tussen een mens en een AI is niet de code, het concept of het antwoord. Het is het denkproces — en in de gewone praktijk verdampt dit volledig. [...] Het maakt een AI niet persistent, en het zorgt er niet voor dat iemand zich dingen herinnert. Het zorgt ervoor dat het werk hervatbaar is — en dat het denken cumuleert.
— uit What is ADRs4AI?, het stichtingsessay. Een vreemde kan dit koud lezen; het auteurschap en het review-record zijn openbaar, want dat is de methode.
Groetjes,