# ai-register

> Llevar un registro de las herramientas de IA de tu proyecto, sus datos, base legal y transferencias, y dejar que una comprobación blanda avise de toda integración de IA que el registro omita.

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

Documentación de BMAD+ › [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/) › ai-register

Los asistentes de código, las líneas de comandos de agentes, las API de modelos que llama tu producto y los servidores MCP tratan datos, a veces personales. `ai-register` mantiene un archivo, `_bmad/ai-processing-register.yaml`, que dice para cada herramienta quién la ofrece, con qué finalidad, qué datos ve, con qué base legal, durante cuánto tiempo y a dónde van los datos fuera del EEE. Su acción `check` busca integraciones de IA en el repositorio y avisa de las que el registro no cubre. Forma parte del instrumental del pack Shield y sirve a quien tiene que preparar un registro de actividades de tratamiento, una EIPD que implique herramientas de IA o una revisión de proveedores.

> **Nota · Una puerta blanda, a propósito** Una entrada ausente es un aviso y nunca hace fallar una compilación; solo un registro ilegible sale con código distinto de cero. El registro documenta tratamientos, no los hace lícitos. La base legal, el mecanismo de transferencia y los acuerdos son decisiones del responsable y de su delegado de protección de datos, y la comprobación solo ve la configuración dentro del repositorio: una herramienta instalada en el equipo de un desarrollador sin archivos de proyecto se descubre preguntando, no con la comprobación.

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

**En la terminal de tu proyecto**

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

**Acciones y opciones de ai-register**

| Opción o acción | Argumento | Por defecto | Qué hace |
| --- | --- | --- | --- |
| `init` | - | - | Copia la plantilla de Shield en `_bmad/ai-processing-register.yaml`. Nunca sobrescribe un registro existente. Las entradas de la plantilla son ejemplos, así que `check` sigue avisando hasta que las sustituyas. |
| `check` | - | - | Detecta las integraciones de IA del proyecto, las compara con el registro e imprime el resultado. |
| `-d, --directory` | `<path>` | carpeta actual | Carpeta del proyecto. |
| `--json` | - | desactivada | Salida legible por máquinas (`schemaVersion: 1`). |

<a id="register-file"></a>
## El archivo de registro

**Forma de una entrada (de la plantilla Shield)**

```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.
```

**Reglas que impone la comprobación**

| Campo | Regla |
| --- | --- |
| `schema` | Debe ser `bmad-plus/ai-processing-register/1`. Las claves de primer nivel desconocidas se rechazan (admitidas: `schema`, `controller`, `reviewed`, `tools`). |
| `controller` | Texto obligatorio: quién es responsable del tratamiento. |
| `reviewed` | Fecha obligatoria escrita `YYYY-MM-DD`. La comprobación avisa cuando tiene más de 365 días. |
| `tools[].id` | Único, minúsculas, dígitos y guiones. |
| `tools[].name`, `provider`, `purpose`, `retention` | Texto obligatorio de hasta 2000 caracteres. |
| `tools[].integrations` | Lista no vacía de los ids de integración que cubre la entrada: un id de herramienta de adaptador (`claude-code`, `gemini-cli`, `antigravity`, `cursor`, `codex-cli`, `opencode`, `aider`), otra herramienta como `github-copilot`, `windsurf` o `continue`, o `mcp:<server name as declared>`. Un id solo puede cubrirlo una entrada. |
| `tools[].data` | Lista no vacía de las categorías de datos que ve la herramienta. |
| `tools[].personalData` | `true` o `false`, obligatorio. |
| `tools[].legalBasis` | Obligatoria cuando `personalData` es `true`, prohibida en caso contrario. Una de `consent`, `contract`, `legal-obligation`, `vital-interests`, `public-task`, `legitimate-interests` (RGPD art. 6.1). |
| `tools[].transfers` | Lista obligatoria, `[]` si no hay ninguna. Cada elemento es `{ to, mechanism }` con un mecanismo entre `adequacy-decision`, `standard-contractual-clauses`, `binding-corporate-rules`, `derogation`. |
| `tools[].agreement` | Texto opcional: el acuerdo de tratamiento vigente. |

<a id="reads-writes"></a>
## Qué lee y qué escribe

