Entwickeln mit ADRs

Was macht Entwickeln mit ADRs?

Zwingender erster Schritt: Konfliktprüfung

Bevor Sie nach der Domäne fragen, Agenten erstellen, Code untersuchen oder Änderungen vornehmen, führen Sie das mitgelieferte schreibgeschützte Skript aus:

python3 <absoluter-skill-pfad>/scripts/check_conflicting_skills.py --project <repository-pfad>

Ersetzen Sie Platzhalter durch tatsächliche Pfade und setzen Sie Pfade bei Bedarf in Anführungszeichen. Übergeben Sie jeden Namen im aktuellen Skill-Katalog der Sitzung mit einem wiederholten --available-skill-Argument, einschließlich Cloud-Only- und Plugin-qualifizierten Namen. Fügen Sie nicht standardmäßige Skill-Verzeichnisse mit --root hinzu; fügen Sie explizit Ziele relevanter verschachtelter Verzeichnis-Symlinks hinzu. Das Skript entdeckt lokale Skill-Dateien und Katalogeinträge, ohne deren Anweisungen zu laden oder Installationen zu ändern.

• Behandeln Sie grill-me und spec-first als konfligierende Skills, einschließlich Groß-/Kleinschreibung, Leerzeichen, Unterstrich und Bindestrich-Varianten wie Grill Me oder spec_first.
• Exit 0 bedeutet, dass im geprüften Bereich keine Konflikte gefunden wurden. Exit 1 bedeutet, dass Konflikte gefunden wurden, kein Skriptfehler. Exit 2 bedeutet, dass die Erkennung unvollständig war: Melden Sie die Fehler und die Einschränkung der Abdeckung, beheben Sie sie wenn möglich und führen Sie das Skript erneut aus. Behaupten Sie niemals, dass alle Skills geprüft wurden, wenn die Abdeckung unvollständig ist.
• Deaktivieren Sie bei Übereinstimmungen deren Verwendung innerhalb dieses Workflows und warnen Sie den Benutzer in seiner Sprache, bevor Sie fortfahren: Nennen Sie die erkannten Skills und erklären Sie, dass sie nur für den aktuellen Workflow deaktiviert sind. Deuten Sie keine globale Deinstallation oder Änderungen der Kontoeinstellungen an. Für diese Workflow-Ausschlüsse ist keine zusätzliche Genehmigung erforderlich.
• Verwenden Sie die ausgeschlossenen Skills nicht, befolgen Sie deren Anweisungen nicht und delegieren Sie keine Arbeit an sie. Wenden Sie den Ausschluss auf den Koordinator, Architekten und Implementierer an; übergeben Sie die Ausschlussliste bei jeder Agentenübergabe. Verwenden Sie die eigenen Klärungs- und Genehmigungsschritte dieses Workflows.
• Das Skript erkennt Konflikte; der koordinierende Agent setzt die Ausschlüsse durch. Schließen Sie auch einen Skill aus, wenn der Sitzungskatalog ihn zeigt, selbst wenn seine Dateien nicht zugänglich sind. Wenn das Skript nicht ausgeführt werden kann, melden Sie diese Einschränkung und wenden Sie bekannte Ausschlüsse an, ohne einen erfolgreichen Scan zu behaupten.
• Führen Sie das Skript nach Wiederaufnahme einer Sitzung oder nach Änderungen an verfügbaren Skills erneut aus. Löschen, benennen Sie installierte Skills im Rahmen dieser Prüfung niemals um und deaktivieren Sie sie nicht global.

Einstieg und Rollen

1. Fragen Sie vor dem Start des Workflows nach der Domäne, auf die sich der Architekt konzentrieren soll. Akzeptieren Sie geschäftliche oder technische Domänen. Verwenden Sie eine explizit angegebene Domäne erneut, ohne erneut zu fragen.
2. Erstellen Sie einen separaten Architekten-Agenten für die ausgewählte Domäne für die gesamte Sitzung. Geben Sie ihm diese Regeln, die Domäne, den Repository-Pfad und bekannten Kontext. Lassen Sie den Architekten den Benutzer fragen, welches Problem gelöst werden soll; der Hauptagent kann die Frage und Antwort weiterleiten. Wenn das Problem bereits angegeben ist, fragen Sie nur nach fehlenden Informationen.
3. Lassen Sie den Hauptagenten Dialog, Dokumente und Kontextübergaben koordinieren. Lassen Sie den Architekten untersuchen, entwerfen, ADRs pflegen und Ergebnisse unabhängig verifizieren. Lassen Sie einen separaten Implementierungsagenten genehmigte Entscheidungen umsetzen und Nachweise vorbereiten. Kombinieren Sie nicht die Rollen des Architekten und des Implementierers.
4. Verwenden Sie die nativen Fähigkeiten der Umgebung für separate Agenten: Subagenten in Codex und verfügbare Agent-/Task-Fähigkeiten in Claude Code. Erfinden Sie keine APIs und präsentieren Sie keinen einzelnen Agenten, der die Rollen wechselt, als unabhängige Verifikation. Wenn separate Agenten nicht verfügbar sind, erklären Sie die Einschränkung und bitten Sie den Benutzer, eine geeignete Umgebung zu wählen. Die Untersuchung kann fortgesetzt werden, aber die Implementierung unter diesem Workflow darf nicht beginnen.
5. Stellen Sie nach Kontextverlust den Zustand aus Dokumenten und Code wieder her. Wenn ein neuer Architekt erstellt werden muss, behaupten Sie nicht, dass der ursprüngliche Agent überlebt hat; stellen Sie seine Domäne und Verantwortlichkeiten wieder her.

