Projektdokumentation

Hilft beim Erstellen und Aktualisieren des gesamten Dokumentations-Sets eines Softwareprojekts, unter Einhaltung einer festen Struktur und einer festgelegten Beziehung zwischen AGENTS.md und MEMORY.md. Verwende diese Fähigkeit jedes Mal, wenn der Nutzer eine Dokumentation von Grund auf neu erstellen, nach Änderungen aktualisieren oder die Konsistenz zwischen den Dateien sicherstellen möchte.

Zielstruktur

Jedes Projekt, das diese Fähigkeit verwaltet, sollte sich diesem Layout annähern:

mi-proyecto/
├── README.md          # Was es ist, wie man es startet
├── AGENTS.md           # Regeln und Anweisungen für Agenten
├── MEMORY.md            # Aktuelle Entscheidungen und Verworfenes
├── CHANGELOG.md          # Was sich zwischen Versionen geändert hat
├── DESIGN.md             # Visuelles Design-System (nur bei UI)
└── docs/
    ├── architecture.md
    ├── plans/            # Pläne der Agenten, eine Datei pro Plan
    └── (OpenAPI + Scalar, bereitgestellt von der API unter /docs)

Falls das Projekt bereits einige dieser Dateien besitzt, lies sie zuerst und aktualisiere sie direkt – überschreibe sie nicht blind. Wenn eine Datei fehlt, erstelle sie gemäß der entsprechenden Vorlage unten.

Arbeitsablauf

Erhebe, was existiert. Liste das Projektwurzelverzeichnis und docs/ auf, um zu sehen, welche Dateien bereits vorhanden sind. Lies bestehende AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md vollständig – sie sind absichtlich kurz gehalten.
Ermittle den Umfang. Wenn der Nutzer eine bestimmte Datei nennt (z.B. „aktualisiere das CHANGELOG“), konzentriere dich darauf, prüfe aber trotzdem, ob diese Änderung Auswirkungen auf MEMORY.md oder AGENTS.md haben sollte (siehe Propagierungsregel unten). Wenn der Nutzer etwas Allgemeines sagt wie „dokumentiere mein Projekt“ oder „aktualisiere die Dokumentation“, gehe jede Datei in der obigen Struktur durch.
Sammle die Fakten, die du aus der Codebasis selbst benötigst (Paketmanifeste, Einstiegspunkte, Skripte, Routen, aktuelle Commits) anstatt zu raten. Erfinde keine Befehle, Stack-Details oder Endpunkte – überprüfe sie, indem du den Code oder die Konfigurationsdateien liest.
Schreibe oder aktualisiere jede Datei mit der entsprechenden Referenzvorlage. Halte die strengen Längenlimits für AGENTS.md (~30-40 Zeilen) und MEMORY.md (~50 Zeilen) ein – dies sind tragende Einschränkungen, keine Vorschläge, da Agenten diese Dateien in jeder Sitzung neu lesen und aufgeblähte Versionen nicht mehr nützlich sind.
Berichte zurück, welche Dateien erstellt bzw. aktualisiert wurden, und weise auf alles hin, das du nicht verifizieren konntest (z.B. „ich habe keinen Testbefehl gefunden, bitte bestätige“).

Die Dokumente

README.md

Beantwortet für einen Menschen die Fragen „Was ist das und wie führe ich es aus?“. Siehe references/readme-template.md. Entnimm die Befehle zum Ausführen/Installieren/Testen direkt den tatsächlichen Skripten des Projekts (package.json, Makefile, pyproject.toml, etc.) – rate niemals Befehl-Namen.

AGENTS.md

Anweisungen für Code-Agenten, die in diesem Repository arbeiten. Siehe references/agents-template.md für die genauen Abschnitte und deren Reihenfolge. Hartes Limit: insgesamt ~30-40 Zeilen. Wenn es bereits länger ist, besteht deine Aufgabe beim Aktualisieren ebenso im Kürzen wie im Hinzufügen – verschiebe alles, was wie eine vorübergehende Entscheidung oder eine in Bearbeitung befindliche Notiz wirkt, stattdessen in MEMORY.md und behalte hier nur dauerhafte Regeln.

MEMORY.md

Sitzungsübergreifendes Gedächtnis: was im Moment wahr ist, warum wichtige Entscheidungen getroffen wurden, was ausprobiert und verworfen wurde, was als nächstes ansteht. Siehe references/memory-template.md. Hartes Limit: ~50 Zeilen. Kürze beim Aktualisieren aktiv – lösche oder komprimiere Einträge, die nicht mehr relevant sind, anstatt die Datei endlos wachsen zu lassen.

Wie AGENTS.md und MEMORY.md zusammenhängen (dies ist die Kernkonvention – mach es richtig):

AGENTS.md muss einen kurzen Abschnitt „Memoria“ enthalten, der den Agenten sagt, sie sollen zu Beginn einer Aufgabe MEMORY.md lesen und am Ende aktualisieren. Verwende diese genaue Formulierung als Basis und passe sie nur an, wenn das Projekt sie bereits anders formuliert:

