zehuichan/vibe-harness

Dokumentationsstandard

Mache jede Seite auffindbar, für Neulinge lesbar und präzise genug für Agenten und Maintainer. Die Stufen, Schreibregeln, Budgets und die Schlampigkeits-Checkliste leben in docs/AGENTS.md; dieses Skill besitzt den Workflow zu deren Anwendung. Bewahre ein Zuhause pro Fakt: Quelle, Tests, generierte Kataloge, READMEs, Anleitungen und Agentennotizen behalten jeweils ihre eigene Art von Wahrheit. Dies ist eine Richtlinie, keine Checkliste.

Arbeitsablauf

Folge dieser Reihenfolge für jeden angeforderten Umfang. Halte den gemeinsamen Leserpfad kurz, lösche jedoch keine Fehler, Zuständigkeiten, Einschränkungen oder andere erforderliche Verträge, um Wörter zu reduzieren.

1. Lies die Stamm- und Unterbaum-AGENTS.md-Dateien, docs/AGENTS.md, die Zielseite, deren Quelle und Tests sowie deren Navigationsinhaber.
2. Klassifiziere die Seite nach einer primären Aufgabe und Leser: Schnellstart, Benutzeraufgabenanleitung, Mitwirkenden-Tutorial, Architekturübersicht, Modulreferenz, generierte Referenz, Agentenanweisung, Entscheidungsprotokoll oder Kratzer.
3. Platziere die Seite bei ihrem nächsten Inhaber. Halte Modulverträge neben dem Code des Moduls; verwende docs/ für modulübergreifende Lern-, Benutzer-, Entwickler- und Architekturmaterialien.
4. Definiere den Startzustand des Lesers, das beobachtbare Ergebnis, den wahrscheinlichen Fehler, den Wiederherstellungspfad und die nächste nützliche Tiefe, bevor Details geschrieben werden.
5. Schreibe in der durch Seitenstruktur vorgegebenen Reihenfolge: Titel, Zusammenfassung, Inhaltsverzeichnis, benutzerseitiger Inhalt, entwicklerseitiger Inhalt, optionales Weiterführendes.
6. Wenn das Profil surfaces.bilingual-docs aktiviert, aktualisiere das Gegenstück im selben Durchlauf und halte Überschriften, Listen, Tabellen, Code und Links zeilenweise ausgerichtet.
7. Überprüfe jede Behauptung anhand von Code, Tests, Generatoren, Paketmetadaten oder einem aktuellen Entscheidungsinhaber und führe die Operationen aus, die die Seite anweist (siehe das Faktencheck-Verfahren unten). Aktualisiere den Inhaber vor jedem abgeleiteten Artefakt.
8. Führe die commands.docs-check und git diff --check des Profils aus, lies dann das vollständige Diff einmal auf Korrektheit und einmal auf Kürze und Passgenauigkeit.

Faktencheck-Verfahren: Testen, nicht annehmen

Die Dokumentation beschreibt, wie sich das Produkt heute verhält, und der einzige zulässige Beweis für eine Operationsbehauptung ist, sie ausgeführt zu haben. Dies gilt für jede neue Seite und jeden neuen Absatz, der einen Befehl, Standardwert, Fehler, eine Ausgabe oder einen Plattformunterschied behauptet.

1. Klassifiziere das Subjekt, bevor Installations- oder Nutzungshinweise geschrieben werden. Lies die Fakten (Manifeste, Einstiegspunkte, Exporte), nicht den Ordnernamen. Eine Bibliothek, ein Plugin, ein CLI und ein Dienst haben jeweils einen anderen Nutzungspfad; kopiere niemals eine Anleitung, die für eine andere Art geschrieben wurde.
2. Führe jede behauptete Operation gegen den aktuellen Checkout aus. Führe jeden Befehl, jeden Konfigurationsausschnitt und jedes Beispiel genau so aus, wie die Seite es zeigen wird; schreibe nur das auf, was du beobachtet hast, einschließlich Warnungen und Fehlermodi. Wenn eine Behauptung von Anmeldeinformationen oder einem Netzwerk abhängt, das du nicht hast, sage dies und nenne den Verifikationsinhaber, anstatt das Verhalten zu behaupten.
3. Lösche, was du nicht reproduzieren konntest. Übernimm niemals einen Befehl, ein Feld, einen Standardwert oder ein Verhalten aus dem Gedächtnis, Analogie oder einem benachbarten README. Wenn eine Behauptung nicht reproduziert werden kann, korrigiere die Behauptung, nicht den Test.
4. Überprüfe alte Dokumentationen gegen den neuesten Standardzweig. Bevor du eine bestehende Seite überarbeitest, hole den neuesten Standardzweig ab und vergleiche; korrigiere veraltete Aussagen anhand des Codes, nicht anhand des alten Prosa.

