Wiki - Projektwiki für Agenten

Wiki

Ein Projektwiki ist ein Ordner mit Markdown-Seiten, der das Projekt erklärt: was seine Teile tun, warum es so funktioniert, wie es funktioniert, und wo die Belege sind. Menschen lesen es. Agenten pflegen es. Jede neue Quelle, Frage oder Codeänderung sollte es ein wenig vollständiger und genauer machen.

Dies folgt dem „LLM-Wiki“-Muster: Rohquellen behalten, Seiten schreiben, die sie zusammenfassen und verbinden, und einen Index sowie ein Protokoll führen, sodass das Ganze navigierbar bleibt.

Repo-Regeln haben Vorrang

Wenn das Repository bereits ein Wiki hat, lies dessen Schema- oder Anweisungsdatei (normalerweise wiki/README.md, wiki/AGENTS.md oder wiki/schema.md), bevor du etwas änderst. Dessen Layout, Metadaten, Link-Stil und Befehle haben Vorrang vor den Standardeinstellungen hier. Verwende die Wiki-Skripte des Repositorys, wenn sie existieren, und bearbeite keine Dateien, die sie generieren, von Hand.

Die Bestandteile

Bestandteil	Was es ist	Wer es bearbeitet
Quellen	Kopien von Rohmaterial: Issues, PRs, Artikel, Notizen, Transkripte	Einmal hinzugefügt, dann nie geändert
Seiten	Geschriebene Erklärungen zu Themen, die Quellen und Code zitieren	Aktualisiert, sobald sich Fakten ändern
Schema	Eine Datei mit den Wiki-Regeln: Layout, Metadaten, Konventionen	Bewusst geändert
Index	Eine Liste jeder Seite mit einer einzeiligen Zusammenfassung	Neu generiert oder vollständig gehalten
Log	Eine datierte, nur anhängbare Liste von Änderungen am Wiki	Ein Eintrag pro Operation

Ein Standardlayout für ein neues Wiki:

wiki/
├── README.md     # Was das Wiki ist und wie man es nutzt
├── schema.md     # Die Regeln (der einzige Ort, an dem sie niedergeschrieben sind)
├── index.md      # Jede Seite, eine Zeile pro Seite
├── log.md        # Was sich geändert hat, neuestes zuletzt
├── pages/        # Themenseiten
└── sources/      # Rohmaterial, nach dem Hinzufügen unverändert

Ein kleines Projekt kann hier aufhören. Füge Unterordner nur hinzu, wenn es genug Seiten gibt, dass Leute Dinge nicht finden können.

Wer hat Recht, wenn Quellen sich widersprechen

Schreibe im Schema nieder, welche Quelle für welche Art von Behauptung gewinnt. Für die meisten Softwareprojekte:

• Wie sich der Code heute verhält: der Code und seine Tests.
• Was entschieden wurde, und warum: der Entscheidungsdatensatz, das Issue oder der PR, in dem es entschieden wurde.
• Was geplant oder in Arbeit ist: der Issue-Tracker oder die Roadmap.

Wenn eine Seite und ihre Autorität sich widersprechen, korrigiere die Seite und behalte eine kurze Notiz darüber, was sich geändert hat, falls die alte Überzeugung erinnernswert ist. Bearbeite niemals eine Quelle, um sie anzupassen.

Seiten

• Ein Thema pro Seite, mit einem klaren Titel. Aktualisiere die vorhandene Seite, anstatt eine nahezu identische hinzuzufügen.

• Zitiere, was du behauptest. Verlinke auf die Quelle oder nenne die Datei. Ein Leser sollte jede wichtige Aussage überprüfen können.

• Verwende relative Markdown-Links ([Parser](parser.md)), es sei denn, das Wiki verwendet bereits einen anderen Stil.

• Halte das Frontmatter klein. Ein nützliches Minimum:

  ---
  title: Parser
  summary: Wie Eingabedateien gelesen und validiert werden.
  sources: [sources/issue-42.md]
  code: [src/parser.ts]
  updated: 2026-01-31
  ---
  

  Füge nur Felder hinzu, wenn eine Person oder ein Skript sie verwendet.

