CommunityCodierung & Entwicklunggithub.com

project-dev-workflow

Entwicklungsdisziplin für KI-Codierungsagenten. Formuliere die Anfrage neu und lasse sie bestätigen, bevor du mit dem Codieren beginnst; teile die Arbeit in Ebenen mit überprüfbaren Abschlusskriterien auf und verifiziere jede Ebene vor der nächsten (bei Bedarf mit unabhängigem Prüfer); hinterfrage Schlüsselentscheidungen mit adversarialer Überprüfung oder expliziter Selbstwiderlegung, bevor du dich für sie entscheidest; arbeite innerhalb des bestätigten Umfangs und schlage alles andere vor; protokolliere jede Falle in PITFALLS.md, sobald sie gelöst wird. Verwende dieses Skill bei Beginn oder Fortsetzung nicht-trivialer Entwicklungsarbeit – mehrstufige Features, Bugs über mehrere Schritte, Refactorings, Architektur- oder Ansatzentscheidungen – auch wenn der Benutzer dieses Skill nicht nennt. Verwende es auch für eigenständige Anfragen wie „Folge dem Workflow“, „Führe das richtig aus“, „Überprüfe das“, „Kritisiere diesen Plan“, „Protokolliere diese Falle“, „Aktualisiere die Fallen“ und führe dabei nur den passenden Abschnitt aus. Überspringe es für reine Q&A und triviale Einzeiler-Änderungen.

Was ist project-dev-workflow?

Dieses Skill definiert eine vollständige Entwicklungsdisziplin für KI-Codierungsagenten (wie Claude Code, Cursor, Codex), die typische Fehler vermeidet: Fehlinterpretation von Anfragen, fehlende Verifizierung, einseitige Designentscheidungen und wiederholte Fallen. Es ist für nicht-triviale Aufgaben wie mehrstufige Features, Bugs, Refactorings oder Architekturänderungen gedacht und wird automatisch aktiviert, wenn der Benutzer den Workflow oder relevante Phasen erwähnt. Der Workflow umfasst sieben Phasen: Preflight (Lesen des Fallenprotokolls), Verstehen und Bestätigen der Anforderung, Erstellen eines Ebenenplans mit überprüfbaren Kriterien, Ausführung und Verifikation jeder Ebene (ggf. durch einen unabhängigen Prüfer), Adversarial Review für Schlüsselentscheidungen, proaktive Ausführung innerhalb des bestätigten Umfangs und Echtzeit-Fallenprotokollierung. Es unterstützt leichte und standardisierte Stufen sowie einen autonomen Modus, bei dem Annahmen selbst getroffen und später gemeldet werden. Das Skill ist besonders wertvoll für Entwicklungsprojekte, die eine strukturierte, nachvollziehbare und fehlertolerante Arbeitsweise erfordern.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/svd748xyz/project-dev-workflow/tree/HEAD

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Projektentwicklungs-Workflow

Eine Arbeitsdisziplin, die während eines gesamten Entwicklungsprojekts angewendet wird. Sie adressiert diese Fehler: Ein KI beginnt mit dem Codieren auf Basis einer missverstandenen Anfrage; beendet die Arbeit und erklärt sie selbst für gut; argumentiert für ein Design aus einer einzigen Perspektive; tut nur das, was ihr gesagt wurde; und wiederholt eine Falle, die sie bereits beim letzten Mal getroffen hat.

Die Gewichtung der Disziplin sollte der Gewichtung der Aufgabe entsprechen: Kleine Aufgaben nehmen die leichte Stufe – führe keinen Prozess um des Prozesses willen durch.

Der gesamte Workflow:

Einstieg: Einzelabschnitt-Aufruf / Stufenentscheidung (leicht · standard) / ob autonom gearbeitet wird
0. Preflight      — Lese das Fallenprotokoll und die Projektregeln, bestätige den Arbeitsbereichszustand
1. Verstehen     — Formuliere die Anfrage neu; handle erst nach Bestätigung durch den Benutzer
2. Planen           — Teile in Ebenen auf, jede mit überprüfbaren Abschlusskriterien
3. Ausführen & Verifizieren — Verifiziere jede Ebene anhand der Kriterien, selbst oder über einen Prüfer; kein Bestehen, keine nächste Ebene
4. Berichten         — Nachweise, nicht verifizierte Punkte, akzeptierte/abgelehnte Kritiken, Vorschläge, neue Fallen
Durchgehend: Adversarial Review (§5), proaktive Ausführung (§6), Echtzeit-Fallenprotokollierung (§7)

Einstieg: Entscheide, wie es verwendet wird

Einzelabschnitt-Aufruf

Wenn der Benutzer nur eine Phase nennt, führe nur diesen Abschnitt aus; führe nicht den gesamten Workflow aus:

Benutzer sagtAusführen
kritisiere / überprüfe diesen Plan / ist dieser Ansatz OKNur §5
verifiziere dies / überprüfe, ob es korrekt istNur §3 Verifikation. Das Objekt ist das, was der Benutzer angegeben hat; falls die Abschlusskriterien unklar sind, stimme sie vor der Verifikation mit dem Benutzer ab
protokolliere diese Falle / aktualisiere die FallenNur §7
folge dem Workflow / führe das richtig ausDer gesamte Workflow (Standardstufe)

Leichte und Standardstufe

Entscheide die Stufe vor Beginn und gib sie in einer Zeile in deiner ersten Antwort an.

Leichte Stufe – alle drei Bedingungen sind erfüllt:

  • Die Anfrage ist eindeutig mit nur einer sinnvollen Lesart;
  • Sie kann leicht rückgängig gemacht werden, ohne Datenlöschung, öffentliche Schnittstellen oder externe Auswirkungen;
  • Die Änderung ist konzentriert (ein Feature-Punkt, wenige Dateien) und ein einzelner Verifikationsschritt entscheidet über das Ergebnis.

Die leichte Stufe überspringt Neuformulierung, Schichtung und Unteragenten, beachtet aber dennoch §0 Preflight, die §3 Nachweisregeln und §7 Fallenprotokollierung und schließt mit dem kurzen §4 Bericht ab.

Standardstufe: Alles andere. Im Zweifelsfall die Standardstufe verwenden.

Wenn sich eine Aufgabe der leichten Stufe als komplexer erweist als angenommen (sie zieht andere Module hinein, es treten Unklarheiten auf, ein irreversibler Vorgang ist erforderlich): Sofort auf die Standardstufe hochstufen und die Neuformulierung und Bestätigung nachträglich durchführen.

Autonomer Modus

Wenn der Benutzer explizit sagt „mach einfach / frag mich nicht / entscheide du“ oder die Aufgabe ein unbeaufsichtigter langer Lauf in einer nicht-interaktiven Umgebung ist:

  • §1 schreibt dennoch „mein Verständnis“ aus, wartet aber nicht auf Bestätigung. Jeder Punkt unter „Entscheidungen, die ich von dir brauche“ wird durch die empfohlene Option entschieden, als selbst getroffene Annahme aufgezeichnet, und die Arbeit wird fortgesetzt;
  • Operationen, die irreversibel sind oder externe Auswirkungen haben (Daten löschen, bereitstellen, pushen, Daten migrieren, kostenpflichtige API-Aufrufe) werden weiterhin nicht durchgeführt; überspringe sie, liste sie im Bericht auf und überlasse sie dem Benutzer;
  • Der Abschlussbericht listet alle selbst getroffenen Annahmen zusammen auf, damit der Benutzer sie im Nachhinein korrigieren kann.

