Doku-Strategie: Standards & Strukturen für AI-assisted Pflege ohne Drift #62

New Issue

tobias · 2026-04-10T00:54:42+02:00

tobias commented

2026-04-10 00:54:42 +02:00

Frage

Welche anerkannten Standards und Strukturen gibt es für Doku-Pflege in einem AI-assisted Codebase, sodass es kein Aktualisierungsproblem gibt? Pflege im Code + Generierung, oder was ist sinnvoll?

Diskussion (Sessionsprotokoll 2026-04-10)

Kurzantwort: Kein anerkannter Standard für "LLM generiert Doku autoritativ" — das ist Antipattern (nicht-deterministisch, teuer, drift-anfällig). Der etablierte Sweet-Spot ist Pflege im Code → Generieren via Tooling, LLM nur als Schreib-Assistent für Drafts und Konsistenz-Reviews.

Anerkannte Bausteine

Diátaxis Framework (https://diataxis.fr) — vier Doku-Quadranten Tutorials/How-to/Reference/Explanation. Verwendet von Django, FastAPI, NumPy. Klare Trennung welcher Teil generiert wird (Reference) und welcher manuell.
Docstring-as-source-of-truth + Auto-Generation:
- Python: mkdocs + mkdocstrings zieht Docstrings + Pydantic-Schemas → Reference-Site mit null Drift
- Sphinx mit autodoc als ältere robuste Alternative
- FastAPI hat OpenAPI-Auto-Gen schon eingebaut
Architecture Decision Records (ADRs) — kurze immutable Markdown-Files in mit Context/Decision/Consequences. Bei Änderung superseded (neuer ADR ersetzt alten), nie überschrieben. Drift-immun.
Doctest — Code-Beispiele in Docstrings sind echte Tests via .
CLAUDE.md / agent-instructions als AI-Onboarding-Layer (Anthropic/Cursor/Aider Konvention).
README-Driven Development + Changelog (Keep-a-Changelog, Conventional Commits).

Wo LLM hilft / wo NICHT

Wofür	Wofür NICHT
Initiale Docstring-Drafts	Autoritative Reference generieren
Konsistenz-Review im CI ("Docstring noch korrekt nach Diff X?")	Architektur-Entscheidungen treffen
Tutorial-Drafts	Live-Doku auto-regenerieren
Pre-commit-Lint von Docstrings	Code aus Doku rückwärts-generieren

Konkret für gwoe-antragspruefer

Aktueller Stand:

hat exzellente Docstrings pro Adapter mit Reverse-Engineering-Findings → nahe Diátaxis-Reference, nur Tooling fehlt
ist einzige Onboarding-Quelle, gepflegt
(29. März, statisch, teilweise stale) und sind klassische Drift-Fallen
Keine ADRs, keine Reference-Site, keine Doctests

Empfohlene Schritte (priorisiert)

-Folder einführen, wichtige Entscheidungen retrospektiv festhalten:
- ADR 0001 LLM-Citation-Binding (warum Option B aus #60 strukturell nötig war)
- ADR 0002 Adapter-Architektur (Klassen vs. parametrisierte Subclasses)
- ADR 0003 Embedding-Pipeline mit reconstruct_zitate
- ADR 0004 Sub-D Citation-Property-Tests
  Klein, einmalig, danach immutable.
mkdocs + mkdocstrings aufsetzen → Reference-Site aus Adapter-Docstrings. ~1h Setup, danach null Pflegeaufwand.
** und archivieren oder ersetzen** durch generated reference + ADR-Index + knappes README.
Doctest-Cleanup-Pass auf bestehende Docstring-Examples (ein paar im embeddings.py).
Pre-commit-Hook für LLM-Doku-Review als nice-to-have.

Acceptance Criteria (Vorschlag)

als Referenz-ADR angelegt
mkdocs.yml + mkdocstrings konfiguriert, rendert Reference aus parlamente.py + embeddings.py + analyzer.py
/ entweder aktualisiert oder durch Verweis auf generated docs ersetzt
CI-Step der ausführt
CLAUDE.md aktualisiert mit Verweis auf docs/-Struktur

## Frage Welche anerkannten Standards und Strukturen gibt es für Doku-Pflege in einem AI-assisted Codebase, sodass es kein Aktualisierungsproblem gibt? Pflege im Code + Generierung, oder was ist sinnvoll? ## Diskussion (Sessionsprotokoll 2026-04-10) **Kurzantwort:** Kein anerkannter Standard für "LLM generiert Doku autoritativ" — das ist Antipattern (nicht-deterministisch, teuer, drift-anfällig). Der etablierte Sweet-Spot ist **Pflege im Code → Generieren via Tooling, LLM nur als Schreib-Assistent für Drafts und Konsistenz-Reviews**. ### Anerkannte Bausteine 1. **Diátaxis Framework** (https://diataxis.fr) — vier Doku-Quadranten Tutorials/How-to/Reference/Explanation. Verwendet von Django, FastAPI, NumPy. Klare Trennung welcher Teil generiert wird (Reference) und welcher manuell. 2. **Docstring-as-source-of-truth + Auto-Generation:** - Python: mkdocs + mkdocstrings zieht Docstrings + Pydantic-Schemas → Reference-Site mit null Drift - Sphinx mit autodoc als ältere robuste Alternative - FastAPI hat OpenAPI-Auto-Gen schon eingebaut 3. **Architecture Decision Records (ADRs)** — kurze immutable Markdown-Files in mit Context/Decision/Consequences. Bei Änderung superseded (neuer ADR ersetzt alten), nie überschrieben. Drift-immun. 4. **Doctest** — Code-Beispiele in Docstrings sind echte Tests via . 5. **CLAUDE.md / agent-instructions** als AI-Onboarding-Layer (Anthropic/Cursor/Aider Konvention). 6. **README-Driven Development + Changelog** (Keep-a-Changelog, Conventional Commits). ### Wo LLM hilft / wo NICHT | Wofür | Wofür NICHT | |---|---| | Initiale Docstring-Drafts | Autoritative Reference generieren | | Konsistenz-Review im CI ("Docstring noch korrekt nach Diff X?") | Architektur-Entscheidungen treffen | | Tutorial-Drafts | Live-Doku auto-regenerieren | | Pre-commit-Lint von Docstrings | Code aus Doku rückwärts-generieren | ### Konkret für gwoe-antragspruefer Aktueller Stand: - hat exzellente Docstrings pro Adapter mit Reverse-Engineering-Findings → nahe Diátaxis-Reference, nur Tooling fehlt - ist einzige Onboarding-Quelle, gepflegt - (29. März, statisch, teilweise stale) und sind klassische Drift-Fallen - Keine ADRs, keine Reference-Site, keine Doctests ### Empfohlene Schritte (priorisiert) 1. **-Folder einführen**, wichtige Entscheidungen retrospektiv festhalten: - ADR 0001 LLM-Citation-Binding (warum Option B aus #60 strukturell nötig war) - ADR 0002 Adapter-Architektur (Klassen vs. parametrisierte Subclasses) - ADR 0003 Embedding-Pipeline mit reconstruct_zitate - ADR 0004 Sub-D Citation-Property-Tests Klein, einmalig, danach immutable. 2. **mkdocs + mkdocstrings aufsetzen** → Reference-Site aus Adapter-Docstrings. ~1h Setup, danach null Pflegeaufwand. 3. ** und archivieren oder ersetzen** durch generated reference + ADR-Index + knappes README. 4. **Doctest-Cleanup-Pass** auf bestehende Docstring-Examples (ein paar im embeddings.py). 5. **Pre-commit-Hook für LLM-Doku-Review** als nice-to-have. ## Acceptance Criteria (Vorschlag) - [ ] als Referenz-ADR angelegt - [ ] - [ ] mkdocs.yml + mkdocstrings konfiguriert, rendert Reference aus parlamente.py + embeddings.py + analyzer.py - [ ] / entweder aktualisiert oder durch Verweis auf generated docs ersetzt - [ ] CI-Step der ausführt - [ ] CLAUDE.md aktualisiert mit Verweis auf docs/-Struktur

tobias referenced this issue from a commit

2026-04-10 01:38:10 +02:00

#62 Phase 1+3: ADRs + Doku-Struktur in webapp/docs/

tobias referenced this issue from a commit

2026-04-10 09:42:47 +02:00

#62 Phase 2: mkdocs + caddy-gitea-pages Hosting auf docs.gwoe.toppyr.de

tobias referenced this issue from a commit

2026-04-10 09:47:08 +02:00

#62 Phase 2: Pivot nginx + docs.toppyr.de/gwoe-antragspruefer/

tobias referenced this issue from a commit

2026-04-10 14:14:18 +02:00

#62: API-Reference + Datenmodelle + Embeddings-Pipeline (mkdocstrings)