## Memoria
- Al empezar, lee `MEMORY.md` para conocer el estado del proyecto y las decisiones tomadas.
- Al terminar una tarea, actualízalo: estado actual, decisiones importantes (con su porqué) y errores a evitar.
- Mantenlo breve (máximo ~50 líneas): resume o elimina lo que ya no aporte.
- Si algo se convierte en una regla permanente, propón moverlo a `AGENTS.md` en lugar de dejarlo en la memoria.
- No guardes nunca datos sensibles (claves, tokens, datos personales).

Der Abschnitt „Límites“ in AGENTS.md muss ✅ Siempre: actualizar MEMORY.md al terminar cada tarea. enthalten.
Propagierungsregel: MEMORY.md enthält Dinge, die für den Moment wahr sind – aktueller Zustand, Entscheidungen mit Begründung, gewonnene Erkenntnisse, nächste Schritte. AGENTS.md enthält Dinge, die immer wahr sind – dauerhafte Regeln, Konventionen, Stack, Grenzen. Wenn etwas in MEMORY.md aufhört, eine einmalige Entscheidung zu sein, und zu einer ständigen Regel wird (z.B. aus „wir haben beschlossen, X nie zu verwenden“ wird „verwende X nie, Punkt“), verschiebe es nach oben in AGENTS.md und entferne es aus MEMORY.md. Überprüfe beim Aktualisieren einer der beiden Dateien immer, ob diese Beförderung stattfinden sollte.
Schreibe niemals Geheimnisse, Tokens oder personenbezogene Daten in eine der beiden Dateien.

CHANGELOG.md

Beantwortet die Frage „Was hat sich zwischen den Versionen geändert?“. Folge der Keep a Changelog-Konvention (Added/Changed/Fixed/Removed unter jeder Version, Neuestes zuerst, mit einem Unreleased-Abschnitt ganz oben für laufende Arbeiten). Siehe references/changelog-template.md. Füge beim Aktualisieren Einträge unter Unreleased hinzu, während die Arbeit erledigt wird, und erstelle einen neuen datierten Versionsabschnitt erst, wenn der Nutzer eine Veröffentlichung signalisiert.

DESIGN.md

Beantwortet die Fragen „Wie sieht es aus und wie sollte die UI gebaut werden?“ – das visuelle Design-System, gelesen von Agenten, die UI generieren. Es liegt im Projektwurzelverzeichnis (nicht in docs/), neben AGENTS.md. Es folgt dem offenen Google Stitch DESIGN.md-Format (Spezifikation: github.com/google-labs-code/design.md, derzeit alpha). Siehe references/design-template.md für die Vorlage und eine Erklärung jedes Blocks.

Nur für Projekte mit einer Benutzeroberfläche (Web, mobil, Desktop). Wenn das Projekt eine reine API/CLI/Bibliothek ohne UI ist, erstelle es nicht und erwähne dies im Bericht.
Zwei Ebenen: YAML-Frontmatter mit maschinenlesbaren Tokens (colors, typography, rounded, spacing, components) – dies sind die normativen Werte – plus einem Markdown-Textkörper, der das Warum erklärt. Tokens sagen was; Prosa sagt wann und warum und verweist auf Tokens mit Namen, anstatt Hex-Codes zu wiederholen.
Abschnittsreihenfolge ist fest: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts. Behalte diese Überschriften genau so bei (Tools identifizieren sie anhand des Namens; die Aliase Brand & Style, Layout & Spacing und Elevation werden ebenfalls akzeptiert) und schreibe die Prosa in der Sprache des Projekts. Abschnitte können weggelassen, aber nicht umsortiert werden, und eine doppelte Überschrift ist ein Fehler. Zusätzliche Abschnitte (z.B. Iconography & Imagery, Motion, Accessibility) sind erlaubt – platziere sie immer nach Do's and Don'ts.
Entnimm Werte aus dem Code, erfinde sie niemals: Tailwind-Konfiguration, CSS-Variablen (:root, globals.css), UI-Library-Theme-Dateien, geladene Schriftarten, Figma/DTCG-Token-Exporte. Wenn das Projekt eine UI, aber noch keine definierte visuelle Identität hat, schlage Werte vor und kennzeichne sie im Bericht als „Vorschlag, bitte bestätigen“.
Wenn bereits eine DESIGN.md existiert, lies sie und aktualisiere sie direkt – überschreibe sie niemals stillschweigend. Halte Tokens mit dem Code synchron, wenn Farben, Schriftarten oder Abstände geändert werden.
Kein striktes Zeilenlimit (es ist ein Referenzdokument wie docs/architecture.md), aber halte jeden Abschnitt fokussiert: 3–6 Aufzählungspunkte oder ein kurzer Absatz.
Validiere: Wenn Node verfügbar ist, führe npx @google/design.md lint DESIGN.md aus und behebe Fehler (broken-ref) und sinnvolle Warnungen (missing-primary, contrast-ratio, section-order); andernfalls teile dem Nutzer den Befehl mit.
Wenn AGENTS.md existiert und DESIGN.md nicht erwähnt, schlage dem Nutzer vor (wende es nicht selbstständig an), einen einzeiligen Verweis hinzuzufügen, damit UI-Agenten es vor dem Generieren von UI lesen – beachte das ~30-40-Zeilen-Limit von AGENTS.md.