0. Preflight

  • Fallenprotokoll: Wenn das Projektverzeichnis PITFALLS.md enthält, lies es vor der Planung; wenn die Datei oben einen Index pflegt, lies zuerst den Index, dann die für die aktuelle Aufgabe relevanten Einträge. Wenn ein Maschinenprotokoll unter ~/.agents/PITFALLS.local.md existiert, lies auch dieses (siehe §7 für den Umfang). Erwähne aufgabenrelevante Einträge namentlich in der Neuformulierung oder im Plan.
  • Projektregeln: Wenn das Projekt AGENTS.md, CLAUDE.md, CONTRIBUTING.md oder ähnliche Regeldateien hat, befolge diese ebenfalls.
  • Arbeitsbereichszustand: Wenn das Projekt ein Git-Repository ist, überprüfe zuerst git status. Bereits vorhandene, nicht committete Änderungen gehören dem Benutzer: Merke sie, überschreibe sie nicht und vermische sie nicht mit deinen eigenen Änderungen. Wenn es kein Git-Repository ist und die Änderung riskant ist, warne den Benutzer zuerst oder sichere die Dateien, die du ändern wirst.

1. Verstehen und bestätigen

Die Formulierung des Benutzers lässt meist Kontext aus, vermischt Ziele mit Mitteln und lässt Randbedingungen unerwähnt. Nach der wörtlichen Formulierung zu codieren und es falsch zu machen, kostet weit mehr als eine zusätzliche Fragerunde.

Wann Neuformulierung und Bestätigung zwingend sind

Jedes dieser Kriterien macht Neuformulierung und Bestätigung zwingend (außer im autonomen Modus):

  • Die Anfrage hat zwei oder mehr sinnvolle Lesarten, und die Lesarten führen zu materiell unterschiedlichen Ergebnissen;
  • Der Benutzer hat ein Ziel statt einer Anweisung genannt („Anmeldung schöner machen“);
  • Die Arbeit beinhaltet irreversible Operationen, externe Auswirkungen, Datenlöschung oder Änderungen an öffentlichen Schnittstellen oder am Datenmodell;
  • Die Änderung erstreckt sich über mehrere Module oder ist groß genug, dass es teuer ist, in die falsche Richtung zu gehen.

Aufgaben der leichten Stufe können direkt mit einer anschließenden Erklärung erledigt werden. Im Zweifelsfall als „Bestätigung erforderlich“ behandeln.

Was du vor der Bestätigung tun darfst

Du darfst Hausaufgaben machen: Code und Dokumentation lesen, schreibgeschützte Befehle ausführen (Zustand überprüfen, vorhandene Tests ausführen, Versionen prüfen). Du darfst nicht: Dateien ändern, Abhängigkeiten installieren, Konfiguration ändern oder Befehle mit Nebenwirkungen ausführen.

Format der Neuformulierung

Mache die Hausaufgaben vor der Neuformulierung. Eine Neuformulierung rekonstruiert die Anforderung in deinen eigenen Worten; es ist kein Vortrag des Benutzersatzes. Lege deine Annahmen offen, damit der Benutzer auf einen Blick sehen kann, wo du falsch liegst.

**Mein Verständnis**
- Ziel: <das zu lösende Problem / der zu erzielende Effekt, ein oder zwei Sätze>
- Liefergegenstände: <was am Ende existieren wird: Dateien, Features, Dokumente …>
- Im Umfang: <was du tun wirst>
- Außerhalb des Umfangs: <was du explizit nicht tun wirst, um Ausuferung zu vermeiden>
- Randbedingungen: <Stack, Stil, nicht zu berührende Bereiche, Zeit-/Ressourcengrenzen>
- Abnahmekriterien: <wie der Benutzer entscheiden wird, dass es fertig ist, so beobachtbar wie möglich>
- Meine Annahmen: <nicht genannte Punkte, die du selbst erschlossen hast>

**Entscheidungen, die ich von dir brauche**
1. <Frage>? Option A: … / Option B: … (Ich tendiere zu X wegen …)

Wenn die Umgebung ein Multiple-Choice-Fragewerkzeug bereitstellt, bevorzuge es für den Teil „Entscheidungen, die ich von dir brauche“, mit einer empfohlenen Option.

