Anforderungen über MCP

Wer Anforderungen als .req.md-Dateien pflegt (siehe Anforderungen), lässt ein KI-Coding-Tool diesen Corpus direkt über zehn MCP-Tools bearbeiten, statt die Dateien selbst zu parsen: drei rein lesende Abfrage-Tools — req_context, req_search und req_justify —, req_affected und req_verify, die einen Diff und die Pin-Auswertungs-Engine in agentennutzbare Antworten übersetzen, req_acknowledge, die eine geführte Ausnahme-Mutation, req_coverage, das die bidirektionale Traceability-Coverage über den ganzen Corpus meldet, sowie drei Autoren-Tools — req_draft, req_bind und req_request_acceptance —, mit denen ein Agent eine neue Anforderung entwerfen, Kriterien und Anker an Code binden und Arbeit zur menschlichen Prüfung markieren kann. Keines der zehn kann eine Anforderung annehmen. Das bleibt ein menschlicher Akt auf der Kommandozeile über codecharter req; ein Agent kann eine Änderung in den dahinterstehenden Anforderungen verankern, fragen, ob die vom Menschen bereits angenommenen Kriterien noch gelten, messen, wie viel der Codebase gerechtfertigt ist, einen Entwurf oder eine Bindung zur menschlichen Prüfung vorschlagen, oder eine geführte Freigabe für eine einzelne Analyselücke festhalten — aber er kann nicht entscheiden, dass eine Anforderung erfüllt ist.

Warum die Annahme nie über MCP läuft

Eine angenommene Anforderung ist die Behauptung, dass der Code tatsächlich tut, was die Anforderung beschreibt — eine Wertung, die das Corpus-Format bewusst über einen Menschen leitet, 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 unten 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 Anforderungen, dazu was sie transitiv rechtfertigt (über den vom [Satisfies]-Anker erreichbaren Aufrufgraphen), was sie verfeinert, und was sich mit ihr überschneidet (andere Anforderungen 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 jeder Anforderung mitkommt (none, summary oder full).

Eine Anforderung, die über mehr als eine Beziehung erreicht wird, behält nur ihre stärkste — ein direkter Anker 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

Anforderungen 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 Anforderungswurzeln laufen, die dessen Existenz rechtfertigen. Das outcome des Ergebnisses ist einer von drei Zuständen:

• justified — mindestens ein [Satisfies]-Anker einer Anforderung 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 Sie darauf trainieren, seinen not_justified-Ergebnissen zu misstrauen.

witness steuert, wie viel rechtfertigende Evidenz zusätzlich zum Ergebnis mitkommt: none, roots (die [Satisfies]-Ankerstellen der rechtfertigenden Anforderung, als Mengenzugehörigkeit beschriftet — Standard) oder paths (optional, eine token-begrenzte Breitensuche nach einem tatsächlichen Aufrufpfad von einem Anker zum Target, deterministisch und auf eine feste Sprunggrenze gedeckelt — ein null-Pfad bedeutet, dass innerhalb der Grenze keiner gefunden wurde, nicht dass keiner existiert).

Regel-Kriterien werden von den Abfrage-Tools nie ausgewertet

Die rule:-Kriterien einer Anforderung — die gegen den Graphen Ihrer Solution geprüft werden — werden von den Abfrage-Tools bewusst nie ausgewertet. Von den dreien meldet nur req_context überhaupt einen Kriterienzustand, und es wertet dabei ausschließlich die pin-abgeleiteten Kriterien aus (test, manual, integration, external); req_search und req_justify melden keinen Kriterienzustand, der auszuwerten wäre. Eine Anforderung mit einem rule:-Kriterium kommt weiterhin aus req_context zurück, mit diesem Kriterium 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 Regel-Kriterien.

req_affected

Das Anforderungs-Gegenstück zu analyze_diff: welche Anforderungen ein Diff berührt, und welcher Kriterien Pins dadurch ungültig geworden sein könnten. Der Abgleich erfolgt auf Dateiebene — die eigene .req.md-Datei einer Anforderung hat sich geändert, oder die Datei eines file+selector-Ankers — und jedes getroffene Kriterium meldet ein pin_impact-Signal (rule-input-changed, fingerprint-suspect, test-hash-suspect, none oder unknown-analysis-unavailable, wenn kein Code-Modell verfügbar war). pin_impact 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 Akzeptanzkriterium — 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 Kriterium als erfüllt markieren; grün wird ein Kriterium nur, wenn der Evaluator es tatsächlich bestätigt.

scope ist standardmäßig diff — die Anforderungen, 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:-Kriteriums — nicht eine Anforderung, nicht ein Kriterium, 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 unacknowledged_edges am blockierten Kriterium.

Das ist bewusst keine Anforderungsannahme. 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, und req_acknowledge lässt das zu.
• Stufe A (Analyse nicht verfügbar, Kriterium nicht kompilierbar, Schema-Mismatch, ungebundener Parameter, Auswertungsfehler, unentschiedene Pfadsuche) — ein Defekt im Kriterium oder im Lauf selbst, nichts am Code, das man akzeptieren könnte. req_acknowledge verweigert diese bedingungslos, unabhängig davon, was der Aufrufer angibt.

req_acknowledge verweigert außerdem eine Kante, die am Kriterium aktuell nicht auftritt, ein Kriterium, das kein rule:-Kriterium ist (nur Regel-Kriterien 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 Kriteriums 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, Kriterienvorschläge als rule, test, manual, integration oder external, sowie Ankervorschlä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 eine Anforderung 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 einer bestehenden Anforderung ein Kriterium oder einen Anker hinzu, oder aktualisiert bei einem bestehenden Kriterium den Carrier-Wert, status oder die confidence-Übersteuerung.

Jedes neue Kriterium oder jeder neue Anker 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 Anker-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 Kriteriums 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 Kriterium 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 die Anforderung 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 Kriteriums. 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 nearest_anchored_neighbour-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 is_inconclusive: 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 (justified_percent, accounted_percent) 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 sieben Abfrage-, Verifikations- und Coverage-Tools — req_context, req_search, req_justify, req_affected, req_verify, req_acknowledge 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.