Requirements

Mit CodeCharter verfolgt ihr Requirements direkt neben dem Code, der sie umsetzt. Jedes Requirement ist eine Markdown-Datei mit einem YAML-Frontmatter- Block unter .codecharter/req (die alte Ablage .codeguard/req wird weiterhin gelesen). Es gibt keine Datenbank und kein externes Werkzeug: der Requirement- Corpus besteht nur aus Dateien in eurem Repository, die sich wie jede andere Datei reviewen, diffen und mergen lassen.

Die .req.md-Datei

Eine Requirement-Datei besteht aus YAML-Frontmatter zwischen ----Markierungen, gefolgt von einem Markdown-Body:

---
id: REQ-1
title: Users can reset their password
priority: must
contractual: true
status: implemented
kind: functional
section: Account management
source: spec.md#3.2
relations:
  refines:
    - REQ-0
  conflicts:
    - REQ-9
criteria:
  - id: C1-1
    rule: some.dsl.expression()
    status: open
    blocked_by:
      - C1-2
    confidence: needs-predicate
  - id: C1-2
    test: Tests.Auth.PasswordReset_Should_SendEmail
anchors:
  - symbol_id: MyApp.Auth.PasswordResetService
---
Beschreibt das Requirement hier in Fließtext. Ganze Sätze, keine Stichpunkt-
Fragmente: das ist der Text, den ein Reviewer oder Auditor liest, um das
„Warum" zu verstehen.

## Out of Scope

Single-Sign-on-Provider sind von diesem Requirement nicht abgedeckt.

Alle Schlüssel sind snake_case. Werte-Token (priority, status, kind sowie die Criteria- und Anchor-Schlüssel unten) sind englisch und kebab-case, sodass sich eine Requirement-Datei unabhängig von der im Team gesprochenen Sprache immer gleich liest.

Frontmatter-Felder

Schlüssel	Pflicht	Wert	Bedeutung
id	ja	<Prefix>-<Nummer>, z. B. REQ-1	Stabiler Bezeichner. Wird von refines, conflicts und documents.yml referenziert.
title	ja	Freitext	Kurze, menschenlesbare Zusammenfassung.
priority	ja	must / should / could	MoSCoW-Priorität.
contractual	ja	true / false	Ob das Requirement Teil einer bindenden Vereinbarung ist (Vertrag, SLA) statt eines internen Ziels.
status	ja	open / in-progress / implemented / partial	Aktueller Lieferstatus.
kind	ja	functional / security / legal / performance / usability / infrastructure	Kategorie.
section	nein	Freitext	Wo das Requirement in einem Quell-Spezifikationsdokument steht.
source	nein	Freitext	Verweis auf diese Quelle, z. B. Datei- und Abschnittsangabe.
relations.refines	nein	Liste von Ids	Requirements, die dieses hier verfeinert oder spezialisiert.
relations.conflicts	nein	Liste von Ids	Requirements, zu denen dieses hier dokumentiert im Spannungsverhältnis steht.
criteria	nein	Liste	Siehe unten.
anchors	nein	Liste	Siehe unten.

Jeder Top-Level-Schlüssel außerhalb dieser Tabelle wird zurückgewiesen, aber nur mit einer Warnung, keinem Fehler: ein unbekannter Schlüssel stammt wahrscheinlicher aus einer neueren CodeCharter-Version als aus einem Tippfehler. codecharter req check meldet ihn trotzdem, damit er nicht unbemerkt bleibt.

Criteria

Ein Criterion ist eine Abnahmeprüfung für das Requirement. Jedes braucht eine id und genau einen von fünf Carrier-Schlüsseln, die festlegen, wie das Criterion verifiziert wird:

Carrier	Bedeutung
rule:	Ein CodeGuard-Regel-DSL-Ausdruck, der gelten muss.
test:	Ein konkreter automatisierter Test, der dieses Criterion prüft.
manual:	Ein Schritt, den ein Mensch verifiziert (z. B. in einem manuellen QA-Durchlauf).
integration:	Eine Integrations- oder Contract-Test-Suite.
external:	Verifiziert durch etwas außerhalb dieses Repositorys (ein Audit, eine dritte Partei).

Ein Criterion mit null Carriern, mehr als einem Carrier oder einem leeren Carrier-Wert ist ungültig, codecharter req check meldet es.

