add-convention

Füge eine Konvention hinzu – aber nur, nachdem bewertet wurde, ob sie existieren sollte und wo sie hingehört. Diese Fähigkeit ist ein Gatekeeper und Router, kein Protokollführer.

Schritt 0 – Vorbedingungen und Kontext

Bestätige, dass das Repository initialisiert ist (bootstrapped).
Lies CONVENTIONS.md und AGENTS.md vollständig, um Überschneidungen mit bestehenden Regeln erkennen und die Passung beurteilen zu können.

Schritt 0.5 – Bewertung (zuerst ausführen)

Führe das gemeinsame Bewertungsprotokoll aus; die Triage-Fragen (Schritt 1) und Routing-Fragen (Schritt 2) werden darunter gestellt:

Bereits gelieferte Antworten zuerst verwenden. Behandle anwendbare, bereits in der Anfrage oder dieser Sitzung gelieferte Entscheidungen, einschließlich der Tiefe, als beantwortet. Fasse sie zusammen, ohne erneut zu fragen; Standardwerte ersetzen niemals explizite Entscheidungen. Wenn jede wesentliche Entscheidung geliefert wurde, fahre fort. Frage nur zu einer wesentlichen fehlenden oder widersprüchlichen Entscheidung. Eine Repository-Präferenz allein ist keine aktuelle Antwort oder Ausführungsgenehmigung.
Tiefenauswahl für ungelöste Entscheidungen. Wenn die Tiefe nicht geliefert wurde und Entscheidungen offen bleiben, frage, wie tief diese Bewertung gehen soll: express – jede Entscheidung nimmt ihre empfohlenen Standardwerte; nur Fragen ohne ableitbaren Standardwert (die grundlegenden Freitexte) werden noch gestellt; guided – nur die unten als "high-impact" markierten Fragen plus die grundlegenden Freitexte; full – jede Frage unten. Wenn die CONVENTIONS.md des Repositorys eine Assessment depth: aufzeichnet, wähle sie vorab als empfohlene Option bei der Frage aus; eine aufgezeichnete Tiefe wird niemals stillschweigend angewendet. Ansonsten empfehle full, wenn die Anfrage mit wenig oder keinem Kontext eintrifft, und express, wenn sie bereits vollständig spezifiziert ist. Zu jeder Frage kann der Bediener "Standardwerte ab hier" oder "gehe tiefer" antworten; erfülle den Wechsel sofort.
Stelle Fragen eine nach der anderen, jede mit einer empfohlenen Option und einem einzeiligen Grund; warte auf jede Antwort.
Verwende strukturierte Auswahl (einfach- oder mehrfach). Wenn der Host ein Werkzeug für strukturierte Einzel-/Mehrfachauswahl bietet, verwende es und markiere die empfohlene Option; ansonsten liste Optionen A/B/C im Klartext auf und nenne die empfohlene. Verwende Freitext nur, wenn eine aufzählbare Menge unmöglich ist (z.B. der genaue Wortlaut).
Der Bediener entscheidet. Fahre niemals an einer Frage ohne Antwort vorbei und rate niemals den Umfang, wenn ohne Kontext aufgerufen.

Fragen (überspringe jede, die die Anfrage bereits beantwortet):

Lohnt sich die Kodifizierung? – ja (wiederkehrend, stabil, prüfbar) oder nein (einmalig, doppelt, änderungsanfällig, vage). *Empfohlen: gemäß der Triage in Schritt 1; diese Frage schließt den Rest auf. (High-impact – wird in guided gefragt.)
Zuhause – AGENTS.md harte Regel / CONVENTIONS.md Richtlinie / GLOSSARY.md Begriff / eigentlich eine Entscheidung (an die new-adr-Fähigkeit übergeben). Empfohlen: gemäß der Natur der Regel (siehe Schritt 2). (High-impact – wird in guided gefragt: Das falsche Zuhause erzeugt Aufwand für die Verschiebung.)
Im Verify-Gate durchsetzen? – ja / nein. Empfohlen: nein, es sei denn, die Regel ist mechanisch prüfbar.
Wortlaut – Freitext (die Regelaussage selbst; wird bei jeder Tiefe gefragt).

Schritt 1 – Bewerten: Lohnt sich die Kodifizierung?

Wende Triage an. Empfehle gegen das Hinzufügen, wenn:

Es ist bereits (explizit oder implizit) durch eine bestehende Konvention abgedeckt – verweise darauf anstatt zu duplizieren.
Es ist eine einmalige, keine wiederkehrende Entscheidung – die Kodifizierung fügt Rauschen hinzu.
Es ist wahrscheinlich änderungsanfällig – verfrühte Regeln werden zu veralteter Altlast.
Es ist zu vage, um prüfbar oder handlungsleitend zu sein, wie es geschrieben steht.