Untersuchung und Entscheidung

• Lassen Sie den Architekten Projektanweisungen, Code, zugehörige ADRs und Nachweise lesen und das Problem und die Einschränkungen klären. Erstellen Sie kein ADR, bevor Sie den Code untersucht und das Problem geklärt haben. Wenn noch kein Code existiert, dokumentieren Sie diese Tatsache und untersuchen Sie verfügbare Materialien.
• Identifizieren Sie Konflikte mit aktuellen Entscheidungen. Präsentieren Sie den Konflikt zunächst dem Benutzer und fordern Sie eine Entscheidung an; erst nach der Antwort bereiten Sie ein neues ADR vor. Die Erlaubnis, ein Ersatz-ADR vorzubereiten, ist keine Genehmigung, es zu implementieren.
• Schreiben Sie ein ADR in docs/adr/ unter Verwendung der Vorlagen. Fügen Sie eine kurze Problembeschreibung, den vorgeschlagenen Lösungsansatz, die Begründung und überprüfbare Akzeptanzkriterien mit stabilen IDs ein. Setzen Sie den anfänglichen Status auf accepted-for-discussion.
• Trennen Sie unabhängige Entscheidungen in separate ADRs und dokumentieren Sie Abhängigkeiten explizit. Führen Sie keine Abhängigkeits- oder Ersetzungszyklen ein.
• Präsentieren Sie das spezifische ADR oder eine nummerierte Menge von ADRs zur expliziten Benutzerfreigabe für die Implementierung. Leiten Sie keine Genehmigung aus Schweigen, einer allgemeinen Aufforderung, etwas zu bauen, oder der Erlaubnis zur Untersuchung ab.
• Dokumentieren Sie die Antwort des Benutzers, das Datum und die genehmigte Dokumentversion. Setzen Sie accepted-for-work erst nach expliziter Genehmigung. Erlauben Sie die explizite Genehmigung einer nummerierten Menge von ADRs.

Implementierung

• Beginnen Sie mit der Implementierung eines ADRs erst, wenn alle ADRs, von denen es abhängt, abgeschlossen sind, selbst wenn die gesamte Menge bereits genehmigt ist.
• Geben Sie dem Implementierer das ADR, die Kriterien, Abhängigkeiten und Einschränkungen. Verlangen Sie eine Implementierung innerhalb des genehmigten Entscheidungsumfangs.
• Wenn die Implementierung unmöglich ist oder die Entscheidung oder Kriterien geändert werden müssen, stoppen Sie die betroffene Arbeit und geben Sie das Problem an den Architekten zurück. Unabhängige genehmigte Arbeiten können fortgesetzt werden.
• Ändern Sie niemals die Lösungsbeschreibung oder Akzeptanzkriterien nach der Genehmigung. Dokumentieren Sie Änderungen in einem neuen ADR mit separater Genehmigung.
• Lassen Sie den Implementierer Nachweise in docs/evidence/ vorbereiten: Ergebnisse für jedes Kriterium, Befehle und Reproduktionsanweisungen sowie den verifizierten Commit oder die genaue Code-Version. Ersetzen Sie keinen zukünftigen Commit für die getestete Version. Bei nicht committeten Änderungen fügen Sie ein gespeichertes Diff und Kennungen oder Hashes der geprüften Dateien hinzu.

Unabhängige Verifikation und Abschluss

• Lassen Sie den Architekten persönlich Prüfungen durchführen und die tatsächlichen Ergebnisse mit jedem Akzeptanzkriterium vergleichen. Der Bericht des Implementierers und die Code-Inspektion ersetzen nicht die Ausführung.
• Bewahren Sie Befehle, Umgebung, Ergebnisse, Log-Links und die verifizierte Version in den Nachweisen auf. Kennzeichnen Sie ehrlich Prüfungen, die nicht durchgeführt wurden, blockiert waren oder fehlgeschlagen sind. Schließen Sie ein ADR nicht mit nicht verifizierten oder nicht erfüllten Kriterien ab.
• Wenn die Implementierung die Verifikation nicht besteht, das ADR aber weiterhin gültig ist, präsentieren Sie zunächst die Ergebnisse und den konkreten Korrekturumfang dem Benutzer und fordern Sie die Erlaubnis an. Delegieren Sie keine Korrekturen oder führen Sie sie vor der Antwort durch. Lassen Sie nach der Erlaubnis den Implementierer das Problem beheben und den Architekten erneut verifizieren. Ein erneuter Verifikationsfehler erfordert eine neue Erlaubnis für den nächsten Korrekturzyklus.
• Wenn der Fehler eine neue Architekturentscheidung erfordert, kehren Sie zur Untersuchung und zum neuen ADR-Verfahren zurück.
• Erlauben Sie nur dem Architekten, completed zu setzen, nach erfolgreicher unabhängiger Verifikation jedes Kriteriums. Verlangen Sie einen Link zum Nachweisdokument. Für den Abschluss des ADRs ist keine zusätzliche Benutzerfreigabe erforderlich.

