RFC-Erstellung und -Pflege

Was macht RFC-Erstellung und -Pflege?

Diese Fähigkeit erstellt und pflegt leichtgewichtige RFCs – nummerierte Markdown-Designvorschläge, die im Repository neben dem Code leben, den sie beschreiben. Ein RFC hält ein Design vor (oder während) der Umsetzung fest: das Problem, den aktuellen Code-Zustand, die getroffenen Entscheidungen mit ihrer Begründung und was bewusst nicht behandelt wird. Die Sammlung wird über eine einzige INDEX.md verfolgt, sodass die gesamte Designhistorie in einer Tabelle durchsuchbar ist.

RFCs sind hier Arbeitsdokumente, keine Bürokratie: Sie existieren, damit Entscheidungen auch bei Kontextverlust erhalten bleiben, damit ein wiederaufgenommener Entwurf ein „ein einziger kleiner PR, nicht mehr“ ist, und damit verworfene Alternativen nicht erneut diskutiert werden.

Verwenden Sie diese Fähigkeit, wenn

• Der Benutzer bittet um das Schreiben eines RFC, eines Designdokuments, eines Designvorschlags, einer technischen Spezifikation oder eines Architekturvorschlags
• Der Benutzer möchte eine Designentscheidung festhalten oder verbindlich machen – mit den Alternativen, die sie geschlagen hat, oder warum ein Ansatz verworfen wurde – bevor er implementiert wird
• Der Benutzer bittet um die Aktualisierung eines RFC (Statusänderung, Ausführungsnotizen, Markierung als ausgeliefert oder abgelehnt)
• Der Benutzer bittet um die Erstellung, Indexierung oder Neuorganisation eines rfcs/- (oder rfc/-)Verzeichnisses
• Eine Diskussion über eine große Funktion soll in einem dauerhaften Dokument festgehalten werden

Verwenden Sie diese Fähigkeit nicht, wenn

• Der Benutzer Produktdokumentation, eine README oder benutzerorientierte Dokumente wünscht (kein Designvorschlag)
• Der Benutzer einen ADR in einem Repository wünscht, das bereits eine etablierte ADR-Konvention hat – folgen Sie stattdessen dieser Konvention
• Die Änderung trivial genug ist, dass eine Commit-Nachricht oder PR-Beschreibung ausreicht

Verzeichnis und Index

Ort. RFCs liegen in einem einzigen flachen Verzeichnis im Repository-Stammverzeichnis: rfcs/ (bevorzugter Standard) oder rfc/. Bevor Sie etwas erstellen, suchen Sie nach einem vorhandenen Verzeichnis mit einem der beiden Namen und folgen Sie diesem. Wenn keines existiert, erstellen Sie rfcs/.

Gitignore ist Sache des Benutzers, nicht Ihre. Manche Projekte committen RFCs; andere ignorieren sie als lokale Arbeitsnotizen. Fügen Sie niemals einen .gitignore-Eintrag für das RFC-Verzeichnis hinzu oder entfernen Sie ihn, es sei denn, es wird ausdrücklich darum gebeten. Wenn das Verzeichnis gitignoriert wird, sollte der INDEX.md-Kopf dies erwähnen (siehe Vorlage), damit Leser wissen, warum es nicht in der Repository-Historie ist.

INDEX.md ist die Quelle der Wahrheit für die Sammlung. Sie enthält drei Dinge:

1. Die nächste freie Nummer, explizit angegeben – Nummern kollidieren, wenn sie parallel vergeben werden, daher benennt der Index die nächste und jede RFC-Erstellung aktualisiert sie im selben Änderungssatz.
2. Die Index-Tabelle: | # | Titel | Status | Einzeiler |, eine Zeile pro RFC, Nummer mit der Datei verlinkt.
3. Die Status-Legende.

Wenn das Verzeichnis existiert, aber eine README.md in dieser Rolle hat, behandeln Sie diese als Index. Wenn Sie gebeten werden, ein neues Verzeichnis einzurichten, verwenden Sie INDEX.md – kopieren Sie references/index-template.md.

