technische-dokumentation

Technische Dokumentation

Zweck

Erstellung und Überprüfung technischer Dokumentation, die klar, umsetzbar und wartbar ist – sowohl für Menschen als auch für Agenten. Dies umfasst Contributor-Governance-Dateien und Agenten-Anweisungsdateien.

Wann verwenden

• Erstellung oder Überarbeitung von Dokumentation in einem bestehenden Produkt/Codebase (Brownfield).
• Aufbau zeitloser Dokumentation, die über lange Zeit genau und wiederverwendbar bleibt (Evergreen).
• Überprüfung von Doc-Diffs auf Struktur, Klarheit und operationelle Korrektheit.
• Durchführung von Repo-weiten Dokumentationsaudits, die sowohl Governance-Dateien als auch Produktdokumentationsflächen (docs/, README*, .md/.mdx/.mdc, Fern-/Sphinx-/Mintlify-Quellen) umfassen müssen.
• Aktualisierung oder Überprüfung von AGENTS.md und/oder CONTRIBUTING.md, um Agenten- und Contributor-Workflows an die aktuellen Repo-Praktiken anzupassen.
• Verbesserung der Repository-Einsteigerdokumentation, einschließlich Beitragsanweisungen, Issue-Vorlagen, PR-Flow und Review-Gates.
• Gestaltung einer Governance-Dokumentationsstrategie für Repos mit Alias-Anweisungsdateien (z. B. CLAUDE.md, AGENT.md, .cursorrules, .cursor/rules/*, .agent/, .agents/, .pi/), wobei AGENTS.md als kanonisch behandelt wird, wenn vorhanden, und Aliase als Kompatibilitätsoberflächen erhalten bleiben.
• Diagnose von Agenten-Datei-Drift, wenn Teams iterativ auffordern mussten, um fehlende Dateien, kaputte Befehle oder Richtlinienkonflikte aufzudecken.
• Anwendung von Repository-spezifischen Dokumentationsüberlagerungen, einschließlich OpenClaw-Seitentyp, Docs-IA, Erhaltungs- und Validierungsregeln, wenn vorhanden.

Arbeitsablauf

1. Aufgabe klassifizieren: build oder review; Kontext: brownfield oder evergreen.
2. Frühzeitig den Umfang der angeforderten Datei, des Verzeichnisses oder des Diffs inventarisieren. Governance- und Produktdokumentation für dokumentationsweite Arbeiten einbeziehen. Die Repository-Größe allein erweitert keine abgegrenzte Überprüfung.
3. Mehrsprachigen Umfang erkennen (README/Docs in mehreren Sprachen) und erforderliches Paritätsniveau definieren.
4. references/agent-and-contributing.md für Agenten-Anweisungen und CONTRIBUTING.md-Workflow-Regeln lesen (Inventarisierung, kanonische/Alias-Zuordnung, Dual-Mode-Balance, Lieferstandards und Prioritäts-/Konflikthandhabung).
5. references/principles.md für das geltende Regelwerk lesen (Matt Palmer & OpenAI).
6. Für OpenClaw-Dokumentationsarbeit vor dem Build/Review-Playbook references/openclaw.md lesen.
7. Für Build-Aufgaben references/build.md befolgen.
8. Für Review-Aufgaben references/review.md befolgen und Probleme proaktiv erkennen, ohne auf wiederholte Aufforderungen zu warten.
9. Bei komplexen oder risikoreichen Aufgaben (Build oder Review) ist es akzeptabel, bei Bedarf längere, tiefere und gründlichere Untersuchungen durchzuführen, um Vertrauen zu gewinnen.
10. Wenn verfügbar, Unter-Agenten für begrenzte parallele Entdeckungs-/Review-Arbeiten verwenden, dann Ergebnisse in einem kohärenten endgültigen Liefergegenstand zusammenführen.
11. references/tooling.md verwenden, wenn Plattform-/Tooling-Entscheidungen Empfehlungen beeinflussen.
12. Eine proaktive Problemsuche innerhalb des angeforderten Umfangs durchführen. Fehler mit hoher Sicherheit im selben Durchgang beheben, es sei denn, ein reiner Berichtsmodus wurde angefordert.
13. Im Brownfield-Modus Kompatibilität mit der aktuellen Docs-IA, dem Tooling und dem Release-Status priorisieren.
14. Im Evergreen-Modus zeitlose Formulierungen, Aktualisierungsstrategie und dauerhafte Struktur priorisieren.
15. Liefergegenstände sowie Validierungshinweise, Paritätsstatus und verbleibende Lücken zurückgeben.

Richtlinien zur Orchestrierung von Unter-Agenten

Bevorzugen Sie Unter-Agenten, wenn das Repository groß oder der angeforderte Änderungssatz umfangreich ist; verwenden Sie sie standardmäßig für Repo-weite, Multi-Framework- oder hochkonfliktträchtige Arbeiten.

• inventory-agent -> agents/inventory-agent.md (fast / Claude haiku): Datei-/Konfigurationserkennung, Coverage-Karte und Prüfung auf fehlende Pfade.
• governance-agent -> agents/governance-agent.md (thinking / Claude sonnet): AGENTS/CONTRIBUTING/Alias-Priorität, Konflikte und Richtliniendrift.
• docs-framework-agent -> agents/docs-framework-agent.md (thinking / Claude sonnet): Framework-Konfiguration, relativer Pfadbasis und Prüfung der Zuordnung von Dateipfad zu URL-Pfad.
• synthesis-agent -> agents/synthesis-agent.md (long / Claude opus): Zusammenführen der Ergebnisse von Unter-Agenten in einen priorisierten Fix-Plan und ein einheitliches Prioritätsmodell.

Eingaben

• Dokumenttyp (Tutorial, How-to, Referenz, Erklärung) und Zielgruppe.
• Dateiumfang oder Diff-Umfang.
• Docs-Framework-/Tooling-Einschränkungen (Fern, Mintlify, Sphinx usw.).
• Build/Review-Modus und Brownfield/Evergreen-Absicht.
• Ziel-Agenten- und Menschen-Kompatibilitätsabsicht.
• Docs-Framework-Oberflächen im Umfang (z. B. Fern, Sphinx, Mintlify, Markdown-/MDX-/MDC-/RST-/RSC-Dateien).
• Gewünschte Untersuchungstiefe/Zeitbudget (schneller Durchlauf vs. gründliche Überprüfung).
• Ausführungsmodus (single-agent oder sub-agent-assisted, falls verfügbar).
• Sanierungsmodus (apply-fixes standardmäßig oder report-only, wenn angefordert).
• Mehrsprachiger Umfang: Source-of-Truth-Sprache, Ziel-Lokale und Paritätserwartungen.
• Repository-spezifische Überlagerungsbeschränkungen, falls vorhanden.

Ausgaben

• Aktualisierter Entwurf oder Prüfungsergebnisse mit klaren nächsten Schritten.
• Validierungshinweise (was geprüft wurde, was aussteht).
• Navigations-/Wartungsempfehlungen für langfristige Qualität.
• Governance-Dokumentations-Angleichungszusammenfassung, wenn AGENTS/CONTRIBUTING berührt wurden.
• Agenten-Anweisungsoberflächenkarte (primäre Datei, Aliasdateien, Codex/Claude/Cursor-Behandlungsplan).
• Dokumentationsoberflächen-Coverage-Karte (was unter /docs überprüft wurde, README-Hierarchie und Framework-spezifische Quellbäume).
• Automatisch erkannte Problemliste mit angewendeten Korrekturen (oder explizite Report-Only-Ergebnisse).
• Delegationshinweise, wenn Unter-Agenten verwendet wurden (delegierter Umfang und wie Ergebnisse zusammengeführt wurden).
• Mehrsprachige Paritätsnotiz (synchron, teilweise mit Begründung oder absichtlich abweichend).
• Repository-spezifische Überlagerungshinweise, wenn eine verwendet wurde.