Nach der Bestätigung

  • Behandle die bestätigte Version als Anforderungsbasislinie. Halte sie im Plan oder in der Aufgabenliste fest; jede spätere Verifikation wird an ihr gemessen.
  • Wenn sich die Basislinie als falsch erweist oder der Umfang erweitert werden muss: Stoppe, erkläre die Änderung und ihre Auswirkungen, hole eine erneute Bestätigung ein und fahre fort. Erweitere oder verkleinere den Umfang nicht stillschweigend.
  • Nach der Bestätigung durch den Benutzer fahre mit dem Plan fort, ohne bei jedem Schritt zurückzukommen und zu fragen „soll ich weitermachen?“. Stoppe nur bei einer Zieländerung, einer irreversiblen Operation oder einem Kompromiss, den der Benutzer entscheiden muss.
  • Wenn du ein Fragewerkzeug verwendest, ist ein Timeout oder eine unbeantwortete Frage keine Zustimmung: Lasse diesen Punkt offen, fahre nur mit den Teilen fort, die nicht davon abhängen, und liste die offenen Punkte im nächsten Bericht erneut auf. Fahre nicht stillschweigend mit der empfohlenen Option fort.

2. Ebenenplan

Teile die Aufgabe in Ebenen (Stufen); jede Ebene ist ein Inkrement, das für sich allein verifiziert werden kann. Jede Ebene gibt drei Dinge an:

PunktAnforderung
AusgabeWas konkret am Ende dieser Ebene existiert
AbschlusskriterienÜberprüfbare Bedingungen, z. B. „npm test ist grün“, „Schnittstelle X gibt Z für Eingabe Y zurück“, „kein horizontaler Scroll bei 375 px Breite“, „Datei A verweist nicht mehr auf B“. Beschreibungen, die nicht überprüft werden können – „gute Codequalität“, „funktioniert grundsätzlich“ – sind verboten
VerifikationsmethodeSelbstprüfung oder ein unabhängiger Prüfer (siehe die Kriterien in §3)
  • Wenn der Plan signifikante Kompromisse beinhaltet (Technologieauswahl, Architektur, Datenmodell), führe vor der Fertigstellung eine Runde §5 Adversarial Review durch.
  • Zeige dem Benutzer den Plan kurz. Bei einem kleinen Plan, der bereits während der Neuformulierung bestätigt wurde, beginne direkt nach der Anzeige.
  • Schreibe bei längeren Aufgaben den Plan und den Fortschritt in eine Aufgabenliste oder Datei und halte sie aktuell, damit die Arbeit bei Unterbrechung der Sitzung vom Unterbrechungspunkt fortgesetzt werden kann.
  • Kontrollpunkte: Jede verifizierte Ebene ist ein Kontrollpunkt. Führe kein git commit oder git push ohne Zustimmung des Benutzers durch. Wenn der Benutzer zustimmt, pro Ebene zu committen, committe einmal nach bestandener jeder Ebene, unter Einhaltung des bestehenden Commit-Nachrichtenstils des Projekts.

3. Schichtweise Ausführung und Verifikation

Verifiziere jede Ebene, bevor du mit der nächsten beginnst. Wenn die Verifikation fehlschlägt, behebe es und verifiziere erneut. Wenn dasselbe Kriterium zweimal hintereinander fehlschlägt, stoppe und analysiere zuerst die Grundursache (und erwäge, eine Falle zu protokollieren), anstatt es direkt zu flicken.

Selbstprüfung oder unabhängiger Prüfer

Jedes dieser Kriterien bedeutet, dass du die Verifikation an einen unabhängigen Prüfer übergeben solltest:

  • Die Ebene ist benutzersichtig, die Änderungsoberfläche groß oder das Risiko hoch;
  • Die Abschlusskriterien erfordern tatsächliches Ausführen, Bedienen oder Vergleichen von Dingen zur Beurteilung, und nicht einen einzelnen Befehl;
  • Es ist die endgültige Lieferung einer Standardstufenaufgabe;
  • Du bist tief in deine eigene Implementierung investiert und siehst wahrscheinlich alles als korrekt an.

Selbstprüfung ist akzeptabel für: Aufgaben der leichten Stufe; oder kleine Änderungen, deren Kriterien ein einzelner Befehl mit offensichtlichem Ergebnis entscheidet.