Nummerierung und Dateinamen

• Nummern sind 4-stellig, nullenaufgefüllt, monoton steigend: 0001, 0002, …
• Zur Zuteilung: Lesen Sie die „nächste freie Nummer“ aus INDEX.md, überprüfen Sie sie mit ls des Verzeichnisses (der Index kann veraltet sein) und nehmen Sie die nächste ungenutzte ganze Zahl.
• Dateiname: NNNN-kebab-case-title.md. Stellen Sie sicher, dass die Nummer im Dateinamen und die # RFC NNNN – Titel-H1 synchron sind – andernfalls treiben sie auseinander und Links brechen in beide Richtungen.
• Nummerieren Sie vorhandene RFCs niemals neu. Nummern sind Identifikatoren, keine zu sortierende Reihenfolge.

Status

• 📝 Entwurf – vorgeschlagen, nicht begonnen (ein „Design festgelegt, nachfragegesteuerter“ RFC ist immer noch Entwurf)
• 🚧 In Bearbeitung – teilweise ausgeliefert
• ✅ Abgeschlossen – vollständig ausgeliefert
• ❌ Abgelehnt / Zurückgezogen – Datei behalten; ein aufgezeichneter Ausschluss verhindert erneute Diskussion

Der Status lebt an zwei Stellen, die übereinstimmen müssen: der Zeile **Status:** im RFC-Kopf und der Spalte Status der Index-Tabelle. Aktualisieren Sie beide im selben Änderungssatz.

RFC-Anatomie

Lesen Sie references/rfc-template.md, bevor Sie einen neuen RFC schreiben, und beginnen Sie damit. Die Form:

Kopfblock (Aufzählungsliste direkt unter der H1, vor jedem Abschnitt):

• **Status:** – Emoji + Wort, optional kommentiert („ausführungsbereit – ein PR“, „Design festgelegt, nicht geplant“)
• **Geltungsbereich:** – ein dichter Absatz: was dieser RFC abdeckt und was er bewusst nicht abdeckt. Dies ist der Absatz, den jemand liest, um zu entscheiden, ob er den Rest lesen soll.
• **Verwandt:** – Links zum berührten Code (relative Links ins Repository), zu anderen RFCs, zu verwandten Arbeiten, zu externen Referenzen
• **Diskussion:** (optional) – Link zu dem Ort, an dem das Design diskutiert wurde oder wird (PR, Issue, Thread); ein Leser, der anderer Meinung ist, geht dorthin, anstatt das Dokument zu forken
• **Ursprung:** (optional) – woher das Design portiert oder verallgemeinert wurde, falls zutreffend

Nummerierte Abschnitte. Der vollständige Satz für einen umfangreichen RFC:

1. Zusammenfassung – was ausgeliefert wird, in wenigen Sätzen
2. Motivation – das Problem, mit Belegen aus der tatsächlichen Codebasis
3. Aktueller Stand – was heute existiert, verifiziert am Code, nicht aus dem Gedächtnis
4. Ziele / Nicht-Ziele – explizit in beide Richtungen
5. Design – der Kern; Unterabschnitte pro Arbeitspaket oder Komponente, mit echten Signaturen/Schemata/Codeblöcken, wo sie das Design festlegen. Wo eine Wahl umstritten war, halten Sie die verworfene Alternative fest und warum sie verloren hat – ein Satz für kleinere Entscheidungen, einen ### Alternativen betrachtet-Unterabschnitt, wenn die Wahl das Design geprägt hat
6. Tests – wie das Design verifiziert wird
7. Dokumentation – welche Dokumentation damit ausgeliefert wird
8. Nicht im Geltungsbereich – benannt und begründet: jedes Element sagt, warum es ausgeschlossen ist und was das ändern würde
9. Risiken – ehrliche Fehlermodi, einschließlich Risiken des Missverstehens des Dokuments
10. Ungelöste Fragen – was geklärt sein muss, bevor das Design als abgeschlossen gilt, im Gegensatz zu dem, was die Implementierung frei klären kann; ein Unbekanntes zu benennen ist besser, als es stillschweigend während der Umsetzung zu klären
11. Entscheidungen – eine nummerierte Tabelle der verbindlichen Entscheidungen; dies macht die Übernahme kostengünstig und erneute Diskussion überflüssig. Wo eine Entscheidung die Zukunft nicht offensichtlich einschränkt, sagt die Zeile dies – die Konsequenzen einer Entscheidung sind der Kontext der nächsten
12. Phaseneinteilung – was zuerst landet, was wovon abhängt