Empfehle für das Hinzufügen, wenn es sich um eine wiederkehrende Entscheidung handelt, deren Mehrdeutigkeit Nacharbeit verursacht, sie stabil ist und so formuliert werden kann, dass ein Agent ihr ohne weitere Interpretation folgen kann. Gib deine Empfehlung und den Grund an, bevor du etwas tust.

Schritt 2 – Routen: Wo gehört es hin?

Entscheide das Zuhause und erkläre die Wahl:

Harte Regel, die Agenten befolgen müssen → ein Aufzählungspunkt in AGENTS.md §Harte Regeln, mit dem Inhalt in CONVENTIONS.md. Verwende für nicht verhandelbare Einschränkungen.
Erstellungs-/Prozessrichtlinien → ein Abschnitt in CONVENTIONS.md. Verwende für "wie wir Dinge tun", das informiert, aber nicht blockiert.
Gemeinsamer Begriff / Definition → GLOSSARY.md (erstelle es, wenn es fehlt – das Hinzufügen des ersten Begriffs aktiviert die Glossary-Ebene; platziere es im aufgezeichneten Artefakt-Stammverzeichnis). Lies die CONVENTIONS.md §Glossar des Repositorys und überprüfe die Regel, die es tatsächlich deklariert; die kanonische Struktur ist eine optionale H1-Überschrift und optionaler Einführungstext, dann genau eine zweispaltige Markdown-Tabelle, deren Kopfzeile Begriff | Definition ist. Jeder Begriff ist seine eigene Zeile. Zeichne einen Begriff niemals als Überschrift, Aufzählungspunkt oder Absatz auf und füge niemals eine zweite Tabelle oder eine andere Spaltenform hinzu. Ein §Glossar, das eine ältere oder andere Glossarkonvention angibt, ist keine Übernahme dieser Tabelle: Verwende die kanonische Form und biete die Migration der Audit-Fähigkeit als separat zugestimmtem Regel-und-Datei-Wechsel an, anstatt die alte Form zu kopieren. Ein fehlendes GLOSSARY.md bleibt ein gültiger Zustand; diese Fähigkeit erstellt es nur, weil tatsächlich ein Begriff hinzugefügt wird.
Es ist tatsächlich eine Entscheidung, keine Konvention (eine architektonische, produktbezogene oder technologische Wahl mit Alternativen und Konsequenzen) → dies ist ein ADR. Stoppe und biete die new-adr-Fähigkeit an; vergrabe keine Entscheidung in CONVENTIONS.

Wenn eine Konvention eine Triage-/Prozessregel ist (z.B. wie eingehende Arbeit triagiert wird),, bevorzuge CONVENTIONS.md mit einem harten Regel-Aufzählungspunkt in AGENTS.md nur für die Teile, die nicht verhandelbar sind.

Schritt 3 – Entwurf und Bestätigung

Formuliere den genauen Wortlaut für die Zieldatei. Halte ihn prägnant, prüfbar und in der Sprache des Repositorys. Zeige den Diff. Bestätige vor dem Schreiben.

Schritt 4 – Schreiben und Committen

Wende die Änderung(en) an. Wenn eine Konvention zu einer harten Regel aufgewertet wird, stelle sicher, dass AGENTS.md und CONVENTIONS.md konsistent bleiben. Conventional Commit (docs: ...); da kein ADR berührt wird, ist kein Rationale:-Footer erforderlich, füge einen hinzu, wenn der Vertrag des Repositorys es bei Konventionsänderungen verlangt.

Hinzufügen oder Erweitern eines Glossars. Verwende die unten definierte kanonische Struktur und die deklarierten Regelprüfungen; die Form darf zwischen den Durchläufen nicht abweichen.

