# ai-register

> Ein Register der KI-Werkzeuge deines Projekts führen, mit Daten, Rechtsgrundlage und Übermittlungen, und per weicher Prüfung vor jeder im Repository gefundenen KI-Integration warnen lassen, die fehlt.

Canonical: https://bmad-plus.rochetta.fr/de/docs/reference/cli-ai-register/
Language: de
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ Dokumentation › [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/) › ai-register

Coding-Assistenten, Agent-Kommandozeilen, von deinem Produkt aufgerufene Modell-APIs und MCP-Server verarbeiten alle Daten, manchmal personenbezogene. `ai-register` führt eine Datei, `_bmad/ai-processing-register.yaml`, die für jedes Werkzeug festhält, wer es bereitstellt, zu welchem Zweck, welche Daten es sieht, auf welcher Rechtsgrundlage, wie lange und wohin die Daten außerhalb des EWR gehen. Die Aktion `check` sucht KI-Integrationen im Repository und warnt vor allen, die das Register nicht abdeckt. Es gehört zum Werkzeugkasten des Shield-Packs und hilft allen, die ein Verarbeitungsverzeichnis, eine DSFA mit KI-Werkzeugen oder eine Lieferantenprüfung vorbereiten müssen.

> **Hinweis · Ein weiches Gate, mit Absicht** Ein fehlender Eintrag ist eine Warnung und lässt nie einen Build scheitern; nur ein nicht lesbares Register endet mit einem Code ungleich null. Das Register hält Verarbeitungen fest, es macht sie nicht rechtmäßig. Rechtsgrundlage, Übermittlungsmechanismus und Vereinbarungen sind Entscheidungen des Verantwortlichen und seiner oder seines Datenschutzbeauftragten, und die Prüfung sieht nur Konfiguration im Repository: Ein auf dem Rechner einer Entwicklerin installiertes Werkzeug ohne Projektdateien findet man durch Fragen, nicht durch die Prüfung.

<a id="synopsis"></a>
## Syntax

**Im Terminal deines Projekts**

```sh
npx bmad-plus ai-register init [-d <path>] [--json]
npx bmad-plus ai-register check [-d <path>] [--json]
```

**Aktionen und Optionen von ai-register**

| Option oder Aktion | Argument | Standard | Was sie tut |
| --- | --- | --- | --- |
| `init` | - | - | Kopiert die Shield-Vorlage nach `_bmad/ai-processing-register.yaml`. Ein vorhandenes Register wird nie überschrieben. Die Einträge der Vorlage sind Beispiele, `check` warnt also weiter, bis du sie ersetzt hast. |
| `check` | - | - | Erkennt die KI-Integrationen des Projekts, vergleicht sie mit dem Register und gibt das Ergebnis aus. |
| `-d, --directory` | `<path>` | aktueller Ordner | Projektordner. |
| `--json` | - | aus | Maschinenlesbare Ausgabe (`schemaVersion: 1`). |

<a id="register-file"></a>
## Die Registerdatei

**Form eines Eintrags (aus der Shield-Vorlage)**

```yaml
schema: bmad-plus/ai-processing-register/1
controller: Example Ltd, 1 Example Street, Example City
reviewed: 2026-09-29
tools:
  - id: coding-assistant
    name: Claude Code
    provider: Anthropic PBC
    integrations: [claude-code]
    purpose: Assist developers in reading, writing and reviewing the code of this repository.
    data:
      - Source code and commit history of this repository
    personalData: true
    legalBasis: legitimate-interests
    retention: The period set by the provider’s terms, written here in days.
    transfers:
      - to: United States
        mechanism: standard-contractual-clauses
    agreement: Data processing addendum attached to the commercial terms.
```

**Regeln, die die Prüfung durchsetzt**