Skalieren Sie den RFC entsprechend seinem Gewicht. Ein kleiner Design-Festlegungs-RFC benötigt nur den Kopfblock, das Design, die Nicht-Ziele und die Entscheidungstabelle. Stoppeln Sie einen zweiseitigen RFC nicht auf zwölf Abschnitte auf; kollabieren Sie einen systemweiten Vorschlag nicht auf drei. Halten Sie die Abschnittsnummerierung für die verwendete Teilmenge fortlaufend.

Schreibstil

• Betonen Sie jede Behauptung mit dem Code. „Aktueller Stand“ und „Motivation“ zitieren Dateien, zeilengenaue Fakten und gemessene Zahlen – verlinken Sie sie mit relativen Pfaden. Ein RFC, der aus dem Gedächtnis argumentiert, ist eine Fiktion mit Überschriften.
• Halten Sie Entscheidungen mit ihrem Warum fest – und ihren Kosten. Die Entscheidungstabelle ist der Vertrag; der Hauptteil trägt die Begründung. Verworfene Alternativen erhalten einen Satz, warum sie verloren haben (eine Alternative, die mit ihrem Kompromiss aufgezeichnet wurde, bleibt verworfen; eine, die nur als „verworfen“ aufgezeichnet wurde, wird erneut vorgeschlagen). Eine Entscheidung, die eine Tür schließt, sagt dies später in ihrer Zeile.
• Pünktlich ist besser als poliert. Ein grober RFC, der existiert, ist besser als ein perfekter, der nicht existiert (Oxides RFD-Regel: „pünktlich statt poliert“). Entwurfsprosa kann grob sein; der Absatz zum Geltungsbereich und die Entscheidungstabelle dürfen dies nicht.
• Seien Sie ehrlich über Grenzen. Wenn ein Mechanismus aufgeschoben, bedingt oder bekanntermaßen unvollständig ist, sagen Sie dies im RFC, anstatt den Leser es entdecken zu lassen. Ausfallschließende Formulierung („abgelehnt“, „löst aus“, „bewusst nicht eingeplant“) ist besser als optimistische Unbestimmtheit.
• Dicht ist besser als lang. Bevorzugen Sie einen tragenden Absatz gegenüber drei dünnen. Insbesondere der Index-Einzeiler: Er muss in sich abgeschlossen genug sein, dass ein Leser den RFC überspringen kann.

Arbeitsabläufe

Die Buchhaltung – Nummernzuteilung, Dateierstellung aus der Vorlage, Index-Zeilen- und nächste-freie-Nummern-Aktualisierungen, Abweichungserkennung – ist mechanisch, und scripts/rfc_index.py erledigt dies ohne die Kollisionen, die die manuelle Zuteilung produziert:

python3 scripts/rfc_index.py check          # Index vs. Dateien, H1 vs. Dateiname, Status, nächste freie
python3 scripts/rfc_index.py next           # nächste freie Nummer
python3 scripts/rfc_index.py new "Titel"    # Zuteilung + Vorlage instanziieren + Indexzeile + erhöhen
python3 scripts/rfc_index.py new "Titel" --number 42   # eine reservierte Nummer oder Neuerstellung eines gelöschten RFC

(Pfade relativ zum Verzeichnis dieser Fähigkeit; von einem Repository-Stammverzeichnis aus ist das Skript unter skills/rfc-writer/scripts/rfc_index.py. Nur lesend außer new; fügen Sie --root VERZ – vor oder nach dem Unterbefehl – hinzu, wenn das Repository nicht das aktuelle Arbeitsverzeichnis ist.) Das Denken – was das Design sagt, was der Einzeiler behauptet, wann sich ein Status ändert – ist Ihre Aufgabe.