Sprachregeln

• Zusammenfassung sagt, was das Subjekt tut. Die Zusammenfassung und benutzerseitigen Abschnitte beschreiben, was ein Leser mit dem Subjekt tun kann (Ergebnisse, wann man es wählt, Hauptkosten), niemals seine interne Identität oder Registrierungen. Lasse Quellkennungen weg, es sei denn, der Leser verwendet sie direkt in einer Konfiguration, einem Befehl oder einer öffentlichen API.
• Entwicklerabschnitte erklären, zählen niemals auf. Entwicklerdetails umfassen das Designkonzept, die Architektur und den ungefähren Datenfluss, genug, um zu verstehen, wie es funktioniert, und verlinken den Code für genaue Details. Keine vollständigen API-Kataloge, Spaltenlisten oder API-Dokument-Wiederholungen.
• Nur aktueller Zustand. Normale Dokumentation beschreibt die aktuelle Codebasis; Geschichte gehört zu Agentennotizen, Postmortems, Release-Notizen und Upgrade-Anleitungen.
• Kontrolliertes technisches Englisch. Gib jedem Satz einen expliziten Akteur und eine Hauptaktion, wenn Mehrdeutigkeit das Verhalten ändern kann; verwende einen Begriff pro Konzept wieder; teile gestapelte Anweisungen; bewahre Modalität und Ausnahmen. Siehe Seitenstruktur.

Qualitätskriterien

• Kurz: der gemeinsame Pfad enthält nur Fakten, die für sein Ergebnis benötigt werden; erschöpfende Wahrheit ist einen Link oder eine Detailebene entfernt.
• Intuitiv: Voraussetzungen gehen abhängigen Konzepten voraus, eine nächste Aktion ist offensichtlich und Überschriften verwenden Begriffe, nach denen Leser suchen.
• Freundlich: Leser können Erfolg erkennen, Risiko vor dem Handeln verstehen, sich von wahrscheinlichen Fehlern erholen und wählen, ob sie tiefer gehen.
• Genau: jede dauerhafte Behauptung hat einen Inhaber und einen Verifikationspfad, der ihrem Risiko angemessen ist.
• Agentenlesbar: stabile Überschriften, Anker, Terminologie und Zuständigkeiten unterstützen gezieltes Abrufen ohne das gesamte Korpus zu laden.
• Vollständig für Neulinge: ein Ingenieur ohne Repository-Kontext kann die relevante Architektur oder Funktion durch drei bis fünf verlinkte Seiten rekonstruieren.

Wende kein universelles Wortlimit auf erschöpfende Referenzen an; messe die Länge des Einstiegspfads, die pro Nachschlagen durchsuchten, nicht zusammenhängenden Materialien und den größten Abschnitt und teile sie durch einen vorhandenen Domain-Inhaber, wenn die Abrufkosten hoch sind.

Das Korpus auditieren

Wende die Autorenreihenfolge aus docs/AGENTS.md auf jedes menschlich lesbare Dokument im Umfang an (nicht auf Agentennotizen): Lokalisiere das Dokument und gib seinen Gegenstand an; setze seine erlaubte Detailtiefe und verschiebe tiefere Erklärungen in besitzende Nachkommen; klassifiziere Tutorial oder Referenz anhand der beabsichtigten Verwendung, nicht des Pfads; teile wesentliche Mischformen auf. Eine Verschiebung erfolgt atomar mit jeder eingehenden Verknüpfung, die in derselben Änderung repariert wird; generierte Kataloge werden niemals manuell bearbeitet.

Jage dann die Schlampigkeits-Checkliste in docs/AGENTS.md, zuerst die günstigsten Sonden: Verwende trim-cot-leakage für Reasoning-Transkript-Leaks, suche nach markanten Phrasen für duplizierte Regeln, ersetze handgeschriebene Kataloge durch ihre autoritativen Besitzer und entferne Spezifikationssprache aus implementierten Agentennotizen. Wenn das Entfernen von Prosa das versprochene Verhalten und nicht dessen Erklärung ändern würde, schlage zuerst die Verhaltensänderung vor (siehe find-simplifications). Behalte jede tragende Regel, vorzugsweise als ein bis drei Zeilen plus einen Link zu ihrer Begründung.

Detaillierte Referenzen

• Seitenstruktur und Stil: Seitenreihenfolge, Abschnittsverlauf, Falten, kontrolliertes technisches Englisch und Hervorhebung.
• Überprüfungskriterien: der Neulings-Test, Evidenzprüfung und README-Überprüfung.

Verwende prose-standard für satzweise Vertragsabdeckung und redaktionelles Urteil.