- `init` escribe un solo archivo, `_bmad/ai-processing-register.yaml`, creando `_bmad` si hace falta. Se niega si `_bmad` no es una carpeta (un enlace escribiría fuera del proyecto).
- `check` no escribe nada. Lee el registro (hasta 256 KB) y busca integraciones de IA en cuatro sitios: los archivos de adaptador que instala BMAD+ (`CLAUDE.md`, `GEMINI.md`, `.cursor/rules/bmad-plus.mdc`, `.codex/AGENTS.md`, `.opencode/AGENTS.md`, `CONVENTIONS.md`), los marcadores propios de las herramientas (`.claude`, `.cursor`, `.cursorrules`, `.gemini`, `.codex`, `.opencode`, `opencode.json`, `.aider.conf.yml`, `.github/copilot-instructions.md`, `.windsurf`, `.windsurfrules`, `.continue`) y los servidores MCP declarados en `.mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json` y `.vscode/mcp.json` (se aceptan comentarios y comas finales).
- No se envía nada a ningún sitio ni se inicia ningún programa. No se siguen los enlaces simbólicos.

<a id="exit-codes"></a>
## Códigos de salida

**Códigos de salida por acción**

| Acción | Código | Significado |
| --- | --- | --- |
| `init` | 0 | Registro escrito. |
| `check` | 0 | El registro se leyó o no existe. Los avisos no cambian esto. |
| `check` | 1 | El registro existe pero es inutilizable: ilegible, YAML inválido o incumple una regla de arriba. El motivo se imprime como `error`. |
| `init`, otra | 3 | Acción desconocida (`ai-register: unknown action "x" (init, check)`) o fallo de `init` (por ejemplo, el registro ya existe). |

<a id="real-output"></a>
## Cómo se ve la salida

Las transcripciones se componen a partir de las plantillas de mensajes del código fuente, sobre un proyecto imaginario que usa Claude Code y un servidor MCP de GitHub y luego añade Cursor. Están marcadas como simuladas.

**Iniciar el registro y comprobarlo**

```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
# El 2/2 supone que el .mcp.json del proyecto declara un servidor github. Sin él, el recuento es 1/1 y una línea indica que mcp:github «not found here (may be used outside the repository)».
```

Salida capturada de una ejecución real. Fuente: Reproducido con el paquete 0.23.0 (packs Core y Shield, Claude Code) en un proyecto desechable cuyo .mcp.json declara un servidor github

**Una herramienta que el registro omite**

```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.
# Código de salida 0: un aviso nunca hace fallar el comando.
```

Salida capturada de una ejecución real. Fuente: Reproducido con el paquete 0.23.0 en el mismo proyecto desechable tras añadir el adaptador de Cursor

Otras líneas posibles: `<file>: absent — 0/N AI integration(s) registered` con el aviso `no AI processing register at _bmad/ai-processing-register.yaml` cuando hay integraciones pero no registro; `warning   the register was last reviewed on <date>, <n> days ago`; `not found here (may be used outside the repository): <ids>` para entradas que no coinciden con nada del repositorio (normal en una API de modelo que solo llama tu producto); y líneas `error` en el flujo de error cuando el registro es inválido. Con `--json`, el resultado incluye `status` (`ok`, `warning` o `error`), `integrations` (cada una con `ids`, `sources`, `coveredBy`), `unmatched`, `warnings` y `errors`.

<a id="doctor"></a>
## La misma comprobación dentro de doctor

Cuando el pack Shield está instalado, `bmad-plus doctor` ejecuta la misma comparación como la comprobación `shield.ai-register`. Es un `pass` («AI processing register covers the N AI integration(s) found.») o un `warning` que lista los problemas y remite a `bmad-plus ai-register check`. Doctor nunca lo convierte en error, así que un registro incompleto no hace fallar la comprobación de salud de una instalación.

<a id="errors"></a>
## Errores y qué hacer

**Mensajes de ai-register**

