Wer Requirements als .req.md-Dateien pflegt (siehe
Requirements), lässt ein KI-Coding-Tool
diesen Corpus über zehn MCP-Tools bearbeiten, statt die Dateien selbst zu
parsen. Warum das überhaupt erstrebenswert ist: ein Agent, der eine Methode
ändert, kann vorher fragen, welche Zusage an ihr hängt, und hinterher
berichten, welche Pins seine Änderung berührt hat. Ohne diesen Zugang
verlässt sich derselbe Agent auf das, was zufällig im Kontextfenster steht.
Die zehn Tools zerfallen in vier Gruppen.
Lesen. req_context, req_search und req_justify beantworten Fragen
über den Corpus und den Codegraphen, ohne etwas zu verändern.
Prüfen. req_affected übersetzt einen Diff in die Menge der berührten
Requirements, und req_verify projiziert das Ergebnis pro Criterion aus
demselben Evaluator, den auch die CLI verwendet.
Messen. req_coverage meldet die bidirektionale Traceability-Coverage
über den ganzen Corpus.
Entwerfen und binden. req_draft, req_bind und
req_request_acceptance schlagen Text zur menschlichen Prüfung vor.
req_acknowledge steht daneben als die eine geführte Ausnahme-Mutation.
Keines der zehn kann ein Requirement annehmen. Das bleibt ein menschlicher
Akt auf der Kommandozeile über codecharter req.
Warum die Annahme nie über MCP läuft
Ein angenommenes Requirement ist die Behauptung, dass der Code tatsächlich
tut, was das Requirement beschreibt. Das ist eine Wertung, die das
Corpus-Format bewusst über einen Menschen leitet, und keine Schlussfolgerung,
die ein Agent an seiner Stelle treffen darf. Die drei Abfrage-Tools unten
berichten deshalb nur, was Corpus und Codegraph bereits sagen, und die drei
Autoren-Tools schlagen ausschließlich Text zur menschlichen Prüfung vor. Von
der einen geführten Mutation in req_acknowledge
abgesehen hat die eigentliche Annahme-Entscheidung, und jedes Pin-Feld, das
sie erzeugt, bewusst kein MCP-Tool.
req_context
Alles Relevante zu einem Code-Symbol oder einer Datei in einem Aufruf: die
direkt verankerten Requirements, dazu was sie transitiv rechtfertigt (über
den vom [Satisfies]-Anchor erreichbaren Aufrufgraphen), was sie verfeinert,
und was sich mit ihr überschneidet (andere Requirements mit einem
gemeinsamen rechtfertigenden Methoden-Footprint, nützlich für gemeinsame
Retrieval-Anfragen).
target löst genauso auf wie bei den Graph-Tools: ein exakter oder
groß-/kleinschreibungsunabhängiger vollständiger Typ-/Methodenname, ein
Namenssuffix oder ein Quelldateipfad. Ein mehrdeutiges oder nicht aufgelöstes
Target liefert eine Kandidatenliste statt zu raten. include wählt aus,
welche der vier Beziehungs-Sektionen berechnet werden (anchored,
justified, refines, overlaps – standardmäßig alle vier), und prose
steuert, wie viel vom Fließtext jedes Requirements mitkommt (none, summary
oder full).
Ein Requirement, das über mehr als eine Beziehung erreicht wird, behält nur seine stärkste – ein direkter Anchor schlägt eine transitive Rechtfertigung, die schlägt eine Refines-Kante, die schlägt eine Überschneidung – sodass dieselbe Id nie mit schwächerer Evidenz beschriftet erscheint, als tatsächlich gefunden wurde.
req_search
Requirements finden nach id, status, kind, priority, dem
contractual-Flag, section oder einem Freitext-query über Id, Titel und
Fließtext. Ergebnisse werden nach Treffstärke sortiert (zuerst ein
Id-Treffer, dann Titel, dann Fließtext) und innerhalb einer Stufe nach Id, so
dass derselbe Corpus in jeder Eingabereihenfolge dieselbe Ergebnisreihenfolge
liefert.
req_justify
Das Gegenstück zu req_context: ausgehend von einem Code-Symbol oder einer
Datei zurück zu den Requirement-Wurzeln laufen, die dessen Existenz
rechtfertigen. Das outcome des Ergebnisses ist einer von drei Zuständen:
justified– mindestens ein[Satisfies]-Anchor eines Requirements erreicht das Target über den Aufrufgraphen.not_justified– das Target wurde zu echtem, analysierbarem Code aufgelöst, und die Suche fand tatsächlich nichts.unknown– alles andere: kein Code-Modell verfügbar, oder ein Target, das nicht zu einer analysierbaren Deklaration aufgelöst wurde.
Fehlende Evidenz wird nie als not_justified dargestellt. Diese
Unterscheidung ist entscheidend: Ein Tool, das "nichts rechtfertigt das"
nicht von "ich konnte es nicht prüfen" unterscheiden kann, würde euch
darauf trainieren, seinen not_justified-Ergebnissen zu misstrauen.
witness steuert, wie viel rechtfertigende Evidenz zusätzlich zum Ergebnis
mitkommt: none, roots (die [Satisfies]-Anchor-Stellen des rechtfertigenden
Requirements, als Mengenzugehörigkeit beschriftet – Standard) oder paths
(optional, eine token-begrenzte Breitensuche nach einem tatsächlichen
Aufrufpfad von einem Anchor zum Target, deterministisch und auf eine feste
Sprunggrenze gedeckelt – ein null-Pfad bedeutet, dass innerhalb der Grenze
keiner gefunden wurde, nicht dass keiner existiert).
Rule-Criteria werden von den Abfrage-Tools nie ausgewertet
Die rule:-Criteria eines Requirements – die gegen den Graphen eurer
Solution geprüft werden – werden von den Abfrage-Tools bewusst nie
ausgewertet. Von den dreien meldet nur req_context überhaupt einen
Criteria-Zustand, und es wertet dabei ausschließlich die pin-abgeleiteten
Criteria aus (test, manual, integration, external); req_search und
req_justify melden keinen Criteria-Zustand, der auszuwerten wäre. Ein
Requirement mit einem rule:-Criterion kommt weiterhin aus req_context
zurück, mit diesem Criterion markiert als hier nicht ausgewertet, statt es
still wegzulassen oder zu raten. Für das tatsächliche Ergebnis
codecharter req check, die
analyze/analyze_diff-MCP-Tools, req_verify (unten) oder req_coverage
ausführen – siehe Rule-Criteria.
req_affected
Das Requirement-Gegenstück zu analyze_diff: welche Requirements ein Diff
berührt, und welcher Criteria Pins dadurch ungültig geworden sein könnten.
Der Abgleich erfolgt auf Dateiebene – die eigene .req.md-Datei eines
Requirements hat sich geändert, oder die Datei eines file+selector-Anchors
– und jedes getroffene Criterion meldet ein pinImpact-Signal
(rule-input-changed, fingerprint-suspect, test-hash-suspect, none
oder unknown-analysis-unavailable, wenn kein Code-Modell verfügbar war).
pinImpact ist nie ein Ergebnis, und es ist nie none ohne Modell – es
sagt "dieser Diff hat eine Eingabe geändert, von der der Pin abhängt", nicht
"der Pin ist jetzt veraltet". Dieses Ergebnis liefert req_verify. Werden
diff/git_ref/files weggelassen, gilt standardmäßig der Arbeitsbaum
gegen HEAD – derselbe Standard wie bei req_verify.
req_verify
Das Ergebnis pro Acceptance-Criterion – holds, violated, unknown,
stale oder open – mit Begründungen, DSL-Verstößen und nicht
quittierten Kanten. req_verify berechnet selbst nichts: Es ist eine dünne
Projektion desselben zusammengeführten Evaluators, den
codecharter req check --with-code zusammensetzt, sodass sich ein Ergebnis
zwischen CLI und diesem Tool konstruktionsbedingt nie unterscheidet. Kein
über req_verify erreichbarer Verb kann ein Criterion als erfüllt markieren;
grün wird ein Criterion nur, wenn der Evaluator es tatsächlich bestätigt.
scope ist standardmäßig diff – die Requirements, die req_affected für
dieselben diff/git_ref-Eingaben melden würde – oder all für den
gesamten Corpus. req_id (eine Id oder eine kommagetrennte Liste) hat
Vorrang vor scope, wenn angegeben.
req_acknowledge
Die eine geführte Ausnahme von "kein MCP-Tool verändert den Corpus":
festhalten, dass eine bestimmte unbekannte Kante in der Auswertung eines
rule:-Criteriums – nicht ein Requirement, nicht ein Criterion, eine
einzelne benannte Kante – verstanden und akzeptiert ist, statt eine Lücke zu
sein, die das Ergebnis weiter blockieren sollte. Eine Kante ist etwas, das
RuleCriterionEvaluator nicht eindeutig
auflösen konnte (ein nicht erkannter Reflection-Aufruf, eine Divergenz
zwischen Dispatch und deklariertem Aufruf und Ähnliches); req_verify meldet
jede noch offene als unacknowledgedEdges am blockierten Criterion.
Das ist bewusst keine Requirement-Annahme. Eine Kante zu quittieren kann
immer nur eine einzelne, benannte Analyselücke aus der Blockade eines
Ergebnisses entfernen, das der Evaluator bei jedem Aufruf weiterhin frisch
berechnet – es kann niemals ein violated-Ergebnis in holds verwandeln,
und es kann niemals die Pin-Felder anfassen, die
codecharter req accept besitzt. Es gibt zwei Stufen von
Kanten, und nur eine davon ist quittierbar:
- Stufe B (
pattern-matches-no-type,dispatch-divergence,opaque-site) – eine echte Analyselücke in einer sonst erfolgreichen Auswertung. Ein Mensch kann diese wissentlich akzeptieren, undreq_acknowledgelässt das zu. - Stufe A (Analyse nicht verfügbar, Criterion nicht kompilierbar,
Schema-Mismatch, ungebundener Parameter, Auswertungsfehler, unentschiedene
Pfadsuche) – ein Defekt im Criterion oder im Lauf selbst, nichts am Code,
das man akzeptieren könnte.
req_acknowledgeverweigert diese bedingungslos, unabhängig davon, was der Aufrufer angibt.
req_acknowledge verweigert außerdem eine Kante, die am Criterion aktuell
nicht auftritt, ein Criterion, das kein rule:-Criterion ist (nur
Rule-Criteria tragen quittierbare Kanten), und einen Aufruf ohne reason
– eine Quittierung ohne Begründung wird als nicht vorhanden gemeldet, exakt
so, als wäre sie nie geschrieben worden. Eine veraltete Quittierung (die
benannte Kanten-Id tritt wegen einer Codeänderung nicht mehr auf) ist rein
berichtend, sichtbar über req_verify, hier nie neu geschrieben.
dry_run ist standardmäßig true: Das Tool liefert den unified Diff genau
der Änderung, die es vornehmen würde – ein Eintrag wird an die
acknowledge:-Sequenz des Criteriums angehängt, jede andere Zeile der Datei
bytegenau erhalten – ohne etwas zu schreiben. dry_run=false übergeben,
sobald der Diff passt.
req_draft
Entwirft eine neue .req.md-Datei: Frontmatter, Criteria-Vorschläge als
rule, test, manual, integration oder external, sowie
Anchor-Vorschläge. Der zusammengesetzte Entwurf wird über denselben Parser
selbst validiert, den codecharter req check verwendet,
bevor er überhaupt geschrieben wird, und jede Diagnose kommt im Ergebnis des
Tools zurück, statt erst später auf der Platte sichtbar zu werden.
write ist standardmäßig false: Das Tool liefert immer das
zusammengesetzte Skelett zur menschlichen Prüfung, bevor irgendetwas die
Platte berührt. write=true übergeben, sobald es passt. req_draft legt nie
still ein Requirement an und überschreibt nie eine bestehende – löst sich
req_id bereits auf eine vorhandene Datei auf, verweigert das Tool; eine
andere Id zu wählen oder die bestehende Datei zu bearbeiten, ist eine
menschliche Entscheidung, kein Parameter, den dieses Tool anbietet.
req_bind
Fügt einem bestehenden Requirement ein Criterion oder einen Anchor hinzu, oder
aktualisiert bei einem bestehenden Criterion den Carrier-Wert, status oder
die confidence-Übersteuerung.
Jedes neue Criterion oder jeder neue Anchor wird standardmäßig mit
unverified vorgeschlagen – req_bind nimmt nie an, dass ein Carrier
korrekt ist, nur weil er benannt wurde. Wird verify_target=true übergeben,
löst das Tool das Target eines test-Carriers gegen das Code-Modell auf,
bevor es geschrieben wird (andere Carrier-Arten und Anchor-Targets kommen
immer als unverified zurück, da das Tool keine Möglichkeit hat zu
bestätigen, dass sie tatsächlich das bezeichnen, was sie angeben).
req_bind verweigert es rundweg, die Carrier-Art eines bestehenden
Criteriums zu wechseln – das ist eine Neuentwurfs-Entscheidung, keine
Bearbeitung – und es kann nie ein Pin-Feld schreiben: dieselben Felder, die
codecharter req accept besitzt, bleiben mechanisch
tabu, genau wie bei req_acknowledge. dry_run liefert eine Diff-Vorschau
der exakten Änderung, ohne sie zu schreiben.
req_request_acceptance
Markiert ein Criterion als bereit für die menschliche Freigabe: schreibt
einen requested_by-, requested_on- und optionalen note-Marker – nie ein
Pin-Feld – und liefert eine lesefertige Frage zurück, dazu den exakten
codecharter req accept-Befehl, mit dem ein Mensch das
Requirement tatsächlich annimmt. Der Marker hält nur fest, dass jemand
gefragt hat; er trägt keine eigene Autorität und ändert das Ergebnis keines
Criteriums. dry_run=true zeigt denselben Marker als Vorschau, ohne ihn zu
schreiben.
req_coverage
Requirement-Corpus-Coverage in beiden Richtungen, das vollständige
Modell steht unter Requirements-Coverage,
die CLI-Oberfläche über denselben Aggregator unter
codecharter req coverage (beide laufen
nie auseinander: ein gemeinsamer IReqCoverageAggregator, zwei Renderer).
Pro Requirement ein Rollup (Requirement → Code), dazu jede Code-Methode
klassifiziert als justified, infrastructure-declared, dead-candidate
oder undocumented-requirement-candidate (Code → Requirement), Letzteres
mit einem nearestAnchoredNeighbour-Hinweis, der req_draft speist.
Anders als jedes andere Tool auf dieser Seite hat req_coverage kein
with_code-artiges Opt-out: Code ist der eigentliche Gegenstand des Tools,
deshalb wird die Solution immer analysiert, und ein nicht ermittelbares
Modell kommt als isInconclusive: true mit einem Hinweis zurück, nie als
erfundene Prozentzahl. git_ref/diff schränken nur die
klassifizierten/Rollup-Listen ein; jede Summe und jeder Prozentwert
(justifiedPercent, accountedPercent) bleibt corpus-weit, dasselbe
scope-Muster, das graph_hubs verwendet. req_coverage ist über MCP rein
lesend: Es schreibt nie die Tolerated-Legacy-Baseline (--write-baseline
ist eine reine CLI-Operation mit Schreibzugriff, bewusst nicht Teil dieses
lesenden Tools) und erzwingt nie das Ratchet-Gate, das bleibt eine
CI-seitige Entscheidung hinter req.coverage.gate.enabled in
.codecharter/config.yml.
Token-Budgets
Die sechs Abfrage-, Verifikations- und Coverage-Tools – req_context,
req_search, req_justify, req_affected, req_verify und req_coverage
– akzeptieren max_tokens und melden estimatedTokens, passend zum
Kürzungsvertrag der Graph-Tools: Ein Ergebnis, das das Budget überschreiten
würde, wird gekürzt (mit einem Hinweis, was aus welchem Grund entfernt
wurde), statt es still überdimensioniert zurückzugeben.
max_reqs/max_results begrenzt die Anzahl unabhängig vom Token-Budget.
req_acknowledge hat kein max_tokens-Argument – der Diff einer einzelnen
Kante ist immer klein genug, um vollständig zurückzukommen. Die drei
Autoren-Tools – req_draft, req_bind und req_request_acceptance –
nehmen ebenfalls kein max_tokens: Ein zusammengesetztes Skelett, die
Diff-Vorschau einer Bindung oder ein Marker für eine Annahme-Anfrage ist
immer klein genug, um vollständig zurückzukommen.