Dokumentation sollte nicht mehr als bloßer Text betrachtet werden, sondern als ausführliche, prüfbare Spezifikation, deren Aussagen unmittelbar durch Code verifiziert werden – ein Ansatz, der sowohl menschliche Entwickler als auch KI‑Agenten zuverlässiger und effizienter arbeitet.

Key Takeaway

Dokumentation sollte nicht mehr als bloßer Text betrachtet werden, sondern als ausführliche, prüfbare Spezifikation, deren Aussagen unmittelbar durch Code verifiziert werden – ein Ansatz, der sowohl menschliche Entwickler als auch KI‑Agenten zuverlässiger und effizienter arbeitet.

Summary

• Paradigmenwechsel: Einführung von validation‑first documentation – statt auf Zuverlässigkeit der Texte zu hoffen, werden deren Behauptungen als Tests ausgeführt.
• Codumentation: Toolset (npm‑Paket) und Vorgehensweise, um Markdown‑Dateien wie README oder CLAUDE.md in modulare Skripte zu verwandeln, die validate()-Funktionen exportieren.
• Arbeitsablauf:

1. Installieren: npm i codumentation --save-dev.
2. Initialisieren: npx codumentation init README.md.
3. Laufzeit: codumentation stats liefert Metriken zu Regelverletzungen.

Fehleranalyse

Fehlerberichte (z. B. fehlender Zod‑Validierer) dienen als Lehrinhalte („errorContent“) für Agenten.

Kritik am „Hope Workflow“

Schreiben → Hoffen → Hoffen → Helfen → … → Stille Zunahme von technischer Schuld. Besonders schädlich für KI‑Agenten, die Dokumente wörtlich übernehmen.

AI‑Optimierungsschleife

Agenten erhalten Feedback zu Regelverstößen, können daraus lernen und sich verbessern. Statistiken ermöglichen gezielte Klarheitsverbesserungen der Dokumente.

Module

Beispiel apiContract.ts prüft automatisch, ob alle API‑Routen Zod‑Schemas besitzen.

Effekte

Automatisierte Verifikation → sofortiges Feedback. Dokumentation wird kontraktbasiert und selbstverteidigend. Reduktion von Sicherheitsrisiken (z. B. Injection) durch garantierte Validierung.

Schlüssel‑Insights

1. Dokumentation als ausführbare Spezifikation. 2. „Hope Workflow“ führt zu technischer Schuld, besonders bei KI‑Context‑Files. 3. Validierungsfehler bilden ein Curriculum für Lernende Agenten. 4. Effektiver Kontext wird durch Messung statt Vermutung erreicht.

Entwickler‑Community

GitHub- und npm-Verweise, um das Tool zu nutzen und weiterzuentwickeln.

Autor

Markus Hav – Lead Researcher für Agents, Benque Max AI Lab, Finland.

Related queries

Wie prüft Codumentation automatisch die Einhaltung von Zod‑Schemas?

Welche Vorteile hat die validation‑first Methode im Vergleich zum Hope Workflow?

Wie kann ich Codumentation in ein bestehendes Projekt integrieren?

Quelle: https://benquemax.com/essay/codumentation