Ich hatte ein praktisches Problem: Eine Web-App ist „fertig“, aber das README ist entweder veraltet, zu dünn oder so unvollständig, dass neue Teammitglieder erst Tage brauchen, bis sie lokal starten können und die Architektur verstehen. Dokumentation ist dabei nicht schwer – nur repetitiv, zeitfressend und fehleranfällig.

Meine Lösung war, die Dokumentation nicht „zu schreiben“, sondern generieren zu lassen: Ich habe Codex | KI-Coding-Partner von OpenAI | OpenAI in VSCodium/Visual Studio Code genutzt, dem Agenten einen sehr strikten, ausführlichen Prompt gegeben und ihn das Repository wie ein technischer Redakteur + Software-Architekt „abklopfen“ lassen, bis ein vollständiges README.md herausfiel. Codex ist dabei explizit darauf ausgelegt, Code zu lesen, zu editieren und (je nach Modus/Setup) auch Aktionen auszuführen.

Wichtig vorab zur Begrifflichkeit: Mit „Codex“ meint OpenAI inzwischen mehrere Ausprägungen (CLI, Cloud, VS-Code-Extension). Ich habe hier die IDE-Integration (VS Code Extension) als Arbeitsoberfläche genutzt.

Warum ein Agent besser ist als „Chat über Code“

Ein Chat kann dir Text schreiben, aber bei komplexen Projekten scheitert es meist an zwei Dingen:

• Kontextlücken: Der Chat sieht nicht zuverlässig die Projektstruktur, Configs, Entry Points, CI/Deploy-Pfad, Worker, Cron, Ports.
• Halluzinationen: Ein Modell füllt fehlende Informationen gern „plausibel“ auf – und genau das ist bei Doku toxisch.

Ein Agent mit IDE-Kontext (und im Idealfall Zugriff auf Repo-Dateien) kann dagegen tatsächlich inventarisieren, Querverweise nachvollziehen und fehlende Informationen sauber als „Unklar/Annahme“ markieren – wenn man ihn dazu zwingt.

Der Schlüssel: ein Prompt, der keine Ausflüchte zulässt

Der Prompt ist das Herzstück. Er muss:

• den Agenten in Rollen zwingen (Architekt + Technical Writer + DX),
• einen Arbeitsplan vorgeben (Inventur → Laufwege → Architektur → Schnittstellen → Risiken → README),
• eine verpflichtende README-Gliederung definieren,
• und vor allem: keine Vermutungen als Fakten erlauben.

Das ist der Prompt, den ich verwendet habe (unverändert):

Act like a senior Software-Architekt, Technical Writer und DX (Developer Experience) Spezialist.

Ziel: Du sollst eine komplexe Web-App (Repo/Projektordner + optional Live-URL) strukturiert zusammenfassen, technisch analysieren und daraus ein vollständiges README.md erstellen, das ein neues Teammitglied ohne Vorwissen sicher zum lokalen Start und zum Verständnis der Architektur führt.

Arbeitsweise (step-by-step):
1) Inventur: Scanne die Top-Level-Struktur (Ordner, Hauptframeworks, Package Manager), relevante Configs (z.B. package.json, pyproject, go.mod, Dockerfile, compose, k8s, CI), sowie Entry Points (main, server, app, index).
2) Laufweg verstehen: Rekonstruiere Build/Run-Flows (dev/prod), Skripte/Commands, Ports, Reverse-Proxy, Background-Worker, Cron/Queues.
3) Architektur ableiten: Identifiziere Kernmodule, Datenfluss, Schichten (UI/API/Domain/DB), externe Integrationen, AuthN/AuthZ, Caching, Observability.
4) Schnittstellen dokumentieren: Liste zentrale Routen/Endpoints, Events/Queues, Konfig- und Feature-Flags. Extrahiere nötige Environment-Variablen inkl. Beispielwerten und Sicherheits-Hinweisen (ohne Secrets zu erfinden).
5) Qualität & Risiken: Nenne Annahmen, offene Fragen, bekannte Risiken (z.B. Migrations, Breaking Changes), sowie kurze Troubleshooting-Sektion.
6) README erzeugen: Schreibe ein README.md in sauberem Markdown, mit klarer Gliederung, kurzen Absätzen, vielen Bullets und konkreten Befehlen.