A – Neuen RFC erstellen

1. Lokalisieren Sie das RFC-Verzeichnis (rfcs/ oder rfc/); wenn keines existiert, führen Sie zuerst Arbeitsablauf D aus.
2. Teilen Sie die nächste Nummer zu und instanziieren Sie die Datei: rfc_index.py new "Titel" – es prägt die Nummer, schreibt die Vorlage, fügt die Indexzeile hinzu und erhöht den nächsten-freien-Anspruch. Die Schritte 3 und 4 bleiben Ihre Aufgabe: es hinterlässt die Vorlage unausgefüllt und schreibt wörtlich TODO: one-line summary in den Index. Von Hand: Lesen Sie die nächste freie Nummer aus dem Index und überprüfen Sie sie mit ls – Nummern kollidieren, wenn sie parallel vergeben werden.
3. Füllen Sie die Datei gemäß der Form von references/rfc-template.md, skaliert auf das Gewicht des Designs. Untersuchen Sie den tatsächlichen Code, bevor Sie den „Aktuellen Stand“ schreiben – dies ist der meiste Aufwand.
4. Ersetzen Sie den Platzhalter-Einzeiler im Index durch eine dichte, in sich abgeschlossene Zusammenfassung.

B – Vorhandenen RFC aktualisieren

1. Wenn Arbeiten teilweise oder vollständig ausgeliefert werden, aktualisieren Sie die Zeile **Status:** – und kommentieren Sie sie mit dem, was ausgeliefert wurde und wann („Ausgeliefert 2026-06-29: …; nur P5 bleibt“).
2. Wenn die Ausführung vom Design abgewichen ist, halten Sie die Abweichung im RFC fest (eine Statusnotiz oder eine Ergänzung im relevanten Abschnitt) – schreiben Sie die Geschichte nicht stillschweigend um; das Entscheidungsprotokoll bleibt anfügeorientiert.
3. Spiegeln Sie den Status (und, wenn sich die Form geändert hat, den Einzeiler) in der Index-Tabelle wider.
4. Abgelehnte Designs erhalten ❌ und bleiben im Verzeichnis.

C – Index pflegen

Führen Sie rfc_index.py check aus – es meldet jede Datei ohne Indexzeile und umgekehrt, H1-vs.-Dateiname-Inkonsistenzen, Statusabweichungen zwischen Kopf und Tabelle, doppelte Nummern und eine nächste-freie-Nummer, die nicht frei ist. Beheben Sie, was es benennt (die Korrekturen sind Beurteilungssache: welcher Status wahr ist, was der Einzeiler sagen sollte), und führen Sie es dann erneut aus, bis es grün ist. Melden Sie, was nicht synchron war.

D – RFC-Verzeichnis initialisieren

1. Erstellen Sie rfcs/ (es sei denn, der Benutzer wünscht rfc/ oder eines existiert bereits).
2. Erstellen Sie INDEX.md aus references/index-template.md, füllen Sie den Projektnamen ein und setzen Sie die nächste freie Nummer auf 0001.
3. Berühren Sie nicht .gitignore – erwähnen Sie, dass das Committen vs. Ignorieren des Verzeichnisses die Wahl des Benutzers ist.

Referenzen

• references/rfc-template.md – RFC-Gerüst mit Anleitungen pro Abschnitt; vor dem Schreiben eines neuen RFC lesen
• references/index-template.md – INDEX.md-Gerüst; beim Initialisieren eines Verzeichnisses verwenden

Verwandte Fähigkeiten

• altitude-docs – die benutzerorientierte Dokumentation, die nach dem Design ausgeliefert wird; der Docs-Abschnitt des RFC verweist darauf
• self-audit – gegnerische Überprüfung des Branches, der einen RFC ausgeführt hat, vor dem Merge
• keep-a-changelog – zeichnet auf, was ausgeliefert wurde; der RFC zeichnet auf, warum es so gebaut wurde