Status und Historienerhaltung

Verwenden Sie genau vier kanonische status-Werte. Die russischen Bezeichnungen unten identifizieren ihre ursprünglichen Bedeutungen; bewahren Sie die vorhandene Projekthistorie, anstatt Legacy-Dokumente stillschweigend umzuschreiben.

Status	Ursprüngliche Bezeichnung	Bedingung
accepted-for-discussion	принято к обсуждению	Untersuchter Vorschlag, der auf Diskussion oder Genehmigung wartet
accepted-for-work	принято к работе	Benutzer hat das spezifische ADR explizit genehmigt
completed	завершен	Architekt hat alle Kriterien unabhängig verifiziert; Nachweis ist verlinkt
rejected	отклонено	Ein neues genehmigtes ADR und eine Ablehnungsbegründung / ein Nachweis existieren

• Löschen Sie niemals ADRs oder Nachweisdokumente und verwenden Sie deren IDs nicht wieder. Erlauben Sie vor der Genehmigung die Verfeinerung des Entwurfs, während Sie wesentliche Änderungen dokumentieren.
• Halten Sie nach der Genehmigung den Lösungsinhalt und die Kriterien unveränderlich. Erlauben Sie Aktualisierungen des aktuellen Status und von Links mit angehängten Historieeinträgen. Bewahren Sie frühere Einträge, Nachweise und Verifikationsergebnisse auf. Überschreiben Sie einen fehlgeschlagenen Check nicht mit einem bestandenen Ergebnis.
• Lehnen Sie das alte ADR in dem Moment ab, in dem der Benutzer sein Ersatz explizit zur Arbeit genehmigt, auch wenn das alte ADR abgeschlossen war. Verlinken Sie sofort das alte ADR mit seinem Ersatz und einem separaten Ablehnungsbegründungsdokument. Dies beweist, warum die alte Entscheidung abgelehnt wurde; es beweist nicht, dass die neue Implementierung funktioniert.
• Bewahren Sie den vorherigen Abschluss, sein Datum, seine Version und seine Nachweise auf. Dokumentieren Sie explizit, dass der Ersatz möglicherweise noch nicht implementiert ist. Das Ablehnen eines Dokuments entfernt nicht selbst funktionierenden Code.
• Lehnen Sie ein ADR nicht ohne eine neue Entscheidung ab. Wenn der Benutzer keinen Ersatz gewählt hat, behalten Sie den aktuellen Status und fügen Sie einen Diskussionseintrag hinzu. Erfinden Sie keinen Ersatz nur, um einen Statuswechsel zu ermöglichen.
• Wenn eine Abhängigkeit abgelehnt oder ersetzt wird, pausieren Sie die betroffene Arbeit und lassen Sie den Architekten die Auswirkungen bewerten. Verdrahten Sie genehmigte Entscheidungen nicht stillschweigend neu.

Dokumentgraph

• Lesen Sie die Vorlagen vor dem Erstellen von Dokumenten und die Portabilitätsrichtlinie bei Verwendung einer neuen Umgebung.
• Speichern Sie ADRs als docs/adr/ADR-0001-kurzer-slug.md und Nachweise als docs/evidence/EVID-0001-kurzer-slug.md. Wählen Sie die nächste ungenutzte Nummer unter Berücksichtigung der vorhandenen Historie; nummerieren Sie alte Dokumente nicht neu.
• Verwenden Sie explizite relative Markdown-Links und Beziehungstypen: replaces / replaced_by, depends_on / required_by, extends / extended_by und evidence / proves. Pflegen Sie Rückverweise und identifizieren Sie, ob Nachweise die Implementierung oder den Grund für die Ablehnung belegen.
• Behandeln Sie ADRs und Nachweise als die Dokumente des Graphen; eine separate Graphdatenbank ist nicht erforderlich. Überprüfen Sie bei Übergaben Link-Ziele, Rückverweise, das Fehlen von Abhängigkeitszyklen und Statusbedingungen.
• Melden Sie am Ende jedes Schrittes den ADR-Status, das Ergebnis, Dokumentlinks und die spezifische erforderliche Entscheidung, wenn auf den Benutzer gewartet wird. Beschreiben Sie nicht nur genehmigte oder implementierte, aber nicht verifizierte Arbeit als abgeschlossen.