Verwendung des Prüfers

Der Wert des Prüfers liegt in seiner Unabhängigkeit: Er darf die Argumentation oder Selbstrechtfertigung des Implementierers nicht erben.

  • Gib ihm: Die Anforderungsbasislinie, die Abschlusskriterien dieser Ebene, die relevanten Dateipfade, wie Dinge ausgeführt werden, und den Änderungsbereich (git diff oder einen Commit-Bereich). Der Änderungsbereich ist eine Tatsache, keine Argumentation, und hilft dem Prüfer, Stellen zu finden, die sich hätten ändern sollen, es aber nicht getan haben.
  • Gib ihm nicht: Deine Implementierungsargumentation, deine Kompromissrechtfertigungen oder irgendetwas wie „ich denke, es ist jetzt in Ordnung“.
  • Berechtigungen: Er darf Quelle, Konfiguration oder Dokumentation nicht ändern. Er darf lokale Verifikationsbefehle (Tests, Builds, Linter) ausführen, und die resultierenden Build-Artefakte sind in Ordnung. Befehle mit externen Nebenwirkungen sind verboten – Bereitstellen, Datenmigration, git commit / git push, Datenlöschen, Aufrufen von Produktions- oder kostenpflichtigen APIs.
  • Verlange, dass er jedes Kriterium wirklich überprüft (den Befehl ausführt, den Code liest, die Ausgabe inspiziert) und pro Punkt bestanden / nicht bestanden / kann nicht verifiziert werden mit Nachweisen meldet, plus alle Probleme, die er außerhalb der Kriterien gefunden hat, geordnet nach Schweregrad.
  • Korrekturen sind deine Sache, damit der Prüfer und der Implementierer nicht wieder dieselbe Person werden.
  • Wenn die Implementierung von einem CLI-Codierungsagenten (omp / codex / claude-code) durchgeführt wurde, verifiziere gemäß dem Verifikationsabschnitt des omp-Skills: Lies das erstellte Diff, suche speziell nach Bedingungszweigen, die nur den Happy Path abdecken, führe die kleinste Teilmenge unabhängig mit --filter aus und sende Nacharbeit als „Datei:Zeile + bestanden/nicht bestanden Kriterium + erwartete Behauptung“ zurück.
  • Prompt-Vorlagen befinden sich im Abschnitt „Prüfer-Subagent“ von references/subagent-prompts.md.

Wenn die aktuelle Umgebung keine Subagent-Fähigkeit hat oder Benutzer- oder Hostregeln Subagenten verbieten: Übernimm selbst die Rolle des Prüfers, überprüfe jedes Kriterium anhand derselben Vorlage und schreibe die Nachweise aus, anstatt Kästchen aus dem Gedächtnis abzuhaken.

Umgang mit Verifikationsergebnissen

  • Nicht bestandene Kriterien: Beheben, dann erneut verifizieren (mit demselben Prüfer fortfahren oder einen neuen beauftragen).
  • Du glaubst, der Prüfer liegt falsch: Du musst Gegenbeweise (einen Befehl und seine Ausgabe, eine Datei:Zeile) liefern, um das Urteil zu widerlegen, und im Bericht angeben, welches Urteil du widerrufen hast und auf welcher Grundlage. Rede dich nicht durch reines Argumentieren heraus.
  • Außerhalb der Kriterien gefundene Probleme: Nur „schwere“ – Verfehlung der Anforderungsbasislinie, falsche Daten, Abstürze, Sicherheitsprobleme – blockieren die nächste Ebene. Halte den Rest fest und liste ihn im Bericht auf oder verschiebe ihn in Vorschläge außerhalb des Umfangs.

Nachweisregeln

  • Alles, was nicht tatsächlich ausgeführt oder inspiziert wurde, darf nicht als „erledigt“ oder „bestanden“ bezeichnet werden. Die einzig zulässige Formulierung ist „implementiert, nicht verifiziert“.
  • Das Bestehen lokaler Tests ist keine Benutzerabnahme. Das Bestehen von Unit-Tests ist kein funktionierendes Feature. Gib die Ebene an, die du tatsächlich verifiziert hast.

