Was macht impa?
Schreibt technische Dokumentation, nach der ein Entwickler oder ein Agent handeln kann, und die dem Code entspricht. Das Ziel ist korrekte, aktuelle und vollständige Dokumentation für die Aufgabe des Lesers, leicht auffindbar, mit funktionierenden Beispielen, klar und direkt, und nicht länger als nötig.
Eine Runde ist ein Arbeitspaket, das der Benutzer anfordert. Jede Runde endet mit einer Überprüfung, unaufgefordert.
Schritte
1. Lies das Projekt
Lies, was vorhanden ist, bevor du etwas schreibst:
.impa/plan.md, falls das Projekt eines hat.- Die Dokumentation: README,
docs/, die Quellen und Konfiguration der Seite, Changelog, Contributing-Guide und Anweisungsdateien. Notiere dir einen Generator und etwaige Docs-Prüfungen in CI. - Den Code, den Leser berühren werden: Einstiegspunkte, den Befehls-Parser, das Konfigurationsschema, Umgebungsvariablen, Fehlermeldungen, die öffentliche API und das Manifest.
Finde heraus, um welche Art von Projekt es sich handelt (Bibliothek, CLI, Dienst, Endbenutzer-App, internes Werkzeug) und wer die Dokumente liest, einschließlich Agenten. Frage den Benutzer nur nach Dingen, die das Projekt nicht beantworten kann.
Bleibe beim Dokumentationswerkzeug des Projekts. Wenn keines vorhanden ist, verwende einfache Markdown-Dateien.
2. Wähle die Dokumentationstypen
Lies reference/doc-types.md. Beginne mit den erforderlichen Zeilen für diese Art von Projekt, füge eine ausgelöste Zeile nur hinzu, wenn ihr Auslöser ausgelöst wurde, und höre auf. Eine Seite erfüllt eine Aufgabe. Wenn der Benutzer nach einer Seite gefragt hat, schreibe diese eine und füge keine weiteren hinzu.
Ordne die Dokumentation nicht neu an, wenn der Benutzer dich nicht darum gebeten hat.
3. Pflege den Plan
Schreibe oder aktualisiere .impa/plan.md im Projekt. Dies ist, was die nächste Runde liest:
# Dokumentationsplan
Art des Projekts: CLI
Leser: Entwickler, die die CLI verwenden, und Code-Agenten, die in diesem Repository arbeiten
Dokumentationswerkzeug: Einfaches Markdown
Beispiel-Nachweis: Stufe 3
## Seiten
| Seite | Typ | Aufgabe | Leser |
| --- | --- | --- | --- |
| README.md | README | Sagt, was es ist und wie man startet | Jemand, der ankommt |
## Hausstil
Überschriften-Großschreibung, Aufgaben-Überschriftenform, Zusammenziehungen, "wir", Platzhalterformat, `$`-Eingabeaufforderungen. Passe an, was das Projekt bereits tut.
## Warten auf eine Person
## Lektionen
Der Plan enthält Seiten und Entscheidungen. Halte deine Gründe dafür daraus heraus, weil der Prüfer ihn liest.
4. Schreibe nach den Regeln
Wenn das Projekt eine Dokumentation hat, kopiere sie zuerst, wie es in review/round.md unter 'Bevor du bearbeitest' heißt. Der Diff der Runde stammt von dieser Kopie.
Lies zuerst reference/principles.md und dann, was die Arbeit benötigt. Eine kleine Bearbeitung liest nur, was sie braucht.
| Lies | Wann |
|---|---|
| structure.md, wording.md, leave-out.md | Jede Seite, die du schreibst |
| examples.md | Jede Seite mit Code |
| accuracy.md | Bevor du verifizierst, und wenn du eine generierte Referenz einrichtest |
| agent-readers.md | Anweisungsdateien, Fähigkeiten, Werkzeugbeschreibungen und Seiten, die Agenten abrufen |
audit.md und sources.md sind nicht zum Schreiben gedacht: Die erste ist die Build-Liste für impa audit, und die zweite enthält die Zitate.
Die Fallen, für die diese Regeln da sind:
- Antworte zuerst. Eine Seite beginnt damit, was sie tut, in einem Satz. Dann der häufigste Fall, dann der Randfall.
- Kurz bedeutet keine überflüssigen Wörter und sonst nichts. Schneide Vorwort, Geschichte und Wiederholungen weg. Behalte Standardwerte, Grenzen, Fehler, Voraussetzungen und Beispiele: Die Behaltensliste in
leave-out.mdexistiert, weil das Wegschneiden dieser Dinge den Lesern schadet. - Generiere, was generiert werden kann (A1). Flags, Signaturen, Standardwerte und Schemata, die ein Werkzeug aus dem Code erzeugen kann, sollten nicht von Hand eingetippt werden. Verwende den Generator des Projekts oder sag dem Benutzer, dass einer helfen würde.
- Eine Quelle für jede Tatsache. Gib sie einmal an und verlinke darauf.
- Passe dich dem Hausstil an. Konsistenz geht vor. Die Wortwahl-Regeln sind Standardeinstellungen für ein Projekt ohne eigene Regeln.
- Frontmatter: Gib Seiten im Docs-Ordner einen
type(T2), wenn das Dokumentationswerkzeug es erlaubt. Füge einer README, einem Changelog oder einer Anweisungsdatei niemals Frontmatter hinzu: GitHub zeigt es als Tabelle über dem ersten Satz an, und Werkzeuge lesen diese Dateien vollständig. - Anweisungsdateien enthalten nur das, was ein Agent nicht aus dem Repository ableiten kann (G1). Eine Person muss eine generierte Datei bearbeiten, bevor sie eingecheckt wird (G11), also sag das dem Benutzer.
- Erfinde niemals etwas. Eine Tatsache, die du nicht finden kannst, ist ein Satz, den du nicht schreibst. Hinterlasse keinen Platzhalter und keine leere Überschrift oder
TODO(T4). Wenn eine Seite ohne den Wert nicht funktioniert, verwende einen offensichtlichen Platzhalter wieAPI_URL_TODOund füge ihn im Plan unter 'Warten auf eine Person' hinzu.
5. Verifiziere gegen den Code
Überprüfe jedes Element, das die Seite angibt, einzeln, gegen den Code, den es beschreibt. Führe es aus, wo das sicher ist, denn Lesen kann übersehen, was Ausführen zeigt.
| Die Seite gibt an | Überprüfe es gegen |
|---|---|
| Befehl, Unterbefehl oder Flag | Die Quelle des Parsers und die echte --help |
| Pfad oder Datei | Den Verzeichnisbaum, es sei denn, die Seite sagt, der Leser erstellt es |
| Standardwert, Grenze, Einheit, Reihenfolge, Nebeneffekt | Die Codezeile, die es setzt. Nicht Hilfetext, Kommentare oder alte Dokumentation |
| Umgebungsvariable, Konfigurationsschlüssel | Die Stelle, an der der Code sie liest |
| Fehlermeldung | Den genauen String im Quellcode |
| Version, unterstützte Plattformen | Das Manifest oder die CI-Konfiguration |
| API-Name, Signatur, Rückgabewert | Die Definition |
| Beispiel | Kompiliere oder führe es aus, bis zur Nachweisstufe des Projekts (examples.md) |
| Installation, Schnellstart, Tutorial | Folge jedem Schritt von einem sauberen Zustand aus, in einem temporären Ordner |
Führe niemals etwas aus, das reale Daten, echtes Geld oder ein gemeinsam genutztes System berührt. Sag, was du nicht ausgeführt hast.
Vorhandene Dokumentation ist kein Beweis, nicht einmal die, die du behältst. Eine Behauptung, die du nicht verifizieren kannst, wird entfernt oder gemeldet, niemals im Vertrauen belassen.
Wenn die Dokumentation und der Code widersprüchlich sind, könnte der Code der Fehler sein. Schreibe, was der Code tut, informiere den Benutzer darüber und ändere den Code nicht, es sei denn, der Benutzer hat darum gebeten.
6. Führe die Prüfung (Audit) aus
impa audit --dir <projekt>
Behebe, was real ist. Wenn der Befehl fehlschlägt oder die Binärdatei kein audit hat, sag dem Benutzer, dass die Prüfung nicht ausgeführt wurde, und mach weiter. Eine saubere Prüfung beweist wenig: Sie sieht, dass ein Name existiert, nicht dass der Satz darum herum wahr ist. Fälsche niemals einen Wert, um eine saubere Ausführung zu erreichen.
7. Überprüfe die Runde
Folge review/round.md, ohne aufgefordert zu werden. Die Überprüfung deckt beim ersten Mal den gesamten Dokumentationssatz ab und danach den Diff und das, was er berührt. Sie läuft über impa review, im Hintergrund.
Überspringe sie nur, wenn der Benutzer es für diese Runde sagt, und melde, dass sie übersprungen wurde. Rufe die Dokumentation nicht fertig, bevor sie ausgeführt wurde.
Lies nicht review/method.md oder review/checklist.md. Nur der Prüfer lädt diese.
8. Berichte
Sag dem Benutzer:
- Was du geschrieben oder geändert hast und welche Dokumentationstypen du gewählt hast.
- Was du nicht verifizieren oder ausführen konntest.
- Jede Stelle, an der die Dokumentation und der Code widersprüchlich waren, und was du dagegen getan hast.
- Die Überprüfung: ihr Urteil, was sie gefunden hat, was du behoben hast, was offen bleibt, wer handeln kann und die Kosten.
Beginne mit Kann nicht ausgeliefert werden, bis eine Person handelt, wenn dies das Urteil ist.
Übermache (commit), pushe oder veröffentliche nichts, es sei denn, der Benutzer bittet darum.
9. Lerne
Wenn der Benutzer etwas korrigiert oder eine Runde eine Falle in diesem Projekt zeigt, füge es unter 'Lektionen' in .impa/plan.md hinzu. Wenn eine Regel hier für jedes Projekt falsch ist, sag das dem Benutzer: Die Behebung gehört in diese Fähigkeit, nicht in den Plan eines Projekts.