Woher die Regel stammt. Wenn CONVENTIONS.md keinen §Glossar-Abschnitt hat (ein Legacy-Repository, das älter ist, oder eine Ebene, die vor der Aufzeichnung der Regel aktiviert wurde),, falle auf die oben genannte kanonische Standardform zurück: optionale # Glossar-Überschrift und Einführungstext, dann eine Begriff | Definition-Tabelle. Erfinde keine andere Form für dieses Repository und bearbeite keine nicht verwandten Konventionen stillschweigend.
Lesen der deklarierten Regel. Wenn ein §Glossar existiert, lies, was es tatsächlich deklariert. Wenn es die kanonische zweispaltige Begriff | Definition-Tabelle beschreibt, folge ihr und ändere sie nur auf ausdrücklichen Wunsch. Wenn es eine andere oder ältere Glossarkonvention angibt (Aufzählungspunkte, Prosa, eine andere Spaltenform), hat das Repository diese Tabelle nicht übernommen: Kopiere nicht die alte Form und schreibe die Regel nicht stillschweigend um. Verwende die kanonische Form für den Begriff und biete die Migration der Audit-Fähigkeit an, die die Regel und die Datei zusammen als einen separat zugestimmten Diff abdeckt.
Aufzeichnen der Konvention. Wenn ein §Glossar fehlt, biete an – als eigene bestätigte Änderung, getrennt von dem hinzuzufügenden Begriff – einen ## Glossar-Abschnitt in CONVENTIONS.md aufzuzeichnen, der die tatsächlich verwendete Form angibt. Zeige diesen Diff und schreibe ihn nur, wenn der Benutzer zustimmt; schreibe niemals andere CONVENTIONS.md-Abschnitte um oder ordne sie neu, um Platz zu schaffen, und wenn der Benutzer ablehnt, behalte das Glossar kanonisch, aber lasse CONVENTIONS.md unverändert.
Erstellen der Datei. Schreibe die optionale # Glossar-Überschrift und eventuellen kurzen Einführungstext, den das Repository benötigt, dann die einzelne zweispaltige Tabelle mit Kopfzeile Begriff | Definition und dem neuen Begriff als erster Zeile. Erfinde keine Platzhalterbegriffe.
Erweitern einer bestehenden Datei. Behalte die Überschrift, den Einführungstext, die Reihenfolge der Einträge und jede vorhandene Zeile Byte für Byte bei. Hänge den neuen Begriff als eine neue Zeile an; baue die Datei niemals neu auf, sortiere sie neu oder formatiere sie um und führe niemals eine zweite Tabelle ein.
Ankerpunkte. Wenn die Zeile des neuen Begriffs von einem Überschriftenanker aus erreichbar ist, den ein eingehender Link bereits verwendet, behalte diesen Anker auf der Zeile bei, anstatt das Ziel fallen zu lassen; wenn der Anker nicht erhalten werden kann, stoppe und melde es, anstatt zu raten.
Bedeutung bewahren. Behalte die Schreibweise des Begriffs, Aliasse, Links und Inline-Code genau so bei, wie geliefert. Maskiere einen literalen senkrechten Strich als \|. Wenn eine Definition tatsächlich mehrzeilig ist, behalte sie in einer Zelle mit <br> für den harten Zeilenumbruch, anstatt in zusätzliche Zeilen überzugehen.
Duplikate und Mehrdeutigkeit. Wenn der Begriff bereits existiert, zeige die vorhandene und die vorgeschlagene Definition und frage, ob die vorhandene Zeile aktualisiert oder belassen werden soll. Führe niemals stillschweigend eine Zusammenführung, Ersetzung oder eine zweite Zeile für denselben Begriff durch und rate niemals eine Definition.
Nicht-kanonische Datei. Wenn die vorhandene GLOSSARY.md aus Aufzählungspunkten, Prosa, Überschriften oder einer gemischten Form besteht, hänge keine konkurrierende Zeile an und schreibe die Datei nicht als Nebeneffekt des Hinzufügens eines Begriffs um. Hebe die nicht-kanonische Struktur hervor und biete die zugestimmte Migration der Audit-Fähigkeit an; wende sie nur an, wenn der Benutzer den konkreten Diff akzeptiert. Eine abgelehnte Migration belässt die Datei so, wie der Benutzer sie behält.

Nenne die Regel und die durchgeführte Weitergabe; liste nicht aktualisierte Repositorys auf.

Abschlussbericht

Beende jeden Durchlauf, einschließlich blockierter, fehlgeschlagener und gestoppter Durchläufe, mit einem Abschnitt, der genau Status auf einen Blick heißt und diese drei Bezeichnungen enthält:

Dieser Durchlauf: nur tatsächlich versuchte Aktionen und ihre Ergebnisse; zitiere die genaue Ausgabe und den Exit-Code jedes Verify-Gates, einschließlich Timeouts oder Unterbrechungen.
Gesamt: implementiert, teilweise verifiziert, verifiziert, blockiert, fehlgeschlagen oder unbekannt. Ein bestandener Unterschritt ist kein Gesamterfolg; unvollständige oder fehlende Nachweise werden nie zum Erfolg.
Noch zu tun: jede verbleibende Aktion, ungelöster Befund, Verifikation, Bereinigung oder erforderliche Eingabe. Schreibe "Keine" nur, wenn die gesamte Aufgabe nachweislich abgeschlossen ist; unterlasse niemals Arbeit, weil ein Budget zu Ende ging.

Routinemäßige Fortschrittsmeldungen benötigen keinen Block. Halte abschließende Ergebnisse kurz und unterscheide Arbeiten, die auf einem PR vorbereitet wurden, von Arbeiten, die als ausgeliefert bestätigt wurden.

EvolveHQ/docflow

Was ist docflow?

In Ihrer bevorzugten KI fragen

Dokumentation