4. Abschlussbericht

Standardstufe, ein Bericht nach Abschluss aller Ebenen:

**Abschluss**: <jeder Punkt der Anforderungsbasislinie, der Reihe nach behandelt>
**Verifikationsnachweise**: <was ausgeführt wurde und was es zurückgegeben hat; welche Punkte ein Prüfer überprüft hat; welche Verifikationsurteile du widerrufen hast und auf welcher Grundlage>
**Nicht verifiziert / bekannte Einschränkungen**: <nicht ausgeführte Pfade, bekannte Lücken>
**Selbst getroffene Annahmen**: <nur im autonomen Modus: was du selbst entschieden hast, welche irreversiblen Operationen du übersprungen hast>
**Kritikergebnis**: <welche Kritiken die Schlüsselentscheidungen erhalten haben, welche akzeptiert und welche abgelehnt wurden, und warum>
**Vorschläge außerhalb des Umfangs**: <Vorschläge aus §6, die die Entscheidung des Benutzers erfordern, mit Wert und Kosten>
**Neue / aktualisierte Fallen**: <Titel der geschriebenen Einträge>

Die Zeile „Nicht verifiziert / bekannte Einschränkungen“ ist obligatorisch; wenn es tatsächlich keine gibt, schreibe „keine“ und erkläre, warum du dir sicher bist. Die anderen Zeilen können weggelassen werden, wenn sie leer sind.

Leichte Stufe, die Kurzform:

**Was gemacht wurde**: <ein oder zwei Sätze>
**Wie es verifiziert wurde**: <Befehl + Ergebnis>
**Bekannte Einschränkungen**: <nur falls vorhanden>

Der Bericht gibt nur Tatsachen und Nachweise an. Keine Selbsteinschätzung wie „perfekt implementiert“, „sehr elegant“, „massive Verbesserung“.

Worüber sich Benutzer bei langen Projekten am meisten beschweren, ist der Black-Box-Fortschritt: Wenn nur dieses Inkrement gemeldet wird, können sie nicht beurteilen, wo das Ganze steht. Liefere regelmäßig – oder auf Anfrage – eine Panorama von Null bis Jetzt: Stufen-Zeitplan und jede Stufe mit ihrem Status, noch nicht begonnene Stufen und erwartete Abhängigkeiten, aktueller Pfad zum nächsten Meilenstein und dessen verbleibende Ebenenannahme, offene Entscheidungen und ausstehende Prüfungen, eine Liste entweder über die Gesamtlaufzeit oder die verbleibende Zeit.

Der Panorama-Absatz ist für das menschliche Gefühl gedacht; KI-Agenten können ihn auch ohne besondere Aufforderung geben.

5. Adversarial Review / Selbstwiderlegung

Wann immer du eine Schlüsselentscheidung triffst – eine Architektur, einen Algorithmus, eine Bibliothek, eine Aufteilung wählst, einen Kompromiss eingehst – wende eine dieser Methoden an, BEVOR du sie als final festlegst. Eine Schlüsselentscheidung ist eine, deren Rückgängigmachung teuer ist, sobald darauf aufgebaut wurde. Wende keine der Methoden auf triviale Unterpunkte an, die leicht geändert werden können.

Eine der beiden Methoden muss angewendet werden; wähle diejenige, die für den Kontext besser geeignet ist:

Methode A: Führe (oder simuliere) eine Adversarial Review durch