| Feld | Regel |
| --- | --- |
| `schema` | Muss `bmad-plus/ai-processing-register/1` sein. Unbekannte Schlüssel der obersten Ebene werden abgelehnt (erlaubt: `schema`, `controller`, `reviewed`, `tools`). |
| `controller` | Pflichttext: wer für die Verarbeitung verantwortlich ist. |
| `reviewed` | Pflichtdatum im Format `YYYY-MM-DD`. Die Prüfung warnt, wenn es mehr als 365 Tage zurückliegt. |
| `tools[].id` | Eindeutig, Kleinbuchstaben, Ziffern und Bindestriche. |
| `tools[].name`, `provider`, `purpose`, `retention` | Pflichttext mit bis zu 2000 Zeichen. |
| `tools[].integrations` | Nicht leere Liste der Integrations-IDs, die der Eintrag abdeckt: eine Adapter-Tool-ID (`claude-code`, `gemini-cli`, `antigravity`, `cursor`, `codex-cli`, `opencode`, `aider`), ein anderes Werkzeug wie `github-copilot`, `windsurf` oder `continue`, oder `mcp:<server name as declared>`. Eine ID kann nur von einem Eintrag abgedeckt werden. |
| `tools[].data` | Nicht leere Liste der Datenkategorien, die das Werkzeug sieht. |
| `tools[].personalData` | `true` oder `false`, Pflicht. |
| `tools[].legalBasis` | Pflicht bei `personalData: true`, sonst verboten. Eine von `consent`, `contract`, `legal-obligation`, `vital-interests`, `public-task`, `legitimate-interests` (DSGVO Art. 6 Abs. 1). |
| `tools[].transfers` | Pflichtliste, `[]` für keine. Jedes Element ist `{ to, mechanism }` mit einem Mechanismus aus `adequacy-decision`, `standard-contractual-clauses`, `binding-corporate-rules`, `derogation`. |
| `tools[].agreement` | Optionaler Text: die bestehende Auftragsverarbeitungsvereinbarung. |

<a id="reads-writes"></a>
## Was es liest und schreibt

- `init` schreibt genau eine Datei, `_bmad/ai-processing-register.yaml`, und legt `_bmad` bei Bedarf an. Es lehnt ab, wenn `_bmad` kein Ordner ist (ein Link würde außerhalb des Projekts schreiben).
- `check` schreibt nichts. Es liest das Register (bis 256 KB) und sucht KI-Integrationen an vier Stellen: den von BMAD+ installierten Adapterdateien (`CLAUDE.md`, `GEMINI.md`, `.cursor/rules/bmad-plus.mdc`, `.codex/AGENTS.md`, `.opencode/AGENTS.md`, `CONVENTIONS.md`), den eigenen Markern der Werkzeuge (`.claude`, `.cursor`, `.cursorrules`, `.gemini`, `.codex`, `.opencode`, `opencode.json`, `.aider.conf.yml`, `.github/copilot-instructions.md`, `.windsurf`, `.windsurfrules`, `.continue`) und den MCP-Servern aus `.mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json` und `.vscode/mcp.json` (Kommentare und abschließende Kommas werden akzeptiert).
- Es wird nichts irgendwohin gesendet und kein Programm gestartet. Symbolischen Links wird nicht gefolgt.

<a id="exit-codes"></a>
## Exit-Codes

**Exit-Codes je Aktion**

| Aktion | Code | Bedeutung |
| --- | --- | --- |
| `init` | 0 | Register geschrieben. |
| `check` | 0 | Das Register wurde gelesen oder fehlt. Warnungen ändern daran nichts. |
| `check` | 1 | Das Register existiert, ist aber unbrauchbar: nicht lesbar, kein gültiges YAML oder eine Regel oben verletzt. Der Grund wird als `error` ausgegeben. |
| `init`, sonst | 3 | Unbekannte Aktion (`ai-register: unknown action "x" (init, check)`) oder `init` fehlgeschlagen (zum Beispiel existiert das Register schon). |

<a id="real-output"></a>
## So sieht die Ausgabe aus

Die Mitschnitte sind aus den Meldungsvorlagen im Quellcode zusammengesetzt, für ein erdachtes Projekt, das Claude Code und einen GitHub-MCP-Server nutzt und später Cursor hinzufügt. Sie sind als simuliert markiert.

**Das Register starten und prüfen**

```text
$ npx bmad-plus ai-register init
_bmad/ai-processing-register.yaml: started from the Shield template. Replace the example entries, then run bmad-plus ai-register check.
$ npx bmad-plus ai-register check
_bmad/ai-processing-register.yaml: reviewed 2026-09-29 — 2/2 AI integration(s) registered
  registered claude-code → coding-assistant
  registered mcp:github → issue-tracker-connector
# Die 2/2 setzen voraus, dass die .mcp.json des Projekts einen github-Server deklariert. Ohne ihn lautet die Zählung 1/1, und eine Zeile meldet, dass mcp:github „not found here (may be used outside the repository)“ ist.
```

