AI für Tech-Dokumentation & ADRs

MetinC — Sat, 14 Mar 2026 14:33:00 +0000

Grundsätzlich aI für Tech-Dokumentation & ADRs: Technische Dokumentation, Architecture Decision Records und README Files mit ChatGPT & Claude. 10 Prompts.

Einleitung

Zudem helfen klare Strukturen dabei, den Überblick zu behalten.

Gute Dokumentation ist der Unterschied zwischen einem wartbaren und einem unwartbaren Projekt. AI ist perfekt dafür: Es kann Code lesen und Dokumentation generieren. Hier sind 10 Prompts für technische Dokumentation, ADRs und READMEs.

Tatsächlich zeigt die Praxis, dass dieser Ansatz sehr effektiv ist.

Insbesondere für fortgeschrittene Projekte ist das relevant.

Prompt 1: README erstellen

Grundsätzlich gibt es dabei einige Punkte zu beachten.

Erstelle eine professionelle README.md für mein Projekt:

Projekt: [z.B. "React Component Library"]
Zielgruppe: [z.B. "Open Source Nutzer" / "Team-Mitglieder"]

Erstelle Sektionen:
1. **Header**: Name, ein Satz Beschreibung, Badges (CI, npm, License)
2. **Demo/Screenshot**: Visueller Eindruck (GIF, Screenshot)
3. **Features**: Bullet Points der Hauptfeatures
4. **Installation**: npm install mit Voraussetzungen
5. **Quick Start**: Minimales Code-Beispiel (Copy-Paste-fähig!)
6. **Usage**: Ausführlichere Beispiele pro Feature
7. **API Reference**: Props/Config Tabelle
8. **Configuration**: Alle Optionen mit Default-Werten
9. **Contributing**: How to contribute (kurz, mit Link zu CONTRIBUTING.md)
10. **License**: MIT/Apache-2.0

README Qualitäts-Check:
- Kann ein neuer Entwickler in 5 Min starten?
- Ist das erste Code-Beispiel copy-paste-fähig?
- Sind alle Voraussetzungen genannt?

Tatsächlich lässt sich dieser Code direkt in dein Projekt übernehmen.

Zusätzlich gibt es einige bewährte Tipps für den Alltag.

Prompt 2: Architecture Decision Record

Dennoch ist es wichtig, die Grenzen der AI-Unterstützung zu kennen.

Im Grunde vereinfacht dieser Ansatz den gesamten Workflow erheblich.

Erstelle ein ADR (Architecture Decision Record):

Entscheidung: [z.B. "Wir verwenden PostgreSQL statt MongoDB"]
Kontext: [z.B. "E-Commerce App mit komplexen Relationen"]

Erstelle nach ADR-Format:
1. **Titel**: ADR-001: [Entscheidungs-Titel]
2. **Status**: Proposed / Accepted / Deprecated / Superseded
3. **Datum**: Wann die Entscheidung getroffen wurde
4. **Kontext**: Warum musste diese Entscheidung getroffen werden?
5. **Entscheidung**: Was wurde entschieden?
6. **Alternativen**: Welche Optionen wurden evaluiert?
7. **Pro/Contra**: Für jede Alternative
8. **Konsequenzen**: Was ändert sich durch die Entscheidung?
9. **Risiken**: Welche Risiken gibt es?
10. **Review-Datum**: Wann die Entscheidung überprüft wird

ADR als Markdown in docs/adr/ Ordner.
Index-Datei (docs/adr/README.md) mit allen ADRs.
"Leichtgewicht-ADR": Max. 1 Seite, keine Bürokratie!

Dementsprechend ist eine manuelle Überprüfung empfehlenswert.

Im Folgenden gehe ich auf die wichtigsten Details ein.

Prompt 3: API Dokumentation

Insbesondere für komplexe Projekte ist das ein entscheidender Vorteil.

Weiterhin ist es wichtig, die Grundlagen zu verstehen.

Erstelle API Dokumentation:

API: [z.B. "REST API für User Management"]
Format: [OpenAPI/Swagger / Markdown / Docusaurus]