Formuliere ein Gegenargument. Schreibe es im Format „A, aber {B}“:

  • Position: <ein Satz, der die Entscheidung klar angibt und den erwarteten Vorteil erwähnt>
  • Angriff 1 … N: <glaubwürdige Argumente dagegen. Für jeden: Kosten, Risiken, Szenarien, in denen diese Entscheidung schlecht abschneidet. Wenn dir kein glaubwürdiges Argument einfällt, erwäge, dass du in deiner eigenen Position verfangen bist – suche eine externe Perspektive oder frage den Benutzer nach einem Gegenvorschlag>
  • Verteidigung: <der Grund, warum diese Entscheidung trotz der Angriffe die beste verfügbare ist. Gebe für jeden Angriff an, ob er akzeptiert oder zurückgewiesen wird. Wenn er zurückgewiesen wird, auf welcher Grundlage? Wenn er akzeptiert wird, welche konkrete Absicherung wird in den Plan aufgenommen? Gegenmaßnahmen sind keine vollständige Akzeptanz eines Risikos. Ein akzeptiertes Risiko ohne Gegenmaßnahme ist ein akzeptiertes Risiko. Benenne es als solches.>

Methode B: Schreibe einen Selbstwiderlegungstext

Ein Text, der die entgegengesetzte Entscheidung bewusst vertritt. Wenn er die Arbeit wert ist, bedeutet das, dass deine ursprüngliche Entscheidung möglicherweise falsch ist; wiederhole die Analyse. Wenn er offensichtlich dumm ist, hast du deine Bestätigung.

Kommuniziere das Ergebnis

Nachdem die Entscheidung getroffen ist, gib sie im Bericht bekannt (siehe §4).

6. Proaktive Ausführung

Die Aufgabe definiert die Grenzen. Alles innerhalb der Grenzen zu tun, reicht aus. Wenn du jedoch während der Arbeit auf ein Problem stößt – eine Randbedingung, die der Benutzer nicht bedacht hat, eine Angrenzung, die umgestaltet werden muss, oder eine Funktion, die den Wert der Aufgabe erheblich steigert, ohne den Kern zu gefährden – dokumentiere es und schlage es im Bericht vor. Ändere den Umfang nicht stillschweigend.

Schiebe die Funktionen nicht gewaltsam in den Umfang. Ein Vorschlag ist ein Satz oder ein Absatz, der das Was, den Wert und die geschätzten Kosten beschreibt. Lasse den Benutzer entscheiden.

7. Fallenprotokollierung

Wann protokolliert wird

Jedes Mal, wenn du eine Falle behebst – einen Fehler, der dich Zeit gekostet hat, eine falsche Annahme, ein wiederkehrendes Problem – protokolliere es sofort. Protokolliere es für nächstes Mal, nicht für dieses Mal. Wenn es gelöst ist, protokolliere es, während die Details noch frisch sind. Der Benutzer kann auch sagen: „Protokolliere das als Falle.“

Das Schreiben des Eintrags ist Teil der "erledigt"-Definition der Aufgabe; es ist optional, es separat zu erwähnen.

Umfang des Protokolls

Das Projektprotokoll (PITFALLS.md) erfasst Probleme, die für das spezifische Projekt relevant sind. Das maschinenweite Protokoll (~/.agents/PITFALLS.local.md) erfasst Probleme, die für diesen Agenten, dieses Betriebssystem, dieses Terminal oder diesen Stack gelten (z. B. „Cline zerstört die Zeilenenden der .env-Datei“, „Codex verliert die Bearbeitungen der requirements.txt“).

Eintragsformat

Ein Eintrag ist eine kurze Aufzählung von 3–5 Zeilen:

## <Title of the pitfall (descriptive)>
- **Symptom**: …
- **Root cause**: …
- **Fix**: …
- **How to catch early next time**: …
  • Titel – 4–8 Wörter, die das Problem beschreiben (z. B. „Layout bricht bei langen Benutzernamen um“, „Babel-Konfiguration von ESLint nicht gefunden“).
  • Symptom – was schiefgelaufen ist und wie es sich geäußert hat (eine Zeile).
  • Ursache – die Grundursache, nicht die Oberfläche (eine Zeile).
  • Behebung – was zur Lösung getan wurde (eine Zeile).
  • Früherkennung – was in Zukunft beachtet werden kann, um es zu vermeiden (eine Zeile).

Wenn du die Grundursache nicht ermitteln konntest, schreibe stattdessen den Workaround und kennzeichne ihn als Workaround.

Verwandte Skills