Ausgabe eines echten Laufs. Quelle: Mit dem Paket 0.23.0 (Packs Core und Shield, Claude Code) in einem Wegwerfprojekt nachgespielt, dessen .mcp.json einen github-Server deklariert

**Ein Werkzeug, das dem Register fehlt**

```text
$ npx bmad-plus ai-register check
_bmad/ai-processing-register.yaml: reviewed 2026-09-29 — 2/3 AI integration(s) registered
  registered claude-code → coding-assistant
  registered mcp:github → issue-tracker-connector
  warning   cursor is set up (.cursor/rules/bmad-plus.mdc, .cursor) but not in the AI processing register
  Add each tool with its purpose, data, legal basis, retention and transfers; see the Shield template shared/ai-processing-register-template.yaml.
# Exit-Code 0: Eine Warnung lässt den Befehl nie scheitern.
```

Ausgabe eines echten Laufs. Quelle: Mit dem Paket 0.23.0 im selben Wegwerfprojekt nachgespielt, nachdem der Cursor-Adapter hinzugefügt wurde

Weitere mögliche Zeilen: `<file>: absent — 0/N AI integration(s) registered` mit der Warnung `no AI processing register at _bmad/ai-processing-register.yaml`, wenn es Integrationen, aber kein Register gibt; `warning   the register was last reviewed on <date>, <n> days ago`; `not found here (may be used outside the repository): <ids>` für Einträge, die im Repository nichts treffen (normal für eine Modell-API, die nur dein Produkt aufruft); und `error`-Zeilen auf dem Fehlerstrom, wenn das Register ungültig ist. Mit `--json` enthält das Ergebnis `status` (`ok`, `warning` oder `error`), `integrations` (jeweils mit `ids`, `sources`, `coveredBy`), `unmatched`, `warnings` und `errors`.

<a id="doctor"></a>
## Dieselbe Prüfung in doctor

Ist das Shield-Pack installiert, führt `bmad-plus doctor` denselben Vergleich als Prüfung `shield.ai-register` aus. Sie ist ein `pass` („AI processing register covers the N AI integration(s) found.“) oder eine `warning`, die die Probleme auflistet und auf `bmad-plus ai-register check` verweist. Doctor macht daraus nie einen Fehler, ein unvollständiges Register lässt die Gesundheitsprüfung einer Installation also nicht scheitern.

<a id="errors"></a>
## Fehler und was zu tun ist

**Meldungen von ai-register**

| Meldung | Ursache | Was tun |
| --- | --- | --- |
| `ai-register: _bmad/ai-processing-register.yaml already exists` | `init` überschreibt nie. | Die vorhandene Datei bearbeiten oder vorher wegverschieben. |
| `ai-register: _bmad is not a folder` | An `_bmad` liegt etwas, das kein Ordner ist. | Entfernen oder umbenennen, dann `init` erneut ausführen. |
| `ai-register: unknown action "x" (init, check)` | Die Aktion ist weder `init` noch `check`. | Eine der beiden Aktionen verwenden. |
| `error     _bmad/ai-processing-register.yaml: tool X: legalBasis must be one of ...` | `personalData` ist true, und die Rechtsgrundlage fehlt oder ist unbekannt. | Eine der sechs Rechtsgrundlagen wählen oder `personalData: false` setzen und `legalBasis` entfernen. |
| `error     ... tool X: transfers must list where data goes outside the EEA ([] for nowhere)` | Die Liste `transfers` fehlt. | `transfers: []` ergänzen oder die Ziele mit Mechanismus. |
| `error     ... tool X: <id> is already covered by Y` | Zwei Einträge beanspruchen dieselbe Integrations-ID. | Die ID nur in einem Eintrag lassen. |
| `error     ... register: schema must be "bmad-plus/ai-processing-register/1"` / `unknown key(s) ...` | Falsche `schema`-Zeile oder unbekannter Schlüssel. | Die `schema`-Zeile korrigieren, den unbekannten Schlüssel entfernen oder umbenennen. |
| `error     ... register: reviewed: expected a date written YYYY-MM-DD` | Das Prüfdatum ist in dieser Form kein echtes Kalenderdatum. | Als `2026-09-29` schreiben. |
| `warning   <file> cannot be read (...); its MCP servers are not checked` | Eine MCP-Deklarationsdatei ist kein gültiges JSON (Kommentare und abschließende Kommas sind in Ordnung). | Die Datei korrigieren; bis dahin werden ihre Server nicht verglichen. |
| `warning   <file> declares the MCP server "<name>", whose name cannot be registered; it is not checked` | Der Servername enthält Zeichen, die eine Register-ID nicht tragen kann. | Den Server in der MCP-Datei umbenennen oder eine Notiz dazu außerhalb des Registers führen. |