docs/architecture.md

Beantwortet die Frage „Wie ist das gebaut?“ – Komponenten, Datenfluss, wichtige Design-Entscheidungen und deren Gründe, bemerkenswerte Einschränkungen. Siehe references/architecture-template.md. Dies ist das eine Dokument, das länger sein darf als die anderen, da es ein Referenzdokument ist und nicht jede Sitzung erneut gelesen wird – bevorzuge aber dennoch Diagramme und kurze Abschnitte gegenüber langen Prosatexten. Verwende ein Mermaid-Diagramm für die Hauptkomponenten-/Datenflussansicht, wenn es hilfreich ist.

docs/plans/

Wenn ein Agent einen Plan für eine nicht-triviale Aufgabe erstellt (ein mehrstufiger Implementierungsplan, ein Migrationsplan, ein Refactoring-Plan), speichere ihn hier als eigene Datei, anstatt ihn nur im Chat zu hinterlassen. Erstelle das Verzeichnis, falls es nicht existiert. Benenne Dateien nach dem Schema YYYY-MM-DD-kurzer-slug.md (z.B. 2026-10-03-add-payment-webhook.md), damit sie chronologisch sortiert sind. Jede Plan-Datei sollte in sich abgeschlossen sein: Ziel, Ansatz, Schritte, offene Fragen. Lösche alte Pläne nicht, nachdem sie abgeschlossen sind – sie sind eine historische Aufzeichnung; wenn das Projekt eine „erledigt“-Markierung wünscht, füge stattdessen eine einzeilige Statusnotiz am Anfang der Datei hinzu, anstatt sie zu entfernen.

API-Dokumentation – OpenAPI + Scalar

Dies ist keine statische Markdown-Datei – sie wird live von der API bereitgestellt, typischerweise unter einer /docs- oder /reference-Route über Scalar's API-Reference-Renderer, der eine OpenAPI-Spezifikation liest. Wenn der Nutzer darum bittet, API-Dokumentation einzurichten oder zu aktualisieren:

Überprüfe, ob das Projekt bereits eine OpenAPI-Spezifikation generiert (Framework-Dekorateure/Annotationen, eine openapi.yaml/openapi.json-Datei oder eine bereits in den Abhängigkeiten enthaltene Spezifikationsgenerierungsbibliothek).
Wenn die Spezifikation existiert, aber noch nicht über Scalar bereitgestellt wird, richte die Scalar-Middleware/den Handler für das Framework des Projekts ein (Scalar hat offizielle Integrationen für die meisten gängigen Backend-Frameworks – überprüfe die aktuellen Paketnamen/APIs, anstatt Annahmen zu treffen, da sich dieses Ökosystem schnell weiterentwickelt) und mounte sie unter /docs.
Wenn noch keine Spezifikation existiert, generiere eine aus den vorhandenen Routen/Handlern (die meisten Frameworks haben eine Bibliothek, die OpenAPI aus Routendefinitionen/Typen ableitet – bevorzuge dies gegenüber dem händischen Schreiben von YAML), bevor du Scalar einrichtest.
Pflege niemals manuell eine riesige statische OpenAPI-YAML-Datei, wenn das Framework sie aus dem Code ableiten kann – das gerät sofort außer Sync. Bevorzuge Code-First-Generierung.
Notiere die /docs-URL in README.md, sobald sie eingerichtet ist, damit Menschen wissen, wo sie sie finden.

Checkliste vor dem Abschluss

AGENTS.md ist ≤ ~40 Zeilen und enthält einen Abschnitt „Memoria“, der auf MEMORY.md verweist
MEMORY.md ist ≤ ~50 Zeilen und nichts Bleibendes, das in AGENTS.md gehört, ist darin gestrandet
README.md-Befehle wurden gegen die tatsächliche Projektkonfiguration überprüft, nicht angenommen
CHANGELOG.md folgt dem Keep-a-Changelog-Format mit einem Unreleased-Abschnitt
DESIGN.md (nur wenn das Projekt eine UI hat) liegt im Projektwurzelverzeichnis, seine Tokens stimmen mit dem echten Code überein, die Abschnitte folgen der kanonischen Reihenfolge und npx @google/design.md lint DESIGN.md meldet keine Fehler
docs/architecture.md spiegelt die aktuelle Struktur wider, keine veraltete
Neue Agentenpläne werden unter docs/plans/ mit einem datierten Dateinamen gespeichert
In kein Dokument wurden sensible Daten (Schlüssel, Tokens, personenbezogene Daten) geschrieben

Projekt-Dokumentations-Set (Johan409IA/skills)

Was ist skills)?

In Ihrer bevorzugten KI fragen

Dokumentation