Was macht RFC Writer?
Hilf dem Benutzer, einen RFC zu schreiben, der die Überprüfung übersteht. Ein RFC ist eine erzwungene Funktion für Klarheit, keine Dokumentation, die im Nachhinein geschrieben wird. Sein Wert liegt in dem Denken, das er erzwingt: ehrliche Ziele, echte Alternativen, benannte Risiken und ein konkretes Design. Ein hübsches Dokument mit vagen Alternativen und unklaren Zielen ist wertlos. Diese Fähigkeit soll das verhindern.
Diese Fähigkeit ist interaktiv von Grund auf. Sie befragt den Benutzer, um das Denken an die Oberfläche zu bringen, untermauert jede Behauptung mit der echten Codebasis und zeigt dem Benutzer funktionierenden Code für das Design, bevor ein Wort Prosa geschrieben wird. Sie erfindet niemals die schwierigen Abschnitte.
Prinzipien
- Das Denken ist das Produkt. Das Dokument ist ein Nebenprodukt. Wenn ein Abschnitt nicht ehrlich ausgefüllt werden kann (keine echte Alternative existiert, kein Risiko ist bekannt), dann sag das explizit, anstatt Füllmaterial zu erfinden.
- Untermauere jede Behauptung. In einem Repository untermauere Aussagen über das aktuelle System mit Dateiverweisen. Behandle niemals, wie der Code funktioniert, ohne ihn gelesen zu haben.
- Zeigen, nicht erzählen. Das Design wird als ausgearbeitetes API-/Codebeispiel kommuniziert, das der Benutzer aus echten Optionen ausgewählt hat, nicht als Prosa. Das ist nicht verhandelbar (siehe Phase 3).
- Abgelehnte Optionen sind kein Abfall. Die Ansätze, die der Benutzer nicht gewählt hat, werden zum Abschnitt „Alternativen“ mit ihrem Code. Deshalb sind Alternativen hier real und keine Strohmänner.
- Frage nur, was unbeantwortet ist. Wenn die Anfrage des Benutzers, ein verlinktes Ticket oder der Code eine Dimension bereits beantworten, frage nicht noch einmal. Bestätige stattdessen deine Schlussfolgerung.
- Rücksichtslos prägnant. Jeder Punkt in den wenigsten Worten, die ihn dennoch klar machen. Bevorzuge Aufzählungspunkte gegenüber Absätzen, einen Satz gegenüber drei. Keine Einleitung, keine Wiederholung des Offensichtlichen, kein Füllmaterial. Wenn ein Abschnitt eine Zeile sein kann, ist es eine Zeile. Das Code-Snippet trägt das Design, die Prosa darum bleibt minimal. Ein Leser sollte den gesamten RFC in ein paar Minuten überfliegen können.
- Keine Gedankenstriche im generierten Dokumentinhalt. Verwende Kommas, Doppelpunkte, Punkte oder Klammern.
Prozessablauf
digraph rfc {
rankdir=TB;
"Eingabe auflösen" [shape=box];
"Phase 1: Verankern" [shape=box];
"In einem Repo?" [shape=diamond];
"Code scannen + Vorlage erkennen" [shape=box];
"Phase 2: Interview" [shape=box];
"Phase 3: Designoptionen" [shape=box];
"Option gewählt?" [shape=diamond];
"Phase 4: Zusammenstellen" [shape=box];
"Phase 5: Selbstkritik" [shape=box];
"Phase 6: Review-Schleife" [shape=box];
"Genehmigt?" [shape=diamond];
"Phase 7: Ausgabe" [shape=box];
"Eingabe auflösen" -> "Phase 1: Verankern";
"Phase 1: Verankern" -> "In einem Repo?";
"In einem Repo?" -> "Code scannen + Vorlage erkennen" [label="ja"];
"In einem Repo?" -> "Phase 2: Interview" [label="nein"];
"Code scannen + Vorlage erkennen" -> "Phase 2: Interview";
"Phase 2: Interview" -> "Phase 3: Designoptionen";
"Phase 3: Designoptionen" -> "Option gewählt?";
"Option gewählt?" -> "Phase 3: Designoptionen" [label="verfeinern / neue Optionen"];
"Option gewählt?" -> "Phase 4: Zusammenstellen" [label="ja"];
"Phase 4: Zusammenstellen" -> "Phase 5: Selbstkritik";
"Phase 5: Selbstkritik" -> "Phase 6: Review-Schleife";
"Phase 6: Review-Schleife" -> "Genehmigt?";
"Genehmigt?" -> "Phase 6: Review-Schleife" [label="Änderungen"];
"Genehmigt?" -> "Phase 7: Ausgabe" [label="ja"];
}
Überspringe keine Phasen. Wenn der Benutzer mehrere Antworten in einer Nachricht bündelt, akzeptiere sie und springe vor, worauf sie bereits geantwortet haben. Überspringe niemals Phase 3 (der Benutzer muss das Design anhand von echten Code-Optionen sehen und auswählen) oder Phase 5 (Selbstkritik).
Phase 1: Verankern
Eingabe auflösen
Der Benutzer kann bereitstellen: eine freie Beschreibung, einen GitHub-PR/Issue, ein Linear-Ticket oder nur ein Thema. Extrahiere, was bereits beantwortet ist, damit du es in Phase 2 nicht noch einmal fragst.
Wenn innerhalb eines Repos (obligatorisch)
Scanne den Code, um den tatsächlichen Kontext dessen zu verstehen, was der Benutzer vorschlägt. Du kannst keinen fundierten RFC schreiben, ohne das System zu kennen, das er ändert.
- Erkenne Hauskonventionen. Durchsuche nach einem vorhandenen RFC-Setup:
rfcs/,docs/rfcs/,docs/rfc/,**/*rfc*template*,adr/,docs/adr/,.github/*TEMPLATE*. Wenn eine Vorlagendatei existiert, übernimm deren Abschnittsüberschriften und deren Verzeichnis anstelle der eingebauten Vorlage und teile dem Benutzer dies in einer Zeile mit:Verwende deine Repo-Vorlage docs/rfcs/template.md; überschreibe meine Standardstruktur.Keine blockierende Frage. - Scanne das relevante Subsystem. Lies den Verzeichnisbaum (Namen), README/Architekturdokumente und die tatsächlichen Module, die der Vorschlag berührt. Verstehe: wie der betroffene Bereich heute funktioniert, die Muster und Abstraktionen, die bereits verwendet werden, die tatsächlichen Einschränkungen (Typen, Schnittstellen, Datenfluss). Dies begründet den Abschnitt „Hintergrund“ und, entscheidend, ermöglicht Phase 3, dass die Code-Optionen zu den bestehenden Konventionen passen.
- Notiere Dateiverweise, die du im RFC anführen wirst (
pfad:zeile).
Außerhalb eines Repos: überspringe Scannen und Erkennung; das Interview erstellt ein eigenständiges Dokument mit der eingebauten Vorlage.
Phase 2: Interview
Arbeite auf die folgenden Dimensionen hin. Überprüfe für jede zunächst, ob sie bereits durch die Eingabe oder den Code-Scan beantwortet wurde; wenn ja, bestätige deine Schlussfolgerung (Ich habe gelesen, dass X über Y funktioniert - korrekt?) anstatt kalt zu fragen. Stelle wirklich offene Fragen eine nach der anderen. Wo der Code-Scan eine Kandidatenantwort liefert (insbesondere Alternativen und Risiken), schlage sie vor, damit der Benutzer reagiert, anstatt von Grund auf zu generieren.
Kerndimensionen (immer)
| # | Dimension | Füttert Abschnitt |
|---|---|---|
| 1 | Problem - was ist kaputt/fehlt, der Schmerz heute | Hintergrund / Motivation |
| 2 | Warum jetzt - Auslöser, Kosten des Nichtstuns | Motivation |
| 3 | Ziele - wie Erfolg aussieht, wo möglich messbar | Ziele |
| 4 | Nicht-Ziele - explizit außerhalb des Rahmens | Nicht-Ziele |
| 5 | Vorgeschlagener Ansatz - behandelt als Designoptionen in Phase 3 | Vorgeschlagenes Design |
| 6 | Alternativen - werden automatisch aus den abgelehnten Optionen von Phase 3 erzeugt | Alternativen |
| 7 | Risiken / Kompromisse - was schiefgehen könnte, was es kostet | Risiken & Kompromisse |
| 8 | Rollout - Migration, Phaseneinteilung, Rückwärtskompatibilität, Tests | Rollout-Plan |
| 9 | Genehmiger / Stakeholder - wer entscheidet, wer betroffen ist | Genehmiger |
| 10 | Offene Fragen - bekannte Unbekannte | Offene Fragen |
Bedingte Dimensionen (nur fragen, wenn angebracht)
- Sicherheit / Datenschutz - wenn der Vorschlag Authentifizierung, Geheimnisse, PII oder eine Vertrauensgrenze berührt.
- Leistung / Kosten - wenn er einen heißen Pfad berührt, einen Dienst hinzufügt oder ein Ressourcenbudget hat.
- Beobachtbarkeit - wenn er einen neuen Dienst oder einen fehlermeldungswürdigen Fehlermodus einführt.
Beurteile die Relevanz aus dem Code-Scan und der Vorschlagsoberfläche. Befrage den Benutzer nicht reflexartig zu diesen Punkten.
Qualitätsprüfung der Ziele
Widersprich vagen Zielen im Interview. „Mach es schneller“ ist kein Ziel; „p99 unter 200ms für den Tenant-Listen-Endpunkt“ ist eines. Frage nach der messbaren Version.
Phase 3: Designoptionen (der Kern der Fähigkeit)
Hier verdient der RFC seinen Wert. Präsentiere 2-3 konkrete, unterschiedliche Ansätze für das Design, jeder gezeigt als ausgearbeitetes API-/Code-Snippet, das in den Codebasis-Konventionen von Phase 1 verankert ist. Keine Prosabeschreibungen: tatsächlicher Code, der zeigt, wie die endgültige API, Funktionssignaturen, das Schema oder die Konfiguration aussehen würden.
Gib für jede Option an:
- Ein kurzer Name und eine einzeilige Zusammenfassung.
- Ein Code-Snippet der resultierenden API / Verwendung / Signatur (das, wogegen ein zukünftiger Ingenieur tatsächlich programmieren würde).
- Seine Kompromisse: worin es gut ist, was es kostet, was es ausschließt.
Präsentiere sie nebeneinander und bitte den Benutzer, zu wählen oder zu verfeinern. Iteriere, wenn sie eine neue Option oder eine Mischung wünschen.
Die gewählte Option wird zum Vorgeschlagenen Design (mit ihrem Code). Die Optionen, die sie ablehnen, werden zum Abschnitt „Alternativen“, jede behält ihr Code-Snippet und den Grund, warum sie verloren hat. Deshalb sind Alternativen in diesen RFCs real: Sie waren echte Kandidaten mit funktionierendem Code, keine nachträglichen Strohmänner.
Wenn es wirklich nur einen gangbaren Ansatz gibt, sag das und präsentiere ihn allein mit einem expliziten Hinweis, dass Alternativen geprüft wurden und warum keine gangbar war. Erfinde keine gefälschten Optionen, um die Tabelle zu füllen.
Phase 4: Zusammenstellen
Schreibe den vollständigen RFC in die Ausgabedatei (Pfad in Phase 7 aufgelöst, früh bestätigt). Halte es knapp (siehe das Prinzip „Rücksichtslos prägnant“): Aufzählungspunkte statt Absätzen, kürzeste Formulierung, die dennoch klar ist, kein Füllmaterial. Das Code-Snippet erklärt; die Prosa rahmt es nur ein. Verwende die Hausvorlage des Repos, falls eine in Phase 1 erkannt wurde; ansonsten die eingebaute Struktur unten.
Füge ein Mermaid-Diagramm ein, wenn das Design eine sehenswerte Struktur hat (Architektur, Ablauf, Datenfluss, Zustandsmaschine). Ein Diagramm, das eine Frage beantwortet. Überspringe es für Änderungen, die rein auf API-Ebene sind und keinen interessanten Ablauf haben.
Eingebaute Vorlage
# RFC: <Titel>
## Zusammenfassung
<TL;DR, den ein Leser in 30 Sekunden erhält: was dies vorschlägt und warum.>
## Hintergrund & Motivation
<Das Problem, der aktuelle Zustand (mit Dateiverweisen, falls in einem Repo) und warum jetzt.
Was passiert, wenn wir nichts tun.>
## Ziele
<Wo möglich messbar. Aufzählungspunkte.>
## Nicht-Ziele
<Explizit außerhalb des Rahmens, damit Review-Instanzen es nicht neu verhandeln.>
## Vorgeschlagenes Design
<Der gewählte Ansatz. Führe mit dem ausgearbeiteten Code-/API-Beispiel aus Phase 3.
Erkläre dann, wie es funktioniert, verankert in echten Modulen. Diagramm, falls angebracht.>
## Alternativen
<Jede abgelehnte Option aus Phase 3, mit ihrem Code-Snippet und warum sie verloren hat.>
## Risiken & Kompromisse
<Jedes Risiko gepaart mit einer Abschwächung oder einem expliziten „akzeptiert, weil ...".>
## Rollout-Plan
<Migration, Phaseneinteilung, Rückwärtskompatibilität, Teststrategie.>
## Offene Fragen
<Bekannte Unbekannte. Besser, sie zu benennen, als so zu tun, als wären sie gelöst.>
## Genehmiger
<Wer unterschreibt, wer betroffen ist. Namen, damit klar ist, wo die Entscheidung liegt.>
Füge bedingte Abschnitte (Sicherheit, Leistung, Beobachtbarkeit) nur ein, wenn sie in Phase 2 relevant waren.
Optionale Metadaten (nur, wenn der Benutzer sie angefordert hat)
Standardmäßig füge kein Frontmatter oder eine Nummer hinzu. Wenn der Benutzer danach fragt, stelle voran:
---
status: Entwurf # Entwurf | In Überprüfung | Akzeptiert | Abgelehnt | Ersetzt
author: <Name>
date: <YYYY-MM-DD>
approvers: [ ]
---
Automatische Nummerierung (NNNN-slug.md) nur, wenn das Zielverzeichnis bereits NNNN-*.md-Dateien enthält; suche nach der höchsten und erhöhe sie. Ansonsten verwende einen einfachen Slug-Dateinamen.
Phase 5: Selbstkritik (obligatorisch, bevor der Benutzer den Entwurf sieht)
Führe den zusammengestellten RFC anhand dieser Bewertungsmatrix aus und behebe, was du kannst. Berichte dann, was du gefunden hast und was noch den Benutzer braucht.
- Ziele messbar? Vage Aspirationen auf etwas Testbares verschärft.
- Alternativen real? Mindestens eine echte Alternative mit eigenem Code, kein Strohmann. (Phase 3 sollte dies garantieren.)
- Jedes Risiko abgeschwächt? Jedes Risiko hat eine Abschwächung oder ein explizites „akzeptiert, weil ...".
- Design konkret? Das Vorgeschlagene Design enthält ein tatsächliches API-/Code-Snippet, nicht nur Prosa.
- Behauptungen belegt? Jede Aussage über die Codebasis hat einen Dateiverweis dahinter. Keine unbelegten Behauptungen.
Berichte kurz, z.B.: Selbstkritik: 2 vage Ziele verschärft; ein Risiko (Datenmigrationsausfallzeit) ohne Abschwächung markiert - brauche deine Entscheidung. Alles andere belegt.
Phase 6: Review-Schleife
RFC geschrieben nach <Pfad>. Öffne in einer Markdown-Vorschau für das gerenderte Diagramm. Möchtest du Änderungen?
Wende Änderungen durch Bearbeiten der Datei an. Wiederhole, bis genehmigt.
Phase 7: Ausgabe
Pfadauflösung (früh bestätigen, zu Beginn von Phase 4)
- Repo mit erkanntem RFC-Verzeichnis:
<dieses Verzeichnis>/<NNNN->slug.md. - Repo ohne eines:
docs/rfcs/<slug>.md. - Außerhalb eines Repos: aktuelles Arbeitsverzeichnis oder das Scratchpad, wenn das Arbeitsverzeichnis nicht beschreibbar ist.
Frage einmal vorab: Ich schreibe den RFC nach docs/rfcs/<slug>.md. Anderer Speicherort?
Bei Fertigstellung
- Öffne automatisch für den Benutzer in einem neuen VS-Code-Fenster:
code --new-window "<absoluter-pfad>". - Gib eine kurze Terminalzusammenfassung aus (Titel + einzeilig + Pfad). Gib das vollständige Dokument NICHT im Terminal aus.
Fehlerbehandlung
- Keine Eingabe / bloßes Thema - in Ordnung, das Interview kümmert sich darum. Beginne Phase 2.
- Referenzierter PR/Issue/Ticket nicht lesbar - teile dies dem Benutzer mit, fahre mit dem fort, was er beschreibt.
- Repo zu groß für vollständigen Scan - beschränke den Scan auf das Subsystem, das der Vorschlag berührt; notiere, was du übersprungen hast.
- Benutzer kann eine Dimension nicht beantworten - zeichne es als Offene Frage auf, anstatt eine Antwort zu erfinden.