Optionale Criterion-Schlüssel:

• status: open markiert ein noch nicht erfülltes Criterion. Lasst den Schlüssel bei einem erfüllten Criterion weg: es gibt kein explizites „geschlossen"-Token.
• blocked_by: listet die Ids anderer Criteria (in diesem oder einem anderen Requirement), die zuerst landen müssen.
• confidence: needs-predicate markiert ein Criterion, dessen rule:-Ausdruck ein Platzhalter ist, noch nicht durch ein echtes, prüfbares Prädikat gedeckt.

Ein Requirement mit status: implemented, während eines seiner Criteria noch status: open trägt, ist ein Widerspruch, den codecharter req check findet: ihr könnt ein Requirement nicht als erledigt beanspruchen, während die eigene Abnahmeprüfung das Gegenteil sagt.

Anchors

Ein Anchor verknüpft ein Requirement mit dem Code, der es umsetzt. Heute gibt es drei Arten, alle nur deklarativ (noch keine Laufzeit-Verifikation):

Anchor	Schlüssel	Bedeutung
Attribute-expected	attribute_expected:	Nennt einen vollqualifizierten Typ; das Requirement gilt als erfüllt durch jedes Symbol mit [Satisfies("REQ-1")] aus dem Paket CodeCharter.Annotations an einem Member, das diesem Typ zuweisbar ist.
File-Selector	file: + selector:	Zeigt auf einen Dateipfad und einen textuellen Selector darin (z. B. eine Klassendeklaration).
Symbol-Id	symbol_id:	Nennt ein vollqualifiziertes Symbol direkt.

Ein Requirement mit status: implemented oder status: partial ganz ohne Anchor ist ein Fehler: ein „umgesetztes" Requirement ohne jeden Verweis auf den umsetzenden Code lässt sich nicht nachverfolgen. Dieselbe Lücke bei einem open- oder in-progress-Requirement ist nur eine Warnung: dass noch nicht begonnene Arbeit noch keinen Anchor hat, ist normal.

## Out of Scope

Eine ## Out of Scope-Überschrift im Body (Groß-/Kleinschreibung egal, beliebig viel Whitespace) startet einen Abgrenzungsabschnitt: alles danach gilt als Grenze des Requirements, was es bewusst nicht abdeckt. Diese Grenze in derselben Datei wie das Requirement selbst zu halten, sorgt dafür, dass sie mit dem Requirement mitwandert, statt in einer separaten, leicht vergessenen Notiz zu leben.

documents.yml: Requirements zu Dokumenten organisieren

Neben den .req.md-Dateien gruppiert eine optionale .codecharter/req/documents.yml Requirements zu Dokumenten und Kapiteln, etwa einem Lastenheft, einem Pflichtenheft oder einem Abnahmeprotokoll:

title_page:
  title: Sample Product — Requirements
  subtitle: Volume 1
  customer: ACME Corp
  project: Sample Product
  version: "1.0"
  issued_on: "2026-01-01"
documents:
  - slug: requirements-specification
    kind: requirements-specification
    title: Requirements Specification
    chapters:
      - slug: account-management
        title: Account management
        requirements:
          - REQ-1
          - REQ-2

kind ist eines von requirements-specification, functional-specification oder acceptance-protocol. codecharter req check gleicht die requirements-Listen der Kapitel gegen den Corpus ab: eine Id, die nirgends existiert, ist ein Fehler, ein Requirement, das existiert aber in keinem Kapitel auftaucht, ist eine Warnung, sodass nichts still aus dem veröffentlichten Dokumentensatz herausfällt.

Den Corpus prüfen

Führt codecharter req check aus, um alles auf dieser Seite zu validieren: doppelte Ids, ins Leere zeigende refines/conflicts-Referenzen, Criteria ohne nutzbaren Carrier, den Widerspruch implemented-mit-offenen-Criteria, fehlende Anchors und die documents.yml-Querverweise. Die vollständige Liste der Codes, Exit-Codes und Ausgabeformate steht unter codecharter req check.

Anforderungen aus einem KI-Coding-Tool lesen

Ein Agent, der in Ihrer Codebasis arbeitet, kann denselben Corpus über MCP lesen, ohne je eine .req.md-Datei direkt anzufassen: siehe Anforderungen über MCP für die drei rein lesenden Tools (req_context, req_search, req_justify).