| Mensaje | Causa | Qué hacer |
| --- | --- | --- |
| `ai-register: _bmad/ai-processing-register.yaml already exists` | `init` nunca sobrescribe. | Edita el archivo existente o muévelo antes. |
| `ai-register: _bmad is not a folder` | Hay algo que no es una carpeta en `_bmad`. | Quítalo o renómbralo y vuelve a ejecutar `init`. |
| `ai-register: unknown action "x" (init, check)` | La acción no es `init` ni `check`. | Usa una de las dos acciones. |
| `error     _bmad/ai-processing-register.yaml: tool X: legalBasis must be one of ...` | `personalData` es true y la base legal falta o es desconocida. | Elige una de las seis bases legales, o pon `personalData: false` y quita `legalBasis`. |
| `error     ... tool X: transfers must list where data goes outside the EEA ([] for nowhere)` | Falta la lista `transfers`. | Añade `transfers: []`, o los destinos con su mecanismo. |
| `error     ... tool X: <id> is already covered by Y` | Dos entradas reclaman el mismo id de integración. | Deja el id en una sola entrada. |
| `error     ... register: schema must be "bmad-plus/ai-processing-register/1"` / `unknown key(s) ...` | Línea `schema` incorrecta o clave no reconocida. | Corrige la línea `schema` y quita o renombra la clave desconocida. |
| `error     ... register: reviewed: expected a date written YYYY-MM-DD` | La fecha de revisión no es una fecha de calendario real con esa forma. | Escríbela como `2026-09-29`. |
| `warning   <file> cannot be read (...); its MCP servers are not checked` | Un archivo de declaración MCP no es JSON válido (los comentarios y las comas finales están bien). | Corrige el archivo; hasta entonces sus servidores no se comparan. |
| `warning   <file> declares the MCP server "<name>", whose name cannot be registered; it is not checked` | El nombre del servidor tiene caracteres que un id de registro no admite. | Renombra el servidor en el archivo MCP o guarda una nota sobre él fuera del registro. |

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

<a id="example-cli-ai-register-inventory"></a>
### Inventariar las herramientas de IA y rellenar el registro

Tu equipo usa un asistente de código y dos servidores MCP, y nadie ha anotado qué ven.

**En tu asistente de IA**

```text
Shield, ¿qué herramientas de IA tocan los datos de este proyecto? Ejecuta la comprobación del registro, crea el registro si no existe y rellena una entrada por herramienta. Pregúntame lo que no puedas leer en el repositorio en lugar de adivinarlo.
```

**Lo que deberías obtener** Shield ejecuta `bmad-plus ai-register check`, lista las integraciones encontradas (archivos de adaptador, carpetas de herramientas, servidores MCP) y las que debe preguntarte porque no dejan rastro en el repositorio, como una API de modelo que llama tu producto. Ejecuta `ai-register init`, sustituye los ejemplos de la plantilla por una entrada por herramienta, rellenando proveedor, finalidad, datos, retención y transferencias a partir de los términos del proveedor y de lo que la herramienta puede leer, y lo dice con claridad cuando un dato se desconoce. Para las entradas con datos personales propone una base legal que tú decides. Termina volviendo a ejecutar `check` e informando de las integraciones registradas y de los avisos que queden.

<a id="example-cli-ai-register-before-dpia"></a>
### Comprobar el registro antes de una EIPD

Vas a realizar una evaluación de impacto sobre la protección de datos de una funcionalidad que usa herramientas de IA.

**En tu asistente de IA**

```text
Shield, antes de empezar la EIPD, comprueba que el registro de tratamiento de IA está completo y revisado. Lista las herramientas sin entrada, las entradas sin base legal y todo lo revisado hace más de un año.
```

**Lo que deberías obtener** Shield ejecuta `bmad-plus ai-register check` (solo lectura). Informa de cada línea `warning` (herramientas configuradas pero no registradas, una revisión de más de 365 días) y, si el registro es inválido, de cada línea `error`, lo que también implica el código de salida 1. Después lee el archivo de registro para localizar entradas que aún necesitan una decisión y recuerda que la detección solo ve lo configurado en el repositorio. No elige una base legal por ti; para un tratamiento a gran escala o novedoso recomienda seguir con el flujo de EIPD.

**Véase también**

- [Resumen de la CLI](https://bmad-plus.rochetta.fr/es/docs/reference/cli-overview/)
- [doctor: informa de la misma comprobación como aviso](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/)
- [assurance: el otro archivo de evidencias de Shield](https://bmad-plus.rochetta.fr/es/docs/reference/cli-assurance/)
- [Adaptadores: los archivos que busca la comprobación](https://bmad-plus.rochetta.fr/es/docs/reference/adapters/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)