Jede Unklarheit in deiner Spezifikation
ist ein Token, den dein Agent verbrennt.

Was ohne sie schiefgeht.

• 🌀 Spezifikationen driften ab.

  Die Spezifikation im Dokument, der Thread in Slack und der Code im PR weichen wochenlang stillschweigend voneinander ab. Niemand weiß, welche Version des Gesprächs kanonisch ist.

  Die Lösung

  Eine einzige kanonische Spezifikation im Repository, versioniert zusammen mit dem Code. specscore lint läuft in der CI bei jedem Push; die Git-Historie ist der Prüfpfad. Spezifikation, Thread und PR können nicht unbemerkt voneinander abweichen – sie teilen sich dieselbe geprüfte Datei.

• 🌫️ AC bleiben vage.

  „Fehler elegant behandeln“ sollte eigentlich heißen:„Toast anzeigen und zurückrollen.“ Oder war es„loggen und wiederholen“? Der Agent muss raten.

  Die Lösung

  Der Linter fängt mehrdeutige Kriterien ab, bevor auch nur eine Zeile Code geschrieben wird. Das Verb fällt durch das Linting, weil ihm ein konkretes Objekt oder eine Bedingung fehlt. Die Warnung zu beheben zwingt dich aufzuschreiben, was „behandeln“tatsächlich bedeutet.

• 🤖 Agenten liefern das Falsche.

  Menschen interpolieren, fragen nach, klären auf. KI-Agenten nicht – sie implementieren das Muster, das in ihren Trainingsdaten am häufigsten vorkam. Der Code besteht das Review, weil er irgendetwas Sinnvolles tut. Nur eben nicht das, was du meintest.

  Die Lösung

  Strukturierte Eingabe. KI-Agenten parsen REQ-IDs, AC-IDs und GIVEN / WHEN / THEN-Szenarien deterministisch – es gibt nichts zu interpolieren. Jeder Plan muss die AC-IDs nennen, die jede Aufgabe erfüllt, sodass das Gebaute immer gegen das Spezifizierte überprüfbar bleibt.

• 🔁 Du zahlst doppelt für eine vage Spezifikation.

  Der Agent baut etwas anhand eines mehrdeutigen Briefings, du bemerkst den Fehler und promptest ihn erneut – auf vier verschiedene Arten. Jedes halbfertige Feature und jeder Neuversuch kostet Tokens. Je vager die Spezifikation, desto mehr Runden vergehen bis zum Ziel.

  Die Lösung

  Linte die Spezifikation, bevor der Agent startet.specscore lint weist vage Verben und fehlende Akzeptanzkriterien von vornherein ab, sodass der Agent ein konkretes Briefing einmal umsetzt, anstatt über mehrere Schleifen hinweg zu raten. Der günstigste Agenten-Durchlauf ist der, den du nicht wiederholen musst.

• 💸 Agenten zahlen dafür, deine Spezifikationen neu zu lesen.

  Ein KI-Agent, der beantworten soll: „Was hängt von diesem Feature ab?“, liest das gesamte README des Features. Dann jeden übergeordneten Index. Dann geschwisterliche Features zur Sicherheit. Jede Abfrage ist ein neuer Parsing-Vorgang. Tokens verpuffen; die Latenz steigt; und die Rechnung steigt mit.

  Die Lösung

  Strukturierte Abfragen statt Datei-Lesen.specscore feature tree liefert die Hierarchie als YAML; feature deps durchläuft die transitive Abhängigkeitskette; feature info liefert Status, Owner und offene Fragen – jeweils in einem einzigen Aufruf. Der Agent navigiert den Graphen, nicht die Prosa.

• 🔗 Code vergisst seine Spezifikation.

  Sechs Monate später debuggst du eine Funktion und niemand erinnert sich mehr, welches Feature sie implementiert. Die Verknüpfung zwischen Code und Spezifikation lebte in jemandes Kopf – und diese Person ist längst weg. Der PR, der sie einführte, liegt tief im Archiv.

  Die Lösung

  Quellcode-Annotationen. Kommentare wie// specscore: features/checkout/apply-discount/R1.AC-2machen die Verknüpfung maschinenlesbar und überstehen jedes Refactoring. specscore code deps beantwortet„Welche Spezifikation implementiert diese Datei?“ in einem einzigen Aufruf; der Linter markiert Referenzen auf gelöschte Spezifikationen.

• 🏷️ Statusänderungen laufen auseinander.

  Du änderst ein Feature in seinem README von Draftauf Approved, aber der übergeordnete features-index führt es weiterhin als Draft. Drei Wochen später liest ein Agent den Index und glaubt, es sei noch im Review. Der Status lebt an zwei Stellen – und sie widersprechen sich.

  Die Lösung

  specscore feature change-status schreibt das Status-Feld des Features um und synchronisiert die Zeile im features-index in einem atomaren Schritt neu – schlägt der Lint fehl, wird die Änderung rückgängig gemacht. Der Status existiert an einem einzigen kanonischen Ort; der Index ist eine daraus generierte Ansicht.

• 📋 Spezifikationen vergessen, was sie nicht wissen.

  Eine Spezifikation liest sich, als sei alles geklärt – bis dir einfällt, dass die Frage „Und was ist mit Zeitzonen?“vor zwei Monaten in einem Slack-Thread unterging und nie im Dokument landete. Jetzt bist du mitten in der Implementierung und niemand kennt die Antwort.

  Die Lösung

  Jedes SpecScore-Feature hat einen PflichtabschnittOutstanding Questions. Der Linter lehnt Features ab, die ihn auslassen – leer ist in Ordnung ("None at this time."), aber fehlend nicht. Ungelöste Fragen stehen sichtbar im Dokument, sind per CLI abfragbar und können nicht vergessen werden.