<a id="examples"></a>
## Beispiele

<a id="example-cli-ai-register-inventory"></a>
### KI-Werkzeuge inventarisieren und das Register füllen

Dein Team nutzt einen Coding-Assistenten und zwei MCP-Server, und niemand hat festgehalten, was sie sehen.

**In deinem KI-Assistenten**

```text
Shield, welche KI-Werkzeuge berühren die Daten dieses Projekts? Führe die Registerprüfung aus, lege das Register an, falls es keins gibt, und fülle pro Werkzeug einen Eintrag. Frag mich nach allem, was du im Repository nicht lesen kannst, statt es zu raten.
```

**Das solltest du erhalten** Shield führt `bmad-plus ai-register check` aus, listet die gefundenen Integrationen (Adapterdateien, Werkzeugordner, MCP-Server) und diejenigen, nach denen es fragen muss, weil sie keine Spur im Repository hinterlassen, etwa eine von deinem Produkt aufgerufene Modell-API. Es führt `ai-register init` aus, ersetzt die Beispiele der Vorlage durch einen Eintrag pro Werkzeug und füllt Anbieter, Zweck, Daten, Aufbewahrung und Übermittlungen aus den Bedingungen des Anbieters und dem, was das Werkzeug lesen kann, und sagt klar, wenn eine Tatsache unbekannt ist. Bei Einträgen mit personenbezogenen Daten schlägt es eine Rechtsgrundlage vor, die du entscheidest. Zum Schluss führt es `check` erneut aus und meldet die registrierten Integrationen und verbleibende Warnungen.

<a id="example-cli-ai-register-before-dpia"></a>
### Das Register vor einer DSFA prüfen

Du willst eine Datenschutz-Folgenabschätzung für eine Funktion durchführen, die KI-Werkzeuge nutzt.

**In deinem KI-Assistenten**

```text
Shield, prüfe vor Beginn der DSFA, ob das KI-Verarbeitungsregister vollständig und überprüft ist. Liste Werkzeuge ohne Eintrag, Einträge ohne Rechtsgrundlage und alles auf, was vor mehr als einem Jahr zuletzt geprüft wurde.
```

**Das solltest du erhalten** Shield führt `bmad-plus ai-register check` aus (nur lesend). Es meldet jede `warning`-Zeile (eingerichtete, aber nicht registrierte Werkzeuge, eine Prüfung älter als 365 Tage) und, falls das Register ungültig ist, jede `error`-Zeile, was auch Exit-Code 1 bedeutet. Danach liest es die Registerdatei nach Einträgen, die noch eine Entscheidung brauchen, und weist darauf hin, dass die Erkennung nur sieht, was im Repository konfiguriert ist. Eine Rechtsgrundlage wählt es nicht für dich; bei großflächiger oder neuartiger Verarbeitung empfiehlt es, mit dem DSFA-Workflow weiterzumachen.

**Siehe auch**

- [CLI-Überblick](https://bmad-plus.rochetta.fr/de/docs/reference/cli-overview/)
- [doctor: meldet dieselbe Prüfung als Warnung](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/)
- [assurance: die andere Shield-Nachweisdatei](https://bmad-plus.rochetta.fr/de/docs/reference/cli-assurance/)
- [Adapter: die Dateien, die die Prüfung sucht](https://bmad-plus.rochetta.fr/de/docs/reference/adapters/)

[BMAD+ Dokumentation](https://bmad-plus.rochetta.fr/de/docs/) · [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/)

[Quellcode auf GitHub](https://github.com/lrochetta/BMAD-PLUS)