• Jede Seite ist erreichbar vom Index und von mindestens einer verwandten Seite.

Operationen

Ein neues Wiki einrichten

1. Schau dir an, welche Dokumentation bereits existiert und wer sie liest. Dupliziere keine funktionierende Doku-Website.
2. Schlage dem Benutzer das Layout und das Schema vor und stimme dich ab, bevor du Seiten schreibst.
3. Erstelle README.md, schema.md, index.md und log.md.
4. Schreibe ein paar Seiten für die wichtigsten Teile des Projekts, halte dann inne und stimme dich mit dem Benutzer ab, bevor du den Rest ausfüllst.
5. Verweise die Agentenanweisungen des Repositorys (AGENTS.md, CLAUDE.md) auf das Schema, anstatt die Regeln darin zu kopieren.

Eine Quelle hinzufügen

1. Speichere das Rohmaterial unter sources/, mit Herkunft und Datum.
2. Lies es vollständig.
3. Finde jede vorhandene Seite, die davon betroffen ist, und aktualisiere sie. Erstelle eine neue Seite nur für ein Thema, das noch keine hat.
4. Notiere alles darin, das aktuellen Seiten widerspricht, und löse es mit den Autoritätsregeln.
5. Aktualisiere den Index und füge einen Logeintrag hinzu.

Eine Quelle zu speichern, ohne Seiten zu aktualisieren, ist nicht abgeschlossen. Die Seiten sind das, was Leute lesen.

Eine Frage beantworten

1. Beginne mit dem Index, durchsuche dann Seitentitel und -texte.
2. Lies die relevanten Seiten und überprüfe wichtige Behauptungen mit ihren Quellen oder dem Code.
3. Antworte mit Links zu den Seiten und den Belegen, die du verwendet hast. Sage, wo sie sich widersprechen oder wo das Wiki keine Antwort hat.
4. Wenn die Antwort neu ist und wahrscheinlich erneut gefragt wird, biete an, sie zum Wiki hinzuzufügen.

Nach einer Codeänderung aktualisieren

Wenn eine Änderung die Funktionsweise von etwas verändert:

1. Durchsuche das Wiki nach den Dateien, Funktionen und Begriffen, die die Änderung berührt hat.
2. Aktualisiere jede betroffene Seite im selben PR wie die Codeänderung.
3. Aktualisiere den Index, wenn sich Titel oder Zusammenfassungen geändert haben, und füge einen Logeintrag hinzu.

Die Gesundheit des Wikis prüfen

Suche nach:

• defekten Links und Codepfaden, die nicht mehr existieren;
• Seiten ohne eingehende Links;
• doppelten Seiten zum gleichen Thema;
• Quellen, die keine Seite zitiert;
• Seiten, die sich widersprechen oder dem Code widersprechen;
• einem Index, der Seiten vermisst oder gelöschte auflistet.

Behebe mechanische Probleme wie Links und den Index direkt. Melde Ermessensentscheidungen, wie das Zusammenführen von Seiten oder die Entscheidung, welche Behauptung richtig ist, dem Benutzer.

Logeinträge

Füge einen Eintrag pro Operation am Ende von log.md hinzu:

## 2026-01-31 14:05 UTC: ingest | Issue 42, leere Eingabezeilen

Das Issue als Quelle hinzugefügt und den Validierungsabschnitt der Parser-Seite aktualisiert.

Füge immer die Uhrzeit und die Zeitzone hinzu, damit Einträge am selben Tag in der richtigen Reihenfolge bleiben.

Nicht tun

• Eine Quelle nach dem Hinzufügen bearbeiten.
• Große Teile des Wikis ohne Nachfrage umstrukturieren oder umbenennen.
• Seiten löschen, weil sie veraltet sind. Markiere sie als veraltet und verlinke auf das, was sie ersetzt hat.
• Dieselben Regeln an mehreren Orten schreiben. Das Schema ist die einzige Kopie.
• Das Wiki als autoritärer behandeln als den Code, den es beschreibt.
• In ein externes System (Confluence, Notion, Issue-Tracker) schreiben ohne Zustimmung des Benutzers.