Erstelle pro Endpoint:
1. **Method + URL**: POST /api/v1/users
2. **Beschreibung**: Was macht der Endpoint?
3. **Auth**: Welche Berechtigung wird benötigt?
4. **Request Headers**: Content-Type, Authorization
5. **Request Body**: JSON Schema mit Beschreibung pro Feld
6. **Response 200**: Success Response mit Beispiel
7. **Response 4xx/5xx**: Error Responses mit Codes
8. **Query Parameters**: Pagination, Filtering, Sorting
9. **Code-Beispiel**: curl, JavaScript fetch, Python requests
10. **Rate Limits**: Requests pro Minute, Headers

API Docs Tools:
- Swagger UI (aus OpenAPI Spec generiert)
- Redoc (schöneres Design)
- Mintlify / ReadMe.com (gehostet)
- Bruno / Insomnia Collections als Alternative

Folglich erhältst du mit diesem Ansatz deutlich bessere Resultate.

Dennoch sollte man die Limitierungen im Blick behalten.

Prompt 4: Onboarding Guide

Natürlich solltest du den Output immer kritisch hinterfragen.

Zusammenfassend lässt sich sagen, dass dies ein zentraler Aspekt ist.

Erstelle einen Onboarding Guide für neue Team-Mitglieder:

Projekt: [z.B. "Next.js + Prisma + PostgreSQL SaaS"]
Zielgruppe: [z.B. "Neuer Frontend/Backend Entwickler"]

Erstelle:
1. **Voraussetzungen**: Node.js, Docker, Git, IDE Setup
2. **Repo klonen & Setup**: git clone, npm install, .env.local
3. **Lokale Datenbank**: Docker Compose, Migrations, Seed
4. **Dev Server starten**: npm run dev (was man sehen sollte)
5. **Architektur-Überblick**: Ordner-Struktur, wichtige Dateien
6. **Tech Decisions**: Warum Next.js? Warum Prisma? (Verweis auf ADRs)
7. **Workflows**: Branch-Strategie, PR-Prozess, Deploy
8. **Coding Conventions**: ESLint Rules, Naming, File Structure
9. **Hilfreiche Links**: Confluence, Slack Channels, Dashboards
10. **Erste Aufgabe**: "Good First Issue" zum Warmwerden

Ziel: Neuer Dev commited am ersten Tag Code!
Format: Markdown mit Copy-Paste Terminal Commands.

Ebenfalls empfehlenswert ist eine regelmäßige Überprüfung der Ergebnisse.

Prompt 5: Code-Dokumentation

Im Grunde ist der Schlüssel zum Erfolg ein iteratives Vorgehen.

Somit kannst du direkt mit der Umsetzung beginnen.

Generiere Code-Dokumentation aus meinem Code:

Code:
```
[CODE HIER EINFÜGEN]
```

Erstelle:
1. **JSDoc/TSDoc**: Funktions-Dokumentation mit @param, @returns, @example
2. **Inline Comments**: Erklärung von komplexer Logik (WARUM, nicht WAS)
3. **Module Description**: Was macht dieses Modul/diese Klasse?
4. **Usage Examples**: Typische Anwendungsfälle
5. **Type Documentation**: Interfaces/Types mit Beschreibung pro Feld
6. **Error Cases**: Welche Errors können geworfen werden?
7. **Side Effects**: Welche Nebeneffekte gibt es?
8. **Performance Notes**: O(n²) Hinweise, bekannte Bottlenecks
9. **TODO/FIXME**: Bekannte Limitierungen dokumentieren
10. **Deprecation Notices**: Was ist deprecated und warum?

Regel:
- Kommentiere WARUM, nicht WAS (Code sagt WAS)
- Guter Variablen-Name > Kommentar
- Jede exported Funktion braucht JSDoc
- Komplexe Business Logic immer kommentieren

Weiterhin ist es ratsam, die Ergebnisse immer kritisch zu prüfen.

Deshalb ist es wichtig, diesen Abschnitt aufmerksam zu lesen.

Prompt 6: Operations Runbook

Weiterhin profitierst du von der ständigen Weiterentwicklung der AI-Tools.

Dementsprechend solltest du die folgenden Aspekte kennen.

Erstelle ein Operations Runbook für meine App:

App: [z.B. "SaaS auf Vercel + PlanetScale + Redis"]