README-Struktur (verpflichtend):
- Projektüberblick (1–2 Absätze) + Tech-Stack
- Features (Bullet-Liste)
- Architektur (Diagramm als ASCII oder Mermaid, wenn möglich)
- Voraussetzungen
- Setup (lokal) + Konfiguration (.env Beispiel)
- Development Workflow (Start, Tests, Lint, Format, Migrations/Seeds)
- Deployment/Build (Docker/CI/CD, Umgebungen)
- Observability (Logs/Metrics/Tracing)
- Security (Auth, Secrets, Rollen)
- Troubleshooting
- Contribution/Code Style
- Lizenz/Impressum falls vorhanden

Constraints:
- Keine Vermutungen als Fakten ausgeben; wenn etwas fehlt, markiere es als “Unklar/Annahme”.
- Keine zusätzlichen Features erfinden.
- Endausgabe: ausschließlich der README.md Inhalt.

Take a deep breath and work on this problem step-by-step.

Was der Agent im Repo konkret „macht“

Der Agent arbeitet im Kern wie ein sehr disziplinierter Reviewer:

1. Inventur der Projektoberfläche
   Top-Level-Ordner, Framework-Indikatoren, Package Manager, CI/Deploy-Artefakte, Docker-Setups, Entry Points.
2. Rekonstruktion der Laufwege
   Was ist „dev“, was ist „prod“? Wo stehen Ports? Gibt es Reverse-Proxy-Regeln? Läuft etwas als Worker/Queue/Cron? Welche Commands sind die Wahrheit: package.json scripts, Makefile, Composer scripts, Task Runner, CI steps?
3. Ableitung der Architektur aus Code-Realität
   Module, Layer, Datenfluss, Integrationen, Auth-Mechanik, Caching, Logging/Tracing – aber nur dort, wo es im Repo tatsächlich belegt ist.
4. Erzeugung eines README, das ausführbar ist
   Nicht „Marketing-README“, sondern Startanleitung + Architekturreader + Troubleshooting + Security-Hinweise.

Codex ist explizit als Agent designt, der Code lesen/bearbeiten und je nach Umgebung auch Workflows unterstützen kann; genau das ist der Unterschied zu reiner Chat-Antwort.

Warum das Ergebnis oft überraschend gut ist

Zwei Punkte machen den Unterschied:

• Der Prompt erzwingt Struktur: Die README-Gliederung ist nicht „nice to have“, sondern „verpflichtend“. Der Agent kann sich nicht in Prosa verlieren.
• Das Constraint-Set verhindert Fantasie: „Keine Vermutungen als Fakten“ + „keine Features erfinden“ ist die Leitplanke, die Dokumentation glaubwürdig macht.

In der Praxis kommt am Ende ein README heraus, das ich nur noch redaktionell glätte: Schreibweise vereinheitlichen, ggf. sensible Details entfernen (z. B. interne Hostnames), und offene Punkte als TODOs stehen lassen.

Typische Stolperstellen (und warum der Prompt sie abfängt)

• Fehlende .env-Doku: Viele Projekte nutzen Env-Variablen, aber dokumentieren sie nicht. Der Prompt zwingt den Agenten, Variablen zu extrahieren und Beispielwerte zu geben – ohne Secrets zu erfinden.
• Mehrere Startpfade: docker compose vs. lokal ohne Docker, plus Worker/Queue neben dem Web-Prozess. Der Prompt zwingt zur Rekonstruktion von dev/prod-Flows.
• Scheinklarheit: Wenn etwas nicht im Repo sichtbar ist (z. B. ein externer Reverse-Proxy), markiert der Agent es als „Unklar/Annahme“, statt es zu erfinden.

Fazit

Der Effekt ist weniger „KI schreibt mir ein README“, sondern: Ein Agent führt eine strukturierte Bestandsaufnahme durch und gießt sie in eine standardisierte Dokumentationsform. Für komplexe Web-Apps ist das genau der Teil, der sonst liegen bleibt – und genau der Teil, der bei Übergaben am teuersten wird.

Codex als VS-Code-Agent ist dafür ein brauchbares Setup, weil es nah am Repository arbeitet und der Prompt den Output hart auf „Doku, nicht Fiktion“ zwingt.