Erstelle Runbook-Einträge für:
1. **Deployment**: Schritt-für-Schritt Production Deploy
2. **Rollback**: Wie auf vorherige Version zurückkehren
3. **Database Migration**: Sichere Migration in Production
4. **Scaling**: Wann und wie skalieren
5. **Backup & Restore**: DB Backup Procedure
6. **Secret Rotation**: API Keys, DB Passwörter ändern
7. **SSL/TLS**: Zertifikate erneuern
8. **Monitoring Check**: Tägliche Checks
9. **Emergency Contacts**: Wer ist wann erreichbar?
10. **Vendor Status Pages**: Wo prüfe ich ob Vercel/DB down ist?

Format pro Eintrag:
- Wann nutzen (Trigger/Symptom)
- Schritt-für-Schritt Anleitung
- Terminal Commands (copy-paste)
- Erwartetes Ergebnis
- Eskalation wenn es nicht funktioniert

Dabei zeigt dieses Beispiel den grundlegenden Ansatz.

Grundsätzlich empfiehlt es sich, schrittweise vorzugehen.

Prompt 7: Changelog & Release Notes

Grundsätzlich gilt: Je präziser dein Prompt, desto besser das Ergebnis.

Tatsächlich ist dieser Bereich besonders wichtig für Entwickler.

Erstelle Changelog und Release Notes:

Änderungen seit letztem Release:
```
[GIT LOG / COMMIT MESSAGES / PR TITLES HIER]
```

Erstelle:
1. **CHANGELOG.md**: Keep a Changelog Format (keepachangelog.com)
2. **Kategorien**: Added, Changed, Deprecated, Removed, Fixed, Security
3. **User-facing**: Technische Commits zu User-verständlichen Einträgen
4. **Breaking Changes**: Deutlich hervorgehoben mit Migration Guide
5. **Semantic Versioning**: Major/Minor/Patch basierend auf Änderungen
6. **GitHub Release**: Formatierte Release Notes für GitHub
7. **Blog Post**: Längerer Blog Post für größere Releases
8. **Migration Guide**: Schritt-für-Schritt bei Breaking Changes
9. **Known Issues**: Bekannte Probleme in diesem Release
10. **Credits**: Contributors und deren Beiträge

Automatisierung:
- Conventional Commits → Auto Changelog (standard-version)
- @changesets/cli für Monorepos
- release-please für GitHub Releases

Außerdem kannst du den Prompt für verschiedene Programmiersprachen anpassen.

Ebenso hilfreich ist ein strukturierter Ansatz bei der Umsetzung.

Prompt 8: Architektur-Diagramme

Dabei solltest du besonders auf die Details achten.

Außerdem gibt es hilfreiche Tools, die dich dabei unterstützen.

Erstelle Architektur-Diagramme für mein Projekt:

System: [z.B. "Next.js → API → PostgreSQL → Redis → Stripe"]

Erstelle als Mermaid Diagramme:
1. **System Overview**: High-Level Komponenten und Verbindungen
2. **Sequence Diagram**: User Checkout Flow (Frontend → API → Payment)
3. **ER Diagram**: Datenbank-Relationen
4. **Deployment Diagram**: Vercel, DB, Redis, CDN
5. **Component Diagram**: Frontend Module und Dependencies
6. **Flow Chart**: CI/CD Pipeline
7. **State Machine**: Order Status (Pending → Paid → Shipped → Delivered)
8. **Class Diagram**: Wichtige Domain Models
9. **C4 Model**: Context, Container, Component, Code Levels
10. **Network Diagram**: Firewall, Load Balancer, Subnets

Mermaid Syntax:
```mermaid
graph TD
    A[User] --> B[Next.js on Vercel]
    B --> C[API Routes]
    C --> D[(PostgreSQL)]
    C --> E[(Redis Cache)]
```

Tools: Mermaid (in Markdown), Excalidraw, draw.io

Darüber hinaus solltest du diesen Aspekt berücksichtigen.

Prompt 9: Technical RFC

Tatsächlich macht dieser Ansatz in der Praxis den Unterschied.

Deshalb lohnt es sich, dieses Thema genauer zu betrachten.

Erstelle ein Technical RFC (Request for Comments):

Feature: [z.B. "Echtzeit-Notifications per WebSocket"]
Kontext: [z.B. "Aktuell Polling alle 30s, wird zu teuer bei Scale"]

Erstelle RFC mit:
1. **Summary**: Was wird vorgeschlagen? (1 Absatz)
2. **Motivation**: Warum brauchen wir das?
3. **Background**: Aktueller Stand und Probleme
4. **Proposed Solution**: Detaillierter technischer Vorschlag
5. **Alternatives**: Andere Lösungen die evaluiert wurden
6. **Design Details**: API, Datenmodell, Architektur
7. **Migration Plan**: Schrittweise Umsetzung
8. **Testing Strategy**: Wie wird die Lösung getestet?
9. **Risks & Mitigations**: Risiken und Gegenmaßnahmen
10. **Open Questions**: Was muss noch geklärt werden?

RFC Prozess:
- Draft → Team Review (1 Woche) → Approved/Rejected
- Alle können kommentieren
- Entscheidung wird dokumentiert (→ ADR)
- Implementation nach Approval

Deshalb empfiehlt es sich, den Prompt schrittweise zu verfeinern.

Somit ergibt sich ein klarer Vorteil gegenüber manuellen Methoden.

Prompt 10: Dokumentation aktuell halten

Somit bist du optimal vorbereitet, um dieses Wissen anzuwenden.

Vor allem für den praktischen Einsatz sind diese Informationen wertvoll.

Erstelle eine Strategie um Dokumentation aktuell zu halten:

Problem: [z.B. "Docs sind veraltet, niemand pflegt sie"]

Strategien:
1. **Docs-as-Code**: Dokumentation im gleichen Repo wie Code
2. **PR Rule**: Jeder PR mit Code-Änderung muss Docs updaten
3. **Auto-Generated Docs**: TypeDoc, Swagger, Storybook
4. **Doc Tests**: Prüfe ob Code-Beispiele in Docs noch funktionieren
5. **Docs Owner**: Pro Sektion gibt es einen Verantwortlichen
6. **Review Cycle**: Quartalsweise Docs-Review im Sprint
7. **Stale Detection**: Bot der bei veralteten Docs warnt
8. **Search**: Algolia DocSearch für schnelles Finden
9. **Feedback**: "War diese Seite hilfreich?" Button
10. **Templates**: Prefilled Templates für neue Docs

Minimale Dokumentation die immer gepflegt sein muss:
- README (Setup + Quick Start)
- ADRs (Entscheidungen)
- API Docs (auto-generiert!)
- Runbook (Operations)

Alles andere: Lieber keine Docs als veraltete Docs!

Somit sparst du Zeit und erhältst qualitativ hochwertigeren Output.

Vor allem in der Praxis hat sich dieser Workflow bewährt.

FAQ

Was ist die wichtigste Dokumentation?

Allerdings gibt es dabei auch einige Fallstricke zu beachten.

Darüber hinaus bietet dieser Abschnitt konkrete Beispiele und Tipps.

1. Deshalb rEADME (wie starte ich?), 2. ADRs (warum so?), 3. API Docs (wie nutze ich?), 4. Runbook (was wenn kaputt?). Diese vier decken 80% des Bedarfs. Alles andere ist nice-to-have. Lieber wenig aber aktuell als viel und veraltet.

Wie halten wir Docs aktuell?

Hierbei ist es entscheidend, den richtigen Kontext zu liefern.

Dennoch solltest du einige Besonderheiten beachten.

Docs-as-Code: Dokumentation im gleichen Repo, im gleichen PR geändert. Zudem auto-generierte Docs wo möglich (TypeDoc, Swagger). PR-Review Checklist: „Docs updated?“. Quartalsweiser Review-Sprint. Veraltete Docs sind schlimmer als keine Docs.

Kann AI meine Dokumentation schreiben?

Ebenfalls wichtig: Die regelmäßige Überprüfung der Ergebnisse.

Insbesondere für den Einstieg sind die folgenden Informationen hilfreich.

AI kann READMEs, JSDoc, ADRs, Onboarding Guides und API Docs aus Code generieren. Natürlich paste deinen Code und lass AI die Dokumentation erstellen. Dann prüfen und anpassen. Für ADRs: Beschreibe die Entscheidung, AI erstellt das strukturierte Dokument.

Außerdem profitierst du von einem systematischen Vorgehen.

Verwandte Artikel:

Folglich verbessert sich die gesamte Codequalität deutlich.

Dabei zuletzt aktualisiert: März 2026

Der Beitrag AI für Tech-Dokumentation & ADRs erschien zuerst auf MetinCelik.de.

ADR Archive - MetinCelik.de