<SYSTEM>This is the full developer documentation for Falcux AI-First</SYSTEM>

# Descripción general

> Qué es el paquete @falcux/ai-first, cómo se instala en un comando y qué puedes hacer con él.

`@falcux/ai-first` es gobierno del contexto para proyectos que se construyen con agentes de código. Trae tres piezas: los **templates** de los documentos que el agente necesita leer, las **skills** que le dicen cómo trabajar en cada tipo de tarea y el **detector de entropía**, que mide cuánto se alejó lo que el proyecto documenta de lo que el proyecto es. La CLI nunca llama a un modelo ni a la red: entrega el procedimiento; la inferencia la pone tu propio agente.

## Comenzar

En la raíz de tu proyecto, o en una carpeta vacía:

* npx

  ```bash
  npx @falcux/ai-first@latest init
  ```

* pnpm dlx

  ```bash
  pnpm dlx @falcux/ai-first@latest init
  ```

El `@latest` evita que `npx` reutilice una versión vieja de su caché. `init` escribe `AI-FIRST.md`, el registro de decisiones y la carpeta de cambios, instala las skills, deja el hook de git y el flujo de CI, y nunca sobreescribe nada que ya exista. Si es tu primera vez, sigue el [inicio rápido](/docs/empezar/inicio-rapido/).

## Lo que puedes hacer

### Arrancar un producto desde una idea

Con la entrevista, `init` instala `protocolo-arranque`. Tu agente la conduce hasta el PRD, la arquitectura y las primeras specs, con la decisión de stack registrada en el ADR.

```text
Usa protocolo-arranque. Quiero construir una app para reservar canchas de fútbol.
```

[Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/)

### Adaptar las skills a tu proyecto

La entrevista escribe tus comandos, tu fase y tu orden de implementación dentro de cada skill instalada, entre marcas que respeta en la siguiente corrida.

```bash
npx @falcux/ai-first@latest init --entrevista
```

[Adaptar las skills](/docs/guias/adaptar-las-skills/)

### Desarrollar una feature con spec antes que código

`protocolo-features` recorre la pre-implementación y la secuencia por capas antes de que el agente escriba una línea.

```text
Usa protocolo-features para agregar la exportación de reservas a CSV.
```

[Desarrollar una feature](/docs/guias/desarrollar-una-feature/)

### Cambiar algo que ya funciona sin romperlo

`protocolo-cambios` clasifica el cambio, abre su documento en `docs/changes/pending/` y analiza el impacto antes de tocar nada.

```text
Usa protocolo-cambios: el formulario de reserva pasa de tres pasos a uno.
```

[Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/)

### Cerrar la sesión sin perder el contexto

`protocolo-cierre` escribe el registro de sesión, actualiza la documentación y envía cada aprendizaje a su sitio.

```text
Usa protocolo-cierre para cerrar la sesión de hoy.
```

[Cerrar la sesión](/docs/guias/cerrar-la-sesion/)

### Auditar la entropía, en local y en CI

`audit` corre cinco verificaciones en código puro y devuelve un puntaje de 0 a 100. El hook de `pre-push` y el flujo de CI que deja `init` lo corren por ti.

```bash
npx @falcux/ai-first@latest audit
```

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)

## Quiero… → Usa…

| Quiero…                                            | Usa…                                                                 |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| Preparar un repo para la metodología               | `npx @falcux/ai-first@latest init`                                   |
| Que las skills conozcan mis comandos y mi fase     | `init --entrevista`                                                  |
| Definir el producto antes de programar             | la skill `protocolo-arranque`                                        |
| Implementar algo nuevo                             | la skill `protocolo-features`                                        |
| Modificar algo que ya funciona                     | la skill `protocolo-cambios`                                         |
| Cerrar una sesión de trabajo                       | la skill `protocolo-cierre`                                          |
| Saber si la documentación sigue diciendo la verdad | `npx @falcux/ai-first@latest audit`                                  |
| Cortar un pull request por cualquier hallazgo      | `audit --estricto`, que ya corre en `.github/workflows/ai-first.yml` |
| Saber qué versión tengo                            | `npx @falcux/ai-first@latest --version`                              |

El porqué de cada pieza —por qué un registro de decisiones, por qué Zonas Prohibidas, por qué un protocolo antes de cada tarea— está en la pestaña [Metodología](/docs/metodologia/).

## Próximos pasos

[Inicio rápido](/docs/empezar/inicio-rapido/)De una carpeta vacía a tu primer audit limpio.

[Qué deja init en tu repo](/docs/empezar/que-instala/)Cada archivo que escribe, para qué sirve y quién lo lee.

[Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/)Qué salta, qué sugiere y qué tienes que revisar.

[Agentes compatibles](/docs/empezar/agentes/)Cómo lee las skills cada herramienta.

# Inicio rápido

> De una carpeta vacía a un repo configurado y un primer audit con entropía 0, en seis pasos.

Esta página te lleva de una carpeta vacía a un repo con la metodología configurada y un primer `audit` limpio. Son unos minutos; lo que más tiempo toma es leer lo que `init` escribió.

## Requisitos

* **Node 22.12 o más nuevo.** El paquete lo declara en `engines` (`>=22.12.0`). `npx` viene con npm.
* **git.** Si la carpeta todavía no es un repositorio, `init` corre `git init` por ti; `audit` siempre necesita uno.

Para saber qué versión del paquete estás corriendo:

```bash
npx @falcux/ai-first@latest --version
```

## De cero a primer audit

1. **Crea la carpeta del proyecto.**

   ```bash
   mkdir mi-proyecto && cd mi-proyecto
   ```

2. **Corre `init`.**

   ```bash
   npx @falcux/ai-first@latest init
   ```

   Sin `@latest`, `npx` puede servirte una versión vieja de su caché; sin `init`, sólo imprime la ayuda. Los detalles están en la [referencia de init](/docs/referencia/init/).

3. **Responde la entrevista.** En una terminal interactiva y en un proyecto sin documentación, `init` pregunta lo que no puede deducir. Cada pregunta trae un valor por defecto entre corchetes; Enter lo acepta.

   * Cómo se llama el proyecto.
   * En qué fase está: exploración, MVP o producción.
   * Qué clase de producto es: SaaS o aplicación web con sesión, landing o sitio de contenido, API sin interfaz, herramienta de línea de comandos o librería, o aplicación móvil. Esto decide qué skills se instalan.
   * Qué forma tiene el repositorio: una sola aplicación, un monorepo o uno de varios repos.
   * Con qué comando se verifica que el proyecto está sano, y los de tipos y lint si los hay.
   * Si trabajas con varios agentes en paralelo.
   * Qué archivo lleva el número de versión.
   * En qué orden se implementa una feature; las opciones dependen de la clase de producto.
   * Una confirmación por cada Zona Prohibida que `init` sugiere.

   Las respuestas van a `AI-FIRST.md` y a la sección «Adaptación a tu proyecto» de cada skill instalada. Con entrevista se instala también `protocolo-arranque`, la skill que define el producto. Si prefieres no responder ahora, `--sin-entrevista` la salta.

   Así termina `init` en una carpeta vacía llamada `demo`, corrido con `--sin-entrevista`:

   ```text
   ai-first init — demo


     escrito  .git/
     escrito  AI-FIRST.md
     escrito  docs/ADR.md
     escrito  docs/SESSION_LOG.md
     escrito  docs/changes/CHANGE_LOG.md
     escrito  docs/changes/pending/.gitkeep
     escrito  .agents/skills/protocolo-features
     escrito  .agents/skills/protocolo-cambios
     escrito  .agents/skills/protocolo-cierre
     escrito  .agents/skills/version-bump
     escrito  .agents/skills/test-fix
     escrito  .claude/skills
     escrito  .githooks/pre-push
     escrito  core.hooksPath
     escrito  .github/workflows/ai-first.yml
     escrito  AGENTS.md


     1 Zona Prohibida sugerida: .env*
     0 superficies de decisión: —
     2 artefactos declarados


   Revisa AI-FIRST.md —sobre todo las razones de cada zona— y AGENTS.md, y luego corre `ai-first audit`.
   ```

   Qué es cada línea está en [Qué deja init en tu repo](/docs/empezar/que-instala/).

4. **Revisa `AI-FIRST.md`.** Es el mapa que el detector verifica. Mira sobre todo las Zonas Prohibidas: `init` las sugiere por lo que encuentra en el repo, y `.env*` siempre. Al final del archivo, en «Notas», hay una línea por zona para completar:

   ```md
   Por qué `.env*` es Zona Prohibida: _(completar: qué cuesta revertir un error ahí)_.
   ```

   El criterio es el costo de revertir un error ahí, no la importancia del archivo. Quita las que no apliquen: pocas, o se vuelven ruido. El formato completo está en la [referencia de AI-FIRST.md](/docs/referencia/ai-first-md/).

5. **Corre el primer `audit`.**

   ```bash
   npx @falcux/ai-first@latest audit
   ```

   ```text
   ai-first audit — demo
   árbol de trabajo contra HEAD · 0 archivos tocados


   ✓ Zona Prohibida tocada
   ✓ Decisión sin fila en ADR
   – Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
   ✓ Artefacto huérfano
   – Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


   Entropía: 0 / 100 (0 P0 · 0 P1 · 0 P2)
   ```

   Cómo se lee:

   * La segunda línea dice qué compara: sin `--base`, el árbol de trabajo contra el último commit. Antes de tu primer commit cuenta como tocados los archivos que `init` acaba de escribir; después del commit, 0.
   * `✓` es una verificación aprobada, `✗` una con hallazgos y `–` una omitida, siempre con su razón. Omitido no es aprobado: el check no tenía con qué correr. Alcance se omite porque todavía no hay un cambio abierto, e Inventario porque el proyecto no declara componentes.
   * La última línea es el puntaje: `min(100, 40·P0 + 20·P1 + 8·P2)`. Más alto es peor. El código de salida es 0; con cualquier P0 sería 1.

6. **Haz el commit.**

   ```bash
   git add -A
   git commit -m "chore: configura ai-first"
   ```

   Desde ahora, cada `git push` pasa por `.githooks/pre-push`, que corre el mismo `audit` sobre lo que vas a publicar y sólo interrumpe ante un P0.

Consejo

Si el proyecto todavía es sólo una idea, el paso siguiente es pedirle a tu agente que use `protocolo-arranque`. Si lo instalaste sin entrevista, vuelve a correr `init` con `--skills protocolo-arranque`: lo que ya existe se salta.

## Próximos pasos

[Qué deja init en tu repo](/docs/empezar/que-instala/)Cada pieza, qué hace y qué skill o check la usa.

[Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/)De la idea al PRD, la arquitectura y las specs.

[ai-first audit](/docs/referencia/audit/)Modos, opciones y códigos de salida.

# Qué deja init en tu repo

> La anatomía de lo que escribe ai-first init, pieza por pieza, y qué skill o verificación usa cada una.

`init` deja en el repo todo lo que los protocolos y el detector dan por hecho. Esta página recorre cada pieza: qué es, qué contiene al nacer y quién la lee.

## El árbol

Así queda una carpeta vacía después de `npx @falcux/ai-first@latest init --sin-entrevista`, sin contar `.git/`:

* .agents/

  * skills/

    * protocolo-cambios/

      * SKILL.md

      * references/

        * documento-de-cambio.md

    * protocolo-cierre/

      * SKILL.md

    * protocolo-features/

      * SKILL.md

    * test-fix/

      * SKILL.md

    * version-bump/

      * SKILL.md

* .claude/

  * skills enlace simbólico a ../.agents/skills

* .githooks/

  * pre-push

* .github/

  * workflows/

    * ai-first.yml

* docs/

  * ADR.md

  * SESSION\_LOG.md

  * changes/

    * CHANGE\_LOG.md

    * pending/

      * .gitkeep

* AGENTS.md

* AI-FIRST.md

Además, en la configuración local del repo, `core.hooksPath` queda apuntando a `.githooks`. `init` no escribe `CLAUDE.md`: si usas Claude Code, el template `templates/CLAUDE_MD_TEMPLATE.md` del paquete es una línea, `@AGENTS.md`.

## AI-FIRST.md

El mapa que el detector verifica. Un frontmatter YAML con lo que `init` encontró, cada campo con un comentario que explica para qué es:

* `zonas_prohibidas`: rutas que el agente no modifica sin aprobación explícita. `init` sugiere las que encuentra —carpetas de migraciones, `infra/`, `terraform/`, `LICENSE`— y `.env*` siempre. Tocar una es un **P0**.
* `superficies_de_decision`: rutas donde un cambio se presume decisión arquitectónica, como `**/*.config.*` o los flujos de `.github/workflows/`. Si una se toca y el ADR no gana una fila, es un **P1**. Si no encuentra ninguna, el campo queda comentado.
* `alcance.spec`: la carpeta del cambio en curso, `docs/changes/pending/`.
* `artefactos`: los documentos que hablan de este repo, como `AGENTS.md` y el ADR. El detector comprueba que lo que mencionan exista.

`verificacion`, el comando que decide si el proyecto está sano, sale de los scripts `build` y `test` del `package.json` si los hay. Con entrevista, `fase`, `perfil` y `verificacion` quedan con tus respuestas. Debajo del frontmatter, la sección «Notas» pide la razón de cada zona. La skill `protocolo-arranque` también escribe en este archivo. Campo por campo, en la [referencia de AI-FIRST.md](/docs/referencia/ai-first-md/).

## docs/ADR.md

El registro de decisiones, vacío salvo por sus reglas y un molde comentado de `ADR-001`. Una decisión entra si es difícil de revertir, tenía alternativas reales y alguien va a preguntar por qué dentro de seis meses. No se edita: se agrega una nueva que supera a la vieja.

Lo usan `protocolo-cierre`, `protocolo-features`, `protocolo-cambios`, `protocolo-arranque` e `information-architecture`. La verificación «Decisión sin fila en ADR» busca encabezados `## ADR-` nuevos en él. Si el repo ya tenía un `ADR.md` en la raíz o en `docs/`, `init` usa ése.

## docs/SESSION\_LOG.md

El registro de sesiones: qué se hizo, qué cambió y qué quedó pendiente, con la sesión más reciente arriba. Nace con su cabecera y ninguna entrada. Lo escribe `protocolo-cierre` en su Fase A y lo verifica el humano; `version-bump` lo lee.

## docs/changes/

* `pending/` es donde vive el documento de un cambio mientras está abierto. `protocolo-cambios` lo crea ahí a partir de su molde, `references/documento-de-cambio.md`, y la verificación «Alcance excedido» lee la lista de archivos de esa spec. Nace con un `.gitkeep` para que git la versione vacía.
* `CHANGE_LOG.md` es el resumen permanente de cada cambio cerrado. Al cerrarlo, el documento sale de `pending/` y su resumen queda acá.

## .agents/skills y el enlace .claude/skills

Las skills, copiadas del paquete. Sin entrevista son las cinco que no piden interfaz: `protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `version-bump` y `test-fix`. Con entrevista, las que pida el perfil del producto, más `protocolo-arranque`. `--skills` elige otras y `--enlazar` deja enlaces simbólicos en vez de copias.

`.agents/skills/` es la carpeta del estándar Agent Skills. `.claude/skills` es un enlace simbólico relativo a ella, porque Claude Code lee su propia carpeta: cada archivo existe una sola vez. Cómo las lee cada herramienta, en [Agentes compatibles](/docs/empezar/agentes/).

## El bloque de AGENTS.md

Si no había `AGENTS.md`, `init` lo crea con una cabecera mínima que apunta al template. Si ya existía, agrega al final un bloque entre dos marcas:

```md
<!-- ai-first:inicio -->
### Metodología AI-First
…
<!-- ai-first:fin -->
```

Dentro va una tabla con cada skill instalada y cuándo se invoca, y otra que traduce el vocabulario del manual a las rutas del repo: registro de sesión, registro de decisiones, cambio en curso. Cada corrida de `init` reescribe lo que hay entre las marcas con lo que encuentra instalado; **fuera de ellas no toca una letra**. Si falta una de las dos marcas, o están al revés, `init` se detiene y te pide arreglarlo a mano.

## .githooks/pre-push y core.hooksPath

El punto de control local. Antes de cada `git push` corre `audit` sobre el rango que vas a publicar, **sin `--estricto`**: imprime todo, pero sólo un P0 interrumpe el push. Si la rama todavía no existe en el remoto, audita el árbol de trabajo.

* Busca el `ai-first` del proyecto, luego el del PATH, y sólo usa `npx --no-install`, que no descarga nada. Si no lo encuentra, avisa y deja pasar el push.
* Si no encuentra `node`, lo busca en las rutas habituales y en `nvm.sh`; si aun así no aparece, avisa y deja pasar.
* Se salta con `git push --no-verify`.

Para que git lo use, `init` fija `core.hooksPath` en `.githooks`, **sólo si estaba sin configurar**. Un `core.hooksPath` de husky o lefthook no se pisa: se reporta como sugerido. Con `--hook-local` el hook va a `.git/hooks/`, que no viaja en el clon; con `--sin-hook` no se escribe. Es un hook de git, no un hook del agente.

## .github/workflows/ai-first.yml

El mismo detector en cada pull request, **con `--estricto`**: acá cualquier hallazgo, P1 o P2 incluidos, deja el check en rojo. Hace checkout con toda la historia, instala Node 22 y corre:

```bash
npx --yes @falcux/ai-first audit --base "origin/${{ github.base_ref }}" --estricto
```

Con `--sin-ci` no se escribe.

## Nunca sobreescribe

Lo que ya existe se salta, se reporta y el comando sigue. Cada línea del reporte tiene uno de tres estados:

| Estado     | Qué significa                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `escrito`  | No existía y `init` lo creó.                                                                                     |
| `saltado`  | Ya existía y no se tocó. Entre paréntesis, la razón si no es «ya existe».                                        |
| `sugerido` | Hacía falta algo en un archivo o una configuración que ya existía; en vez de cambiarlo, `init` dice qué agregar. |

Una skill cuya carpeta ya existe se salta entera, sin fusionar nada dentro. El enlace `.claude/skills` tampoco se crea si ahí ya hay algo. Correr `init` dos veces deja el repo igual.

Nota

Todas las opciones de `init` y el detalle de cada estado están en la [referencia de init](/docs/referencia/init/).

## Próximos pasos

[El formato de AI-FIRST.md](/docs/referencia/ai-first-md/)Cada campo del frontmatter y cómo lo lee el detector.

[ai-first init](/docs/referencia/init/)Todas las opciones y lo que reporta.

[Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/)Qué pasa cuando el repo ya tiene AGENTS.md, hooks o documentación.

# Adoptar en un proyecto existente

> Qué hace init en un repo que ya tiene código, AGENTS.md, hooks o documentación, y qué te toca revisar después.

`init` está pensado para correr sobre un repo con historia. No sobreescribe nada: lo que ya existe se salta y se reporta, y lo que haría falta cambiar en un archivo tuyo se sugiere en vez de escribirse. Esta página dice qué pasa con cada cosa que ya tengas y qué revisar al terminar.

## Correrlo

Desde la raíz del repo:

```bash
npx @falcux/ai-first@latest init
```

Para dejar fuera el hook, el flujo de CI o la entrevista, mira [Qué dejar fuera](#qu%C3%A9-dejar-fuera).

## Lo que ya tienes

| Si ya hay…                                                           | `init`…                                                                                                                 |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `AGENTS.md`                                                          | Agrega al final su bloque entre `<!-- ai-first:inicio -->` y `<!-- ai-first:fin -->`. El resto del archivo queda igual. |
| `AI-FIRST.md`                                                        | Lo salta. Si le falta `alcance.spec`, lo reporta como sugerido con la línea que añadir.                                 |
| `ADR.md` en la raíz o en `docs/`                                     | Lo usa como registro de decisiones y no crea otro.                                                                      |
| `docs/SESSION_LOG.md` o `docs/changes/CHANGE_LOG.md`                 | Los salta.                                                                                                              |
| Una skill con el mismo nombre en `.agents/skills/`                   | Salta la carpeta **entera**, sin fusionar nada dentro.                                                                  |
| `.claude/skills` como directorio real                                | Lo deja como está y lo reporta: un enlace encima habría creado `.claude/skills/skills`.                                 |
| `core.hooksPath` apuntando a otro sitio, como el de husky o lefthook | No lo cambia. Escribe `.githooks/pre-push` igual y reporta la configuración como sugerida.                              |
| `.github/workflows/ai-first.yml`                                     | Lo salta.                                                                                                               |

Este es el reporte real sobre un repo con `AGENTS.md`, `package.json`, una carpeta `migrations/`, componentes en `src/components/` y `core.hooksPath` apuntando a `.husky`, corrido sin terminal interactiva:

```text
ai-first init — tienda


  escrito  AI-FIRST.md
  escrito  docs/ADR.md
  escrito  docs/SESSION_LOG.md
  escrito  docs/changes/CHANGE_LOG.md
  escrito  docs/changes/pending/.gitkeep
  escrito  .agents/skills/protocolo-features
  escrito  .agents/skills/protocolo-cambios
  escrito  .agents/skills/protocolo-cierre
  escrito  .agents/skills/version-bump
  escrito  .agents/skills/test-fix
  escrito  .claude/skills
  escrito  .githooks/pre-push
  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks
  escrito  .github/workflows/ai-first.yml
  escrito  AGENTS.md


  Sin entrevista: no hay terminal interactiva.


  2 Zonas Prohibidas sugeridas: migrations/, .env*
  1 superficie de decisión: **/*.config.*
  2 artefactos declarados


Revisa AI-FIRST.md —sobre todo las razones de cada zona— y AGENTS.md, y luego corre `ai-first audit`.
```

La línea `escrito AGENTS.md` significa que se agregó el bloque, no que se reemplazó el archivo. Una segunda corrida sobre el mismo repo reporta todo como `saltado`, y `AGENTS.md` con la razón «el bloque ya está al día».

## La entrevista, en un repo documentado

`init` considera que el proyecto ya está documentado si encuentra `AI-FIRST.md`, `AGENTS.md` o algún `.md` bajo `docs/` que git no ignore, sin contar los que `init` mismo escribe. En ese caso, en una terminal interactiva, dice qué encontró y ofrece la entrevista con saltarla como valor por defecto:

```text
¿Entrevistar de todos modos? [s/N]
```

Las skills se instalan igual; la entrevista sólo sirve para adaptarlas. Para entrevistar sin la pregunta previa:

```bash
npx @falcux/ai-first@latest init --entrevista
```

Sin terminal interactiva —en CI, con la entrada redirigida o desde otro comando— no se entrevista nunca, y el reporte lo dice. `--entrevista` en ese caso es un error de uso.

## Revisa las Zonas Prohibidas

`init` sugiere zonas por lo que encuentra —carpetas de migraciones, `infra/`, `terraform/`, `LICENSE`— y agrega `.env*` siempre. En el repo del ejemplo, el `AI-FIRST.md` quedó así:

```yaml
zonas_prohibidas:
  - ruta: "migrations/"
    razon: "esquema de base de datos"
    desde: 2026-09-23
  - ruta: ".env*"
    razon: "credenciales"
    desde: 2026-09-23
```

La razón por defecto es genérica. Cámbiala por lo que cuesta revertir un error ahí, quita las que no sean tuyas y agrega las que `init` no puede adivinar. Pocas zonas: si todo es prohibido, nada lo es.

Revisa también `superficies_de_decision` y, si tienes componentes, las dos líneas comentadas de `artefactos` que activan la verificación de inventario:

```yaml
  # Hay componentes en src/components/. Para vigilar su inventario, descomenta:
  # inventario_componentes: docs/COMPONENTES.md
  # componentes_dir: "src/components/"
```

Después corre `npx @falcux/ai-first@latest audit` y haz el commit.

## Qué dejar fuera

| Opción             | Efecto                                                                                       |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `--sin-hook`       | No escribe el hook de git ni toca `core.hooksPath`.                                          |
| `--hook-local`     | El hook va a `.git/hooks/`, que no viaja en el clon, y la configuración del repo no se toca. |
| `--sin-ci`         | No escribe `.github/workflows/ai-first.yml`.                                                 |
| `--sin-entrevista` | No entrevista nunca.                                                                         |

`--sin-hook` y `--hook-local` se contradicen: juntas son un error de uso. Si ya usas husky o lefthook, el reporte te da dos salidas: mover el hook a la carpeta que ya usas o cambiar la configuración a `.githooks`. La lista completa de opciones está en la [referencia de init](/docs/referencia/init/).

## Instalar sólo las skills, sin la CLI

Si no quieres correr `init`, puedes copiar las skills a mano. Es lo mismo que hace el comando con ellas, sin el resto: no escribe `AI-FIRST.md`, ni el ADR, ni el hook. Primero trae la carpeta `skills/` del paquete:

* Desde npm

  ```bash
  npm pack @falcux/ai-first@latest
  tar -xzf falcux-ai-first-*.tgz
  origen=package/skills
  ```

* Desde git

  ```bash
  git clone --depth 1 https://github.com/HoruxDeEdfu/falcux-ai-first-package.git
  origen=falcux-ai-first-package/skills
  ```

Y después, desde la raíz de tu proyecto:

```bash
mkdir -p .agents/skills


# Copia sólo las que tu proyecto no tenga ya
for carpeta in "$origen"/*/; do
  nombre=$(basename "$carpeta")
  if [ -e ".agents/skills/$nombre" ]; then
    echo "saltada: $nombre — ya existe en tu proyecto"
  else
    cp -r "$carpeta" ".agents/skills/$nombre"
  fi
done


# Un solo enlace para Claude Code, si no hay nada en su sitio
mkdir -p .claude
[ -e .claude/skills ] || ln -s ../.agents/skills .claude/skills
```

Al terminar, borra lo que descargaste: la carpeta `package/` y el `.tgz`, o el clon.

El bucle copia las once; `init`, por defecto, sólo cinco. Borra las que no vayas a usar todavía. Salta la carpeta entera cuando el nombre ya existe, en vez de fusionarla: copiar sin más habría pisado tu `SKILL.md` y dejado los archivos de apoyo del paquete dentro de tu skill, en silencio. El enlace tampoco se crea si `.claude/skills` ya es algo, porque sobre un directorio real te dejaría un `.claude/skills/skills` que no lee nadie.

Precaución

Una skill copiada a mano no está adaptada. Cada una trae al final la sección «Adaptación a tu proyecto» con lo que hay que cambiar; sin eso ocupa presupuesto de carga y da instrucciones que no aplican a tu stack. La entrevista de `init` hace esa adaptación por ti.

### Si un nombre ya está ocupado

Seis skills llevan nombres de oficio —`i18n`, `test-fix`, `version-bump`, `ux-writer`, `ux-audit`, `information-architecture`— y tu proyecto puede tener ya una con alguno. Tienes tres salidas:

* **Quedarte con la tuya.** No hagas nada: el bucle ya la saltó.

* **Quedarte con la del paquete.** Borra la tuya y vuelve a correr el bucle.

* **Tener las dos.** Copia la del paquete con el prefijo `ai-first-` y cambia el `name:` de su frontmatter para que coincida con la carpeta:

  ```bash
  cp -r "$origen/i18n" .agents/skills/ai-first-i18n
  ```

  Las demás skills la siguen nombrando `i18n`, así que deja escrita la equivalencia en tu `AGENTS.md` mientras convivan.

## Próximos pasos

[Qué deja init en tu repo](/docs/empezar/que-instala/)Cada pieza y quién la lee.

[Adaptar las skills](/docs/guias/adaptar-las-skills/)La entrevista y lo que queda por hacer a mano.

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)El hook, el flujo de CI y cómo leer lo que reportan.

# Agentes compatibles

> Cómo leen las skills y el AGENTS.md Claude Code, Codex, Cursor, OpenCode y Kimi Code, y qué hacer con una herramienta que no carga skills.

Las skills del paquete siguen el formato del estándar abierto *Agent Skills*: una carpeta por skill con un `SKILL.md` cuyo frontmatter lleva `name` y `description`. Cualquier herramienta que lea ese formato las carga sin cambios. El paquete las documenta para cinco: Claude Code, Codex, Cursor, OpenCode y Kimi Code.

## Una carpeta, dos rutas de lectura

`init` instala las skills una sola vez, en `.agents/skills/`, y crea un enlace para la herramienta que no lee esa carpeta:

| Agente      | Lee las skills desde                                              | Cómo se invoca una skill                             |
| ----------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
| Claude Code | `.claude/skills/`, que es un enlace simbólico a `.agents/skills/` | Con `/nombre`                                        |
| Codex       | `.agents/skills/`                                                 | Con `$nombre`                                        |
| Cursor      | `.agents/skills/`                                                 | La carga cuando su descripción coincide con la tarea |
| OpenCode    | `.agents/skills/`                                                 | La carga cuando su descripción coincide con la tarea |
| Kimi Code   | `.agents/skills/`                                                 | La carga cuando su descripción coincide con la tarea |

Para Cursor, OpenCode y Kimi Code el paquete no documenta más que eso: que leen `.agents/skills/` de forma nativa y cargan una skill por su descripción. Si tu herramienta tiene una forma explícita de invocarla, está en su propia documentación, no en la del paquete.

Cada archivo existe una sola vez: no hay copias que sincronizar. El enlace se versiona en git como enlace, no como copia.

## AGENTS.md y CLAUDE.md

`AGENTS.md` lo leen todas las herramientas; ahí `init` deja el bloque que dice qué skill se usa cuándo y dónde escribe cada una. Claude Code lee `CLAUDE.md`, que en esta metodología es una sola línea:

```md
@AGENTS.md
```

`init` no escribe `CLAUDE.md`. El molde está en `templates/CLAUDE_MD_TEMPLATE.md` del paquete.

## Windows sin enlaces simbólicos

Si tu equipo trabaja en Windows sin enlaces simbólicos habilitados, `.claude/skills` puede ser una copia de `.agents/skills/`. En ese caso, declara en `AGENTS.md` cuál es la fuente y cuál la copia, para que nadie edite la que no es.

## Herramientas sin carga de skills

Si tu herramienta no carga skills por su cuenta, guarda los `SKILL.md` como documentos en `docs/` e indícale desde `AGENTS.md` cuándo leer cada uno:

```md
## Documentación especializada
- Antes de implementar un feature, leer `docs/protocolos/features.md`
- Antes de escribir textos visibles, leer `docs/protocolos/ux-writer.md`
```

Menos elegante que la carga automática, mismo resultado.

Nota

El paquete no instala hooks del agente, como `PostToolUse` o `Stop`: cada herramienta los configura en su propio formato y quedaron fuera del estándar *Agent Skills*. El hook que deja `init` es de git, `.githooks/pre-push`, y funciona igual con cualquier agente.

## Próximos pasos

[Qué deja init en tu repo](/docs/empezar/que-instala/)Las skills, el enlace y el bloque de AGENTS.md, pieza por pieza.

[Las 11 skills](/docs/referencia/skills/)Qué hace cada una y cuándo se activa.

[Adaptar las skills](/docs/guias/adaptar-las-skills/)Que cada skill conozca tus comandos y tu orden de implementación.

# Arrancar un producto desde cero

> Cómo llevar una idea o un requerimiento en bruto hasta el PRD, la arquitectura, las specs y la decisión de stack con protocolo-arranque.

Tienes una idea, un requerimiento o las notas de una reunión, y todavía no hay PRD ni arquitectura. Quieres que el agente te ayude a definir el producto y que lo que salga quede escrito en el repo, no en un chat.

## Cuándo usarla

* Hay una idea o un requerimiento y `docs/` está vacío, o sólo tiene lo que escribió `init`.
* Hay que decidir el stack y nadie lo ha registrado.
* Un proyecto existente cambió tanto de alcance que su PRD dejó de describirlo.

`protocolo-arranque` corre **una vez** por proyecto, o una vez por giro grande de producto. Si el producto ya está definido y vas a construir una parte, es [Desarrollar una feature](/docs/guias/desarrollar-una-feature/). Si vas a modificar algo que ya funciona, incluido un artefacto que este protocolo escribió, es [Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/).

## Antes de empezar

`protocolo-arranque` no está entre las cinco skills que `init` instala por defecto. Entra de dos maneras:

* **Con la entrevista.** En una carpeta vacía y desde una terminal, `init` entrevista sin preguntar, y cuando entrevista instala `protocolo-arranque` junto con las skills que pide el perfil del producto:

  ```bash
  npx @falcux/ai-first@latest init
  ```

* **Sola, en un repo ya inicializado.** Si corriste `init` sin entrevista, agrégala con `--skills`. Instala sólo las que nombras; las que ya estaban no se tocan.

  ```bash
  npx @falcux/ai-first@latest init --skills protocolo-arranque
  ```

Con entrevista, `AI-FIRST.md` declara el perfil —`producto` y `repositorio`— y la skill lo lee para saber qué artefactos escribir. Sin perfil, es lo primero que te pregunta. La entrevista está en [Adaptar las skills](/docs/guias/adaptar-las-skills/).

## Paso a paso

1. **Dale el contexto base.** Pega el mensaje, el documento o las notas tal como estén, y nombra la skill para que el agente la cargue:

   ```text
   Usa protocolo-arranque. Este es el requerimiento tal como llegó:


   [pega aquí el correo, las notas de la reunión o el documento]


   El cliente ya tiene una base de datos en PostgreSQL que hay que usar.
   Antes de escribir nada, haz el descubrimiento completo.
   ```

   La skill lee primero `AI-FIRST.md`, `AGENTS.md`, lo que haya en `docs/` y `docs/ADR.md`, para no preguntarte lo que ya está escrito.

2. **Responde el descubrimiento.** Es la Fase 1, y no se genera ningún artefacto hasta que cierra. El agente arma un benchmark de herramientas parecidas, con una línea por cada una, y te dice si lo que quieres construir ya se puede comprar. Después pregunta en tandas, sin límite, por el problema y el éxito, los usuarios, la lógica de negocio, los datos, las integraciones y las restricciones.

   Si una idea tuya es ineficiente, la skill le pide proponer la alternativa con su porqué. Si la reafirmas, se acata y queda en el ADR con las dos posturas.

3. **Cierra la fase.** Cierra cuando el agente puede decir, sin suponer, qué se construye, para quién, con qué reglas, contra qué datos y cómo se mide el éxito. Te pregunta si falta algo y enumera lo que quedó supuesto.

4. **Deja que genere los artefactos, en orden.** La Fase 2 escribe cada documento desde su template del paquete, en su ruta definitiva:

   ```text
   1. Decisión de stack        → fila en docs/ADR.md
   2. docs/PRD.md              → qué se construye y para quién
   3. docs/ARQUITECTURA.md     → componentes, límites y el diagrama
   4. docs/GUIA_DISENO.md      → si el producto tiene interfaz
   5. docs/specs/<modulo>.md   → una por módulo, en orden de construcción
   6. AI-FIRST.md y AGENTS.md  → completar con lo que ahora se sabe
   ```

   El agente no instala nada ni corre generadores de proyecto: deja escritos los comandos de instalación en la fila del ADR o en el PRD. Tampoco escribe las specs de todo el backlog, sólo las de lo que se construye primero.

5. **Revisa la validación final.** La skill comprueba que el PRD y la arquitectura no se contradigan, que cada decisión difícil de revertir tenga su fila, que `AI-FIRST.md` declare las Zonas Prohibidas que la arquitectura hizo evidentes y que las specs listen sus archivos. La última comprobación es el detector:

   ```bash
   npx @falcux/ai-first@latest audit
   ```

6. **Cierra el tramo.** El arranque se cierra como cualquier otro trabajo, con `protocolo-cierre`. Ver [Cerrar la sesión](/docs/guias/cerrar-la-sesion/).

Precaución

Si el agente empieza a escribir «se definirá más adelante», si dos artefactos cuentan distinto el mismo flujo o si el PRD crece con features que nadie pidió, la skill manda detener la generación y volver a la Fase 1.

## Qué queda escrito

Qué artefactos salen depende del perfil. Todos salen de un template del paquete:

| Artefacto                                     | Template                                  | Cuándo                                             |
| --------------------------------------------- | ----------------------------------------- | -------------------------------------------------- |
| Fila de la decisión de stack en `docs/ADR.md` | —                                         | Siempre                                            |
| `docs/PRD.md`                                 | `templates/PRD_TEMPLATE.md`               | Siempre                                            |
| `docs/ARQUITECTURA.md`                        | `templates/ARQUITECTURA_TEMPLATE.md`      | Siempre                                            |
| `docs/specs/<modulo>.md`                      | `templates/SPEC_MODULO_TEMPLATE.md`       | Una por módulo; en una landing, una sola del sitio |
| `docs/GUIA_DISENO.md`                         | `templates/GUIA_DISENO_TEMPLATE.md`       | Con interfaz: saas, landing, movil                 |
| `docs/COMPONENTES.md`                         | `templates/COMPONENT_LIBRARY_TEMPLATE.md` | Con interfaz: saas, landing, movil                 |
| `docs/TECH_NOTES.md`                          | `templates/TECH_NOTES_TEMPLATE.md`        | Siempre                                            |

Además, completa `AI-FIRST.md` con las Zonas Prohibidas —migraciones, infraestructura, secretos— y su razón, y `AGENTS.md` **fuera** de las marcas del bloque que mantiene `init`. En un monorepo la arquitectura describe qué paquete depende de qué; en varios repos, el PRD y la arquitectura viven en uno solo.

El registro de sesión, el de cambios y el handoff no son artefactos de arranque: nacen vacíos con `init` y los llenan otras skills.

## Qué vigila el detector

* **Artefacto huérfano (P2).** Cada ruta que un artefacto declarado en `AI-FIRST.md` menciona tiene que existir. Por eso, con varios repos, los demás referencian el PRD en prosa y sin ruta: una ruta a otro repo se cobra como huérfana.
* **Zona Prohibida tocada (P0).** Sólo vigila las zonas que declares. Las que el arranque hizo evidentes van a `AI-FIRST.md` antes de la primera feature.
* **Alcance excedido (P1).** Lee la sección «Archivos» o «Alcance» de la spec activa, con las rutas entre acentos graves. La sección «Archivos del módulo» del template ya tiene ese nombre, sin número delante, por esa razón.
* **Inventario de componentes (P2).** Se reporta omitido hasta que `artefactos` declara `inventario_componentes` y `componentes_dir`.

El detalle de cada una está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

El stack va primero porque condiciona todo lo demás y es la decisión más cara de revertir, y las specs van al final porque cada una necesita saber en qué capa vive. La cadena completa, y qué pasa cuando se salta un eslabón, está en [La cadena de artefactos](/docs/parte-2/cadena-de-artefactos/).

## Próximos pasos

[Desarrollar una feature](/docs/guias/desarrollar-una-feature/)Construir lo que el arranque definió, spec por spec.

[Adaptar las skills](/docs/guias/adaptar-las-skills/)La entrevista que fija el perfil y adapta cada skill.

[Templates](/docs/apendices/templates/)Los templates de los que sale cada artefacto.

# Adaptar las skills a tu proyecto

> Qué pregunta la entrevista de init, qué escribe dentro de cada skill, cómo repetirla y cómo instalar más skills.

Tienes las skills instaladas y quieres que hablen de tu proyecto: tus comandos, tu secuencia de implementación, tu manifiesto de versión. Una skill copiada sin adaptar ocupa presupuesto de carga y da instrucciones que no aplican. La entrevista de `init` escribe esa adaptación por ti.

## Cuándo usarla

* Corriste `init` sin terminal interactiva, o con `--sin-entrevista`, y las skills quedaron con su texto genérico.
* Cambió algo que la entrevista pregunta: el comando de verificación, la secuencia de implementación, si trabajas con varios agentes en paralelo.
* Quieres instalar skills que no vinieron por defecto.

Si lo que falta es definir el producto —PRD, arquitectura, specs—, la entrevista no lo hace: es [Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/).

## Antes de empezar

Necesitas una **terminal interactiva**. Sin ella, `init` no entrevista nunca, y `--entrevista` sale con un error en vez de quedarse esperando. Cuándo entrevista `init` por su cuenta:

| El proyecto                                                                | Qué hace `init`                                                 |
| -------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Sin documentación: sin `AI-FIRST.md`, sin `AGENTS.md`, sin nada en `docs/` | Entrevista sin preguntar                                        |
| Ya documentado                                                             | Dice qué encontró y ofrece la entrevista; por defecto, la salta |
| Sin terminal interactiva, o con `--sin-entrevista`                         | No entrevista                                                   |
| Con `--entrevista`                                                         | Entrevista aunque el proyecto esté documentado                  |

## Paso a paso

1. **Corre la entrevista.** Desde la raíz del repo:

   ```bash
   npx @falcux/ai-first@latest init --entrevista
   ```

   `init` nunca sobreescribe: lo que ya existe se salta y se reporta. Correrlo otra vez sobre un repo inicializado es seguro.

2. **Responde.** Todas las preguntas traen un valor por defecto entre corchetes, y Enter lo acepta. Varios salen de tu repo: el nombre, los comandos de `package.json`, el manifiesto.

   | Pregunta                                             | Para qué sirve                                                   |
   | ---------------------------------------------------- | ---------------------------------------------------------------- |
   | Nombre del proyecto                                  | `AI-FIRST.md`                                                    |
   | Fase: exploración, MVP o producción                  | La lee quien abre el archivo; no cambia ninguna verificación     |
   | Clase de producto: saas, landing, api, cli, movil    | Decide qué skills se instalan y qué artefactos pide el arranque  |
   | Forma del repositorio: único, monorepo, varios repos | El perfil, junto con la anterior                                 |
   | Comando que decide que el proyecto está sano         | Las skills que verifican                                         |
   | Comando de tipos y de lint, si hay                   | `protocolo-features` y `test-fix`                                |
   | ¿Varios agentes en paralelo?                         | Si no, la división por agentes se retira de la skill de features |
   | Archivo que lleva el número de versión               | `version-bump`                                                   |
   | Orden en que se implementa una feature               | Las opciones dependen de la clase de producto                    |
   | Una confirmación por cada Zona Prohibida sugerida    | El criterio es el costo de revertir un error ahí                 |

3. **Lee el reporte.** Cada línea dice `escrito`, `saltado` o `sugerido`. Una skill cuyo bloque no cambió aparece como saltada, con la razón.

4. **Revisa cada skill adaptada.** La adaptación vive bajo el encabezado «Adaptación a tu proyecto» de cada `SKILL.md`, entre `<!-- ai-first:inicio -->` y `<!-- ai-first:fin -->`. Debajo, fuera de las marcas, sigue la lista genérica de la skill: lo que la entrevista no cubre se completa ahí, a mano. Puedes pedirle al agente que te diga qué falta:

   ```text
   Lee la sección «Adaptación a tu proyecto» de cada skill en .agents/skills/.
   Para cada una, dime qué puntos de la lista genérica no responde el bloque
   que escribió init. No edites nada todavía.
   ```

5. **Completa fuera de las marcas.** Lo que agregues fuera sobrevive a la siguiente corrida; lo que edites dentro, no. Por ejemplo, los tests intocables de `test-fix` o quién firma el cierre del descubrimiento en `protocolo-arranque`.

## Qué queda escrito

**En cada skill, el bloque entre marcas.** Sólo en las skills para las que la entrevista tiene algo que decir:

| Skill                                                               | Qué recibe                                                                                                             |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `protocolo-arranque`                                                | El perfil y la tabla de artefactos que le corresponden, con su template                                                |
| `protocolo-features`                                                | La secuencia elegida, los comandos, si hay agentes en paralelo y, sin interfaz, qué pasos no aplican                   |
| `test-fix`                                                          | Los comandos y cómo delegar la corrida                                                                                 |
| `version-bump`                                                      | El manifiesto, único sitio donde se escribe el número                                                                  |
| `protocolo-cambios`                                                 | Dónde vive el cambio en curso y el comando de verificación; en monorepo o varios repos, cómo cuenta el flujo corto     |
| `protocolo-cierre`                                                  | La tabla de documentos del proyecto y el comando de verificación; si no hay manifiesto, que el paso del bump no aplica |
| `protocolo-ux`, `ux-writer`, `ux-audit`, `information-architecture` | El perfil y los documentos de diseño, sólo si el producto tiene interfaz                                               |

`i18n` no recibe bloque: la entrevista no pregunta nada que le sirva.

**En `AI-FIRST.md`, la fase y el perfil**, cuando `init` crea el archivo. Si ya existía no lo toca, como a cualquier otro archivo: si el perfil cambió, se edita a mano.

**Las skills del perfil que falten.** Con entrevista, la selección por defecto deja de ser las cinco de siempre:

| Clase de producto | Skills                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------- |
| saas, movil       | Las cinco de base, `protocolo-ux`, `ux-writer`, `ux-audit` e `information-architecture` |
| landing           | Las cinco de base, `protocolo-ux`, `ux-writer` y `ux-audit`                             |
| api, cli          | Las cinco de base                                                                       |

A todas se suma `protocolo-arranque`. Las cinco de base son `protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `version-bump` y `test-fix`. Las que ya estaban se saltan enteras; el bloque se reescribe en todas las de la selección.

### Instalar más skills

`--skills` elige cuáles instalar, separadas por comas, o `todas`:

```bash
npx @falcux/ai-first@latest init --skills ux-writer,i18n
npx @falcux/ai-first@latest init --skills todas
```

Un nombre que el paquete no trae detiene el comando antes de entrevistar, con la lista de las disponibles. El bloque de `AGENTS.md` se reescribe con lo que quedó instalado.

### Las skills enlazadas no se adaptan

Con `--enlazar`, cada skill es un enlace simbólico a la carpeta `skills/` del paquete en vez de una copia. Una skill enlazada **nunca** se adapta: escribir ahí cambiaría la fuente y no tu copia. El reporte la marca como `sugerido` y lo dice.

Nota

Si una skill del paquete choca con una tuya del mismo nombre, `init` salta la del paquete y no toca la tuya. Las tres salidas posibles están en [Las 11 skills](/docs/referencia/skills/).

## Qué vigila el detector

Las skills no son artefactos declarados, así que `audit` no las recorre. Sí recorre `AGENTS.md`, que `init` declara en `artefactos`: el check de **artefacto huérfano (P2)** verifica que existan las rutas y los nombres que menciona, incluidos los de la tabla de skills del bloque. Si borras una skill a mano, vuelve a correr `init` para que el bloque se reescriba con lo que de verdad hay. Ver [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

Las marcas son el manifiesto: separan lo que escribió la herramienta de lo que escribiste tú, y por eso `init` puede reescribir sin pisar nada. Qué es una skill, cómo nace de un protocolo y por qué se adapta a cada proyecto está en [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/).

## Próximos pasos

[ai-first init](/docs/referencia/init/)Todas las opciones del comando.

[Las 11 skills](/docs/referencia/skills/)Qué hace cada skill y cuándo se activa.

[Arrancar un producto](/docs/guias/arrancar-un-producto/)Lo que la entrevista no hace: definir el producto.

# Desarrollar una feature

> Cómo construir un módulo, una página o un endpoint nuevo con protocolo-features y verificarlo con test-fix.

Tienes una feature nueva por construir —una página, un módulo, un endpoint, un formulario— y quieres que el agente la implemente sin inventar requerimientos ni salirse del alcance. `protocolo-features` ordena el trabajo antes y durante el código; `test-fix` lo verifica al final.

## Cuándo usarla

* Feature nuevo: página, módulo, endpoint, formulario o flujo.
* Cualquier implementación que agregue modelos, casos de uso o componentes nuevos.

No es para fixes de bugs, cambios cosméticos ni refactors sin comportamiento nuevo: eso es [Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/). Si la implementación exige cambiar la arquitectura existente, tampoco: es un cambio, no una feature.

## Antes de empezar

`protocolo-features` y `test-fix` vienen en la instalación por defecto. Si todavía no corriste `init`:

```bash
npx @falcux/ai-first@latest init
```

Necesitas además una **spec implementable**: qué hace la feature, criterios de aceptación verificables, qué incluye y qué no, y qué módulos usa y cuáles no debe tocar. Si el producto salió de [Arrancar un producto](/docs/guias/arrancar-un-producto/), está en `docs/specs/`. Si no existe, la skill la genera y te pide validarla antes de implementar.

## Paso a paso

1. **Pide la pre-implementación, sin código.** Son siete pasos obligatorios, y el último deja escrita la secuencia:

   ```text
   Usa protocolo-features para el módulo de reportes (docs/specs/reportes.md).
   Haz sólo la pre-implementación: verifica la spec, arma la tabla de reuso,
   revisa dependencias y deja escrita la secuencia. No escribas código todavía.
   ```

2. **Revisa el plan.** Lo que tiene que traer:

   * La comprobación de **Zonas Prohibidas**: si la feature entra en una, se pide la aprobación o se replantea el enfoque antes de escribir código.
   * La **tabla de reuso**, con una fila por pieza: reusa, extiende, nueva compartida o nueva local. Toda pieza «nueva local» justifica por qué no se pudo reusar. Sin esta tabla, el plan está incompleto.
   * Las **dependencias técnicas**: migración, tipos compartidos, endpoints, claves de i18n.
   * La **secuencia**: qué variante aplica —full-stack, solo-backend o solo-frontend—, qué pasos se omiten y qué comando verifica cada uno.

   Si alguna fila de la tabla es difícil de revertir —un paquete compartido nuevo, un límite entre capas, una dependencia de producción—, va también como fila en `docs/ADR.md`.

3. **Implementa por capas, de adentro hacia afuera.** El orden por defecto va del schema al dominio, la aplicación, la infraestructura de backend, lo compartido y la interfaz, y después los tests. Si la entrevista de `init` fijó otra secuencia, está en la sección «Adaptación a tu proyecto» de la skill. La regla no cambia: no se avanza si el paso actual no compila o rompe tests.

   ```text
   Plan aprobado. Implementa el paso 2 de la secuencia, dominio, y nada más.
   Cuando compile y los tests existentes pasen, muéstrame el diff y espera.
   ```

   Todo texto visible nuevo pasa por `ux-writer` antes de escribirse.

4. **Verifica con test-fix.** Corre los tests del alcance que tocó la sesión, con la salida filtrada para que al contexto sólo lleguen las fallas:

   ```text
   Usa test-fix sobre lo que tocó esta sesión. Unitarios e integración;
   E2E no por ahora.
   ```

   Cada falla se clasifica. Las **mecánicas** —un mock viejo, un import movido, un campo renombrado— se corrigen sin preguntar. Las **de negocio** —el test espera A, el código da B y no está claro cuál es correcto— te las pregunta con opciones. Hay un máximo de dos rondas; si quedan fallas, reporta con diagnóstico y para. Con el alcance en verde, corre la suite completa, tipos y lint una sola vez.

5. **Pasa los checklists.** Técnico, de UX si hay interfaz, y de completitud. El que más se olvida: **lo que estaba fuera de alcance no se implementó**.

6. **Cierra la sesión.** Con `protocolo-cierre`, antes del commit. Ver [Cerrar la sesión](/docs/guias/cerrar-la-sesion/).

Precaución

Detén el trabajo y reevalúa si el agente modifica archivos fuera de la spec, si aparecen más de tres archivos que la spec no nombraba o si los tests existentes empiezan a fallar sin razón aparente.

Los tests E2E se corren sólo si lo pides, nunca como consecuencia de la parte unitaria. Los tests que protegen una invariante de seguridad o de aislamiento no se ajustan: si fallan, es un incidente. Esos se listan en la adaptación de `test-fix`.

## Qué queda escrito

* El código y los tests de la feature, en el orden de la secuencia.
* La spec, si no existía y hubo que generarla.
* Una fila en `docs/ADR.md` por cada decisión difícil de revertir que salió del plan.
* El inventario de componentes al día, en el mismo commit, si se tocó la librería de componentes.

`protocolo-features` no escribe el registro de sesión: eso lo hace `protocolo-cierre`.

## Qué vigila el detector

* **Zona Prohibida tocada (P0).** Si la feature tocó una zona declarada, el hook pre-push detiene el push. Por eso la skill la comprueba en el paso 1.
* **Decisión sin fila en ADR (P1).** Un `package.json` que suma o quita una dependencia de producción, o un archivo de `superficies_de_decision`, sin una fila nueva en el ADR. Se evita escribiendo la fila; si no era decisión, con `<!-- ai-first: sin-decision -->` en el cuerpo del commit.
* **Alcance excedido (P1).** Por defecto `alcance.spec` apunta a `docs/changes/pending/`, y sin un cambio abierto el check se omite. Si apuntas `alcance.spec` a la spec del módulo, su sección «Archivos del módulo» define el alcance de la sesión.
* **Inventario de componentes (P2).** Un componente nuevo en `componentes_dir` que el inventario no menciona, si `AI-FIRST.md` declara las dos claves.

El detalle está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

Sin spec, la AI inventa requerimientos; sin secuencia escrita, los pasos se saltan sobre la marcha. El inventario de reuso es el paso que más deuda evita y el que más se salta. El criterio completo está en el [Protocolo de desarrollo de features](/docs/parte-3/protocolo-features/).

## Próximos pasos

[Cerrar la sesión](/docs/guias/cerrar-la-sesion/)El registro de sesión, los docs y la versión, antes del commit.

[Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/)Cuando la feature toca lo que ya existe.

[Las 11 skills](/docs/referencia/skills/)protocolo-ux, ux-writer e i18n, que entran cuando hay interfaz.

# Cambiar algo que ya funciona

> Cómo modificar una feature implementada con protocolo-cambios, su documento CHG y el alcance que el detector compara contra el commit.

Tienes algo que ya funciona y tiene que cambiar: un requerimiento que se movió, algo que la AI implementó mal, un patrón que no aguanta en mobile. Quieres cambiarlo sin que el agente lo reconstruya desde cero ni toque lo que no debe.

## Cuándo usarla

* Un requerimiento cambia después de implementado.
* La AI implementó algo incorrecto y hay que corregirlo.
* Un patrón no funciona en la práctica y necesita ajustarse.
* Cambian prioridades que afectan features existentes.
* Cambia un documento de gobierno, como un artefacto que escribió el arranque.

No es para un typo o un botón roto, ni para un refactor que no cambia comportamiento. Una feature nueva que no toca nada existente es [Desarrollar una feature](/docs/guias/desarrollar-una-feature/).

## Antes de empezar

`protocolo-cambios` viene en la instalación por defecto, con el molde del documento de cambio dentro, en su carpeta `references/`. `init` deja además la carpeta `docs/changes/pending/`, el registro `docs/changes/CHANGE_LOG.md` y, en `AI-FIRST.md`, la línea que hace que el detector lea el cambio en curso:

```yaml
alcance:
  spec: docs/changes/pending/
```

Si tu `AI-FIRST.md` ya existía cuando corriste `init`, esa línea no se escribe: el reporte la deja como sugerida y hay que agregarla a mano.

## Paso a paso

1. **Clasifica el cambio.** Hay cuatro tipos —corrección, ajuste de diseño, cambio de requerimiento, cambio de prioridad— y dos flujos:

   | Flujo    | Cuándo                                                            |
   | -------- | ----------------------------------------------------------------- |
   | Corto    | 1–2 archivos, sin cambio de schema                                |
   | Completo | 3 o más archivos, cambia el schema o cambian flujos de navegación |

   Si el cambio toca una Zona Prohibida, se pide la aprobación antes de escribir el documento, no después.

2. **Escribe el CHG antes de tocar código.** Va en `docs/changes/pending/CHG-XXX_nombre.md`, con el número correlativo siguiente, copiado del molde de la skill:

   ```text
   Usa protocolo-cambios. El listado de clientes pagina de a 20 y el equipo de
   ventas necesita filtrar por país. Clasifica el cambio, dime si es flujo corto
   o completo y escribe el CHG en docs/changes/pending/. No implementes nada.
   ```

   El corazón del documento es el par **estado actual / estado deseado**. Sin el estado actual descrito con precisión, la AI reconstruye el feature en vez de modificarlo. El flujo corto llena Metadata, §1 a §4, §9, §10, §13 y §14; el completo, todo.

3. **Declara los archivos afectados entre acentos graves.** Es lo que el detector compara contra lo que el commit tocó de verdad. El título de la subsección tiene que **empezar** por «Archivos» o «Alcance», sin número delante:

   ```md
   ### Archivos afectados


   - [ ] `src/clientes/listado.ts` — agrega el filtro por país
   - [ ] `src/clientes/listado.test.ts` — casos del filtro
   - [ ] `src/clientes/componentes/**` — el selector nuevo
   ```

4. **Analiza el impacto en una sesión aparte.** En el flujo completo, una sesión dedicada que no modifica nada: archivos afectados directa e indirectamente, migraciones, tests que van a fallar, contradicciones con `AGENTS.md` o la spec, y lógica existente que cubra parte del cambio.

5. **Implementa por pasos, en una sesión limpia.** Nunca en la misma sesión donde se trabajó en otra cosa. Cada paso toca tres archivos o menos; si no, se subdivide.

   ```text
   Vamos a implementar CHG-012 (docs/changes/pending/CHG-012_filtro-pais.md).
   Implementa SOLO el paso 1. Muéstrame el diff y no avances hasta que confirme.
   ```

   Para un cambio de requerimiento o de prioridad, la skill pide una rama propia: `git checkout -b change/CHG-XXX-nombre`.

6. **Verifica.** Contra el estado deseado del documento, los tests relevantes y, si el cambio tocó la interfaz, el skeleton: es la deriva que más se pierde en el flujo corto.

7. **Cierra.** Actualiza los docs afectados, agrega el resumen a `docs/changes/CHANGE_LOG.md` y **elimina** el archivo de `pending/`.

Nota

Un cambio que además es una decisión —difícil de revertir, con alternativas reales que se descartaron— lleva también su fila en `docs/ADR.md`, en el mismo commit que el CHG. No es duplicar: el CHG documenta qué cambió y se archiva; el ADR documenta por qué y sobrevive. La §6 del documento hace esa pregunta.

## Qué queda escrito

| Archivo                                                        | Cuándo                                                |
| -------------------------------------------------------------- | ----------------------------------------------------- |
| `docs/changes/pending/CHG-XXX_nombre.md`                       | Al abrir el cambio; se elimina al cerrarlo            |
| `docs/changes/CHANGE_LOG.md`                                   | Al cerrar: fecha, tipo, archivos, resumen y lecciones |
| `docs/ADR.md`                                                  | Si la §6 del documento dijo que sí                    |
| La spec del módulo, el PRD, la arquitectura, la guía de diseño | Los que el cambio afectó, al cerrar                   |

Un archivo en `pending/` sin actividad por dos semanas o más se revisa, y si ya no aplica pasa al registro como «Descartado».

## Qué vigila el detector

**Alcance excedido (P1)** es el check de esta guía. Con `alcance.spec` apuntando a `docs/changes/pending/`, `audit` toma cada documento de esa carpeta, busca la sección cuyo título empieza por «Archivos» o «Alcance» y extrae las rutas entre acentos graves, con globs. Los archivos tocados que no coinciden con ninguna, por encima de la tolerancia, son un P1. La tolerancia es 0 si `alcance.tolerancia` no la declara.

* No cuentan como fuera de alcance `AI-FIRST.md`, la propia carpeta de cambios ni los artefactos declarados en `AI-FIRST.md`.
* Los placeholders con `{llaves}` y `XXX` del molde se ignoran.
* Sin ningún CHG abierto, el check se reporta **omitido**, no aprobado: no hay alcance que exceder. Con un CHG que no lista rutas, también se omite, y la razón lo dice.

Para evitar el hallazgo, declara los archivos en el CHG antes de implementar y, si el trabajo crece, actualiza la lista antes del commit. Si al cerrar no eliminas el documento de `pending/`, sigue contando como cambio abierto en la sesión siguiente.

Si el cambio suma una dependencia de producción o toca una superficie de decisión, también aplica **Decisión sin fila en ADR (P1)**. El detalle de los cinco checks está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

Un cambio sin evaluación de impacto es una apuesta: el documento existe para que el humano entienda qué se toca y qué se puede romper antes de que la AI ejecute. El criterio completo está en el [Protocolo de gestión de cambios](/docs/parte-3/protocolo-cambios/).

## Próximos pasos

[Cerrar la sesión](/docs/guias/cerrar-la-sesion/)El registro de sesión y la versión, después del cambio.

[Las cinco verificaciones](/docs/referencia/verificaciones/)Cómo lee el detector el alcance, con el resto de los checks.

[documento-de-cambio.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cambios/references/documento-de-cambio.md)El molde completo del CHG, tal como viaja con la skill.

# Cerrar la sesión

> Cómo cerrar un tramo de trabajo con protocolo-cierre y version-bump, para que la sesión siguiente arranque con el contexto al día.

Terminaste un tramo de trabajo con cambios en el código y quieres que la próxima sesión, tuya o de otro, lo retome sin reconstruir qué pasó. `protocolo-cierre` documenta la sesión; `version-bump` decide el número de versión que viaja en el mismo commit.

## Cuándo usarla

* Al terminar una sesión de implementación de features.
* Al terminar una corrección de bugs que modificó comportamiento.
* Al terminar una sesión de gestión de cambios.
* Al terminar un refactor que afectó la arquitectura.

No hace falta en sesiones exploratorias sin cambios de código, en fixes de typos ni en sesiones de sólo lectura. Si todavía no verificaste los tests, eso va antes: `test-fix`, en [Desarrollar una feature](/docs/guias/desarrollar-una-feature/).

## Antes de empezar

Las dos skills vienen en la instalación por defecto, y `init` deja el registro que el cierre escribe, `docs/SESSION_LOG.md`, vacío y con su cabecera. Para que `version-bump` clasifique bien, el proyecto necesita commits convencionales —`feat:`, `fix:`, `docs:`—; sin ellos, la clasificación cae en leer el diff, que es más lento y menos confiable.

El cierre tiene tres fases, y sólo la primera es del agente:

| Fase           | Quién                             |
| -------------- | --------------------------------- |
| A — Documentar | El agente, con `protocolo-cierre` |
| B — Verificar  | El humano, no delegable           |
| C — Commit     | El humano, no delegable           |

## Paso a paso

1. **Pide la Fase A.** Antes del commit:

   ```text
   Usa protocolo-cierre para cerrar esta sesión. No hagas commit.
   ```

   El agente reúne el contexto objetivo con `git diff --name-only HEAD`, `git status --short` y `git log --oneline -10`, y lee las últimas dos entradas del registro de sesión y el registro de cambios. Lo que no aparece en el diff no pasó.

2. **Deja que revise las migraciones.** Si el schema cambió y no hay migración nueva, lo avisa en el reporte como bloqueante suave. No la ejecuta por su cuenta.

3. **Revisa la entrada del registro.** Va al tope de `docs/SESSION_LOG.md`, con el número de sesión siguiente: resumen, cambios por área, validación y pendientes. Si un check no se corrió, dice «no ejecutado», nunca un PASS inventado.

4. **Revisa los docs que tocó.** Sólo los que la sesión afectó: `AGENTS.md` si cambió una regla activa, `docs/ADR.md` si hubo una decisión, el inventario de componentes si se tocó uno compartido, el registro de cambios si un cambio se completó. Los aprendizajes van a **un** destino según su tipo, no a todos.

5. **Decide la versión.** El cierre clasifica la sesión y, si amerita bump, pasa a `version-bump`:

   ```text
   Usa version-bump. Analiza los commits desde el último tag y recomiéndame
   el bump. No apliques nada hasta que confirme.
   ```

   La regla del máximo manda: un solo commit MAJOR en el rango gana sobre cualquier cantidad de PATCH. Sin tu confirmación explícita, no aplica nada. Con ella, actualiza todos los manifiestos a la misma versión y fecha la entrada del CHANGELOG en ese mismo commit.

6. **Haz la Fase B.** El reporte termina con tu lista: si el resumen refleja lo que hiciste, si los docs son precisos, si los aprendizajes son reales, si pasa la suite completa, si quedó algo sin documentar y, si hubo bump, si las versiones quedaron sincronizadas.

7. **Haz la Fase C.** Un commit con el código y los docs juntos. Después, el tag lo creas tú, con el número que confirmaste:

   ```bash
   git tag v0.Y.Z && git push origin v0.Y.Z
   ```

Precaución

El tag va después del commit de cierre, nunca antes. Un tag creado antes apunta a un commit que no tiene los manifiestos actualizados. Por eso `version-bump` no lo crea.

## Qué queda escrito

| Archivo                                                                             | Quién lo escribe                                                        |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `docs/SESSION_LOG.md`                                                               | `protocolo-cierre`, una entrada nueva al tope                           |
| `AGENTS.md`, `docs/ADR.md`, guía de diseño, inventario de componentes, arquitectura | `protocolo-cierre`, sólo los que la sesión afectó                       |
| `docs/TECH_NOTES.md`                                                                | `protocolo-cierre`, si el aprendizaje es una cicatriz de stack          |
| `docs/changes/CHANGE_LOG.md`                                                        | `protocolo-cierre`, si un cambio se completó; el CHG sale de `pending/` |
| Los manifiestos, como `package.json`                                                | `version-bump`, tras tu confirmación                                    |
| La entrada del CHANGELOG                                                            | `version-bump`, con la fecha del bump                                   |

Ninguna de las dos toca código ni hace commits.

## Qué vigila el detector

* **Decisión sin fila en ADR (P1).** Si la sesión sumó o quitó una dependencia de producción, o tocó una superficie de decisión, el ADR tiene que ganar una fila en el mismo rango. El detector la reconoce por su encabezado, `## ADR-NNN` o `### ADR-NNN`. Si el cambio no era una decisión, se silencia con `<!-- ai-first: sin-decision -->` en el cuerpo del commit; esa anotación sólo se lee en modo rango, con `--base`.
* **Artefacto huérfano (P2).** Si el cierre nombra en `AGENTS.md` o en el ADR un archivo que ya no existe, se reporta. El registro de sesión no se declara como artefacto: es cronología, y nombra con razón cosas que ya se retiraron.
* **Alcance excedido (P1).** Si el CHG del cambio que cerraste sigue en `pending/`, el detector lo sigue leyendo como abierto.

El detalle de cada una está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

La AI puede describir lo que hizo, pero no puede juzgar si está bien, y un commit es una firma que tiene dueño: por eso sólo la Fase A se delega. El criterio completo está en el [Protocolo de cierre de sesión](/docs/parte-3/protocolo-cierre/).

## Próximos pasos

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)Lo que corre en el push, después del commit de cierre.

[Las 11 skills](/docs/referencia/skills/)protocolo-cierre y version-bump, con las demás.

[Protocolo de cierre de sesión](/docs/parte-3/protocolo-cierre/)El capítulo del manual.

# Auditar en local y en CI

> Cómo funciona el punto de control que deja init, el hook pre-push y el flujo de GitHub Actions, y cómo correr el detector en otro CI o desde una herramienta.

Tienes el proyecto inicializado y quieres que la entropía documental se mida sola, sin depender de que alguien se acuerde de correr `audit`. `init` deja escrito el punto de control: el mismo detector en dos sitios, con tolerancias distintas.

| Dónde                                  | Cuándo corre                      | Qué lo detiene                       |
| -------------------------------------- | --------------------------------- | ------------------------------------ |
| Hook de git `.githooks/pre-push`       | En cada `git push`, en tu máquina | Sólo un P0                           |
| Flujo `.github/workflows/ai-first.yml` | En cada pull request              | Cualquier hallazgo, con `--estricto` |

## Cuándo usarla

* Acabas de correr `init` y quieres entender qué dejó en el push y en los pull requests.
* Tu CI no es GitHub Actions y necesitas el comando para montarlo.
* Quieres leer el resultado desde otra herramienta, o guardarlo en `AI-FIRST.md`.

Si lo que quieres es evitar un hallazgo concreto, la guía del flujo que lo produce lo explica: [Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/) para el alcance, [Cerrar la sesión](/docs/guias/cerrar-la-sesion/) para la fila del ADR.

## Antes de empezar

`init` escribe los dos por defecto. `--sin-hook` y `--sin-ci` los omiten, y `--hook-local` deja el hook en `.git/hooks/`, que no viaja en el clon, en vez de `.githooks/`, que sí viaja y se revisa en un PR.

El hook no baja nada de la red: usa el detector del proyecto, el del `PATH` o el que `npx` ya tenga en su caché. Para que siempre lo encuentre, instálalo como dependencia de desarrollo:

```bash
pnpm add -D @falcux/ai-first
```

## Paso a paso

1. **Corre el detector a mano una vez.** Sin opciones, compara el árbol de trabajo contra `HEAD`:

   ```bash
   npx @falcux/ai-first@latest audit
   ```

   Un repo recién inicializado, sin cambios:

   ```text
   ai-first audit — demo
   árbol de trabajo contra HEAD · 0 archivos tocados


   ✓ Zona Prohibida tocada
   ✓ Decisión sin fila en ADR
   – Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
   ✓ Artefacto huérfano
   – Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


   Entropía: 0 / 100 (0 P0 · 0 P1 · 0 P2)
   ```

   Un check omitido no es un check aprobado: le falta lo que necesita para correr, y la razón lo dice.

2. **Mira qué hace el hook.** `init` lo escribe en `.githooks/pre-push` y apunta `core.hooksPath` a esa carpeta. En cada push, toma como base lo que el remoto ya tiene y corre `audit --base` sobre ese rango; si la rama todavía no existe en el remoto, corre contra el árbol de trabajo. Corre **sin `--estricto`**: un P1 o un P2 se imprimen y el push sigue. Un P0 lo detiene. Así se ve uno, en el mismo repo después de tocar `.env.local`:

   ```text
   ai-first audit — demo
   árbol de trabajo contra HEAD · 2 archivos tocados


   ✗ Zona Prohibida tocada
       P0  Zona Prohibida «.env*» tocada — credenciales
             .env.local
   ✓ Decisión sin fila en ADR
   – Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
   ✓ Artefacto huérfano
   – Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


   Entropía: 40 / 100 (1 P0 · 0 P1 · 0 P2)
   ```

   Si no encuentra `node` o el detector, avisa y deja pasar el push: no encontrarse a sí mismo no es motivo para frenar a nadie.

3. **Sáltalo cuando haga falta.** Si el push tiene que salir igual, lo decides tú:

   ```bash
   git push --no-verify
   ```

   El hook no lo combate. El detector informa; la disciplina es del equipo.

4. **Revisa el flujo de CI.** Es el archivo que escribe `init`, tal cual:

   ```yaml
   # El punto de control de la metodología AI-First, en integración continua.
   #
   # Lo escribe `ai-first init`. A diferencia del hook local, éste corre **con
   # `--estricto`**: acá el corte por P1 y P2 sí se quiere, porque hay un humano
   # revisando y el costo de parar es un rebote, no una interrupción.
   name: ai-first


   on:
     pull_request:


   jobs:
     auditar:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with:
             # El detector compara contra la rama base: sin historia no hay rango.
             fetch-depth: 0
         - uses: actions/setup-node@v4
           with:
             node-version: 22
         - name: Entropía documental
           run: npx --yes @falcux/ai-first audit --base "origin/${{ github.base_ref }}" --estricto
   ```

   Tres cosas sostienen el paso. `fetch-depth: 0` trae la historia: sin ella, la rama base no existe en el checkout y `audit` sale con código 2, avisando que la ref no existe en el repositorio. `--base` compara el rango de la rama base a `HEAD`, que es lo que el pull request agrega. `--estricto` hace que un P1 o un P2 también fallen el paso.

5. **Móntalo en otro CI, si no usas GitHub.** El paso es el mismo comando, con Node 22.12 o superior, la historia completa del repo y la rama base del pull request o merge request:

   ```bash
   npx --yes @falcux/ai-first@latest audit --base "origin/<rama base>" --estricto
   ```

Precaución

Un `core.hooksPath` ya configurado —por husky, lefthook u otro gestor de hooks— no se pisa: el reporte de `init` lo marca como `sugerido` y te dice que muevas el hook a esa carpeta o cambies la configuración. Cambiarlo apagaría los hooks que ya tenías.

### Los códigos de salida

| Código | Cuándo                                                                              |
| ------ | ----------------------------------------------------------------------------------- |
| 0      | Sin hallazgos, o sólo P1 y P2 sin `--estricto`                                      |
| 1      | Cualquier P0, o cualquier hallazgo con `--estricto`                                 |
| 2      | Error de uso: no es un repo git, no hay `AI-FIRST.md`, la ref de `--base` no existe |

### Para una herramienta: `--json`

Con `--json`, la misma información sale en JSON. Es la salida real del ejemplo del P0 de arriba:

```json
{
  "proyecto": "demo",
  "modo": "arbol",
  "cambiados": [
    ".env.local",
    "src/a.ts"
  ],
  "resultados": [
    {
      "check": "zona-prohibida",
      "estado": "hallazgos",
      "hallazgos": [
        {
          "severidad": "P0",
          "ruta": ".env*",
          "mensaje": "Zona Prohibida «.env*» tocada — credenciales",
          "detalle": [
            ".env.local"
          ]
        }
      ]
    },
    {
      "check": "decision-sin-adr",
      "estado": "aprobado"
    },
    {
      "check": "alcance-excedido",
      "estado": "omitido",
      "razon": "no hay ninguna spec activa en docs/changes/pending/"
    },
    {
      "check": "artefacto-huerfano",
      "estado": "aprobado"
    },
    {
      "check": "inventario-componentes",
      "estado": "omitido",
      "razon": "faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»"
    }
  ],
  "conteo": {
    "p0": 1,
    "p1": 0,
    "p2": 0
  },
  "entropia": 40,
  "codigoDeSalida": 1
}
```

`modo` es `arbol` sin `--base` y `rango` con ella. El código de salida del proceso es el mismo que `codigoDeSalida`.

### Para guardar la lectura: `--registrar`

`--registrar` escribe el resultado en el bloque `auditoria` del frontmatter de `AI-FIRST.md`: la fecha, la entropía y el conteo de P0, P1 y P2. Sólo lo escribe cuando lo pides, y sólo reemplaza ese bloque, sin tocar el resto del frontmatter. Como cualquier cambio del repo, queda en la historia si lo commiteas.

```bash
npx @falcux/ai-first@latest audit --registrar
```

## Qué queda escrito

| Archivo                                | Qué es                                                            |
| -------------------------------------- | ----------------------------------------------------------------- |
| `.githooks/pre-push`                   | El hook, ejecutable; con `--hook-local`, en `.git/hooks/pre-push` |
| `core.hooksPath`                       | La configuración local de git que apunta a `.githooks/`           |
| `.github/workflows/ai-first.yml`       | El flujo de GitHub Actions                                        |
| El bloque `auditoria` de `AI-FIRST.md` | Sólo con `--registrar`                                            |

## Qué vigila el detector

Esta guía es el detector: los cinco checks corren en los dos sitios. Lo que cambia es qué detiene el trabajo. En el hook, sólo **Zona Prohibida tocada (P0)**. En CI, también **Decisión sin fila en ADR** y **Alcance excedido** (P1), y **Artefacto huérfano** e **Inventario de componentes** (P2). El puntaje es `min(100, 40·P0 + 20·P1 + 8·P2)`: más alto es peor. Qué detecta cada uno y cómo se evita está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Por qué funciona así

Un hook que bloquea por todo se desinstala, y con él se van los cinco checks. En el push se interrumpe a una persona en medio de su trabajo, y sólo lo justifica un P0; en un pull request hay un humano revisando, y el costo de parar es un rebote. Los instrumentos que el detector verifica están en [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/); cómo se adopta el método en un equipo, fase por fase, en [Escalar al equipo y costos](/docs/parte-4/escalar-y-costos/).

## Próximos pasos

[ai-first audit](/docs/referencia/audit/)Todas las opciones, el puntaje y los códigos de salida.

[Las cinco verificaciones](/docs/referencia/verificaciones/)Qué detecta cada check y con qué severidad.

[El formato de AI-FIRST.md](/docs/referencia/ai-first-md/)Las claves que el detector lee.

# Solución de problemas

> Los problemas conocidos de init, audit y el hook de pre-push, cada uno con su síntoma, su causa y qué hacer.

Los problemas que se conocen con `@falcux/ai-first` 0.5.1, cada uno con el síntoma que ves, la causa y qué hacer. Si el tuyo no está, revisa primero qué versión corres con `npx @falcux/ai-first@latest --version`.

## El hook dice que no encuentra node

**Síntoma.** Al hacer push aparece esto y el push sigue sin auditar:

```text
ai-first: no encuentro node, así que el punto de control no corrió.
          Si empujas desde un cliente gráfico, arráncalo desde una
          terminal o deja node en /usr/local/bin.
```

**Causa.** Un push lanzado desde un cliente gráfico, un IDE o un servicio del sistema no hereda el PATH de tu shell, que es donde nvm, Homebrew o fnm dejan `node`. El hook lo busca en `/opt/homebrew/bin`, `/usr/local/bin` y en `nvm.sh`; si aun así no aparece, avisa y deja pasar. No encontrar `node` nunca frena un push.

**Qué hacer.** Arranca el cliente desde una terminal, para que herede su PATH, o deja `node` en `/usr/local/bin`. Hasta entonces, el CI sigue auditando cada pull request.

## El hook dice que ai-first no está instalado

**Síntoma.**

```text
ai-first: no está instalado, así que el punto de control no corrió.
          Instálalo con «pnpm add -D @falcux/ai-first» o quita este hook.
```

**Causa.** El hook no descarga nada. Busca el `ai-first` de `node_modules`, luego el del PATH, y sólo usa `npx --no-install` si el paquete ya está en la caché de npx. Si no encuentra ninguno, avisa y deja pasar.

**Qué hacer.** Instálalo como dependencia de desarrollo, como sugiere el mensaje, para que todo el equipo corra la misma versión.

## init reporta «saltado» o «sugerido»

**Síntoma.** El reporte de `init` trae líneas como éstas:

```text
  saltado  AI-FIRST.md (ya existe)
  saltado  AGENTS.md (el bloque ya está al día)
  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks
```

**Causa.** `init` nunca sobreescribe. `saltado` es algo que ya existía y no se tocó; no es un error. `sugerido` es algo que haría falta cambiar en un archivo o una configuración tuya: en vez de cambiarlo, te dice qué agregar. Una skill cuya carpeta ya existe se salta entera.

**Qué hacer.** Lee la razón de cada `sugerido` y aplícala a mano si te sirve. Si quieres la versión del paquete de algo que se saltó, borra la tuya y vuelve a correr `init`: sólo escribe lo que falta. Si una skill chocó con una tuya del mismo nombre, las salidas están en [Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/#si-un-nombre-ya-est%C3%A1-ocupado).

## core.hooksPath ya estaba configurado

**Síntoma.** El push no pasa por el hook de ai-first, y el reporte de `init` dijo:

```text
  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks
```

**Causa.** El repo ya usaba husky, lefthook u otra carpeta de hooks. `init` escribió `.githooks/pre-push`, pero no cambió `core.hooksPath`: hacerlo habría apagado los hooks que ya tenías. Git sigue leyendo la carpeta anterior.

**Qué hacer.** Una de dos: mueve el contenido de `.githooks/pre-push` al `pre-push` de la carpeta que ya usas, o apunta git a `.githooks` si ya no necesitas la otra:

```bash
git config core.hooksPath .githooks
```

## audit sale con código 1

**Síntoma.** `audit` termina con código 1 y el hook frena el push, o el check del pull request queda en rojo.

```text
ai-first audit — demo
árbol de trabajo contra HEAD · 2 archivos tocados


✗ Zona Prohibida tocada
    P0  Zona Prohibida «.env*» tocada — credenciales
          .env.local
✓ Decisión sin fila en ADR
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


Entropía: 40 / 100 (1 P0 · 0 P1 · 0 P2)
```

**Causa.** Hay al menos un P0: se tocó una Zona Prohibida. Sin `--estricto`, es lo único que hace salir con 1. Con `--estricto`, que es como corre el flujo de CI, también sale con 1 ante cualquier P1 o P2.

**Qué hacer.** Si el cambio en la zona fue un error, reviértelo. Si fue deliberado y aprobado, la zona está bien declarada y el hallazgo cumplió su función: decide con tu equipo si se publica. Si la zona no debía serlo, quítala de `zonas_prohibidas` en `AI-FIRST.md`. Qué significa cada hallazgo está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## audit sale con código 2

**Síntoma.** `audit` o `init` terminan con código 2 y un mensaje que empieza por `ai-first:`, por ejemplo:

```text
ai-first: No hay AI-FIRST.md en /ruta/a/tu/proyecto.
```

**Causa.** El código 2 es un error de uso, no un hallazgo: no hay `AI-FIRST.md`, su formato no se puede leer, la carpeta no es un repositorio git, la ref de `--base` no existe, dos opciones se contradicen, se pidió una skill que el paquete no trae o el bloque de `AGENTS.md` tiene una marca sin su pareja. Una opción desconocida también sale con 2, aunque con una traza de Node en vez de un mensaje propio.

**Qué hacer.** Lee el mensaje: dice qué falta. Si no hay `AI-FIRST.md`, corre `npx @falcux/ai-first@latest init`. Para ver las opciones válidas, `npx @falcux/ai-first@latest --help`.

## Un check aparece como omitido

**Síntoma.** Una línea empieza con `–` y dice «omitido»:

```text
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»
```

**Causa.** El check no tenía con qué correr. Omitido no es aprobado: no se verificó nada, y la razón dice qué falta. Alcance se omite mientras no haya un cambio abierto en `docs/changes/pending/`, que es lo correcto. Inventario se omite mientras `AI-FIRST.md` no declare el inventario y la carpeta de componentes.

**Qué hacer.** Nada, si el proyecto no tiene eso. Si lo tiene, declara lo que la razón pide en `AI-FIRST.md`. Si hay componentes, `init` deja las dos líneas comentadas bajo `artefactos`, listas para descomentar.

## Un P1 por «Decisión sin fila en ADR» que no es una decisión

**Síntoma.** Tocaste una superficie de decisión o cambiaste las dependencias de producción de un `package.json`, no era una decisión arquitectónica, y aparece un P1. Así se ve tras agregar una dependencia:

```text
ai-first audit — nuevo
árbol de trabajo contra HEAD · 1 archivo tocado


✓ Zona Prohibida tocada
✗ Decisión sin fila en ADR
    P1  Hay señales de decisión arquitectónica y ADR.md no ganó ninguna fila
          package.json: +zod
          Silenciar: agregar la fila al ADR, o «<!-- ai-first: sin-decision -->» en el cuerpo del commit.
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


Entropía: 20 / 100 (0 P0 · 1 P1 · 0 P2)
```

Sin `--estricto` el código de salida es 0: el P1 avisa, no frena.

**Causa.** El check es una heurística: una superficie tocada, o una dependencia de producción agregada o quitada, se presume decisión. A veces no lo es, como cambiar un número de versión en un archivo de configuración.

**Qué hacer.** Si era una decisión, agrega la fila al ADR. Si no, escribe esta anotación en el cuerpo del commit:

```text
<!-- ai-first: sin-decision -->
```

Por ejemplo:

```bash
git commit -m "chore: sube la version en la configuracion" -m "<!-- ai-first: sin-decision -->"
```

La anotación sólo se lee en modo rango, con `--base`: es como corren el flujo de CI y el hook cuando la rama ya existe en el remoto. En modo árbol de trabajo no hay commits donde buscarla; ahí el P1 se imprime pero no frena nada salvo con `--estricto`. No quites la superficie de `superficies_de_decision` para silenciarlo: ahí viven las decisiones reales.

## Necesito publicar sin pasar por el hook

**Síntoma.** El hook frena un push que tienes que hacer igual.

**Causa.** El hook corre `audit` sin `--estricto`, así que lo frena un P0 —una Zona Prohibida tocada— o un error de uso con código 2, como un `AI-FIRST.md` que no se puede leer. El mensaje de `audit` dice cuál de los dos.

**Qué hacer.** Si es deliberado:

```bash
git push --no-verify
```

Precaución

`--no-verify` salta el hook, no el flujo de CI: el pull request se audita igual, con `--estricto`. El detector informa; la disciplina es del equipo.

## Relacionado

[ai-first audit](/docs/referencia/audit/)Modos, opciones y códigos de salida.

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)El hook, el flujo de CI y cómo leer lo que reportan.

[Novedades](/docs/novedades/)Qué cambió en cada versión publicada.

# ai-first init

> Qué escribe init, sus opciones, qué skills instala, cómo reporta lo que ya existía y cómo funciona la entrevista.

`init` deja un repositorio listo para la metodología en un comando: escribe `AI-FIRST.md` y los registros que los protocolos asumen, instala las skills, monta el punto de control y mantiene un bloque en `AGENTS.md`. Nunca sobreescribe: lo que ya existe se salta y se reporta.

## Uso

```text
ai-first init  [--raiz <dir>] [--enlazar] [--skills <lista>|todas]
               [--entrevista | --sin-entrevista]
               [--sin-hook] [--hook-local] [--sin-ci]
```

Para correrlo sin instalar nada, desde la raíz del proyecto:

```bash
npx @falcux/ai-first@latest init
```

El `@latest` importa: si alguna vez corriste una versión anterior, `npx` puede reutilizar la que guardó en su caché sin preguntarle al registro. Y el subcomando también: `npx @falcux/ai-first` a secas sólo imprime la ayuda.

## Qué escribe

En este orden, que es también el del reporte:

1. **`.git/`**, sólo si la carpeta todavía no era un repositorio: corre `git init` y sigue. No crea commits.
2. **`AI-FIRST.md`**, con lo que encontró el escaneo: Zonas Prohibidas sugeridas, superficies de decisión y documentos existentes. El formato está en [El formato de AI-FIRST.md](/docs/referencia/ai-first-md/).
3. **`docs/ADR.md`**, vacío salvo por su cabecera y el molde de una fila entre comentarios. Si el repo ya tiene `ADR.md` o `docs/ADR.md`, se usa ése.
4. **`docs/SESSION_LOG.md`** y **`docs/changes/CHANGE_LOG.md`**, con su cabecera, y **`docs/changes/pending/`**, que se crea con un `.gitkeep`.
5. **Las skills**, cada una en `.agents/skills/<nombre>/`. Cuáles, en [Qué skills instala](#qu%C3%A9-skills-instala).
6. **La adaptación de cada skill**, sólo si hubo entrevista: un bloque dentro de su sección «Adaptación a tu proyecto».
7. **`.claude/skills`**, un enlace simbólico relativo a `.agents/skills/` para que Claude Code las lea.
8. **El hook de git**: `.githooks/pre-push`, ejecutable, y `core.hooksPath` apuntando a `.githooks` en la configuración local del repo. Con `--hook-local` va a `.git/hooks/pre-push` y la configuración no se toca.
9. **`.github/workflows/ai-first.yml`**, el flujo de integración continua.
10. **El bloque de `AGENTS.md`**, entre `<!-- ai-first:inicio -->` y `<!-- ai-first:fin -->`: qué skills hay instaladas, cuándo se invoca cada una y dónde escribe cada una. Si `AGENTS.md` no existe, lo crea con una cabecera mínima que apunta al template.

La configuración de git que toca es sólo la del repo, y sólo `core.hooksPath` cuando estaba vacía. La global del usuario, nunca.

### Qué busca el escaneo

`init` no pregunta lo que puede deducir. Mira los archivos que git conoce, seguidos o nuevos no ignorados:

| Qué                     | Dónde lo busca                                                                                                                                                                                            | Qué hace con ello                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Nombre del proyecto     | `name` de `package.json`, sin el scope; si no hay, el nombre de la carpeta                                                                                                                                | `proyecto`                                                           |
| Comando de verificación | Los scripts `build` y `test` de `package.json`, con el gestor que indique el lockfile                                                                                                                     | `verificacion`; sin scripts, queda comentado                         |
| Zonas Prohibidas        | `migrations/`, `prisma/migrations/`, `supabase/migrations/`, `db/migrations/`, `infra/`, `terraform/` y `LICENSE`, si existen. `.env*` se sugiere siempre                                                 | `zonas_prohibidas`, con una razón por defecto que tienes que revisar |
| Superficies de decisión | `**/*.config.*`, `**/schema.prisma`, `pnpm-workspace.yaml`, `turbo.json`, `Dockerfile`, `docker-compose*.yml`, `wrangler.*`, `vercel.json`, `netlify.toml`, `.github/workflows/*.yml`, si alguno coincide | `superficies_de_decision`; sin coincidencias, queda comentado        |
| Documentos              | `AGENTS.md`, `ARQUITECTURA.md`, `GUIA_DISENO.md`, `TECH_NOTES.md`, `SESSION_LOG.md`, `CHANGE_LOG.md`, `COMPONENT_LIBRARY.md` y sus variantes, en la raíz o en `docs/`                                     | `artefactos`, más `adr` y `agents` siempre                           |
| Carpeta de componentes  | `src/components/`, `components/`, `app/components/`, `packages/ui/src/components/`                                                                                                                        | Deja comentadas las dos claves del check 5 para que las actives tú   |

Nota

`init` declara `agents` y `adr` como artefactos, pero no el registro de sesión ni el de cambios aunque los escriba: son cronología, nombran archivos que ya se retiraron, y la verificación de artefactos huérfanos los cobraría para siempre.

## Opciones

| Opción             | Qué hace                                                                                                                                                                                                             | Por defecto                                           |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `--raiz <dir>`     | Raíz del repositorio.                                                                                                                                                                                                | El directorio actual                                  |
| `--enlazar`        | Instala las skills como enlaces simbólicos relativos a la carpeta `skills/` del paquete, en vez de copiarlas. Para el repo del paquete y para quien lo vendoriza en un monorepo. Una skill enlazada nunca se adapta. | Copia                                                 |
| `--skills <lista>` | Cuáles instalar, separadas por comas, o `todas`. Un nombre que el paquete no trae detiene el comando antes de instalar nada.                                                                                         | Ver [Qué skills instala](#qu%C3%A9-skills-instala)    |
| `--entrevista`     | Entrevista aunque el proyecto ya esté documentado. Necesita una terminal interactiva.                                                                                                                                | Entrevista sólo si el proyecto no tiene documentación |
| `--sin-entrevista` | No entrevista nunca, ni en un repo vacío.                                                                                                                                                                            | —                                                     |
| `--sin-hook`       | No escribe el hook de git ni toca `core.hooksPath`.                                                                                                                                                                  | Escribe el hook                                       |
| `--hook-local`     | El hook va a `.git/hooks/`, que no viaja en el clon, y la configuración del repo no se toca.                                                                                                                         | `.githooks/`, que sí viaja y se revisa en un PR       |
| `--sin-ci`         | No escribe el flujo de integración continua.                                                                                                                                                                         | Lo escribe                                            |

`--entrevista` y `--sin-entrevista` se contradicen, igual que `--sin-hook` y `--hook-local`: pasar las dos de un par sale con 2.

## Qué skills instala

| Situación                       | Qué instala                                                                                                                 |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Sin `--skills` y sin entrevista | Las cinco que no piden interfaz: `protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `version-bump` y `test-fix` |
| Sin `--skills`, con entrevista  | Las que pide el perfil del producto, más `protocolo-arranque`                                                               |
| `--skills todas`                | Las once                                                                                                                    |
| `--skills protocolo-ux,i18n`    | Exactamente ésas, con o sin entrevista                                                                                      |

Lo que pide cada perfil, según la respuesta a «¿Qué clase de producto es?»:

| Producto        | Skills                                                                                  |
| --------------- | --------------------------------------------------------------------------------------- |
| `saas`, `movil` | Las cinco de base, `protocolo-ux`, `ux-writer`, `ux-audit` e `information-architecture` |
| `landing`       | Las cinco de base, `protocolo-ux`, `ux-writer` y `ux-audit`                             |
| `api`, `cli`    | Las cinco de base                                                                       |

`i18n` no la instala ningún perfil: entra sólo con `--skills`. `protocolo-arranque` entra con la entrevista porque es la skill que se usa una vez, al principio; en un repo ya definido sobra. El catálogo completo está en [Las 11 skills](/docs/referencia/skills/).

## Nunca sobreescribe

Ni archivos, ni carpetas, ni enlaces. Cada ítem del reporte termina en uno de tres estados:

| Estado     | Qué significa                                                                     |
| ---------- | --------------------------------------------------------------------------------- |
| `escrito`  | No existía y se creó.                                                             |
| `saltado`  | Ya existía y no se tocó. Si la razón no es «ya existe», se dice entre paréntesis. |
| `sugerido` | Hacía falta escribir en algo que ya existía. No se escribe: se dice qué añadir.   |

Los casos concretos:

* **Una skill que ya existe se salta entera.** No se fusiona nada dentro de su carpeta.
* **`AI-FIRST.md` existente** se salta. Si le falta `alcance.spec`, se reporta como sugerido con la línea que falta; si ya la tiene, como saltado.
* **`.claude/skills`** se salta si ya hay algo ahí. Si es un directorio real y no un enlace, se dice: crear el enlace dentro habría dejado un `.claude/skills/skills` que no lee nadie.
* **`core.hooksPath` ya configurado** con otra carpeta, por ejemplo la de husky o lefthook, no se pisa: queda sugerido, con la carpeta a la que apunta.
* **Una skill instalada con `--enlazar`** no se adapta: queda sugerida, porque escribir ahí cambiaría la carpeta del paquete y no tu copia.
* **`AGENTS.md`** es la excepción razonada: su bloque se reescribe en cada corrida, pero **sólo lo que está entre las marcas**. Fuera de ellas no cambia una letra. Si el bloque ya está al día, se reporta saltado. Una marca sin su pareja, o las dos al revés, detiene el comando: un bloque roto se arregla a mano.

Correrlo dos veces deja el repo igual.

## La entrevista

Pregunta lo que no se puede deducir y lo escribe donde corresponde. Nada de ella llama a un modelo: definir el producto —PRD, arquitectura, specs— es trabajo de la skill `protocolo-arranque`, que corre tu agente.

### Cuándo se entrevista

* **Un proyecto sin documentación** se entrevista sin preguntar.
* **Un proyecto documentado** recibe la oferta, con saltarla como valor por defecto (`[s/N]`). Cuenta como documentado si git ya conoce `AI-FIRST.md`, `AGENTS.md` o algún `.md` bajo `docs/`, sin contar los que escribe el propio `init`.
* **Con `--entrevista`** se entrevista siempre; **con `--sin-entrevista`**, nunca.
* **Sin terminal interactiva**, como en integración continua, no se entrevista nunca, y el reporte lo dice con la línea `Sin entrevista: no hay terminal interactiva.`

Todo lo que puede fallar por uso —un nombre de skill que no existe, un bloque roto en `AGENTS.md`— se comprueba antes de la primera pregunta. Si cancelas a mitad, con Ctrl+C o Ctrl+D, no se escribe nada más; lo único que puede haber quedado es el `git init` de una carpeta que no era repositorio.

### Las preguntas

Todas tienen un valor por defecto entre corchetes, y Enter lo acepta. En las de opción vale el valor, su número en la lista o un prefijo sin ambigüedad.

| Pregunta                                       | Tipo                                     | Por defecto                                | Dónde va                               |
| ---------------------------------------------- | ---------------------------------------- | ------------------------------------------ | -------------------------------------- |
| ¿Cómo se llama el proyecto?                    | texto                                    | El nombre deducido                         | `proyecto` en `AI-FIRST.md`            |
| ¿En qué fase está?                             | `exploracion`, `mvp`, `produccion`       | `exploracion`                              | `fase`                                 |
| ¿Qué clase de producto es?                     | `saas`, `landing`, `api`, `cli`, `movil` | `saas`                                     | `perfil.producto`; decide las skills   |
| ¿Qué forma tiene el repositorio?               | `unico`, `monorepo`, `multiple`          | `unico`                                    | `perfil.repositorio`                   |
| ¿Qué comando decide que el proyecto está sano? | texto                                    | El deducido, o `pnpm test`                 | `verificacion` y varias skills         |
| ¿Y el de tipos?                                | texto                                    | El script de tipos, si lo hay              | `protocolo-features`, `test-fix`       |
| ¿Y el de lint?                                 | texto                                    | El script `lint`, si lo hay                | `protocolo-features`, `test-fix`       |
| ¿Trabajas con varios agentes en paralelo?      | sí/no                                    | no                                         | `protocolo-features`, `test-fix`       |
| ¿Qué archivo lleva el número de versión?       | texto                                    | El manifiesto encontrado, o `package.json` | `version-bump`, `protocolo-cierre`     |
| ¿En qué orden se implementa una feature?       | opción, según el producto                | La primera que ofrece el producto          | `protocolo-features`                   |
| ¿«…» es Zona Prohibida?                        | sí/no, una por zona sugerida             | sí                                         | Un «no» la quita de `zonas_prohibidas` |

Son nueve preguntas fijas, la de la secuencia y una por cada Zona Prohibida sugerida. El número exacto se anuncia antes de empezar.

Las secuencias que ofrece la penúltima pregunta:

| Valor          | Secuencia                                                                                       | Se ofrece a                |
| -------------- | ----------------------------------------------------------------------------------------------- | -------------------------- |
| `hexagonal`    | schema o migración, dominio, aplicación, infraestructura backend, compartido, interfaz, pruebas | `saas`, `api`, `movil`     |
| `capas-web`    | schema, consultas y acciones de servidor, componentes, ruta o página, pruebas                   | `saas`, `landing`, `movil` |
| `vertical`     | contrato de la feature, datos, lógica, interfaz, pruebas                                        | todos menos `cli`          |
| `contenido`    | contenido y copia, componentes, página, pruebas                                                 | `landing`                  |
| `contrato-cli` | contrato, dominio, aplicación, interfaz de línea de comandos, pruebas                           | `cli`, `api`               |

### Dónde escribe las respuestas

* **En `AI-FIRST.md`**: `proyecto`, `fase`, `perfil`, `verificacion` y las zonas confirmadas. Sólo si `init` crea el archivo en esa corrida; un `AI-FIRST.md` que ya existía no se toca.
* **En cada skill instalada**, dentro de su sección «Adaptación a tu proyecto» y entre las mismas marcas que `AGENTS.md`. Cada corrida reescribe lo que hay entre las marcas; lo que agregues fuera sobrevive. Una skill para la que la entrevista no aporta nada, como `i18n`, se reporta saltada con esa razón.

Cómo revisar y completar esa adaptación está en [Adaptar las skills](/docs/guias/adaptar-las-skills/).

## El punto de control

`init` escribe el mismo detector en dos sitios, con tolerancias distintas.

**`.githooks/pre-push`** corre `ai-first audit` **sin `--estricto`** sobre lo que se va a empujar: sólo un P0 interrumpe el push; un P1 o un P2 se imprimen y el push sigue. Toma como base el commit que el remoto ya tiene; si la rama todavía no existe en el remoto, compara el árbol de trabajo. Busca el comando en `node_modules/.bin`, luego en el `PATH`, luego en la caché de `npx` sin descargar nada. Si no encuentra Node o el paquete, avisa y deja pasar el push: no encontrarse nunca es motivo para frenar. Se salta con `git push --no-verify`.

Es un hook **de git**, no del agente: no es el `PostToolUse` ni el `Stop` de [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/).

**`.github/workflows/ai-first.yml`** corre en cada pull request, **con `--estricto`**: ahí cualquier hallazgo corta. Su paso final:

```yaml
- name: Entropía documental
  run: npx --yes @falcux/ai-first audit --base "origin/${{ github.base_ref }}" --estricto
```

Clona con `fetch-depth: 0`, porque sin historia no hay rango que comparar, y usa Node 22.

## Salida

`init --sin-entrevista` en una carpeta vacía llamada `demo`:

```text
ai-first init — demo


  escrito  .git/
  escrito  AI-FIRST.md
  escrito  docs/ADR.md
  escrito  docs/SESSION_LOG.md
  escrito  docs/changes/CHANGE_LOG.md
  escrito  docs/changes/pending/.gitkeep
  escrito  .agents/skills/protocolo-features
  escrito  .agents/skills/protocolo-cambios
  escrito  .agents/skills/protocolo-cierre
  escrito  .agents/skills/version-bump
  escrito  .agents/skills/test-fix
  escrito  .claude/skills
  escrito  .githooks/pre-push
  escrito  core.hooksPath
  escrito  .github/workflows/ai-first.yml
  escrito  AGENTS.md


  1 Zona Prohibida sugerida: .env*
  0 superficies de decisión: —
  2 artefactos declarados


Revisa AI-FIRST.md —sobre todo las razones de cada zona— y AGENTS.md, y luego corre `ai-first audit`.
```

Un ítem saltado se imprime con su razón entre paréntesis, o `(ya existe)`; uno sugerido, con la razón tras una raya. El `AI-FIRST.md` que dejó esta corrida está completo en [El formato de AI-FIRST.md](/docs/referencia/ai-first-md/#un-ejemplo-real).

## Códigos de salida

| Código | Cuándo                                                                                                                                                                                                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`    | Terminó, aunque haya saltado o sugerido cosas: saltar no es error.                                                                                                                                                                      |
| `2`    | Error de uso: dos opciones que se contradicen, `--entrevista` sin terminal interactiva, una skill que el paquete no trae, un bloque roto en `AGENTS.md`, una `--raiz` que no existe, una opción desconocida o una entrevista cancelada. |

`init` nunca sale con `1`: ese código es de `audit`.

## Relacionado

[Qué deja init en tu repo](/docs/empezar/que-instala/)Los mismos archivos, explicados para quien lo corre por primera vez.

[Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/)Qué pasa cuando el repo ya tiene AGENTS.md, skills o hooks propios.

[ai-first audit](/docs/referencia/audit/)El comando que corre el punto de control.

[Las 11 skills](/docs/referencia/skills/)Qué instala cada perfil y qué hace cada skill.

# ai-first audit

> Los dos modos de audit, sus opciones, el puntaje de entropía, los códigos de salida y el formato del reporte legible y del JSON.

`audit` lee `AI-FIRST.md`, le pregunta a git qué cambió, corre las cinco verificaciones y resume el resultado en un puntaje de entropía y un código de salida. No compila nada, no llama a un modelo y no toca la red.

## Uso

```text
ai-first audit [--base <ref>] [--estricto] [--registrar] [--json] [--raiz <dir>]
```

Para correrlo sin instalar el paquete:

```bash
npx @falcux/ai-first@latest audit
```

## Modos

El mismo comando compara dos cosas distintas según reciba o no `--base`.

| Modo      | Se activa      | Qué cuenta como tocado                                                                                                                                           | Dónde se usa                                                                     |
| --------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Árbol** | Sin `--base`   | Lo que difiere de `HEAD`, en el índice o en el árbol de trabajo, más los archivos nuevos sin seguimiento que `.gitignore` no cubre. En un repo sin commits, todo | El hook local, o a mano antes de hacer commit                                    |
| **Rango** | `--base <ref>` | Lo que difiere en el rango `<ref>...HEAD`: lo que la rama trae desde que se separó de `<ref>`                                                                    | Integración continua, y el hook `pre-push` cuando la rama ya existe en el remoto |

La diferencia importa para una verificación: la anotación que silencia la de decisiones vive en el cuerpo de un commit, y en modo árbol no hay commits que leer. Ver [Decisión sin fila en ADR](/docs/referencia/verificaciones/#decisi%C3%B3n-sin-fila-en-adr).

## Opciones

| Opción         | Qué hace                                                                                        | Por defecto               |
| -------------- | ----------------------------------------------------------------------------------------------- | ------------------------- |
| `--base <ref>` | Compara el rango `<ref>...HEAD`. La ref tiene que existir en el repositorio; si no, sale con 2. | Modo árbol, contra `HEAD` |
| `--estricto`   | Sale con 1 también ante un P1 o un P2.                                                          | Sólo un P0 da 1           |
| `--registrar`  | Escribe el resultado en `auditoria` del frontmatter de `AI-FIRST.md`.                           | No escribe nada           |
| `--json`       | Imprime el informe en JSON en vez del reporte legible.                                          | Reporte legible           |
| `--raiz <dir>` | Raíz del repositorio.                                                                           | El directorio actual      |

## Opciones globales

Valen sin subcomando y con cualquiera de los dos.

| Opción            | Qué hace                                                                                                   | Código de salida |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- |
| `-v`, `--version` | Imprime la versión instalada del paquete, leída de su `package.json`. Tiene prioridad sobre todo lo demás. | `0`              |
| `-h`, `--help`    | Imprime la ayuda completa, la de `init` y la de `audit`.                                                   | `0`              |

Sin subcomando y sin `--help`, el binario imprime la misma ayuda pero sale con `2`, porque no se le pidió nada que hacer.

## Estados de una verificación

Cada una de las cinco termina en uno de tres estados, y sólo tres:

| Estado      | Marca en el reporte | Qué significa                                                      |
| ----------- | ------------------- | ------------------------------------------------------------------ |
| `aprobado`  | `✓`                 | Corrió y no encontró nada.                                         |
| `hallazgos` | `✗`                 | Corrió y encontró al menos un hallazgo, cada uno con su severidad. |
| `omitido`   | `–`                 | No pudo correr porque falta lo que necesita leer. Se dice por qué. |

**Un check que no puede correr se reporta omitido, nunca aprobado.** Un `–` no es un visto bueno: es un hueco en la configuración, y el reporte dice cuál. Qué necesita cada uno está en [Las cinco verificaciones](/docs/referencia/verificaciones/).

## Puntaje

```text
entropía = min(100, 40·P0 + 20·P1 + 8·P2)
```

**Más alto es peor.** Mide entropía, no salud: 0 es documentación alineada con el proyecto y 100 es documentación desconectada. Cada hallazgo suma el peso de su severidad, y el total se corta en 100.

Un solo P0 pone el puntaje en 40 sin ayuda de nada más, que es la intención: una Zona Prohibida tocada no se compensa con documentación impecable en todo lo demás. Un P0, un P1 y un P2 dan 68.

En la verificación de Zonas Prohibidas, la unidad del hallazgo es la zona, no el archivo: tocar tres migraciones es un P0, con los tres archivos en el detalle. El puntaje mide cuántas fronteras se cruzaron.

## Códigos de salida

| Código | Cuándo                                                                                                                                                                                                                                                                        |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`    | Sin hallazgos, o sólo P1 y P2 sin `--estricto`.                                                                                                                                                                                                                               |
| `1`    | Algún P0. O algún P1 o P2 con `--estricto`.                                                                                                                                                                                                                                   |
| `2`    | Error de uso: no hay `AI-FIRST.md`, su `formato` es desconocido o su frontmatter no se puede leer, la carpeta no es un repositorio git, la ref de `--base` no existe, o una opción desconocida. También `sync`, `adr` y `handoff`, que están anunciados y todavía no existen. |

Así el mismo comando sirve en un hook local, donde interrumpir por un P2 sería intolerable, y en integración continua, donde se quiere el corte.

## Reporte legible

Es la salida por defecto. En una terminal lleva color; redirigida a un archivo o a otro proceso, no.

Sin hallazgos:

```text
ai-first audit — demo
árbol de trabajo contra HEAD · 0 archivos tocados


✓ Zona Prohibida tocada
✓ Decisión sin fila en ADR
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


Entropía: 0 / 100 (0 P0 · 0 P1 · 0 P2)
```

Sale con 0. Tras tocar un `.env.local` en el mismo repo, que declara `.env*` como Zona Prohibida:

```text
ai-first audit — demo
árbol de trabajo contra HEAD · 2 archivos tocados


✗ Zona Prohibida tocada
    P0  Zona Prohibida «.env*» tocada — credenciales
          .env.local
✓ Decisión sin fila en ADR
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»


Entropía: 40 / 100 (1 P0 · 0 P1 · 0 P2)
```

Sale con 1. La segunda línea dice el modo —`árbol de trabajo contra HEAD`, o `rango <ref>...HEAD`— y cuántos archivos se tocaron. Las verificaciones van siempre en el mismo orden. Bajo cada hallazgo, con sangría, va su detalle: los archivos que lo causaron o qué hacer para silenciarlo.

## Salida JSON

Con `--json`, el mismo informe de la corrida con P0:

```json
{
  "proyecto": "demo",
  "modo": "arbol",
  "cambiados": [
    ".env.local",
    "src/a.ts"
  ],
  "resultados": [
    {
      "check": "zona-prohibida",
      "estado": "hallazgos",
      "hallazgos": [
        {
          "severidad": "P0",
          "ruta": ".env*",
          "mensaje": "Zona Prohibida «.env*» tocada — credenciales",
          "detalle": [
            ".env.local"
          ]
        }
      ]
    },
    {
      "check": "decision-sin-adr",
      "estado": "aprobado"
    },
    {
      "check": "alcance-excedido",
      "estado": "omitido",
      "razon": "no hay ninguna spec activa en docs/changes/pending/"
    },
    {
      "check": "artefacto-huerfano",
      "estado": "aprobado"
    },
    {
      "check": "inventario-componentes",
      "estado": "omitido",
      "razon": "faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»"
    }
  ],
  "conteo": {
    "p0": 1,
    "p1": 0,
    "p2": 0
  },
  "entropia": 40,
  "codigoDeSalida": 1
}
```

| Campo                    | Tipo                  | Qué contiene                                                                                                                                                                                                     |
| ------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proyecto`               | cadena o `null`       | El `proyecto` de `AI-FIRST.md`, o `null` si no lo declara.                                                                                                                                                       |
| `modo`                   | `"arbol"` o `"rango"` | El modo de comparación.                                                                                                                                                                                          |
| `base`                   | cadena                | La ref de `--base`. Sólo aparece en modo rango.                                                                                                                                                                  |
| `cambiados`              | lista de cadenas      | Los archivos tocados, relativos a la raíz, sin duplicados y en orden alfabético.                                                                                                                                 |
| `resultados`             | lista                 | Uno por verificación, en el orden fijo del reporte.                                                                                                                                                              |
| `resultados[].check`     | cadena                | El identificador: `zona-prohibida`, `decision-sin-adr`, `alcance-excedido`, `artefacto-huerfano` o `inventario-componentes`.                                                                                     |
| `resultados[].estado`    | cadena                | `aprobado`, `hallazgos` u `omitido`.                                                                                                                                                                             |
| `resultados[].razon`     | cadena                | Por qué se omitió. Sólo con `omitido`.                                                                                                                                                                           |
| `resultados[].hallazgos` | lista                 | Sólo con `hallazgos`. Cada uno lleva `severidad` (`P0`, `P1` o `P2`), `mensaje` en una línea y, cuando aplica, `ruta` —el patrón, archivo o `archivo:línea` al que se refiere— y `detalle`, una lista de líneas. |
| `conteo`                 | objeto                | Cuántos hallazgos de cada severidad: `p0`, `p1`, `p2`.                                                                                                                                                           |
| `entropia`               | número                | El puntaje, de 0 a 100.                                                                                                                                                                                          |
| `codigoDeSalida`         | `0` o `1`             | El código con el que sale esta corrida, ya aplicado `--estricto`.                                                                                                                                                |

Nota

`codigoDeSalida` nunca vale `2`: un error de uso no produce informe, sino un mensaje en la salida de error que empieza con `ai-first:`.

## `--registrar`

Escribe en el frontmatter de `AI-FIRST.md` un bloque `auditoria` con la fecha de hoy, el puntaje y el conteo. Si el bloque ya existe, lo reemplaza; si no, lo agrega al final del frontmatter. Trabaja sobre el texto, no reformatea el YAML: los comentarios y el resto del archivo quedan como estaban.

Tras la corrida con P0, el frontmatter termina así:

```yaml
auditoria:
  fecha: 2026-09-23
  entropia: 40
  hallazgos:
    p0: 1
    p1: 0
    p2: 0
---
```

Sólo guarda la última corrida, y sólo cuando se pide. Si cada `audit` tocara el archivo, el ruido en los diffs haría que el equipo lo ignore. Registrado en un PR, el diff muestra si la entropía subió o bajó. El registro no cambia el código de salida.

## Relacionado

[Las cinco verificaciones](/docs/referencia/verificaciones/)Qué detecta cada una y cómo se silencia.

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)El hook, el flujo de integración continua y qué hacer con cada hallazgo.

[El formato de AI-FIRST.md](/docs/referencia/ai-first-md/)Lo que audit lee antes de correr.

[Solución de problemas](/docs/guias/solucion-de-problemas/)Cuando el comando sale con 2 o un check aparece omitido.

# Las cinco verificaciones

> Qué detecta cada verificación de audit, con qué severidad, qué lee de AI-FIRST.md, cuándo se omite y cómo se silencia.

`audit` corre cinco verificaciones, siempre en el mismo orden. Todas son código puro —git, sistema de archivos y expresiones regulares—, sin modelo, sin conexión y sin API key: la misma entrada da el mismo resultado. Cada una lee una parte de `AI-FIRST.md`, y si esa parte falta se reporta omitida, nunca aprobada.

## Resumen

| # | Verificación                                                                          | Sev.   | Qué detecta                                                  | Por qué importa                                     | Lee de `AI-FIRST.md`                                              |
| - | ------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------- |
| 1 | [Zona Prohibida tocada](#zona-prohibida-tocada)                                       | **P0** | Se tocó una ruta declarada como Zona Prohibida               | Es lo único que corta el flujo aun sin `--estricto` | `zonas_prohibidas`                                                |
| 2 | [Decisión sin fila en ADR](#decisi%C3%B3n-sin-fila-en-adr)                            | **P1** | Señales de decisión arquitectónica sin fila nueva en el ADR  | La decisión existe en el código y no en el registro | `superficies_de_decision`, `artefactos.adr`                       |
| 3 | [Alcance excedido](#alcance-excedido)                                                 | **P1** | Más archivos tocados de los que declara la spec activa       | El alcance creció y nadie lo midió                  | `alcance.spec`, `alcance.tolerancia`                              |
| 4 | [Artefacto huérfano](#artefacto-hu%C3%A9rfano)                                        | **P2** | Un documento declarado, o una ruta que menciona, no existe   | Un documento apunta a algo que ya nadie mantiene    | `artefactos`                                                      |
| 5 | [Inventario de componentes desactualizado](#inventario-de-componentes-desactualizado) | **P2** | Componentes en disco que el inventario no nombra, o al revés | El inventario empezó a mentir                       | `artefactos.inventario_componentes`, `artefactos.componentes_dir` |

Cuatro de las cinco son deterministas y no admiten discusión: una ruta cambió o no cambió, un archivo referenciado existe o no existe, un componente aparece en el inventario o no aparece. **La segunda no lo es**, porque «se tomó una decisión arquitectónica» no cabe en una expresión regular: se resuelve declarando dónde un cambio se presume decisión, produce falsos positivos y por eso se puede silenciar. Una verificación que no se puede silenciar termina desactivada entera, que es peor que tenerla ruidosa.

Los patrones de ruta que usan las verificaciones 1, 2 y 3 siguen las reglas de [Patrones de ruta](/docs/referencia/ai-first-md/#patrones-de-ruta). Qué es «tocado» depende del modo, árbol o rango: ver [Modos](/docs/referencia/audit/#modos).

***

## Zona Prohibida tocada

**Severidad:** P0 · **Identificador:** `zona-prohibida`

Compara cada archivo tocado contra los patrones de `zonas_prohibidas`. Un hallazgo por zona, no por archivo: tocar tres migraciones es una Zona Prohibida tocada, con los tres archivos en el detalle. Si la zona declara `razon`, el mensaje la incluye.

* **Lee:** `zonas_prohibidas[].ruta` y `zonas_prohibidas[].razon`.
* **Se omite si** no hay ninguna zona declarada: `no hay «zonas_prohibidas» declaradas`.
* **No se silencia.** Una Zona Prohibida no impide el cambio, lo hace visible: el hallazgo existe para que un humano decida. Si el cambio estaba aprobado, se publica igual; lo que no se hace es quitar la zona para que el detector calle.

```text
✗ Zona Prohibida tocada
    P0  Zona Prohibida «.env*» tocada — credenciales
          .env.local
```

Por qué y cómo se eligen las zonas está en [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/).

***

## Decisión sin fila en ADR

**Severidad:** P1 · **Identificador:** `decision-sin-adr`

Busca dos señales de que se tomó una decisión arquitectónica:

* **Cambió un archivo que coincide con `superficies_de_decision`.**
* **Un `package.json`, en cualquier carpeta, ganó o perdió una dependencia de producción.** Se comparan las claves de `dependencies`; `devDependencies` no cuenta. Esta señal no hay que declararla.

Si hay alguna señal y el archivo de `artefactos.adr` no ganó una fila en el mismo tramo, emite un P1. **Una fila** es una línea agregada que empieza con un encabezado de nivel 2 o 3 seguido de `ADR-` y un número, como `## ADR-007 — La cola de trabajos pasa a SQS`.

* **Lee:** `superficies_de_decision` y `artefactos.adr`.

* **Se omite si** no hay `artefactos.adr`: `no hay «artefactos.adr» declarado`. Sin superficies declaradas, igual corre: le queda la señal de las dependencias.

* **Se silencia de dos formas:**

  1. **Agregando la fila al ADR**, si de verdad era una decisión.

  2. **Con la anotación en el cuerpo de un commit del rango**, si no lo era, por ejemplo subir un timeout en un `*.config.*`:

     ```text
     <!-- ai-first: sin-decision -->
     ```

     La anotación **sólo se lee en modo rango**, con `--base`: en modo árbol no hay commits cuyo cuerpo leer. Ahí el P1 queda como advertencia y no corta salvo con `--estricto`. El hook `pre-push` corre en modo rango cuando la rama ya existe en el remoto, y el flujo de CI siempre.

```text
✗ Decisión sin fila en ADR
    P1  Hay señales de decisión arquitectónica y ADR.md no ganó ninguna fila
          vite.config.ts (superficie «**/*.config.*»)
          Silenciar: agregar la fila al ADR, o «<!-- ai-first: sin-decision -->» en el cuerpo del commit.
```

Una dependencia aparece en el detalle como `package.json: +nombre` o `package.json: -nombre`. Qué merece una fila y qué no está en [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/).

***

## Alcance excedido

**Severidad:** P1 · **Identificador:** `alcance-excedido`

Compara los archivos tocados contra los que declara la spec activa. Si los que quedan fuera superan `tolerancia`, emite un solo P1 con la lista.

**La spec activa** es `alcance.spec`: un archivo, o una carpeta, y entonces cuenta cada `.md` o `.mdx` que haya dentro y no empiece por punto. `init` la apunta a `docs/changes/pending/`, donde vive el CHG del cambio en curso.

**Cómo declara archivos una spec:** en una sección cuyo encabezado empiece por «Archivos» o «Alcance», de cualquier nivel y sin importar mayúsculas, con cada ruta entre acentos graves. Se admiten patrones. La sección llega hasta el siguiente encabezado de igual o mayor nivel, y lo que esté dentro de un bloque de código no cuenta.

```md
## Archivos


- `src/lib/cola.ts`
- `src/lib/cola.test.ts`
- `docs/specs/cola.md`
```

En la 0.5.1, una ruta declarada tiene que llevar una barra o una extensión conocida, como `.ts`, `.md`, `.json` o `.yml`. Un archivo sin carpeta y sin extensión reconocida —`.npmrc`, `LICENSE`, `Makefile`— no se puede declarar: si lo tocas, cuenta fuera del alcance y sólo lo cubre la tolerancia.

**Nunca cuentan como fuera de alcance:** `AI-FIRST.md`, la propia spec o su carpeta, y cualquier archivo declarado en `artefactos`. Actualizar el registro de sesión al cerrar es parte del protocolo, no un desvío.

* **Lee:** `alcance.spec` y `alcance.tolerancia`. Sin tolerancia declarada vale 0.

* **Se omite si:**

  * no hay `alcance.spec`: `no hay «alcance.spec» declarado`;
  * no hay ninguna spec en esa ruta: `no hay ninguna spec activa en docs/changes/pending/`. Es el caso normal cuando no hay un cambio abierto: no hay alcance que exceder;
  * las specs no listan archivos: `las specs en … no listan archivos (sección «Archivos» o «Alcance» con rutas entre acentos graves)`.

* **Se silencia** declarando en la spec lo que de verdad entró en el cambio, o subiendo `tolerancia` si el proyecto acepta cierto margen.

```text
✗ Alcance excedido
    P1  3 archivos fuera del alcance declarado (tolerancia: 0)
          src/b.ts
          src/c.ts
          vite.config.ts
```

***

## Artefacto huérfano

**Severidad:** P2 · **Identificador:** `artefacto-huerfano`

Verifica que existan los documentos declarados en `artefactos` y que las rutas que mencionan resuelvan. Dos cosas cuentan como huérfano:

* **Un artefacto declarado que no existe.** Una clave que apunta a una carpeta sólo tiene que existir; un archivo, además, se recorre.
* **Una ruta mencionada dentro de un artefacto que no existe**, sea en un enlace `[texto](ruta)` o entre acentos graves.

**Qué cuenta como mención de ruta:** un token con barra o con una extensión conocida, sin espacios. No cuentan las URL, lo que empieza con `/`, `@`, `-` o `~`, las refs de git como `origin/main`, los patrones con `*` y los marcadores como `CHG-XXX` o `docs/…`. **Lo que está dentro de un bloque de código tampoco**: ahí las rutas son ejemplos.

**Cómo resuelve, en orden:**

1. Desde la raíz del repo y desde la carpeta del documento. Lo que `.gitignore` cubre, como `dist/` o `.env`, cuenta como existente: está ausente a propósito.
2. Un nombre sin carpeta, como `cola.ts`, se busca por nombre en todo el repo: la prosa nombra archivos, no siempre los ubica.
3. Una ruta con carpeta cuyo **primer segmento no existe** en la raíz se asume de otro árbol —otro proyecto, un ejemplo, un repo externo— y no se reporta. Un check que no puede verificar algo no lo cuenta como fallo.

* **Lee:** todas las claves de `artefactos`, las conocidas y las que agregues.
* **Se omite si** no hay ningún artefacto declarado: `no hay «artefactos» declarados`. Tras `init` nunca pasa, porque declara `adr` y `agents`.
* **Se silencia** corrigiendo la ruta o quitando la mención. Si la ruta es de otro repositorio, escríbela con su carpeta o sin acentos graves; si es un ejemplo, dentro de un bloque de código.

```text
✗ Artefacto huérfano
    P2  docs/ARQUITECTURA.md menciona src/lib/queue.ts, que no existe
```

Un artefacto que no existe se reporta como `«artefactos.clave» apunta a ruta, que no existe`. En JSON, la `ruta` del hallazgo lleva el número de línea: `docs/ARQUITECTURA.md:3`.

***

## Inventario de componentes desactualizado

**Severidad:** P2 · **Identificador:** `inventario-componentes`

Compara los componentes que hay en `componentes_dir` con lo que nombra el documento de `inventario_componentes`. Es por nombre, así que un renombre sin actualizar el inventario también lo caza. Mira en las dos direcciones:

* **Un componente en disco que el inventario no menciona.** Basta con que el nombre aparezca como palabra entera en cualquier parte del documento.
* **Un encabezado del inventario que nombra un componente que ya no existe.** Sólo cuentan los encabezados de nivel 2 o más con forma de componente: entre acentos graves o ángulos, como `` `Boton` `` o `<Boton>`, o con mayúscula interna, como `BotonPrimario`. Una palabra capitalizada suelta, como «Formularios», es un título de sección y se deja pasar.

**Qué cuenta como componente:** cada archivo `.astro`, `.tsx`, `.jsx`, `.vue`, `.svelte`, `.ts` o `.js` dentro de la carpeta, a cualquier profundidad. `Boton/index.tsx` es el componente `Boton`; un `index` en la raíz de la carpeta es el barril de exportación y no cuenta. Se ignoran los archivos de prueba, de stories y de declaración de tipos, lo que empieza por `.` o `_`, y `node_modules`.

* **Lee:** `artefactos.inventario_componentes` y `artefactos.componentes_dir`. Hacen falta las dos.

* **Se omite si:**

  * falta alguna de las dos claves: `faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»`. Es lo que pasa en un repo recién iniciado: `init` las deja comentadas;
  * la carpeta no existe o no es una carpeta;
  * el inventario no existe. Eso ya lo reporta la verificación de artefactos huérfanos.

* **Se silencia** agregando el componente al inventario, o quitando el encabezado del que ya se borró.

```text
✗ Inventario de componentes desactualizado
    P2  Tarjeta existe en src/components/ y no aparece en COMPONENTES.md
    P2  COMPONENTES.md documenta Modal, que ya no existe en src/components/
```

Nota

Los ejemplos de hallazgo de las verificaciones 2 a 5 salen de una corrida del detector sobre un repo de prueba con esas cinco situaciones montadas. El de la verificación 1 es la corrida de [`ai-first audit`](/docs/referencia/audit/#reporte-legible).

## Relacionado

[ai-first audit](/docs/referencia/audit/)Modos, puntaje y códigos de salida.

[El formato de AI-FIRST.md](/docs/referencia/ai-first-md/)Cada campo que leen las verificaciones.

[Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/)Qué hacer con cada hallazgo en el hook y en el pull request.

[Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/)Los cuatro instrumentos que estas verificaciones miden.

# El formato de AI-FIRST.md

> El frontmatter de AI-FIRST.md campo por campo, con su tipo, si es obligatorio y quién lo lee, más las reglas de los patrones de ruta.

`AI-FIRST.md` es el contrato entre el proyecto y el detector: dice qué gobierna al proyecto y dónde vive cada cosa, en una forma que `audit` puede verificar sin interpretar prosa. Vive en la raíz del repo, lo escribe `init` y lo mantiene el equipo a mano.

## La frontera con AGENTS.md

**`AGENTS.md` es para los agentes. `AI-FIRST.md` es para las herramientas.** El primero es normativo y está en presente: «no toques `migrations/`». El segundo es declarativo y no da órdenes: «`migrations/` es Zona Prohibida desde el 2026-03-12, por esta razón». No lo lee el agente para trabajar; lo lee el detector para medir. La única skill que lo lee al empezar es `protocolo-arranque`, que toma de ahí el perfil, la fase, el comando de verificación y las Zonas Prohibidas.

## Estructura

Markdown con un frontmatter YAML entre dos líneas `---`. **El frontmatter es el contrato**: lo lee el detector sin ambigüedad. **El cuerpo es para humanos** y el detector no lo interpreta: van ahí las notas que ninguna máquina puede verificar, como por qué cada zona es prohibida, o la tabla de permisos del repositorio. El cuerpo no repite el frontmatter: si un dato está en los dos lados, uno de los dos va a mentir.

Una clave que el detector no conoce se ignora, no es error.

## Campos

| Campo                                                 | Tipo             | Obligatorio | Lo escribe `init`                     | Quién lo lee                                |
| ----------------------------------------------------- | ---------------- | ----------- | ------------------------------------- | ------------------------------------------- |
| [`formato`](#formato)                                 | número           | **Sí**      | Sí                                    | `audit`, antes que nada                     |
| [`proyecto`](#proyecto)                               | cadena           | No          | Sí                                    | El reporte de `audit`                       |
| [`fase`](#fase)                                       | cadena           | No          | Sí                                    | Quien abre el archivo; `protocolo-arranque` |
| [`actualizado`](#actualizado)                         | fecha            | No          | Sí                                    | Quien abre el archivo                       |
| [`verificacion`](#verificacion)                       | cadena           | No          | Si lo deduce; si no, comentado        | El humano; `protocolo-arranque`             |
| [`perfil`](#perfil)                                   | mapa             | No          | Sólo con entrevista                   | `protocolo-arranque`                        |
| [`zonas_prohibidas`](#zonas_prohibidas)               | lista            | No          | Sí                                    | Verificación 1; `protocolo-arranque`        |
| [`superficies_de_decision`](#superficies_de_decision) | lista de cadenas | No          | Si encuentra alguna; si no, comentado | Verificación 2                              |
| [`alcance`](#alcance)                                 | mapa             | No          | Sí, con `spec`                        | Verificación 3                              |
| [`artefactos`](#artefactos)                           | mapa             | No          | Sí                                    | Verificaciones 2, 3, 4 y 5                  |
| [`auditoria`](#auditoria)                             | mapa             | No          | No: lo escribe `audit --registrar`    | El humano, en el diff del PR                |

Sin un campo opcional, la verificación que lo necesita se omite y el reporte dice por qué. Nunca se aprueba.

### `formato`

La versión **del formato de este archivo**, no del proyecto. Hoy la única que existe es `1`. Cualquier otro valor, o su ausencia, detiene `audit` con un mensaje y sale con 2: un formato desconocido no se interpreta a medias.

```yaml
formato: 1
```

### `proyecto`

El nombre que encabeza el reporte y el campo `proyecto` del JSON. Sin él, el reporte dice `(sin nombre)` y el JSON, `null`. `init` lo toma del `name` de `package.json`, sin el scope, o del nombre de la carpeta.

### `fase`

`exploracion`, `mvp` o `produccion`. No cambia ninguna verificación: la lee quien abre el archivo, y `protocolo-arranque` para saber en qué punto está el proyecto. `init` escribe `exploracion` salvo que la entrevista diga otra cosa.

### `actualizado`

La fecha de la última revisión del archivo, en formato `AAAA-MM-DD`. `init` pone la del día. Ninguna verificación la lee.

### `verificacion`

El comando que decide si el proyecto está sano, como `pnpm build && pnpm test`. **Lo corre el humano, no el detector**: `audit` mide documentación, no compila nada. `init` lo arma con los scripts `build` y `test` de `package.json`; si no los hay, deja la línea comentada.

### `perfil`

Qué clase de producto es y en qué forma de repositorio vive. Decide qué skills instala `init` con entrevista y qué artefactos escribe `protocolo-arranque`.

```yaml
perfil:
  producto: saas        # saas | landing | api | cli | movil
  repositorio: unico    # unico | monorepo | multiple
```

Las dos claves son obligatorias si el campo está. Un valor fuera de la lista es error de formato y sale con 2, no se reemplaza por uno por defecto: adivinar mal el perfil es peor que no tenerlo. Sin `perfil`, el archivo funciona igual; `protocolo-arranque` lo pregunta.

### `zonas_prohibidas`

Las rutas que el agente no modifica sin aprobación explícita. El criterio es el costo de revertir un error ahí, no la importancia del archivo. Pocas, o se vuelven ruido.

```yaml
zonas_prohibidas:
  - ruta: "migrations/"
    razon: "esquema vivo en producción"
    desde: 2026-03-12
  - ".env*"
```

| Clave   | Tipo   | Obligatoria | Qué es                                                     |
| ------- | ------ | ----------- | ---------------------------------------------------------- |
| `ruta`  | patrón | **Sí**      | Qué se protege. Ver [Patrones de ruta](#patrones-de-ruta). |
| `razon` | cadena | No          | Por qué. Aparece en el mensaje del hallazgo.               |
| `desde` | fecha  | No          | Desde cuándo rige.                                         |

Cada entrada puede ser un mapa o, si sólo lleva ruta, una cadena suelta. Un mapa sin `ruta` es error de formato.

### `superficies_de_decision`

Los archivos donde un cambio se presume decisión arquitectónica: el esquema, los puntos de entrada de los paquetes, las configuraciones. Si uno se toca y el ADR no gana una fila, la verificación 2 emite un P1. Las dependencias de producción se vigilan solas, sin declararlas.

```yaml
superficies_de_decision:
  - "**/*.config.*"
  - "packages/*/src/index.ts"
  - "src/lib/queue.ts"
```

Tiene que ser una lista de cadenas.

### `alcance`

De dónde sale el alcance declarado del cambio en curso.

```yaml
alcance:
  spec: docs/changes/pending/
  tolerancia: 3
```

| Clave        | Tipo   | Por defecto | Qué es                                                                                                      |
| ------------ | ------ | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `spec`       | ruta   | —           | Un archivo, o una carpeta cuyos `.md` y `.mdx` son las specs activas. Sin ella, la verificación 3 se omite. |
| `tolerancia` | número | `0`         | Cuántos archivos fuera del alcance se aceptan antes de emitir el P1.                                        |

Cómo lista archivos una spec está en [Alcance excedido](/docs/referencia/verificaciones/#alcance-excedido). Un valor del tipo equivocado, como `tolerancia: "3"` entre comillas, se ignora sin error.

### `artefactos`

Los documentos que hablan de **este** repo, como un mapa de nombre a ruta relativa a la raíz. La verificación 4 comprueba que existan y que lo que mencionan exista; la 3 nunca los cuenta fuera de alcance.

```yaml
artefactos:
  adr: docs/ADR.md
  agents: AGENTS.md
  arquitectura: docs/ARQUITECTURA.md
  guia_diseno: docs/GUIA_DISENO.md
  inventario_componentes: docs/COMPONENTES.md
  componentes_dir: src/components/
  tech_notes: docs/TECH_NOTES.md
```

| Clave                                                                              | La usa además                                              |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `adr`                                                                              | Verificación 2: es el archivo que tiene que ganar la fila. |
| `inventario_componentes`                                                           | Verificación 5, junto con `componentes_dir`.               |
| `componentes_dir`                                                                  | Verificación 5. Es una carpeta: sólo tiene que existir.    |
| `agents`, `arquitectura`, `guia_diseno`, `tech_notes`, `session_log`, `change_log` | Sólo la 4.                                                 |

Se admite cualquier otra clave: es un documento más que la verificación 4 recorre. Cada valor tiene que ser una cadena con la ruta; una clave con valor nulo se ignora.

Precaución

Declarar el registro de sesión o el de cambios es posible, pero `init` no lo hace a propósito: son cronología, nombran archivos que ya se retiraron, y la verificación 4 cobraría cada mención vieja para siempre.

### `auditoria`

El resultado de la última corrida registrada. Lo escribe `audit --registrar` y nadie más; ninguna verificación lo lee. Existe para que el diff del PR muestre si la entropía subió o bajó.

```yaml
auditoria:
  fecha: 2026-09-23
  entropia: 40
  hallazgos:
    p0: 1
    p1: 0
    p2: 0
```

Cómo se escribe está en [`--registrar`](/docs/referencia/audit/#--registrar).

## Patrones de ruta

`zonas_prohibidas`, `superficies_de_decision` y las rutas que declara una spec usan las mismas reglas, pocas y explícitas:

| Forma          | Ejemplo                   | Coincide con                                                                    |
| -------------- | ------------------------- | ------------------------------------------------------------------------------- |
| Termina en `/` | `migrations/`             | Todo lo que esté debajo de esa carpeta, a cualquier profundidad, desde la raíz. |
| Sin `/`        | `.env*`                   | El nombre del archivo, en cualquier carpeta: también `apps/web/.env.local`.     |
| Con `/`        | `packages/*/src/index.ts` | La ruta completa desde la raíz.                                                 |

Dentro de un patrón, `*` y `?` no cruzan carpetas; `**` sí, y puede valer cero carpetas. Las rutas son relativas a la raíz y se escriben con `/`, que es como las entrega git.

## Errores de formato

Cualquiera de estos detiene `audit` y sale con 2, con el mensaje en la salida de error:

| Mensaje                                                                | Causa                                         |
| ---------------------------------------------------------------------- | --------------------------------------------- |
| `No hay AI-FIRST.md en …`                                              | El archivo no existe en la raíz.              |
| `AI-FIRST.md no tiene frontmatter YAML entre dos líneas «---».`        | Falta el frontmatter, o no está al principio. |
| `El frontmatter no es un mapa YAML.`                                   | El YAML es una lista o un valor suelto.       |
| `«formato: …» no está soportado. Este detector entiende el formato 1.` | `formato` falta o no es `1`.                  |
| `«zonas_prohibidas» debe ser una lista.`                               | —                                             |
| `«zonas_prohibidas[n]» necesita al menos «ruta».`                      | Una entrada es un mapa sin `ruta`.            |
| `«superficies_de_decision» debe ser una lista de cadenas.`             | —                                             |
| `«alcance» debe ser un mapa.`                                          | —                                             |
| `«artefactos» debe ser un mapa de nombre → ruta.`                      | —                                             |
| `«artefactos.clave» debe ser una ruta.`                                | Un valor no es cadena.                        |
| `«perfil.producto» debe ser uno de: saas, landing, api, cli, movil.`   | También su equivalente para `repositorio`.    |

## Un ejemplo real

El `AI-FIRST.md` que deja `init --sin-entrevista` en una carpeta vacía llamada `demo`:

```md
---
# Versión del FORMATO de este archivo, no del proyecto.
formato: 1
proyecto: "demo"
fase: exploracion    # exploracion | mvp | produccion
actualizado: 2026-09-23


# El comando que decide si el proyecto está sano. Lo corre el humano, no el
# detector: audit mide documentación, no compila nada.
# verificacion: pnpm build && pnpm test


# Rutas que el agente no modifica sin aprobación explícita. El criterio es el
# costo de revertir un error ahí, no la importancia del archivo. Pocas, o se
# vuelven ruido. Revisa las sugeridas y completa la razón.
zonas_prohibidas:
  - ruta: ".env*"
    razon: "credenciales"
    desde: 2026-09-23


# Superficies donde un cambio se presume decisión arquitectónica. Si una se toca
# y el ADR no gana una fila, audit emite P1. Las dependencias de producción se
# vigilan solas, sin declararlas.
# superficies_de_decision:
#   - "**/*.config.*"
#   - src/lib/queue.ts


# Alcance de la sesión en curso: la spec del cambio abierto (CHG-XXX), que vive
# en la carpeta que init acaba de crear. Requiere que la spec liste archivos en
# una sección «Archivos» o «Alcance», con rutas entre acentos graves. Sin spec
# activa el check se omite, que es lo correcto: no hay alcance que exceder.
alcance:
  spec: docs/changes/pending/
#   tolerancia: 3


# Documentos que hablan de ESTE repo. audit verifica que lo que mencionan
# exista. Un check sin su artefacto se omite, nunca se aprueba.
artefactos:
  adr: "docs/ADR.md"
  agents: "AGENTS.md"
---


# AI-FIRST.md — demo


> Qué gobierna a este proyecto. Las reglas que el agente obedece están en
> `AGENTS.md`; acá está el mapa que las herramientas verifican.


## Notas


Por qué `.env*` es Zona Prohibida: _(completar: qué cuesta revertir un error ahí)_.
```

Con entrevista, el archivo lleva además el bloque `perfil` y la `fase` y la `verificacion` que se respondieron. En un repo con componentes, `init` agrega bajo `artefactos` las dos claves de la verificación 5, comentadas, para que las actives tú.

## Relacionado

[Las cinco verificaciones](/docs/referencia/verificaciones/)Qué hace cada una con estos campos.

[ai-first init](/docs/referencia/init/)Cómo se genera este archivo y qué deduce el escaneo.

[Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/)Por qué existen las Zonas Prohibidas, el ADR y la medición de entropía.

# Las 11 skills

> El catálogo de las once skills del paquete, con cuándo se activa cada una, qué escribe, cuáles instala init y dónde se explica.

El paquete trae once skills. Una **skill** es un procedimiento en un formato que el agente carga solo cuando la tarea coincide con su descripción: el formato `SKILL.md` del estándar Agent Skills, con `name` y `description` en el frontmatter. `init` las instala en `.agents/skills/`; esta página dice qué hace cada una.

Hay dos tipos. **Cinco son protocolos**: los cuatro de la Parte III del manual en formato ejecutable, más `protocolo-arranque`, que corre antes que todos. **Seis son de oficio**: nacieron resolviendo problemas concretos en proyectos reales y resultaron transferibles.

## Resumen

| Skill                                                   | Tipo      | Se activa                                                                          | Por defecto | Perfiles que la instalan     | Pide interfaz |
| ------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------- | ----------- | ---------------------------- | ------------- |
| [`protocolo-arranque`](#protocolo-arranque)             | Protocolo | Al principio: hay una idea o un requerimiento y todavía no hay PRD ni arquitectura | No          | Todos, con entrevista        | No            |
| [`protocolo-features`](#protocolo-features)             | Protocolo | Comando, módulo o feature nuevo, antes de escribir código                          | **Sí**      | Todos                        | No            |
| [`protocolo-cambios`](#protocolo-cambios)               | Protocolo | Algo que ya funciona tiene que cambiar, incluidos los documentos de gobierno       | **Sí**      | Todos                        | No            |
| [`protocolo-cierre`](#protocolo-cierre)                 | Protocolo | Al cerrar cualquier tramo con commits                                              | **Sí**      | Todos                        | No            |
| [`protocolo-ux`](#protocolo-ux)                         | Protocolo | Al diseñar un feature con interfaz, antes de codear                                | No          | `saas`, `landing`, `movil`   | Sí            |
| [`test-fix`](#test-fix)                                 | Oficio    | Después de implementar, o cuando la suite falla                                    | **Sí**      | Todos                        | No            |
| [`version-bump`](#version-bump)                         | Oficio    | Después de `protocolo-cierre`, para decidir el número de versión                   | **Sí**      | Todos                        | No            |
| [`information-architecture`](#information-architecture) | Oficio    | Al crear, mover o renombrar un módulo, ruta o ítem de navegación                   | No          | `saas`, `movil`              | Sí            |
| [`ux-writer`](#ux-writer)                               | Oficio    | Al escribir cualquier texto visible                                                | No          | `saas`, `landing`, `movil`   | Sí            |
| [`ux-audit`](#ux-audit)                                 | Oficio    | Antes de mergear frontend                                                          | No          | `saas`, `landing`, `movil`   | Sí            |
| [`i18n`](#i18n)                                         | Oficio    | Al agregar textos, plantillas o catálogos                                          | No          | Ninguno: sólo con `--skills` | No            |

**Por defecto** es lo que instala `init` sin entrevista y sin `--skills`: las cinco que no piden interfaz. **Perfiles** es lo que instala con entrevista, según la respuesta a «¿Qué clase de producto es?». Con `--skills todas` entran las once, y con `--skills` y una lista, exactamente ésas. El detalle está en [Qué skills instala](/docs/referencia/init/#qu%C3%A9-skills-instala).

La columna «Se activa» es la misma que `init` escribe en el bloque de `AGENTS.md`. Las descripciones de cada sección son el `description` literal del `SKILL.md`, que es lo que el agente lee para decidir si la carga.

Nota

Cinco skills mandan al registro de decisiones, `docs/ADR.md`, cada decisión difícil de revertir: `protocolo-arranque`, `protocolo-features`, `protocolo-cambios`, `protocolo-cierre` e `information-architecture`. `protocolo-features` y `protocolo-cambios` además piden aprobación antes de tocar una Zona Prohibida. Los dos instrumentos se explican en [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/).

***

## Protocolos

### `protocolo-arranque`

> Protocolo de arranque de un proyecto: del requerimiento en bruto a los artefactos que el desarrollo necesita. Descubrimiento con benchmark de mercado y cuestionamiento exhaustivo hasta cerrar todo vacío, decisión de stack con su fila de ADR, y generación de PRD, arquitectura, specs y guía de diseño a partir de los templates del paquete, en el repo y no en un adjunto. Activar cuando el proyecto todavía no está definido: hay una idea, un requerimiento o notas de reunión, y no hay PRD ni arquitectura escritos. Para implementar un feature de un proyecto ya definido, usar protocolo-features.

**Qué escribe**, en este orden y cada documento desde su [template](/docs/apendices/templates/): la fila de la decisión de stack en `docs/ADR.md`; `docs/PRD.md`; `docs/ARQUITECTURA.md`; `docs/GUIA_DISENO.md` y `docs/COMPONENTES.md` si el producto tiene interfaz; una spec por módulo en `docs/specs/`, o una sola del sitio en una landing; `docs/TECH_NOTES.md`. Al final completa `AI-FIRST.md` y `AGENTS.md`, este último fuera de las marcas de `init`. No instala dependencias ni corre generadores.

Lee primero `AI-FIRST.md`: el perfil decide qué artefactos escribe. Es la única que corre una sola vez por proyecto. Trae `references/artefactos-por-perfil.md`.

Se explica en [La cadena de artefactos](/docs/parte-2/cadena-de-artefactos/) y se usa en [Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-arranque/SKILL.md)

### `protocolo-features`

> Protocolo de desarrollo de features nuevos: pre-implementación en 7 pasos (spec → inventario de reuso → diseño → UX → dependencias → contexto → secuencia), secuencia estricta de implementación por capas, validación incremental y checklists post-implementación. Comprueba Zonas Prohibidas antes de escribir código y manda al ADR las decisiones difíciles de revertir. Activar ANTES de implementar cualquier feature nuevo, página, módulo o endpoint. Para modificar algo que ya existe, usar protocolo-cambios.

**Qué escribe:** el código del feature, en la secuencia de capas del proyecto, y una fila en `docs/ADR.md` si el feature tomó una decisión difícil de revertir. Da por hecha la spec que deja `protocolo-arranque`. La entrevista de `init` le escribe la secuencia, los comandos de verificación y si hay agentes en paralelo.

Se explica en [Protocolo de desarrollo de features](/docs/parte-3/protocolo-features/) y se usa en [Desarrollar una feature](/docs/guias/desarrollar-una-feature/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-features/SKILL.md)

### `protocolo-cambios`

> Protocolo para modificar features ya implementados: clasificación del cambio (corrección / ajuste / requerimiento / prioridad), flujo corto (1-2 archivos) vs. flujo completo (3+ archivos o cambio de schema), documento CHG-XXX obligatorio antes de tocar código, análisis de impacto, implementación por pasos en sesión limpia y cierre en el CHANGE\_LOG. Distingue el cambio, que se archiva, de la decisión arquitectónica, que va al ADR y sobrevive. Activar cuando algo que YA funciona necesita cambiar.

**Qué escribe:** el documento del cambio en `docs/changes/pending/`, antes de tocar código, a partir del molde que trae en `references/documento-de-cambio.md`; ese documento es el que lee la verificación de [alcance excedido](/docs/referencia/verificaciones/#alcance-excedido). Al cerrar, su resumen en `docs/changes/CHANGE_LOG.md`, y el archivo de `pending/` se elimina. Si el cambio es además una decisión arquitectónica, una fila en `docs/ADR.md`.

Se explica en [Protocolo de gestión de cambios](/docs/parte-3/protocolo-cambios/) y se usa en [Cambiar algo que ya funciona](/docs/guias/gestionar-un-cambio/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cambios/SKILL.md)

### `protocolo-cierre`

> Ejecuta la Fase A del protocolo de cierre de sesión: actualiza el SESSION\_LOG, actualiza los docs afectados y enruta los aprendizajes al destino correcto según el árbol de decisión del AGENTS.md, incluida la fila del ADR cuando la sesión tomó una decisión arquitectónica. Activar al terminar cualquier sesión de implementación, antes de hacer commit. Las Fases B (verificar) y C (commit) las hace el humano.

**Qué escribe:** la entrada de la sesión en `docs/SESSION_LOG.md`, los documentos que la sesión dejó desactualizados, y cada aprendizaje en su destino: una fila en `docs/ADR.md` si se decidió algo, una cicatriz en `docs/TECH_NOTES.md`, un cambio cerrado en `docs/changes/CHANGE_LOG.md`. No hace el commit: verificar y firmar es del humano.

Se explica en [Protocolo de cierre de sesión](/docs/parte-3/protocolo-cierre/) y se usa en [Cerrar la sesión](/docs/guias/cerrar-la-sesion/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cierre/SKILL.md)

### `protocolo-ux`

> Reglas de comportamiento e interacción: cuándo modal vs. página nueva, confirmaciones destructivas, navegación por capas (Browse → Create/Edit → Detail), patrones de tabla, formularios, toasts y los 4 estados obligatorios. Activar al DISEÑAR cómo debe comportarse un feature con interfaz — antes de escribir código. Define el QUÉ (comportamiento), no el CÓMO (implementación en el stack).

**Qué escribe:** nada propio. Es una skill de criterio: decide cómo se comporta la interfaz antes de que exista, y la implementación la hace `protocolo-features`. Con entrevista, `init` le escribe dónde están la guía de diseño y el inventario de componentes, o que todavía no existen.

Se explica en [Protocolo UX](/docs/parte-3/protocolo-ux/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-ux/SKILL.md)

***

## Skills de oficio

### `test-fix`

> Corre los tests del alcance que la sesión tocó —unitarios e integración siempre; de extremo a extremo (E2E) sólo bajo decisión explícita—, clasifica cada falla en mecánica (se corrige sin preguntar) o de negocio (se pregunta), aplica la corrección mínima, con un tope de dos rondas, y corre la suite completa una sola vez al final. Activar después de implementar un feature o un cambio, cuando la suite falla y hay que diagnosticar, o como verificación antes del cierre de sesión.

**Qué escribe:** la corrección mínima de cada falla mecánica, en el código o en la prueba. Una falla de negocio no la corrige: la reporta con la decisión que tiene que tomar el humano. Si tras dos rondas quedan fallas, para y reporta. La entrevista de `init` le escribe los comandos de la suite, de tipos y de lint.

Se presenta en [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/test-fix/SKILL.md)

### `version-bump`

> Analiza los commits desde el último tag de versión, clasifica el cambio según SemVer (MAJOR/MINOR/PATCH), recomienda el bump apropiado y lo aplica actualizando los manifiestos del proyecto. Pide confirmación explícita antes de aplicar y NUNCA crea el tag — eso lo hace el humano. Activar al final de una sesión de implementación, después de protocolo-cierre.

**Qué escribe:** el número de versión en todos los manifiestos del proyecto, después de tu confirmación, y la fecha de la entrada del CHANGELOG en el mismo commit, si el proyecto lleva uno. Nunca el tag. La entrevista de `init` le escribe cuál es el manifiesto.

Se presenta en [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/version-bump/SKILL.md)

### `information-architecture`

> Arquitectura de información del producto: qué es una cosa, cómo se llama en cada capa y dónde vive. Reglas de naming (un concepto, un lema), navegación principal vs. configuración, agrupación, modelo de contenido (qué muestra una lista, cuándo un detalle lleva pestañas), relaciones entre módulos y cuándo un cambio de estructura es cambio formal. Activar al diseñar la ESTRUCTURA y el ETIQUETADO de un feature —crear un módulo o ruta, mover algo, renombrar, definir pestañas o columnas, agregar un ítem a la navegación— ANTES de protocolo-ux (comportamiento) y de tu ux-patterns (implementación).

**Qué escribe:** nada propio. Decide la estructura sobre la que `protocolo-ux` define el comportamiento. Un cambio de estructura en algo que ya está en producción lo manda a `protocolo-cambios`, y a `docs/ADR.md` si la razón se va a preguntar en seis meses.

Se menciona en [Protocolo UX](/docs/parte-3/protocolo-ux/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/information-architecture/SKILL.md)

### `ux-writer`

> Contenido, tono y voz del producto: glosario canónico de términos, registros por audiencia, reglas mecánicas de microcopy (botones, títulos, estados vacíos, errores, toasts, confirmaciones) y la regla de temperatura. Activar al escribir o editar CUALQUIER string visible — claves de i18n, plantillas de email y notificación, mensajes de error — y al auditar copy existente.

**Qué escribe:** los textos visibles, según sus reglas. Trae cinco referencias —glosario, voz, superficies, inglés y deuda conocida— que se adaptan al producto: el glosario de otro proyecto no es el tuyo.

Se presenta en [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/ux-writer/SKILL.md)

### `ux-audit`

> Auditoría UX/UI en cuatro capas: análisis estático automatizable (tokens, iconos, i18n, tipografía), validación de patrones de interacción por lectura de código, análisis visual con navegador headless + axe, y juicio subjetivo delegado. Produce un reporte con severidades. Activar antes de mergear un PR de frontend, como gate previo a un release, o ante un reporte de inconsistencia visual.

**Qué escribe:** un reporte de auditoría con los hallazgos por severidad y una acción concreta por hallazgo. No corrige. Trae dos scripts para la primera capa, en `checks/`: el análisis estático y la fidelidad de los skeletons.

Se presenta en [Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/ux-audit/SKILL.md)

### `i18n`

> Las tres capas de internacionalización: strings de interfaz en el frontend, plantillas bilingües de email y notificación en el backend, y campos de etiqueta por idioma en la base de datos para datos dinámicos (roles, estados, catálogos). Activar al agregar cualquier string visible, plantilla de comunicación, campo de catálogo, o al formatear fechas, números y monedas.

**Qué escribe:** los textos y etiquetas en todos los idiomas a la vez: ningún string nuevo se entrega en uno solo. Trae tres referencias, una por capa. Es la única que ningún perfil instala y para la que la entrevista no escribe adaptación.

Se menciona en [GUIA\_DISEÑO.md — Documentación evolutiva](/docs/parte-2/guia-diseno/). [`SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/i18n/SKILL.md)

***

## Cómo se relacionan

```text
protocolo-arranque ──> information-architecture ──> protocolo-ux ──> ux-audit
        │                                            ▲
        └──────────> protocolo-features ──┬──────────┘
                                          ├──> ux-writer ────> i18n
                                          └──> test-fix
                     protocolo-cambios ───┘
                     protocolo-cierre ────────> version-bump
```

Las flechas indican «invoca» o «asume cargada», no un orden de instalación obligatorio: cada skill funciona por separado.

Si tu proyecto ya tiene una skill con el mismo nombre que una del paquete, `init` salta la del paquete entera. Qué hacer entonces está en [Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/).

## Relacionado

[Adaptar las skills a tu proyecto](/docs/guias/adaptar-las-skills/)Lo que escribe la entrevista y lo que queda por hacer a mano.

[ai-first init](/docs/referencia/init/)Cómo se instalan, con qué opciones y qué perfil pide cuáles.

[Templates](/docs/apendices/templates/)Los moldes de los que protocolo-arranque escribe cada documento.

[Skills, hooks y gestión de contexto](/docs/parte-2/skills-hooks-contexto/)Por qué un protocolo rinde más como skill que como documento.

# Templates

> Los ocho templates de documento del paquete y el molde del documento de cambio: qué documento sale de cada uno, dónde vive y quién lo escribe.

Un template es el molde de un documento del proyecto: trae la estructura, las secciones y lo que va en cada una. El paquete trae ocho, más el molde del documento de cambio, que vive dentro de su skill. Viajan en el paquete npm, en su carpeta `templates/`, y cada tarjeta de esta página abre el archivo tal como está publicado.

## Quién los usa

**Los templates ya no se rellenan a mano.** `protocolo-arranque` escribe cada documento a partir del suyo, en su ruta definitiva del repo, después de un descubrimiento que cierra los vacíos y de registrar la decisión de stack en el ADR. El perfil del producto, que declara `AI-FIRST.md`, decide cuáles escribe: un producto sin interfaz no lleva guía de diseño ni inventario de componentes. Qué hace la skill está en [Las 11 skills](/docs/referencia/skills/#protocolo-arranque).

| Template                        | Documento en tu proyecto                 | Lo escribe                                                                                 | Cuándo                                                          |
| ------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `PRD_TEMPLATE.md`               | `docs/PRD.md`                            | `protocolo-arranque`                                                                       | Siempre                                                         |
| `ARQUITECTURA_TEMPLATE.md`      | `docs/ARQUITECTURA.md`                   | `protocolo-arranque`                                                                       | Siempre                                                         |
| `SPEC_MODULO_TEMPLATE.md`       | `docs/specs/<modulo>.md`                 | `protocolo-arranque`                                                                       | Una por módulo; en una landing, una sola, `docs/specs/sitio.md` |
| `GUIA_DISENO_TEMPLATE.md`       | `docs/GUIA_DISENO.md`                    | `protocolo-arranque`                                                                       | Si el producto tiene interfaz: `saas`, `landing`, `movil`       |
| `COMPONENT_LIBRARY_TEMPLATE.md` | `docs/COMPONENTES.md`                    | `protocolo-arranque`                                                                       | Si el producto tiene interfaz                                   |
| `TECH_NOTES_TEMPLATE.md`        | `docs/TECH_NOTES.md`                     | `protocolo-arranque`                                                                       | Siempre                                                         |
| `AGENTS_MD_TEMPLATE.md`         | `AGENTS.md`                              | `init` crea el archivo con su bloque; `protocolo-arranque` lo completa fuera de las marcas | Siempre                                                         |
| `CLAUDE_MD_TEMPLATE.md`         | `CLAUDE.md`                              | Tú: es una línea, `@AGENTS.md`                                                             | Si usas Claude Code                                             |
| `documento-de-cambio.md`        | `docs/changes/pending/CHG-XXX_nombre.md` | `protocolo-cambios`                                                                        | Al abrir cada cambio                                            |

Si prefieres escribir un documento sin la skill, el template sirve igual: copia el molde, reemplaza los marcadores `{...}` con lo de tu proyecto y quita las secciones marcadas `[OPCIONAL]` que no apliquen. Funcionan con cualquier agente, no sólo con Claude Code.

## Archivos de contexto

Los que el agente lee al abrir cada sesión.

[AGENTS\_MD\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/AGENTS_MD_TEMPLATE.md)Fuente de verdad cross-tool (\~150 líneas)

[CLAUDE\_MD\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/CLAUDE_MD_TEMPLATE.md)Puntero liviano + ecosistema de archivos

## Documentos de definición

Los que dicen qué se construye y cómo se ve, antes de escribir código.

[PRD\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/PRD_TEMPLATE.md)PRD completo (10 secciones)

[GUIA\_DISENO\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/GUIA_DISENO_TEMPLATE.md)Guía de diseño organizada por sistema: tokens, tipografía, layout en niveles, móvil, formularios y cicatrices (18 secciones)

[SPEC\_MODULO\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/SPEC_MODULO_TEMPLATE.md)La spec autocontenida de un módulo, que la AI carga sólo cuando trabaja en él; con el índice de docs/specs/ como apéndice

Cada spec lleva una sección «Archivos» o «Alcance» con las rutas entre acentos graves: es la que lee la verificación de [alcance excedido](/docs/referencia/verificaciones/#alcance-excedido).

## Documentos vivos

Crecen con el proyecto y se mantienen en el mismo commit que el código. Son los que el capítulo [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/) nombra como destino de lo que se aprende, y los que `AI-FIRST.md` declara en `artefactos`.

[ARQUITECTURA\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/ARQUITECTURA_TEMPLATE.md)Documento de estado del plano técnico: stack, capas y reglas de dependencia, mapa de módulos, ambientes. El porqué va al ADR

[TECH\_NOTES\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/TECH_NOTES_TEMPLATE.md)Catálogo de cicatrices técnicas por stack: síntoma, causa, solución y fecha para poder podarlas

[COMPONENT\_LIBRARY\_TEMPLATE.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/templates/COMPONENT_LIBRARY_TEMPLATE.md)Inventario vivo de componentes UI por capas: cuándo usar cada uno, cuándo no y qué usar en su lugar

El inventario de componentes es el que vigila la [verificación 5](/docs/referencia/verificaciones/#inventario-de-componentes-desactualizado). Para que lo vigile, `AI-FIRST.md` necesita `artefactos.inventario_componentes` y `artefactos.componentes_dir`.

## El documento de cambio

Los cuatro protocolos de la Parte III ya no se descargan como documento: su versión vigente es la skill. El de cambios exige producir un documento propio antes de tocar código, y éste es su molde:

[documento-de-cambio.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cambios/references/documento-de-cambio.md)El CHG que el protocolo de cambios exige antes de tocar código: impacto, plan, validación y rollback. Vive dentro de su skill, que lo consulta al abrir un cambio

Cada CHG nace en `docs/changes/pending/` del proyecto: ahí lo lee la verificación de alcance y ahí lo revisa un humano en el pull request. El molde vive dentro de la skill porque tiene una sola dueña; los demás templates se quedan aparte porque son documentos permanentes que el `AI-FIRST.md` declara.

Nota

**Las skills no se descargan desde aquí.** Las instala `init`, y el catálogo con el enlace a cada `SKILL.md` está en [Las 11 skills](/docs/referencia/skills/). Cómo instalarlas está en [Inicio rápido](/docs/empezar/inicio-rapido/), y cómo hacerlo en un repo que ya tiene las suyas, en [Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/).

## Relacionado

[Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/)Cómo protocolo-arranque escribe estos documentos a partir de sus templates.

[La cadena de artefactos](/docs/parte-2/cadena-de-artefactos/)Qué alimenta cada documento y en qué orden se escriben.

[Las 11 skills](/docs/referencia/skills/)Las skills del paquete, con su enlace de descarga.

# La metodología

> El manual de Falcux AI-First. Doce capítulos en cuatro partes, de la justificación económica a la adopción en equipo.

Doce capítulos en cuatro partes, de la justificación económica a la adopción en equipo. Explican el porqué de lo que el paquete instala: se leen en orden o se entra directo por el protocolo que haga falta hoy.

## ¿Por qué?

2 capítulos

1. [01El costo de no documentarPor qué documentar antes de codear tiene un ROI medible — con datos reales](/docs/parte-1/costo-de-no-documentar/)
2. [02AI-First no es vibe codingQué es el enfoque AI-First, los 4 roles del developer, y qué lo diferencia del vibe coding](/docs/parte-1/ai-first-no-es-vibe-coding/)

## Fundamentos

5 capítulos

1. [01La cadena de artefactosEl flujo completo: Idea → PRD → Arquitectura → Schema → Contexto AI → Código](/docs/parte-2/cadena-de-artefactos/)
2. [02AGENTS.md — El cerebro del proyectoTemplate y guía para crear el archivo de contexto principal para AI coding agents](/docs/parte-2/agents-md/)
3. [03Gobierno del contextoLos cuatro instrumentos que impiden que la documentación se despegue del proyecto: Zonas Prohibidas, registro de decisiones, permisos del repositorio y la medición de entropía](/docs/parte-2/gobierno-del-contexto/)
4. [04GUIA\_DISEÑO.md — Documentación evolutivaTemplate de guía de diseño que crece orgánicamente con el proyecto](/docs/parte-2/guia-diseno/)
5. [05Skills, hooks y gestión de contextoLas tres capas de optimización: conocimiento on-demand, automatización determinista, y contexto finito](/docs/parte-2/skills-hooks-contexto/)

## Protocolos

4 capítulos

1. [01Protocolo UXPatrones de comportamiento e interacción para que la AI produzca interfaces consistentes](/docs/parte-3/protocolo-ux/)
2. [02Protocolo de gestión de cambiosCómo modificar lo que ya funciona sin romperlo: clasificación, análisis de impacto e implementación por pasos](/docs/parte-3/protocolo-cambios/)
3. [03Protocolo de cierre de sesiónLas tres fases del cierre y por qué solo la primera es delegable a la AI](/docs/parte-3/protocolo-cierre/)
4. [04Protocolo de desarrollo de featuresDe la spec a la verificación: pre-implementación, secuencia estricta y checklists](/docs/parte-3/protocolo-features/)

## Escalar

1 capítulo

1. [01Escalar al equipo y costosCómo llevar la metodología de individual a equipo, y comparación de herramientas y costos](/docs/parte-4/escalar-y-costos/)

# El costo de no documentar

> Por qué documentar antes de codear tiene un ROI medible — con datos reales

> *El argumento más fuerte a favor de documentar no es filosófico — es económico. Cada hora invertida en contexto ahorra días de retrabajo.*

***

## Tres historias, un patrón

### Historia 1: Los 5 restarts

Un product designer con experiencia en desarrollo decide construir un MVP con AI coding agents. Inicializa el proyecto, describe la idea, y le pide al agente que implemente.

Los primeros resultados se ven prometedores. Pero al probar, la mitad de la interfaz es decorativa — botones que no hacen nada, formularios que no envían, menús que no navegan. Cuando empieza a implementar las features reales, el agente cambia el diseño, duplica funcionalidades, y pierde el hilo de lo que ya existe.

Llega un punto donde es imposible continuar. El proyecto es un collage de implementaciones parciales sin coherencia. La única opción es empezar de cero.

Esto ocurre 5 veces. 5 restarts del mismo MVP. 2 sprints de trabajo perdido — no en código, sino buscando cómo hacer que la AI mantenga el contexto del proyecto entre sesiones.

La solución no fue un mejor prompt ni una herramienta diferente. Fue documentar qué se estaba construyendo antes de pedirle a la AI que construyera.

### Historia 2: Las 11 horas

Un tech lead recibe acceso a un AI coding agent para trabajar en un proyecto existente. El proyecto no tiene documentación de arquitectura, ni guía de diseño, ni archivo de contexto para la AI.

El tech lead pasa 11 horas construyendo un solo prompt — intentando darle a la AI suficiente contexto sobre el proyecto para que pudiera ser útil. 11 horas para escribir un prompt. Ni una línea de código. Solo tratando de explicarle al agente qué era el proyecto, cómo estaba estructurado, y qué reglas seguir.

En un proyecto con documentación, ese contexto ya habría existido en un AGENTS.md de 150 líneas que se lee en segundos.

### Historia 3: Las 2 horas

Un equipo de tres personas — product owner, tech lead, y un developer — necesitan implementar una mejora en su producto de firma electrónica. El cliente quiere replicar una experiencia que ya existe en otro módulo de la aplicación.

El proyecto tiene documentación: PRD, specs por módulo, guía de diseño, archivo de contexto para la AI. El equipo configura la sesión, le da el contexto al agente, y trabaja.

En 2 horas, la mejora está implementada, probada, y lista para producción. Lo que en un flujo tradicional hubiera ocupado un sprint completo — estimación, desarrollo, testing, iteración — se resolvió en una mañana.

***

## El patrón

Las tres historias tienen el mismo protagonista: un AI coding agent. La misma tecnología. La misma capacidad de generar código.

La diferencia es una sola: **contexto previo documentado.**

| Escenario            | Documentación previa | Resultado                     | Tiempo             |
| -------------------- | -------------------- | ----------------------------- | ------------------ |
| 5 restarts           | Ninguna              | MVP nunca terminado           | 2 sprints perdidos |
| Prompt del tech lead | Ninguna              | 0 líneas de código producidas | 11 horas           |
| Mejora AutenTIC Sign | Completa             | Feature en producción         | 2 horas            |

El AI coding agent no se volvió más inteligente entre el primer escenario y el tercero. Lo que cambió fue la calidad del contexto que recibió.

***

## Por qué la documentación tradicional no alcanza

La objeción inmediata es: “Pero los proyectos ya tienen documentación — README, comentarios en código, wikis.”

Hay una diferencia fundamental entre documentación para humanos y documentación para AI coding agents.

**Documentación para humanos** asume que el lector tiene contexto implícito. Un developer que lee un README sabe qué es una API REST, entiende las convenciones del framework, y puede inferir patrones del código existente. Los humanos son buenos llenando vacíos.

**Documentación para AI coding agents** no puede asumir nada. El agente empieza cada sesión sin memoria de la anterior. No infiere convenciones — las sigue o las ignora dependiendo de si están escritas explícitamente. No “entiende” que “nunca hardcodear colores” es una regla del proyecto a menos que alguien se lo diga.

Por eso un README típico no funciona como contexto para AI: dice qué es el proyecto y cómo instalarlo, pero no dice qué patrones seguir, qué errores evitar, ni cómo se ve el resultado esperado.

La documentación que Falcux AI-First propone no reemplaza la documentación tradicional. La complementa con una capa diseñada específicamente para que un AI coding agent trabaje como un miembro del equipo que acaba de llegar y necesita saber las reglas del juego.

***

## El concepto: contexto como producto

En desarrollo tradicional, la documentación es un subproducto del código. Se escribe después, si hay tiempo, y se abandona cuando queda obsoleta.

En desarrollo AI-First, **el contexto es el producto principal.** El código es el subproducto.

Esto suena contraintuitivo, pero la lógica es simple: la AI puede generar código a velocidades que ningún humano iguala. Lo que no puede hacer es decidir qué código generar, con qué convenciones, siguiendo qué patrones, respetando qué restricciones. Esas decisiones son humanas. Y la forma de comunicarlas a la AI es a través de documentos de contexto.

Cuando inviertes tiempo en un PRD claro, un AGENTS.md con las reglas del proyecto, y una guía de diseño con los patrones visuales, no estás “documentando” — estás construyendo la interfaz entre tu criterio humano y la capacidad de ejecución de la AI.

El código que la AI produce es tan bueno como el contexto que recibe. Invertir en contexto es invertir directamente en la calidad del código.

***

## La ecuación de tiempo

La objeción que siempre aparece: “Todo eso suena bien, pero toma tiempo. Yo necesito shippear.”

Hagamos la cuenta:

**Sin documentación previa (vibe coding):**

* Sesión 1: AI produce resultado que se ve bien pero no funciona → 2h perdidas
* Sesión 2: Intento corregir, AI pierde contexto → 3h
* Sesión 3: Inconsistencias de diseño, retrabajo → 2h
* Sesión 4: Feature nuevo rompe feature anterior → 3h arreglando
* Sesión 5: Pierdo la paciencia, restart → todo lo anterior perdido
* Total por iteración: 10+ horas con resultado incierto
* Con 5 restarts: 2 sprints sin un MVP funcional

**Con cadena de artefactos:**

* Preparación: PRD + AGENTS.md + schema → 2-4 horas (una vez)
* Sesión 1: AI produce resultado consistente → 2h productivas
* Sesión 2: Retoma donde quedó la anterior → 2h productivas
* Sesión 3: Feature nuevo se integra sin romper → 2h productivas
* Total: 8-10 horas con MVP funcional
* Sin restarts: el proyecto avanza linealmente

**La paradoja:** Invertir 2-4 horas en preparación antes de codear se siente como “perder tiempo”. Pero la alternativa — codear sin preparación — cuesta 10x más en retrabajo, correcciones, e inconsistencias.

No se trata de documentar por documentar. Se trata de que cada hora invertida en contexto ahorra días de retrabajo.

***

## Para quién es esta metodología

Falcux AI-First no es para todos. Es para equipos y personas que:

* **Construyen productos, no experimentos.** Si estás probando una idea en una tarde y la vas a tirar mañana, no necesitas esto. Si estás construyendo algo que va a producción y que otros van a mantener, sí.

* **Trabajan con AI coding agents como herramienta principal.** Si usas AI para autocompletar código (Copilot) pero el humano escribe el 80%, esta metodología es excesiva. Si la AI genera el 60-80% del código y el humano dirige y valida, esta metodología es esencial.

* **Valoran consistencia sobre velocidad bruta.** El vibe coding es más rápido para la primera sesión. Falcux AI-First es más rápido para el proyecto completo. Si tu horizonte es “hoy”, vibecodeá. Si tu horizonte es “las próximas semanas o meses”, sigue leyendo.

* **Están dispuestos a invertir en proceso.** No mucho — estamos hablando de 2-4 horas de preparación por proyecto, no de semanas de planificación. Pero esas horas de preparación existen, y hay que hacerlas.

***

## Lo que viene en este libro

Este primer capítulo hizo el caso de negocio: documentar antes de codear tiene un ROI medible. El resto del libro explica cómo hacerlo.

**Parte I** (este capítulo y el siguiente) establece el por qué y define qué significa “AI-First” como enfoque de desarrollo.

**Parte II** detalla los fundamentos: la cadena de artefactos que produce el contexto, cómo estructurar el AGENTS.md, cómo construir una guía de diseño evolutiva, y cómo gestionar el contexto durante las sesiones.

**Parte III** entrega los 4 protocolos operativos: consistencia de UX, gestión de cambios, cierre de sesión, y desarrollo de features. Cada uno es un proceso replicable con templates y checklists.

**Parte IV** aborda la adopción en equipos: cómo pasar de un workflow individual a una práctica de equipo, y cómo elegir herramientas según presupuesto.

**Los apéndices** incluyen todos los templates descargables, casos de estudio, y un glosario de términos.

Puedes leer el libro de inicio a fin, o saltar directamente a la parte que necesites. Cada capítulo funciona por sí solo, pero todos se alimentan de la misma premisa:

**El costo de no documentar es medible. Y siempre es más alto de lo que crees.**

# AI-First no es vibe coding

> Qué es el enfoque AI-First, los 4 roles del developer, y qué lo diferencia del vibe coding

> *El developer AI-First no escribe código — diseña sistemas, dirige ejecución, cura contexto, y valida resultados. Los cuatro roles a la vez.*

***

## El espectro

Hay un espectro en cómo los equipos usan AI para construir software. Los extremos son claros. El medio es donde está la oportunidad — y la confusión.

### Desarrollo tradicional

El humano escribe todo el código. La AI, si aparece, es autocompletado inteligente — sugiere la siguiente línea, completa una función, genera un snippet. El humano toma el 95% de las decisiones y escribe el 95% del código. La AI es un asistente de escritura, no un constructor.

Funciona. Es predecible. Pero no aprovecha lo que la AI puede hacer hoy.

### Vibe coding

El humano describe una idea en lenguaje natural y la AI genera todo: frontend, backend, base de datos, estilos. El humano no planifica, no documenta, no estructura — simplemente pide y evalúa el resultado. Si se ve bien, avanza. Si no, pide correcciones o empieza de nuevo.

El vibe coding tiene un atractivo innegable: la velocidad inicial es intoxicante. En 10 minutos tienes algo que se ve como un producto. El problema aparece en el minuto 11 — cuando quieres agregar la segunda feature y la AI no recuerda la primera, o cuando el diseño cambia con cada prompt, o cuando descubres que la mitad de la interfaz es decorativa.

El vibe coding funciona para prototipos desechables, demos, y pruebas de concepto que nadie va a mantener. No funciona para productos que van a producción, que necesitan evolucionar, o que más de una persona va a tocar.

### AI-First (donde vive Falcux AI-First)

El humano diseña el sistema, documenta el contexto, y define las reglas. La AI genera el 80-90% del código siguiendo ese contexto. El humano valida, corrige, y mantiene la documentación actualizada para la siguiente sesión.

La diferencia con el vibe coding no es de grado — es de naturaleza. El vibe coder pide y espera. El developer AI-First prepara, dirige, y verifica. El vibe coder trabaja con prompts. El developer AI-First trabaja con sistemas de contexto.

La diferencia con el desarrollo tradicional tampoco es de grado. El developer tradicional invierte su tiempo en escribir código. El developer AI-First invierte su tiempo en diseñar la arquitectura, curar el contexto, y validar los resultados. El código lo genera otro — y ese otro es extraordinariamente rápido pero necesita dirección clara.

***

## Los 4 roles del developer AI-First

En desarrollo tradicional, un developer es fundamentalmente un escritor de código. En desarrollo AI-First, el código lo escribe la AI. Entonces, ¿qué hace el humano?

Hace cuatro cosas, todo el tiempo, simultáneamente:

### Arquitecto

Diseña la estructura del sistema antes de que exista una línea de código. Define las capas, los patrones, las tecnologías, y las restricciones. La AI puede proponer una arquitectura, pero la decisión de adoptarla — con sus tradeoffs de escalabilidad, mantenibilidad, y complejidad — es humana.

El arquitecto responde: ¿cómo se estructura esto?

En la práctica: escribe (o valida) el PRD, la arquitectura técnica, el schema de BD. Define la cadena de artefactos del capítulo anterior. Estas decisiones no son delegables porque dependen de contexto que la AI no tiene — el tamaño del equipo, el presupuesto, la experiencia disponible, las restricciones del negocio.

### Director

Define qué se construye en cada sesión, en qué orden, y con qué restricciones. Le dice a la AI qué hacer, qué no tocar, y qué resultado esperar. No microgestiona cada línea — da la dirección y deja que la AI ejecute.

El director responde: ¿qué hacemos ahora y cómo?

En la práctica: prepara el prompt de implementación con contexto completo. Define la secuencia (schema → backend → frontend → tests). Divide features grandes en pasos pequeños. Detiene la sesión cuando la AI va por mal camino. Es el Protocolo de Desarrollo de Features en acción.

### Curador

Mantiene el contexto del proyecto vivo y actualizado. Cada sesión de implementación produce conocimiento nuevo — gotchas descubiertos, patrones que funcionan, anti-patrones que se deben evitar. El curador captura ese conocimiento y lo integra en los documentos que la AI lee.

El curador responde: ¿qué sabe la AI sobre este proyecto?

En la práctica: mantiene el AGENTS.md con reglas críticas. Actualiza la guía de diseño con cada componente nuevo y cada gotcha. Agrega anti-patrones a “What NOT to Do” conforme se descubren. Ejecuta el Protocolo de Cierre de Sesión. Sin el curador, cada sesión empieza un poco más perdida que la anterior.

### Validador

Revisa lo que la AI produce con criterio técnico y de producto. No lee cada línea de código — verifica que el resultado cumple la spec, que los tests pasan, que el diseño es consistente, y que no se rompió nada existente.

El validador responde: ¿esto está bien?

En la práctica: ejecuta los checklists post-implementación. Verifica que la documentación que la AI actualizó es precisa. Cruza el resultado con el PRD y la guía de diseño. Aprueba o rechaza antes de avanzar al siguiente paso.

### Los 4 roles no son secuenciales

No se ejerce un rol y luego otro. En una sesión típica, el developer AI-First alterna entre los cuatro constantemente:

```plaintext
"Vamos a implementar el módulo de tags"          → Director
"Seguir la clean architecture de 3 capas"        → Arquitecto
"No modificar el módulo de decisiones"            → Director
[AI implementa]
"Los tests pasan, el endpoint responde bien"      → Validador
"Descubrí que ScrollArea necesita altura fija"    → Curador (agrega gotcha)
"Ahora el frontend, usar shadcn/ui"               → Director
[AI implementa]
"El diseño no es consistente con la tabla anterior" → Validador
"Agregar regla: siempre ícono de ojo para detalle" → Curador
```

Esta alternancia constante es lo que hace que el rol sea nuevo — no existe en el desarrollo tradicional porque el humano escribe el código en vez de dirigir a otro que lo escribe.

***

## Qué NO es AI-First

### No es “la AI hace todo sola”

El developer AI-First no pone un prompt y se va a tomar café. Está presente durante toda la sesión, validando paso a paso, corrigiendo el rumbo, y tomando decisiones que la AI no puede tomar. La AI es el ejecutor más rápido que ha existido, pero sin dirección humana produce los mockups decorativos del capítulo anterior.

### No es reemplazar developers

Un equipo AI-First no necesita menos developers — necesita developers con habilidades diferentes. Menos tiempo escribiendo for loops, más tiempo diseñando sistemas, definiendo arquitecturas, y manteniendo contexto. Las habilidades de programación siguen siendo necesarias para validar lo que la AI produce, entender los tradeoffs, y corregir errores que la AI no detecta.

### No es solo para developers

Un product designer que entiende arquitectura y sabe validar código puede ser un developer AI-First efectivo. Un product owner que puede escribir specs claras y evaluar resultados puede dirigir sesiones de implementación. AI-First reduce la barrera de quién puede construir software, pero no la elimina — todavía hay que entender qué se está construyendo.

### No es una bala de plata

Hay proyectos donde AI-First no funciona bien: sistemas legacy sin documentación (la AI no tiene contexto de dónde partir), investigación pura (no hay spec posible porque no se sabe qué se busca), código que requiere optimización de bajo nivel (la AI genera código funcional pero no necesariamente eficiente), y sistemas con requisitos de seguridad extremos (la AI puede introducir vulnerabilidades sutiles que un humano no detecta en la validación).

***

## DEV AI First: el enfoque dentro del enfoque

Falcux AI-First es la metodología. DEV AI First es el enfoque de desarrollo que la metodología enseña. La distinción importa:

**DEV AI First** como enfoque significa: diseñar todo el flujo de desarrollo asumiendo que la AI es el builder principal. No es “desarrollo tradicional con AI auxiliar” — es un flujo rediseñado desde cero donde:

* La documentación se escribe para que la AI la entienda, no solo los humanos
* La arquitectura se define antes del código, no emerge del código
* Las convenciones se codifican explícitamente, no se asumen implícitamente
* La verificación es sistemática, no ocasional
* El contexto es un producto, no un subproducto

Cuando un equipo adopta DEV AI First, no está “agregando AI a su proceso” — está cambiando su proceso para que la AI sea central. La cadena de artefactos, los protocolos, los templates — todo existe porque la AI es el builder principal y necesita una infraestructura de contexto para funcionar bien.

***

## El cambio de mentalidad

La transición más difícil no es técnica. Es mental.

En desarrollo tradicional, el valor del developer se mide en código producido. Más líneas, más commits, más features implementadas. Documentar se siente como “no trabajar” porque no produce código.

En desarrollo AI-First, el valor del developer se mide en calidad de dirección. Un AGENTS.md bien escrito produce mejores resultados que 8 horas de vibe coding. Una guía de diseño con gotchas documentados evita horas de correcciones. Un protocolo de cambios previene regresiones.

El cambio de mentalidad es: **tu trabajo más productivo ya no se ve como trabajo.** Las horas que inviertes preparando artefactos, curando contexto, y documentando anti-patrones son las horas que más impacto tienen en la calidad y velocidad del proyecto. Pero no se ven como “programar” — se ven como “documentar”.

Equipos que no internalizan este cambio terminan con un developer que “vibecodeá rápido” y tres developers arreglando los problemas que el vibe coding creó. Equipos que sí lo internalizan terminan con un developer AI-First que produce el equivalente a un equipo completo — pero invierte la mitad de su tiempo en contexto, no en código.

***

## Dónde empieza el viaje

Si vienes del vibe coding y quieres estructura: empieza por la cadena de artefactos (capítulo 3) y el template de AGENTS.md (capítulo 4). Solo eso ya transforma tu flujo.

Si vienes del desarrollo tradicional y quieres velocidad: empieza por los protocolos (capítulos 7-10). Son procesos concretos que puedes adoptar mañana.

Si eres un líder y quieres que tu equipo adopte esto: empieza por el caso de negocio (capítulo 1, que acabas de leer) y la guía de onboarding (capítulo 11).

El resto del libro detalla cada pieza del sistema. Pero el fundamento es este capítulo y el anterior: documentar antes de codear tiene un ROI medible, y el developer AI-First es un rol nuevo que combina arquitectura, dirección, curaduría, y validación.

El código lo escribe la AI. Tu trabajo es todo lo demás.

# La cadena de artefactos

> El flujo completo: Idea → PRD → Arquitectura → Schema → Contexto AI → Código

> *Idea → PRD → Arquitectura → Schema → Contexto AI → Código*
>
> El flujo que convierte una idea en software funcional sin perder el hilo en el camino.

***

## La historia de los 5 restarts

En mis primeros laboratorios con AI coding agents, el flujo era simple: inicializar un proyecto con un stack, describir una idea en un par de líneas, y pedirle al agente que implementara.

El primer resultado siempre parecía prometedor. La UI aparecía rápido, con menús, botones, y secciones que se veían completas. Pero al probar, la realidad era otra: la mayoría de las opciones eran mockups — se veían pero no hacían nada. Botones decorativos. Formularios que no enviaban. Navegación que no llevaba a ningún lado.

Lo peor venía después, cuando empezaba a implementar las features de verdad. La AI cambiaba el diseño cada vez que le pedía algo nuevo. Funcionalidades se duplicaban en distintas partes de la interfaz. Features nuevas aparecían visibles en la UI pero sin funcionalidad real, mientras las anteriores dejaban de funcionar. Y cuando pedía ajustar el diseño, la AI perdía el contexto de lo que ya existía.

Llegaba un punto — siempre llegaba — donde era imposible continuar. El proyecto se había convertido en capas de implementaciones parciales, sin coherencia entre ellas. La única opción era empezar de cero.

Tuve que reiniciar un mismo MVP al menos 5 veces. Cada restart era un intento de descubrir cómo mantener el contexto del proyecto a lo largo de múltiples sesiones de implementación.

Lo que descubrí, después de esos 5 intentos, no fue un truco de prompting ni una configuración mágica. Fue algo más fundamental: **la AI necesita saber qué está construyendo antes de escribir la primera línea de código.** Y esa información no se puede dar en un párrafo — necesita una cadena de documentos, cada uno alimentando al siguiente.

Esa cadena es lo que este capítulo documenta.

***

## La cadena completa

```plaintext
Idea
  ↓
PRD (qué se construye y para quién)
  ↓
Arquitectura (cómo se estructura técnicamente)
  ↓
DB Schema (qué datos existen y cómo se relacionan)
  ↓
Contexto AI (AGENTS.md + GUIA_DISEÑO.md)
  ↓
Implementación con AI coding agent
  ↓
Documentación post-implementación
```

Cada eslabón produce un artefacto que el siguiente eslabón consume. Romper la cadena — saltar un eslabón — significa que la AI trabaja con información incompleta. A veces funciona. A veces produce los mockups decorativos del inicio de esta historia.

***

## Los eslabones en detalle

### Eslabón 1: PRD — El contrato de qué se construye

**Qué es:** Un documento que describe el producto desde la perspectiva del usuario. Qué hace, para quién, qué problema resuelve, y cuáles son los límites de lo que se construye en esta fase.

**Por qué es el eslabón más crítico:** De toda la cadena, el PRD es el único artefacto que no debería saltarse nunca. Sin PRD, la AI no tiene un norte. Puede generar código que funcione técnicamente pero que no resuelve el problema correcto, o que incluye features que nadie pidió mientras omite las que sí importan.

**Quién lo produce:** Típicamente el PO o el product designer. En equipos pequeños, un LLM puede generar un borrador a partir de un documento de requerimientos o una descripción verbal — pero un humano debe validar que refleja lo que realmente se necesita.

**Señales de un buen PRD para AI:**

* Describe comportamiento esperado, no solo features (“el usuario puede registrar una decisión en 30 segundos” vs. “formulario de decisiones”)
* Define explícitamente qué NO se incluye en esta fase
* Lista criterios de aceptación verificables
* Es independiente de la implementación técnica

**El error más común:** PRDs generados por AI que agregan features que nadie pidió. El LLM tiende a “completar” lo que parece faltar basándose en patrones de productos similares. Siempre validar que cada feature listada fue explícitamente solicitada.

**Formato:** Markdown (`docs/PRD.md`). Puede dividirse por módulo si el producto es grande (`docs/PRD-MODULE1.md`, `docs/PRD-MODULE2.md`).

***

### Eslabón 2: Arquitectura — El plano técnico

**Qué es:** Un documento que define cómo se estructura el sistema: qué tecnologías se usan, cómo se organizan las capas, cómo fluyen los datos, cómo se maneja la autenticación, y qué patrones de diseño se siguen.

**Por qué importa para la AI:** Sin un documento de arquitectura, la AI toma decisiones arquitectónicas por ti. A veces acierta. A veces crea un monolito cuando necesitas microservicios, o pone lógica de negocio en los controllers cuando debería ir en use cases. El documento de arquitectura elimina esa ambigüedad.

**Quién lo produce:** El tech lead o el developer senior. Un LLM puede generar un borrador basado en el PRD + el stack elegido, pero las decisiones de arquitectura son inherentemente humanas — dependen de contexto que la AI no tiene (tamaño del equipo, presupuesto de infraestructura, experiencia del equipo, requisitos de escalabilidad).

**Qué incluir como mínimo:**

* Stack tecnológico con versiones
* Patrón de arquitectura (monolito, clean architecture, microservicios, etc.)
* Estructura del proyecto (monorepo, multi-repo, carpetas)
* Flujo de autenticación
* Patrones de comunicación entre módulos
* Decisiones técnicas y sus justificaciones

**Cuándo se puede saltar:** En prototipos muy rápidos donde el objetivo es validar una idea en horas, no construir algo mantenible. Pero hay que ser honesto: si saltas la arquitectura, estás aceptando deuda técnica desde el día uno.

**Formato:** Markdown (`docs/ARQUITECTURA.md`). Es un documento de estado: describe cómo es el sistema hoy y se sobreescribe cuando cambia; el porqué de cada decisión va al `docs/ADR.md`. (Template: ARQUITECTURA\_TEMPLATE.md)

***

### Eslabón 3: DB Schema — La estructura de los datos

**Qué es:** La definición de los modelos de datos, sus relaciones, y las reglas de integridad. En proyectos con Prisma, es el `schema.prisma`. En otros ORMs, sus equivalentes.

**Por qué importa para la AI:** El schema de BD es el contrato más estricto del sistema. Si la AI empieza a implementar features sin saber qué datos existen y cómo se relacionan, va a inventar modelos sobre la marcha — y cada modelo inventado sobre la marcha es una migración futura que probablemente falle.

**Quién lo produce:** Es el artefacto más variable. Tres escenarios comunes:

1. **El humano lo diseña completo:** Basándose en el PRD y la arquitectura, define los modelos antes de implementar. Máximo control, más tiempo.

2. **La AI lo propone, el humano valida:** Se le da el PRD y se le pide que proponga un schema. Rápido, pero hay que revisar con cuidado — la AI tiende a sobre-normalizar o crear relaciones que no se necesitan.

3. **Se define incrementalmente:** Se empieza con los modelos mínimos y se agregan conforme se implementan features. Funciona en MVPs, pero requiere disciplina en migraciones.

**El gotcha de las migraciones:** Las migraciones de Prisma (y de otros ORMs) a veces fallan cuando la AI modifica el schema sin considerar los datos existentes. Esto es especialmente problemático cuando hay campos que pasan de opcionales a obligatorios, o cuando se renombran tablas. Documentar el estado actual del schema antes de cada cambio reduce significativamente estos problemas.

**Formato:** El archivo del ORM (`packages/prisma/schema.prisma`) + documentación de las decisiones de modelado en `docs/ARQUITECTURA.md` o en la spec del módulo al que pertenecen (`docs/specs/<modulo>.md`, una por módulo, con índice en `docs/specs/README.md`). (Template: SPEC\_MODULO\_TEMPLATE.md)

***

### Eslabón 4: Contexto AI — La interfaz entre el humano y el agente

**Qué es:** Los archivos que le dan a la AI la información que necesita para trabajar en el proyecto: AGENTS.md (reglas, comandos, restricciones), GUIA\_DISEÑO.md (cómo debe verse y comportarse la UI), y skills (conocimiento especializado on-demand).

**Por qué es donde todo converge:** Los tres eslabones anteriores (PRD, arquitectura, schema) producen conocimiento. El contexto AI es donde ese conocimiento se traduce a instrucciones que la AI puede seguir. Sin este eslabón, los documentos anteriores existen pero la AI no los consulta automáticamente.

**Qué incluye:**

* `AGENTS.md` — El cerebro del proyecto. Reglas críticas, comandos, estructura, “What NOT to Do”. Máximo \~150 líneas, el resto delegado a docs y skills. (Template: AGENTS\_MD\_TEMPLATE.md)
* `GUIA_DISEÑO.md` — La guía visual. Tokens de color, tipografía, componentes, patrones de página, gotchas. Crece con el proyecto. (Template: GUIA\_DISENO\_TEMPLATE.md)
* `.claude/skills/` (o equivalente) — Conocimiento especializado que se carga on-demand: clean architecture, testing, i18n, dominio del negocio.

**El principio del AGENTS.md:** Cada línea debe responder a la pregunta “¿la AI cometería un error sin esta instrucción?” Si la respuesta es no, la línea no necesita estar ahí.

**Cuándo se puede simplificar:** Para un prototipo rápido, un AGENTS.md mínimo con descripción del proyecto + stack + comandos + 5 reglas críticas es suficiente. La guía de diseño puede esperar hasta que haya UI que implementar.

**Formato:** Markdown en la raíz del proyecto y en `docs/`.

***

### Eslabón 5: Implementación — Donde la AI trabaja

**Qué es:** Las sesiones de implementación con el AI coding agent, siguiendo el Protocolo de Desarrollo de Features.

**Cómo se alimenta de la cadena:** Cada sesión de implementación consume los artefactos anteriores:

* El PRD le dice QUÉ construir
* La arquitectura le dice CÓMO estructurarlo
* El schema le dice QUÉ DATOS existen
* El AGENTS.md le dice QUÉ REGLAS seguir
* La GUIA\_DISEÑO le dice CÓMO DEBE VERSE

Cuando todos los eslabones están en su lugar, la AI produce resultados consistentes desde el primer intento. Cuando falta alguno, la AI llena el vacío con suposiciones — y esas suposiciones son la causa de los mockups decorativos, las inconsistencias de diseño, y los restarts.

***

### Eslabón 6: Documentación post-implementación — Cerrar el loop

**Qué es:** La actualización de la documentación después de cada sesión, siguiendo el Protocolo de Cierre de Sesión.

**Por qué es un eslabón de la cadena y no un paso suelto:** La documentación que se produce al cerrar una sesión alimenta la siguiente sesión. El SESSION\_LOG.md le dice a la próxima sesión qué se hizo. Los anti-patrones descubiertos se agregan al AGENTS.md. Los gotchas de CSS se agregan a la GUIA\_DISEÑO. Lo que costó horas resolver y ya está resuelto va a `TECH_NOTES.md`, con fecha (Template: TECH\_NOTES\_TEMPLATE.md). Sin este eslabón, cada sesión empieza desde cero — que es exactamente lo que causaba los restarts.

***

## Los artefactos: quién los produce y con qué

| Eslabón             | Artefacto                       | Quién produce                                     | Con qué herramienta                                |
| ------------------- | ------------------------------- | ------------------------------------------------- | -------------------------------------------------- |
| PRD                 | `docs/PRD.md`                   | PO/Designer valida, LLM puede generar borrador    | Claude.ai, ChatGPT, o cualquier LLM conversacional |
| Arquitectura        | `docs/ARQUITECTURA.md`          | Tech lead/Dev senior decide, LLM puede documentar | LLM + conocimiento humano del contexto             |
| Schema              | `schema.prisma` o equivalente   | Variable: humano, AI propone, o incremental       | Claude Code, herramienta de diseño de BD           |
| Contexto AI         | `AGENTS.md` + `GUIA_DISEÑO.md`  | Humano estructura, AI puede llenar detalles       | Editor de texto + templates de Falcux AI-First     |
| Implementación      | Código fuente                   | AI coding agent ejecuta, humano valida            | Claude Code, Antigravity, Cursor, etc.             |
| Post-implementación | SESSION\_LOG, docs actualizados | AI documenta, humano verifica                     | El mismo AI coding agent de la sesión              |

**Patrón predominante:** El humano define la estructura y valida. El LLM genera el contenido detallado. Esto aplica a casi todos los eslabones — la AI es excelente produciendo texto estructurado a partir de una dirección clara, pero mala decidiendo qué dirección tomar.

***

## Qué pasa cuando saltas un eslabón

No todos los eslabones son obligatorios en todas las circunstancias. Pero saltar un eslabón tiene consecuencias predecibles:

| Eslabón saltado     | Consecuencia más probable                                              | Cuándo es aceptable saltarlo                           |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
| PRD                 | La AI implementa features que nadie pidió o ignora las que sí importan | Nunca — siempre tener al menos una spec mínima         |
| Arquitectura        | La AI toma decisiones de arquitectura inconsistentes entre sesiones    | Prototipos de validación rápida (menos de 1 día)       |
| Schema              | Migraciones que fallan, modelos inventados sobre la marcha             | Cuando la AI propone y el humano valida inmediatamente |
| AGENTS.md           | La AI no respeta convenciones, repite errores ya conocidos             | Nunca en proyectos con más de 1 sesión                 |
| GUIA\_DISEÑO        | Inconsistencia visual, cada componente se ve diferente                 | Primera sesión de un MVP (se crea durante, no antes)   |
| Post-implementación | La siguiente sesión no tiene contexto, pendientes se pierden           | Cambios triviales (fix de typo, ajuste cosmético)      |

**La regla práctica:** En un MVP rápido, el mínimo absoluto es PRD + AGENTS.md mínimo. Todo lo demás acelera la calidad pero no es bloqueante para empezar. Conforme el proyecto crece, la deuda de artefactos faltantes se acumula — y pagarla después siempre cuesta más que crearlos desde el inicio.

***

## La cadena adaptada por contexto

No todos los proyectos necesitan la cadena completa al mismo nivel de detalle.

### Prototipo rápido (validar idea en horas)

```plaintext
Idea → Spec mínima (1 página) → AGENTS.md mínimo (50 líneas) → Implementar → Evaluar
```

Se saltan: arquitectura formal, schema previo, guía de diseño. Se aceptan las consecuencias: la AI va a tomar atajos. El objetivo no es calidad — es velocidad de validación.

### MVP serio (construir algo que se shippea)

```plaintext
Idea → PRD → Arquitectura → Schema → AGENTS.md completo + GUIA_DISEÑO básica → Implementar por features → Docs post-sesión
```

Todos los eslabones presentes. La guía de diseño empieza básica (tokens, layout, breakpoints) y crece con cada feature implementado.

### Producto en crecimiento (equipo, múltiples features en paralelo)

```plaintext
PRD por módulo → Arquitectura viva → Schema con migraciones controladas → AGENTS.md + skills + GUIA_DISEÑO madura → Protocolos completos (features, cambios, cierre, UX)
```

La cadena completa con los 4 protocolos activos. El AGENTS.md delega a skills para mantener el contexto ligero. La guía de diseño tiene cientos de líneas documentando cada componente y gotcha.

***

## El costo de la cadena vs. el costo de no tenerla

La objeción más común: “Esto es mucho trabajo antes de empezar a codear.”

La respuesta está en los números:

**Sin cadena de artefactos:**

* 5 restarts de un MVP buscando cómo mantener contexto
* 11 horas de un tech lead construyendo un prompt para un proyecto sin documentación
* Features tipo mockup que hay que reimplementar
* Inconsistencias de diseño que hay que corregir sesión tras sesión

**Con cadena de artefactos:**

* 2 horas implementando algo que hubiera tomado un sprint
* Features que funcionan desde el primer intento
* Sesiones que retoman donde quedó la anterior sin perder contexto
* Una guía de diseño de 1134 líneas que crece sola mientras se construye

El tiempo que inviertes en artefactos previos no es overhead — es la diferencia entre construir sobre una base sólida y construir sobre arena.

***

## Resumen accionable

1. **Siempre** empieza con un PRD o spec mínima — nunca le pidas a la AI que implemente una idea sin documentar qué es.

2. **El AGENTS.md es obligatorio** a partir de la segunda sesión — sin él, cada sesión es un restart parcial.

3. **Deja que la AI genere borradores** de PRD, arquitectura, y schema — pero valida todo antes de implementar. En un producto nuevo, la skill `protocolo-arranque` los escribe en el repo desde los templates del paquete: ver [Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/).

4. **La guía de diseño crece con el proyecto** — no intentes escribirla completa al inicio. Empieza con tokens y layout, agrega componentes y gotchas conforme aparecen.

5. **Cierra cada sesión actualizando la documentación** — el eslabón de post-implementación es lo que hace que la cadena sea un ciclo, no una línea recta.

6. **Adapta la cadena al contexto** — un prototipo no necesita lo mismo que un producto en producción. Pero sé consciente de qué estás saltando y qué deuda estás asumiendo.

# AGENTS.md — El cerebro del proyecto

> Template y guía para crear el archivo de contexto principal para AI coding agents

> Este template define la estructura recomendada para el archivo AGENTS.md (o equivalente). El CLAUDE.md debe contener únicamente: `@AGENTS.md`
>
> **Principio:** Máximo \~150 líneas en este archivo. Todo conocimiento especializado va en skills (.claude/skills/) o documentación referenciada. Cada línea aquí debe responder a: “¿La AI cometería un error sin esta instrucción?”

***

## Cómo usar este template

1. Copiar este archivo como `AGENTS.md` en la raíz del proyecto
2. Crear `CLAUDE.md` con solo: `@AGENTS.md`
3. Reemplazar los placeholders `{...}` con información del proyecto
4. Eliminar las secciones marcadas como `[OPCIONAL]` si no aplican
5. Mover conocimiento extenso a skills o docs referenciados

### Convención de archivos

```plaintext
CLAUDE.md          → Solo referencia: @AGENTS.md (Claude Code)
AGENTS.md          → Fuente de verdad cross-tool (este archivo)
```

Para herramientas que no soportan AGENTS.md (Antigravity, Lovable, etc.), copiar el contenido relevante en el campo de contexto del proyecto.

### El template viaja en el paquete

Este template es `AGENTS_MD_TEMPLATE.md` y viaja en la carpeta `templates/` del paquete `@falcux/ai-first`. En un producto nuevo no hace falta copiarlo a mano: la skill `protocolo-arranque` escribe el AGENTS.md desde él, al final del arranque, cuando ya se conocen el stack, la arquitectura y los comandos. El recorrido está en [Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/).

### El bloque que mantiene `init`

`npx @falcux/ai-first@latest init` no redacta tu AGENTS.md: le agrega un bloque entre `<!-- ai-first:inicio -->` y `<!-- ai-first:fin -->` con las skills instaladas, cuándo invocar cada una y dónde escribe cada una. Si el archivo no existía, lo crea con ese bloque y un puntero a este template; si existía, pone el bloque al final. Cada corrida lo reescribe con lo que encuentra instalado, y fuera de las marcas no toca nada.

La regla que sale de ahí: lo tuyo va fuera de las marcas, y lo de adentro no se edita a mano, porque la próxima corrida lo pisa. Qué más escribe `init` está en [Qué deja init en tu repo](/docs/empezar/que-instala/).

***

# {Nombre del Proyecto}

> {Descripción en 1-2 líneas: qué es, para quién, qué problema resuelve.}

**Dominio:** {URLs de producción si existen}

## Estructura del Monorepo

```plaintext
{nombre}/
├── apps/
│   ├── web/                → {Framework frontend}
│   └── api/                → {Framework backend}
├── packages/
│   ├── ui/                 → {Librería de componentes}
│   ├── shared/             → {Schemas, types, constantes}
│   └── prisma/             → {ORM schema, migraciones}
├── docs/                   → {Documentación del proyecto}
│   ├── PRD.md
│   ├── GUIA_DISENO.md
│   ├── ARQUITECTURA.md
│   └── changes/            → Protocolo de gestión de cambios
│       ├── CHANGE_LOG.md
│       └── pending/
└── CLAUDE.md               → @AGENTS.md
```

## Tech Stack

**Frontend:** {Framework, form library, validación, UI library, CSS, i18n, iconos, testing} **Backend:** {Framework, ORM, validación, auth strategy, scheduling, docs API, testing} **Auth:** {Proveedor → mecanismo → estrategia en backend} **Servicios:** {Email, billing, monitoring, etc.} **Infra:** {Hosting frontend, hosting backend, DB, Auth provider} **Monorepo:** {Package manager, orchestrator, TS config}

## Comandos

```bash
# Desarrollo
{comando dev}                    # {descripción}
{comando build}                  # {descripción}
{comando lint}                   # {descripción}
{comando typecheck}              # {descripción}


# Testing
{comando test frontend}         # {descripción}
{comando test backend}          # {descripción}


# Base de datos
{comando migraciones}           # {descripción}
{comando seed}                  # {descripción}
{comando studio/GUI}            # {descripción}


# UI Components [si aplica]
{comando agregar componente}    # {descripción + notas}
```

## Reglas Críticas

> Solo incluir reglas que la AI violaría sin esta instrucción. Para reglas extensas, crear un skill en .claude/skills/

### Arquitectura

* {Regla 1 — patrón arquitectónico principal y qué NUNCA violar}
* {Regla 2 — dependencias permitidas entre capas}
* {Regla 3 — dónde va la lógica de negocio}

### Multi-tenancy \[si aplica]

* {Regla de aislamiento de datos entre tenants}
* {Cómo se obtiene el tenant\_id}

### UI y Diseño

* {Regla de tokens — NUNCA hardcodear colores}
* {Regla de tipografía o peso de fuente}
* {Referencia a guía de diseño}: ver `docs/GUIA_DISENO.md`
* {Referencia a protocolo UX}: ver la skill `protocolo-ux`

### i18n \[si aplica]

* {Regla de no hardcodear strings}
* {Referencia a skill o convenciones}: ver `.claude/skills/i18n-patterns/`

### ORM / Base de datos

* {Convención de naming — snake\_case, @map, etc.}
* {Campos obligatorios por modelo — id, timestamps, tenant\_id}
* {Soft delete u otras convenciones}

### Git

* Ramas: `{patrón de ramas}`
* Commits: `{patrón de commits}`

## Protocolo de Desarrollo de Features (OBLIGATORIO)

Antes de escribir código para cualquier feature nueva:

1. **Leer** `docs/GUIA_DISENO.md` — aplicar tokens, patrones, layout
2. **Consultar** la skill `protocolo-ux` — verificar navegación por capas, interacciones
3. **\[Si aplica] Lanzar agente especializado** — `{nombre del agente}` para validar enfoque
4. **Verificar** {verificaciones pre-implementación: i18n, tipos, etc.}
5. **Implementar** por pasos pequeños, validando después de cada uno
6. **Después de implementar:** ejecutar `{comando de verificación}` + actualizar docs

### Gestión de cambios post-implementación

Para cambios de requerimientos en features existentes, se activa la skill `protocolo-cambios`. NUNCA implementar un cambio sin documento CHG-XXX previo.

## Documentación

> Listar TODOS los documentos que la AI debe conocer, agrupados por función.

### Especificaciones del producto

* `docs/PRD.md` — {descripción breve}
* `docs/ARQUITECTURA.md` — {descripción breve}
* `docs/specs/\{modulo\}.md` — Specs autocontenidas, una por módulo; cargar la del módulo en curso \[si existen]

### Diseño y UX

* `docs/GUIA_DISENO.md` — Guía de diseño del proyecto (tokens, componentes, gotchas)
* `docs/COMPONENT_LIBRARY.md` — Inventario de componentes UI \[si existe]

### Gestión de cambios

* `docs/changes/CHANGE_LOG.md` — Registro histórico de cambios
* `docs/changes/pending/` — Cambios en proceso

### Requerimientos externos \[si aplica]

* `docs/requerimientos/{archivo}` — {descripción}

## What NOT to Do

> Anti-patrones descubiertos durante el desarrollo. Cada línea existe porque la AI ya cometió este error al menos una vez.

* NO {anti-patrón 1 — framework/librería}
* NO {anti-patrón 2 — arquitectura}
* NO {anti-patrón 3 — UI/diseño}
* NO {anti-patrón 4 — base de datos}
* NO {anti-patrón 5 — navegación/UX}
* NO {anti-patrón 6 — tooling/build}

> Mantener esta lista viva: agregar nuevos anti-patrones conforme se descubren.

## Agent Teams \[OPCIONAL — si se usan equipos de agentes]

> Activar con la configuración correspondiente de la herramienta. Definir roles solo si el proyecto tiene backend + frontend + tests separables.

* **Backend Agent**: {scope, reglas, archivos que puede tocar}
* **Frontend Agent**: {scope, reglas, archivos que puede tocar}
* **Test Agent**: {scope, reglas, qué valida}

Regla: cada agente respeta su scope. Schemas compartidos viven en {paquete compartido}.

## Skills \[OPCIONAL — si la herramienta soporta skills]

> Skills cargan conocimiento on-demand sin inflar este archivo.

* `.agents/skills/{nombre}/` — {descripción}
* `.agents/skills/{nombre}/` — {descripción}

## Estado Actual \[OPCIONAL pero recomendado]

> Fase actual del proyecto. Ayuda a la AI a entender qué existe y qué no.

**Fase actual:** {nombre y descripción de la fase}

**Completado:** {resumen de lo que ya está implementado}

**En progreso:** {qué se está construyendo ahora}

**Pendiente:** {qué NO implementar todavía}

***

# Notas sobre el template

## Secciones obligatorias (mínimo viable)

1. Descripción del proyecto (1-2 líneas)
2. Estructura del repo (árbol)
3. Tech stack (1 línea por capa)
4. Comandos (los que se usan día a día)
5. Reglas críticas (solo las que la AI violaría sin ellas)
6. Documentación (mapa de docs)
7. What NOT to do (anti-patrones reales)

## Secciones recomendadas

8. Protocolo de desarrollo de features
9. Estado actual del proyecto

## Secciones opcionales

10. Agent teams (si se usan)
11. Skills (si la herramienta los soporta)

## Criterio para incluir vs. delegar

| Pregunta                                  | Sí → inline | No → delegar         |
| ----------------------------------------- | ----------- | -------------------- |
| ¿La AI comete errores sin esto?           | ✓           |                      |
| ¿Aplica a TODAS las tareas?               | ✓           |                      |
| ¿Son menos de 5 líneas?                   | ✓           |                      |
| ¿Es conocimiento de dominio extenso?      |             | → skill              |
| ¿Son specs detalladas de un módulo?       |             | → doc referenciado   |
| ¿Son reglas de diseño con tokens/valores? |             | → GUIA\_DISENO.md    |
| ¿Son endpoints o páginas?                 |             | → doc referenciado   |
| ¿Son reglas de negocio extensas?          |             | → PRD o doc dedicado |

## Señales de que tu AGENTS.md es demasiado largo

* Más de 200 líneas → mover conocimiento a skills
* La AI empieza a ignorar reglas del final del archivo → priorizar, mover lo menos crítico
* Tienes secciones que solo aplican a ciertos módulos → convertir en skill
* El archivo tiene código de ejemplo extenso → mover a doc referenciado

# Gobierno del contexto

> Los cuatro instrumentos que impiden que la documentación se despegue del proyecto: Zonas Prohibidas, registro de decisiones, permisos del repositorio y la medición de entropía

> *La cadena de artefactos resuelve cómo empezar bien. El gobierno del contexto resuelve cómo seguir bien doscientas sesiones después.*

Nota

**Varias skills del paquete ejecutan lo que este capítulo prescribe.** Cinco dan por hecho el `docs/ADR.md` y le mandan cada decisión arquitectónica como fila nueva: `protocolo-arranque`, `protocolo-features`, `protocolo-cambios`, `protocolo-cierre` e `information-architecture`. La primera es anterior a los cuatro protocolos de la Parte III: abre el registro con la decisión de stack y declara en `AI-FIRST.md` las Zonas Prohibidas que la arquitectura crea. Es también la única que corre una sola vez por proyecto, o una vez por giro grande de producto; las otras cuatro son recurrentes. Dos, `protocolo-features` y `protocolo-cambios`, además piden aprobación antes de tocar una Zona Prohibida. La matriz de permisos no la invoca ninguna: es un instrumento para humanos. Si este capítulo cambia, esas skills se revisan con él.

[Ver las skills del paquete](/docs/referencia/skills/)

***

## El problema que aparece en el mes cuatro

Los capítulos anteriores resuelven el arranque: una cadena de artefactos que alimenta a la AI, un AGENTS.md que le da reglas, una guía de diseño que crece con el proyecto. Con eso, un proyecto nuevo deja de tener restarts.

Pero hay un segundo problema, y no aparece en la primera semana. Aparece cuando el proyecto lleva meses, cientos de sesiones y más de una persona trabajando encima.

El AGENTS.md dice que la lógica de negocio va en los casos de uso — y hace seis semanas alguien la puso en un controller porque tenía prisa, y nadie actualizó nada. La guía de diseño documenta un componente que se renombró en marzo. El PRD apunta a una spec que se borró. Y cuando alguien pregunta por qué la cola de trabajos usa este proveedor y no aquel, nadie se acuerda: la decisión se tomó en una sesión de agosto y su justificación, si quedó escrita, está en alguna parte de un registro de veintisiete mil líneas.

Nada de eso rompe el build. Todo eso hace que la AI trabaje con información falsa.

**Esa distancia entre lo que el proyecto documenta y lo que el proyecto es se llama entropía documental.** No es desorden: es un desajuste que crece solo, porque el código cambia en cada sesión y la documentación solo cambia cuando alguien se acuerda. La diferencia entre las dos velocidades es la entropía.

El gobierno del contexto es el conjunto de instrumentos que la mantienen acotada.

***

## El síntoma que nadie mide

Un dato de un proyecto real —un CRM de compliance multi-tenant, en producción, construido enteramente con esta metodología— para ver la escala del problema:

| Artefacto        | Tamaño                                       |
| ---------------- | -------------------------------------------- |
| `SESSION_LOG.md` | 27.682 líneas, 626 sesiones                  |
| `TECH_NOTES.md`  | 1.587 líneas de gotchas por stack            |
| Cambios formales | 385 documentos `CHG-XXX`                     |
| `AGENTS.md`      | 201 líneas, contra un techo declarado de 200 |

Ese proyecto está bien documentado. Tiene los cuatro protocolos activos, cierra cada sesión y enruta sus aprendizajes con un árbol de decisión explícito. No es un caso de negligencia — es lo que pasa cuando la metodología funciona durante meses.

Y aun así: si alguien pregunta hoy por qué se eligió un patrón de arquitectura sobre otro, la respuesta está enterrada en una de las 626 entradas del registro o en uno de los 385 cambios. No hay índice. Buscarla cuesta más que volver a decidir, así que en la práctica nadie la busca — y la decisión se vuelve a tomar, a veces al revés.

El `AGENTS.md` de ese proyecto tiene un árbol de decisión de documentación con siete destinos. Vale la pena leerlo con atención, porque es bueno:

| Tipo de contenido                               | Destino                        |
| ----------------------------------------------- | ------------------------------ |
| Invariante arquitectónico o convención vigente  | `AGENTS.md`                    |
| Fix histórico, cicatriz de una librería o stack | `TECH_NOTES.md`                |
| Estado de fase, progreso, lo pendiente          | `SESSION_LOG.md`               |
| Cambio formal con diseño y rollback             | `CHG-XXX.md` → `CHANGE_LOG.md` |
| Reglas de diseño, UX, microinteracciones        | `GUIA_DISENO.md`               |
| Detalles de un módulo                           | `specs/{modulo}.md`            |
| Arquitectura, pilares, stack                    | `ARQUITECTURA.md`              |

Siete destinos, y **ninguno responde «por qué se eligió esto en vez de aquello»**. Están el qué es la regla, el qué se rompió, el qué pasó, el qué cambió, el cómo se ve, el qué hace el módulo y el cómo está armado. Falta el porqué.

Esa fila faltante es el primero de los cuatro instrumentos que siguen.

***

## Instrumento 1 — Zonas Prohibidas

Una Zona Prohibida es una ruta o un patrón del repositorio que el agente no modifica sin aprobación explícita. Migraciones de base de datos, infraestructura, secretos, archivos de licencia.

La instrucción en sí no es nueva: cualquiera le ha escrito a un agente «no toques la carpeta de migraciones». Lo que cambia es dónde vive. Escrita en un prompt, dura lo que dura la ventana de contexto y se pierde en la sesión siguiente. Declarada como sección del AGENTS.md, la lee cualquier agente en cualquier herramienta, al abrir la sesión y sin que nadie se acuerde de repetirla.

```markdown
## Zonas Prohibidas


No se modifican sin aprobación explícita:


  /migrations      esquema vivo en producción
  /infra           terraform, DNS y secretos
  .env*            credenciales
```

**Qué la distingue de un `.gitignore` o de un CODEOWNERS.** Ninguno de los dos sirve para esto. Un `.gitignore` saca el archivo del control de versiones, que es lo contrario de lo que se quiere: una migración tiene que estar versionada. Un CODEOWNERS pide revisión de una persona al abrir un PR, cuando el cambio ya está hecho. Una Zona Prohibida no impide el cambio ni espera al PR: lo **hace visible en el momento**, para que un humano decida antes de que el trabajo se acumule encima.

La regla práctica al declararlas: una Zona Prohibida se justifica cuando el costo de revertir un error ahí es desproporcionado respecto al costo de pedir permiso. Una migración mal ordenada contra una base con datos de producción no se revierte sin ventana de mantenimiento. Un componente mal escrito se reescribe en diez minutos. El primero es zona prohibida; el segundo, no.

Declarar demasiadas las vuelve ruido, y el ruido se ignora.

***

## Instrumento 2 — El registro de decisiones

Un ADR —*Architecture Decision Record*— es el registro de por qué se tomó una decisión, qué alternativas se descartaron y qué consecuencias trajo. Una fila por decisión, en orden, sin borrar nunca.

La idea no es de esta metodología: los ADR existen desde hace años. Lo que este capítulo agrega es dónde encajan en la cadena de artefactos y por qué ninguno de los artefactos anteriores los reemplaza.

### Por qué no lo cubre nada de lo que ya hay

* **`ARQUITECTURA.md` no lo cubre.** Es un documento de estado: describe cómo está armado el sistema hoy. Cuando la decisión cambia, el documento se reescribe y la justificación anterior se sobrescribe. Queda el qué y se pierde el porqué — justo lo que hace falta para saber si la decisión sigue siendo válida o si su premisa ya no aplica.
* **`TECH_NOTES.md` no lo cubre.** Guarda cicatrices: qué se rompió y cómo se arregló. «Prisma genera los tipos pero no el cliente que corre» es un hallazgo, no una decisión. No hubo alternativas que evaluar.
* **`SESSION_LOG.md` no lo cubre.** Es cronología. La decisión aparece ahí mezclada con todo lo demás que pasó ese día, y a las seiscientas sesiones es inencontrable.
* **`CHG-XXX` no lo cubre.** Documenta un cambio a algo que ya funciona, con su diseño y su rollback. Muchos cambios no son decisiones arquitectónicas, y varias decisiones arquitectónicas no pasan por un cambio formal.

### Qué entra y qué no

Un ADR se justifica cuando la decisión cumple las tres condiciones:

1. **Es difícil de revertir.** Si deshacerla cuesta una tarde, no hace falta registrarla.
2. **Tenía alternativas reales que se descartaron.** Si no había otra opción, no hubo decisión: hubo una restricción.
3. **Alguien va a preguntar por qué dentro de seis meses.** Es el filtro que más descarta.

| Sí es ADR                                           | No es ADR                                  |
| --------------------------------------------------- | ------------------------------------------ |
| Elegir Postgres sobre Mongo                         | Subir una versión menor de una librería    |
| Pasar de una cola propia a un servicio administrado | Arreglar un gotcha de la librería de turno |
| Que el dominio no importe de infraestructura        | Cambiar el color de un botón               |
| Adoptar monorepo                                    | Modificar un feature que ya funciona       |

Las cuatro de la derecha tienen destino en el árbol: `SESSION_LOG`, `TECH_NOTES`, `GUIA_DISENO` y `CHG-XXX`, respectivamente.

### El formato

```markdown
## ADR-007 — La cola de trabajos pasa a un servicio administrado


- **Fecha:** 2026-09-12
- **Estado:** aceptada
- **Supera a:** ADR-003


**Contexto.** La cola propia sobre Postgres aguantaba 200 trabajos por minuto
y el pico de cierre de mes llegó a 1.400. Escalarla significaba operar
reintentos, visibilidad y letra muerta a mano.


**Decisión.** Se adopta el servicio administrado con cola de letra muerta.
El módulo de cola pasa a ser un adaptador.


**Alternativas.** Redis con una librería de colas: menos latencia, pero suma
una pieza que hay que operar. Subir la cola propia: más barato hoy, y nos deja
manteniendo infraestructura que no es el producto.


**Consecuencias.** Dependemos del proveedor en una pieza más. Los tests de
integración necesitan un doble local. El costo de infraestructura sube.
```

**Un ADR no se edita cuando cambias de opinión.** Se agrega uno nuevo que lo supera, y el viejo queda marcado como superado con el enlace al que lo reemplaza. Editarlo destruye la única información que el artefacto existe para conservar: que en su momento, con la información de entonces, esa decisión tenía sentido.

Es un registro, no un estado. Es lo que lo hace distinto de todo lo demás en la cadena.

***

## Instrumento 3 — Permisos del repositorio

Quién puede modificar qué parte del repositorio: personas, equipos y agentes. Una tabla, versionada junto al código.

```markdown
| Superficie          | Quién modifica              | Agentes        |
|---------------------|-----------------------------|----------------|
| `packages/prisma/`  | backend                     | con aprobación |
| `packages/ui/`      | diseño y frontend           | sí             |
| `infra/`            | solo la persona de infra    | no             |
| `docs/ADR.md`       | quien toma la decisión      | solo propone   |
```

La columna que no existe en ninguna herramienta de control de acceso es la tercera. Los permisos de un repositorio se diseñaron para personas: un agente que trabaja bajo las credenciales de quien lo ejecuta hereda todos sus permisos, y no hay forma de decir «esta persona sí, pero su agente no». Esta tabla es lo que llena ese hueco, y por eso es un documento y no una configuración.

Cuidado con el nombre

En muchos productos ya existe una «matriz de permisos» que significa otra cosa: los roles y permisos **de la aplicación** —quién aprueba, quién consulta, quién administra—, que es un artefacto del producto y suele vivir en `docs/`. Son dos tablas distintas con el mismo nombre y conviven sin problema, pero conviene titular esta explícitamente **«Permisos del repositorio»** para que nadie las confunda al buscar.

**Cuándo hace falta.** Trabajando solo, no hace falta: la tabla diría lo mismo en todas las filas. Empieza a pagar cuando hay más de una persona y más de un agente sobre el mismo repositorio, que es exactamente donde aparecen los conflictos que nadie atribuye a nadie.

***

## Instrumento 4 — Medir la entropía

Los tres instrumentos anteriores declaran. Este verifica que la declaración siga siendo cierta, porque una Zona Prohibida que nadie comprueba es una advertencia enterrada en un documento, que es donde empezamos.

La clave es que las verificaciones corran **en código puro** —control de versiones, sistema de archivos y expresiones regulares—, sin modelo y sin API key. Tres razones: no cuesta tokens, es determinista (la misma entrada da el mismo resultado, siempre), y sale con código de salida, así que el mismo comando sirve en un hook local y en integración continua.

Cinco verificaciones cubren la mayor parte del desajuste real, y sólo una corta el flujo: tocar una Zona Prohibida. Las otras avisan de una decisión que llegó al código sin llegar al registro, de un alcance que creció más de lo que la spec declaraba, de documentos que apuntan a cosas que ya no existen y de una librería de componentes que cambió sin que su inventario se enterara. Tres de las cinco son deterministas y no admiten discusión: una ruta cambió o no cambió, un archivo referenciado existe o no existe, un componente aparece en el inventario o no. La que detecta decisiones no lo es, porque «se tomó una decisión arquitectónica» no cabe en una expresión regular; se resuelve declarando en qué superficies un cambio se presume decisión, en vez de adivinarlo, y tiene que poder silenciarse con una anotación en el commit. Una verificación que no se puede silenciar termina desactivada entera, que es peor que tenerla ruidosa.

Los hallazgos se resumen en un número de 0 a 100 que **mide entropía, no salud**: 0 es documentación alineada, y un solo P0 mueve la aguja por sí solo, porque una Zona Prohibida tocada no se compensa con documentación impecable en todo lo demás. El valor no está en el número sino en la serie: ver en un PR que la entropía pasó de 12 a 68 dice algo que ninguna lista de hallazgos dice con la misma fuerza.

Todo eso ya corre: es `npx @falcux/ai-first@latest audit`, y `init` deja escritos los dos puntos donde se mide, un hook de git `pre-push` que sólo corta ante un P0 y un flujo de integración continua que corre con `--estricto` en cada pull request. Es un hook de git, no del agente. Qué detecta cada verificación y con qué severidad está en [Las cinco verificaciones](/docs/referencia/verificaciones/); las opciones, el puntaje y los códigos de salida, en [`ai-first audit`](/docs/referencia/audit/); cómo montarlo, en [Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/).

Los cuatro instrumentos de este capítulo no dependen del comando: las Zonas Prohibidas, el registro de decisiones y la tabla de permisos son documentos que se escriben a mano, y `audit` los verifica, no los redacta.

***

## Qué no es gobierno del contexto

* **No es control de acceso.** Nada de esto impide técnicamente un cambio. Lo hace visible. Un agente decidido a tocar una Zona Prohibida puede hacerlo; lo que no puede es que pase inadvertido.
* **No es más documentación.** Es la documentación que ya existe, con los cuatro huecos que deja tapados. Si al agregar estos instrumentos el proyecto termina con más páginas que nadie lee, se aplicó mal.
* **No reemplaza a los protocolos.** Los cuatro protocolos de la Parte III siguen siendo cómo se trabaja. El gobierno del contexto es qué se declara y qué se verifica, que es otra cosa.
* **No sirve en la primera semana.** En un proyecto de dos sesiones no hay entropía que medir. Esto empieza a pagar cuando hay historia que perder.

***

## Resumen accionable

1. **Declara las Zonas Prohibidas en el AGENTS.md**, no en un prompt. El criterio es el costo de revertir un error, no la importancia del archivo. Pocas, o se vuelven ruido.

2. **Abre un `docs/ADR.md` hoy, aunque empiece vacío.** Es el artefacto que ninguno de los otros cubre, y el único cuyo valor depende de haberlo empezado temprano: un registro de decisiones que arranca en el mes seis nace con seis meses de huecos.

3. **Una decisión entra al ADR si es difícil de revertir, tenía alternativas reales y alguien va a preguntar por qué.** Las tres, no dos.

4. **Nunca edites un ADR para cambiar de opinión.** Agrega uno nuevo que lo supere. La justificación vieja es información, no basura.

5. **Agrega la tabla de permisos cuando entre la segunda persona**, no antes. Su columna útil es la de los agentes, que ninguna herramienta de control de acceso tiene.

6. **Lo que no se verifica, se degrada.** Cualquier verificación que corra en código puro y salga con código de salida sirve — empieza por las deterministas, que se montan en una tarde y no admiten discusión.

# GUIA_DISEÑO.md — Documentación evolutiva

> Template de guía de diseño que crece orgánicamente con el proyecto

> Este template define la estructura recomendada para la guía de diseño de un proyecto construido con AI coding agents. Está extraído de la GUIA\_DISENO.md de Virso (1134 líneas co-creadas con Claude Code durante 5 fases de implementación).
>
> **Principio:** Este documento es EVOLUTIVO. No se escribe completo al inicio. Se empieza con las secciones obligatorias y crece conforme se implementa. Cada sesión de implementación puede agregar gotchas, componentes, o patrones nuevos.
>
> **Relación con otros documentos:**
>
> * la skill `protocolo-ux` = principios agnósticos (Capa 1, no cambia entre proyectos)
> * `GUIA_DISENO.md` = especificaciones de proyecto (Capa 2, este documento, único por proyecto)

***

## Cómo usar este template

1. Copiar como `docs/GUIA_DISENO.md` en tu proyecto
2. Llenar las secciones marcadas como **\[OBLIGATORIO]** antes de la primera sesión de implementación de UI
3. Las secciones **\[CRECE CON EL PROYECTO]** se van llenando conforme se implementa
4. Las secciones **\[OPCIONAL]** se agregan si el proyecto las necesita
5. Eliminar toda la guía de uso y los comentarios `<!-- -->` cuando el documento esté en uso

Este template es `GUIA_DISENO_TEMPLATE.md` y viaja en la carpeta `templates/` del paquete `@falcux/ai-first`. En un producto nuevo con interfaz no hace falta copiarlo a mano: la skill `protocolo-arranque` escribe `docs/GUIA_DISENO.md` desde él, después de la arquitectura y antes de las specs. Un producto sin interfaz no la lleva. El recorrido está en [Arrancar un producto desde cero](/docs/guias/arrancar-un-producto/).

***

## Índice

1. [Paleta de colores](#1-paleta-de-colores) — OBLIGATORIO
2. [Tipografía](#2-tipograf%C3%ADa) — OBLIGATORIO
3. [Espaciado y bordes](#3-espaciado-y-bordes) — OBLIGATORIO
4. [Sistema de temas](#4-sistema-de-temas) — OBLIGATORIO si hay dark mode
5. [Layout principal](#5-layout-principal) — OBLIGATORIO
6. [Componentes UI](#6-componentes-ui) — CRECE CON EL PROYECTO
7. [Patrones de página](#7-patrones-de-p%C3%A1gina) — CRECE CON EL PROYECTO
8. [Animaciones y motion](#8-animaciones-y-motion) — OPCIONAL
9. [Iconografía](#9-iconograf%C3%ADa) — OBLIGATORIO
10. [Accesibilidad](#10-accesibilidad) — OBLIGATORIO
11. [Internacionalización](#11-internacionalizaci%C3%B3n) — OPCIONAL
12. [Gotchas del framework CSS](#12-gotchas-del-framework-css) — CRECE CON EL PROYECTO
13. [Responsive design](#13-responsive-design) — OBLIGATORIO
14. [Estructura de archivos UI](#14-estructura-de-archivos-ui) — OBLIGATORIO
15. [Efectos visuales especiales](#15-efectos-visuales-especiales) — OPCIONAL
16. [Checklist para nuevas funcionalidades](#16-checklist-para-nuevas-funcionalidades) — OBLIGATORIO

***

## Principio fundamental

**{Tu principio fundamental de diseño aquí.}**

***

## 1. Paleta de colores \[OBLIGATORIO]

### 1.1 Colores principales

| Rol                        | Valor     | Uso                             |
| -------------------------- | --------- | ------------------------------- |
| **Primary**                | `{valor}` | CTAs, active states, highlights |
| **Primary Foreground**     | `{valor}` | Texto sobre fondo primary       |
| **Destructive**            | `{valor}` | Acciones destructivas           |
| **Destructive Foreground** | `{valor}` | Texto sobre fondo destructive   |

### 1.2 Reglas de contraste

* {Color problemático}: ratio {X:1} contra {fondo}. Solución: {token alternativo}
* **Regla:** `{clase para texto de marca}` para texto legible, NUNCA `{clase primary}` sobre fondos claros

### 1.3 Tokens del tema

```css
/* Copiar los tokens CSS de tu proyecto aquí.
   Esto es la referencia definitiva para la AI. */


/* Light theme */
--color-primary: {valor};
--color-background: {valor};
--color-foreground: {valor};
--color-card: {valor};
--color-card-foreground: {valor};
--color-muted: {valor};
--color-muted-foreground: {valor};
--color-border: {valor};
/* ... */


/* Dark theme (si aplica) */
/* ... */
```

### 1.4 Tokens semánticos de estado \[CRECE CON EL PROYECTO]

| Token                | Uso           | Light     | Dark      |
| -------------------- | ------------- | --------- | --------- |
| `{--color-status-x}` | {descripción} | `{valor}` | `{valor}` |

### 1.5 Fondos semánticos (transparencias) \[CRECE CON EL PROYECTO]

| Contexto   | Background      | Border              | Hover                 |
| ---------- | --------------- | ------------------- | --------------------- |
| Badges     | `bg-{color}/8`  | `border-{color}/15` | —                     |
| Botones    | `bg-{color}/10` | `border-{color}/20` | `hover:bg-{color}/15` |
| Containers | `bg-{color}/8`  | `border-{color}/15` | —                     |

***

## 2. Tipografía \[OBLIGATORIO]

### 2.1 Font stacks

```css
--font-sans: {fuente body}, ui-sans-serif, system-ui, sans-serif;
--font-heading: {fuente headings}, {fallback};
/* --font-mono: {fuente mono}; /* si aplica */
```

### 2.2 Escala tipográfica

| Nivel   | Clases     | Uso                      |
| ------- | ---------- | ------------------------ |
| H1      | `{clases}` | {dónde se usa}           |
| H2      | `{clases}` | {dónde se usa}           |
| H3      | `{clases}` | {dónde se usa}           |
| Body    | `{clases}` | Texto general            |
| Caption | `{clases}` | Fechas, hints, metadatos |
| Label   | `{clases}` | Labels de formularios    |

### 2.3 Reglas

* {Fuente} en todos los headings y títulos
* Nunca `{peso prohibido}` (ej: font-thin, font-light)
* {Otras reglas tipográficas del proyecto}

***

## 3. Espaciado y bordes \[OBLIGATORIO]

### 3.1 Border radius

| Token  | Valor   | Uso                |
| ------ | ------- | ------------------ |
| `{sm}` | {valor} | Badges, chips      |
| `{md}` | {valor} | Buttons, inputs    |
| `{lg}` | {valor} | Cards, dialogs     |
| `{xl}` | {valor} | Containers grandes |

**Patrón:** `{radio grande}` para containers, `{radio pequeño}` para controles internos.

### 3.2 Sombras

```css
--shadow-card: {valor light};  /* light */
--shadow-card: {valor dark};   /* dark (si aplica) */
```

### 3.3 Espaciado común

| Contexto                | Valor   |
| ----------------------- | ------- |
| Padding de página       | {valor} |
| Gap entre cards         | {valor} |
| Padding interno de card | {valor} |
| Margin entre secciones  | {valor} |

***

## 4. Sistema de temas \[OBLIGATORIO si hay dark mode]

### 4.1 Arquitectura

```plaintext
{Librería de temas} con {estrategia (class/attribute)}, defaultTheme="{default}"
```

### 4.2 Reglas de adaptación entre modos

| Aspecto         | Light mode    | Dark mode     |
| --------------- | ------------- | ------------- |
| Fondo del botón | {descripción} | {descripción} |
| Saturación      | {descripción} | {descripción} |
| Texto del botón | {descripción} | {descripción} |
| Sombras         | {descripción} | {descripción} |

**Fórmula para nuevos colores:** {ej: subir lightness +0.07, bajar chroma -0.03, invertir foreground}

### 4.3 Qué NO hacer

* NO dejar el mismo color idéntico en ambos modos
* NO invertir el color simplemente
* {Otras reglas específicas del proyecto}

***

## 5. Layout principal \[OBLIGATORIO]

### 5.1 Estructura

```plaintext
{Diagrama ASCII del layout principal}


Ejemplo:
SidebarProvider
├── Sidebar (collapsible)
└── ContentArea
    ├── TopBar (sticky, header)
    └── main (contenido scrolleable)
```

### 5.2 Sidebar

* **Modo:** {collapsible, fixed, drawer, etc.}
* **Ancho expandido:** {valor}
* **Ancho colapsado:** {valor}
* **Mobile:** {Sheet, drawer, overlay, etc.}
* **Persistencia:** {cookie, localStorage, etc.}
* **Keyboard shortcut:** {atajo}

### 5.3 TopBar / Header

```plaintext
{Diagrama ASCII del header}
```

### 5.4 Focus layout (segundo nivel) \[si aplica]

| Layout      | Route group | Casos de uso |
| ----------- | ----------- | ------------ |
| Con sidebar | `{grupo}`   | {ejemplos}   |
| Sin sidebar | `{grupo}`   | {ejemplos}   |

#### Header del focus layout

```plaintext
{variante 1} → {descripción}
{variante 2} → {descripción}
```

***

## 6. Componentes UI \[CRECE CON EL PROYECTO]

### 6.1 Biblioteca base

{Cantidad} componentes en `{ruta}`:

{Lista de componentes}

### 6.2 Componentes con reglas especiales

#### {Nombre del componente}

* **Variantes:** {listar}
* **Regla especial:** {lo que la AI debe saber}
* **Gotcha:** {error común al usarlo}

***

## 7. Patrones de página \[CRECE CON EL PROYECTO]

### 7.1 {Nombre del patrón} (ej: Auth Pages)

{Descripción breve del layout y comportamiento}

### 7.2 {Nombre del patrón} (ej: Listado con filtros)

{Descripción breve del layout y comportamiento}

### 7.3 Empty state

{Icono} + heading + subtítulo + CTA

***

## 8. Animaciones y motion \[OPCIONAL]

### 8.1 Keyframes

| Nombre   | Efecto        | Duración   |
| -------- | ------------- | ---------- |
| {nombre} | {descripción} | {duración} |

### 8.2 Reglas

* Solo animar `transform` y `opacity` para 60fps
* Duraciones: {micro}ms (micro), {standard}ms (transiciones), {entrance}ms (entradas)
* NO animar `height`, `width`, `top`, `left`
* `will-change: transform` solo donde sea estrictamente necesario

### 8.3 Reduced motion

```css
@media (prefers-reduced-motion: reduce) {
  /* Desactivar todas las animaciones */
}
```

***

## 9. Iconografía \[OBLIGATORIO]

**Librería:** {nombre} — única librería de iconos.

| Contexto      | Tamaño   |
| ------------- | -------- |
| Nav items     | {clases} |
| Card metadata | {clases} |
| Headings      | {clases} |
| Empty state   | {clases} |

* Iconos decorativos: `aria-hidden="true"`
* NO mezclar librerías de iconos

***

## 10. Accesibilidad \[OBLIGATORIO]

### 10.1 Contraste WCAG AA

* Texto normal: 4.5:1 mínimo
* Texto grande: 3:1 mínimo
* {Notas específicas del proyecto sobre contraste}

### 10.2 Focus visible

Todos los interactivos: `{clases de focus}`

### 10.3 ARIA patterns

| Pattern               | Uso                            |
| --------------------- | ------------------------------ |
| `aria-label`          | Botones de solo ícono          |
| `aria-current="page"` | Nav link activo                |
| `aria-hidden="true"`  | Iconos decorativos             |
| `aria-describedby`    | Inputs vinculados a error      |
| `aria-invalid`        | Inputs con error de validación |
| `role="alert"`        | Mensajes de error dinámicos    |
| `role="status"`       | Indicadores de carga           |

### 10.4 Formularios accesibles

```tsx
<!-- Ejemplo de implementación con aria-describedby + aria-invalid -->
{código de ejemplo de tu stack}
```

### 10.5 Landmarks

| Landmark   | Ubicación |
| ---------- | --------- |
| `<main>`   | {dónde}   |
| `<header>` | {dónde}   |
| `<nav>`    | {dónde}   |

### 10.6 Heading hierarchy

```plaintext
<h1> — {uso}
<h2> — {uso}
<h3> — {uso}
```

***

## 11. Internacionalización \[OPCIONAL]

* **Librería:** {nombre y versión}
* **Idiomas:** {idiomas soportados}
* **Mensajes:** `{ruta a archivos de mensajes}`

**Reglas:**

* NUNCA hardcodear strings de UI
* {Reglas de formato, variables, pluralización}

***

## 12. Gotchas del framework CSS \[CRECE CON EL PROYECTO]

### 12.1 {Gotcha 1}

**Problema:** {qué sale mal} **Solución:** {cómo resolverlo} **Ejemplo:**

```css
/* MAL */  {código incorrecto}
/* BIEN */ {código correcto}
```

### 12.2 {Gotcha 2}

***

## 13. Responsive design \[OBLIGATORIO]

### 13.1 Breakpoints

| Nombre  | Ancho     | Comportamiento |
| ------- | --------- | -------------- |
| mobile  | < {valor} | {descripción}  |
| tablet  | {rango}   | {descripción}  |
| desktop | > {valor} | {descripción}  |

### 13.2 Patrones responsive por componente

| Componente     | Mobile           | Desktop          |
| -------------- | ---------------- | ---------------- |
| Sidebar        | {comportamiento} | {comportamiento} |
| {Componente 2} | {comportamiento} | {comportamiento} |
| {Componente 3} | {comportamiento} | {comportamiento} |

***

## 14. Estructura de archivos UI \[OBLIGATORIO]

```plaintext
{Árbol de archivos de UI del proyecto}


Ejemplo:
packages/ui/src/
├── components/
│   ├── ui/              ← componentes base
│   └── {custom}.tsx     ← componentes custom
├── lib/utils.ts         ← utilidades (cn, etc.)
└── index.ts             ← barrel exports
```

***

## 15. Efectos visuales especiales \[OPCIONAL]

### 15.1 {Nombre del efecto}

* **Cómo funciona:** {descripción técnica breve}

* **Dónde se usa:** {componentes que lo usan}

* **Reglas:**

  * {Regla 1 — qué respetar para que el efecto funcione}
  * {Regla 2 — qué NO hacer}

***

## 16. Checklist para nuevas funcionalidades \[OBLIGATORIO]

### Colores y tokens

* [ ] Cero colores hardcodeados — solo tokens semánticos
* [ ] {Regla de contraste específica del proyecto}

### Componentes

* [ ] Reutilizar componentes existentes de `{librería}`
* [ ] {Librería de iconos} para todos los iconos
* [ ] {Patrón de border-radius} respetado

### Tema (si aplica dark mode)

* [ ] Funcional en light y dark sin glitches
* [ ] Contraste WCAG AA verificado

### Accesibilidad

* [ ] Focus visible en todos los interactivos
* [ ] `aria-label` en botones de solo ícono
* [ ] `aria-hidden="true"` en iconos decorativos
* [ ] `role="alert"` en errores dinámicos
* [ ] Heading hierarchy correcta
* [ ] {Otras reglas de a11y del proyecto}

### i18n (si aplica)

* [ ] Textos via sistema de i18n — no hardcodeados

### Responsive

* [ ] Funciona en mobile ({ancho mínimo}) y desktop

### Framework CSS

* [ ] {Gotcha 1 verificado}
* [ ] {Gotcha 2 verificado}

***

# Notas sobre este template

## Secciones obligatorias (llenar antes de implementar UI)

1. Paleta de colores (tokens mínimos)
2. Tipografía (font stacks + escala)
3. Espaciado y bordes (radios + espaciado común)
4. Layout principal (estructura + sidebar)
5. Iconografía (librería + tamaños)
6. Accesibilidad (contraste + ARIA + landmarks)
7. Responsive (breakpoints)
8. Estructura de archivos UI
9. Checklist

## Secciones que crecen con el proyecto

* Componentes UI → agregar cada componente nuevo con sus reglas
* Patrones de página → agregar cada tipo de página implementado
* Gotchas → agregar cada bug/gotcha descubierto
* Tokens de estado → agregar conforme se definen estados del dominio
* Fondos semánticos → agregar conforme se establecen patrones de color

## Secciones opcionales (agregar si el proyecto las necesita)

* Sistema de temas (solo si hay dark mode)
* Animaciones (solo si hay un sistema definido)
* i18n (solo si hay multi-idioma)
* Efectos visuales especiales (glassmorphism, gradientes, etc.)

## Señales de que tu guía necesita actualización

* La AI genera un componente con estilos que no siguen la guía → agregar la regla
* Descubres un bug de CSS que la AI repite → agregar a gotchas
* Implementas un patrón de página nuevo → documentar en sección 7
* Cambias tokens de color → actualizar sección 1
* Agregas un componente a la librería → documentar en sección 6 si tiene reglas especiales

## Tamaño esperado

* Al inicio: \~100-150 líneas (secciones obligatorias con valores mínimos)
* Proyecto maduro: \~500-1000+ líneas (como la guía de Virso con 1134 líneas)
* Esto es normal y esperado — la guía DEBE crecer con el proyecto

# Skills, hooks y gestión de contexto

> Las tres capas de optimización: conocimiento on-demand, automatización determinista, y contexto finito

> *El AGENTS.md es la base. Skills, hooks y gestión de contexto son las optimizaciones que hacen la diferencia entre “funciona” y “funciona consistentemente”.*

***

## Más allá del AGENTS.md

Los capítulos anteriores cubrieron los fundamentos: la cadena de artefactos (capítulo 3), el AGENTS.md como cerebro del proyecto (capítulo 4), y la guía de diseño evolutiva (capítulo 5). Con eso, un proyecto funciona.

Pero “funciona” y “funciona bien a lo largo de 50 sesiones” son cosas distintas. Conforme el proyecto crece, aparecen tres problemas que el AGENTS.md solo no resuelve:

1. **El AGENTS.md se infla.** Cada regla nueva, cada gotcha, cada convención se agrega al archivo. A las 200 líneas, la AI empieza a ignorar instrucciones del final. A las 400, hay reglas que se contradicen entre sí.

2. **Hay procesos que la AI debe seguir siempre, sin excepción.** “Ejecutar Prettier después de cada edición” no es una sugerencia — es una obligación determinista. Pero el AGENTS.md es advisory: la AI lo sigue la mayoría del tiempo, no siempre.

3. **Las sesiones largas degradan la calidad.** La AI tiene un contexto finito. Conforme la conversación crece, las instrucciones del inicio pierden peso frente a los mensajes recientes. Sin gestión activa, la sesión 1 produce excelentes resultados y la sesión 15 produce inconsistencias.

Este capítulo cubre las tres herramientas que resuelven estos problemas: skills para el primero, hooks para el segundo, y técnicas de gestión de contexto para el tercero.

***

## Skills: conocimiento on-demand

### Qué son

Un skill es un archivo markdown con conocimiento especializado que la AI carga solo cuando es relevante para la tarea actual. A diferencia del AGENTS.md (que se lee en cada sesión), los skills se activan bajo demanda — no ocupan contexto cuando no se necesitan.

### Cuándo crear un skill

La regla de decisión es simple:

* **¿Este conocimiento aplica a TODAS las tareas?** → va en el AGENTS.md
* **¿Este conocimiento aplica solo a ciertos tipos de tarea?** → va en un skill

Ejemplos concretos:

| Conocimiento                                            | ¿Dónde?   | ¿Por qué?                                     |
| ------------------------------------------------------- | --------- | --------------------------------------------- |
| “Nunca hardcodear colores”                              | AGENTS.md | Aplica siempre, en toda tarea                 |
| Convenciones de i18n con next-intl v4                   | Skill     | Solo cuando se trabaja en textos/traducciones |
| Clean Architecture: 3 capas, reglas de dependencia      | Skill     | Solo cuando se trabaja en backend             |
| Glosario del dominio de negocio (compliance, SAGRILAFT) | Skill     | Solo cuando se implementan reglas de negocio  |
| Patrones de testing E2E con helpers y mocks             | Skill     | Solo cuando se escriben tests                 |
| Patrones UX del proyecto                                | Skill     | Solo cuando se trabaja en UI                  |

### Estructura de un skill

```plaintext
.claude/skills/{nombre}/SKILL.md
```

Esa es la ruta que lee Claude Code. El paquete las copia a `.agents/skills/`, que no es de ninguna herramienta, y deja `.claude/skills` como enlace a esa carpeta.

El archivo tiene frontmatter YAML + contenido markdown:

```markdown
---
name: i18n-patterns
description: "Convenciones de internacionalización con next-intl v4.
Activar cuando se trabaje con textos de UI, traducciones, o archivos
de mensajes."
---


# Convenciones i18n


## Estructura de archivos
- Mensajes en apps/web/messages/{locale}.json
- Namespaces por feature: home, auth, common, sidebar...


## Uso en componentes
- Client: useTranslations('namespace')
- Server: getTranslations('namespace')


## Reglas
- NUNCA hardcodear strings de UI
- Variables con ICU syntax: "daysAgo": "Hace {days} días"
- Acentos correctos en español
...
```

**La descripción del frontmatter es clave.** La AI usa esa descripción para decidir si cargar el skill. Una descripción vaga (“convenciones de código”) hace que el skill se cargue en momentos innecesarios. Una descripción precisa (“convenciones de next-intl v4, activar cuando se trabaje con traducciones”) hace que se cargue exactamente cuando se necesita.

### Del protocolo al skill

Los cuatro protocolos de la Parte III nacieron como documentos: un `.md` en `docs/` que la AI leía cuando alguien se acordaba de pedírselo. Funcionaba, con una fuga conocida — el protocolo se aplicaba cuando el humano lo recordaba, no cuando la tarea lo requería.

Convertirlos en skills cierra esa fuga. El mismo contenido, con frontmatter que declara cuándo activarse, deja de depender de la memoria de nadie:

| Como documento              | Como skill                                |
| --------------------------- | ----------------------------------------- |
| El humano recuerda cargarlo | La AI lo carga al detectar la tarea       |
| Se lee entero o no se lee   | Se carga solo cuando aplica               |
| Explica el procedimiento    | Ejecuta el procedimiento                  |
| Se desactualiza en silencio | Se rompe visiblemente cuando ya no aplica |

La diferencia práctica es grande. Un protocolo de cierre en `docs/` se cumple la mitad de las veces; el mismo protocolo como skill se cumple cuando la sesión termina, porque eso es lo que dice su descripción.

**Esto no reemplaza al capítulo.** El capítulo explica *por qué* el protocolo es así y qué criterio hay detrás de cada regla — eso lo lee un humano una vez. El skill es el procedimiento destilado que la AI ejecuta muchas veces. Se necesitan los dos: sin el capítulo, nadie sabe qué adaptar; sin el skill, nadie lo aplica consistentemente.

### El paquete de inicio

Falcux AI-First incluye once skills listas para instalar. Cinco son protocolos: los cuatro de la Parte III en formato ejecutable y `protocolo-arranque`, que corre antes que todos y produce la spec que `protocolo-features` da por hecha; las otras seis nacieron resolviendo problemas concretos en proyectos reales y resultaron transferibles. Qué hace cada una y cuándo se activa está en [Las 11 skills](/docs/referencia/skills/); instalarlas es un comando, `npx @falcux/ai-first@latest init`, que se explica en el [Inicio rápido](/docs/empezar/inicio-rapido/).

**No instales las once el primer día.** Por eso `init`, si no le dices otra cosa, instala sólo las cinco que no dependen de una interfaz —`protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `test-fix` y `version-bump`—; con la entrevista, suma las que el perfil del producto pida. El resto entra cuando el proyecto lo pide: `protocolo-ux`, el que más errores evita en un producto con interfaz, junto con `information-architecture` en cuanto haya más de un módulo; `ux-writer` e `i18n` antes de que el copy acumule deriva, porque retrofitearlos es caro; `ux-audit` cuando haya volumen que auditar. `protocolo-arranque` es la excepción: corre una vez, al principio, si el proyecto todavía no tiene PRD.

[Las 11 skills](/docs/referencia/skills/)Qué hace cada una, cuándo se activa y cuáles instala init por defecto.

### Los dos tipos de skill

El paquete de inicio ilustra una distinción útil al decidir qué convertir en skill:

**Skills de procedimiento** — describen *cómo se hace* algo, paso a paso, con un orden que importa. `protocolo-cierre` y `version-bump` son de este tipo: tienen pasos numerados, gates de confirmación y un reporte de salida. Son los que más se benefician del formato, porque un procedimiento leído a medias produce resultados peores que ninguno.

**Skills de criterio** — describen *cómo decidir* algo. `ux-writer` y `protocolo-ux` son de este tipo: no tienen pasos, tienen reglas y una tabla de decisión. Su valor está en resolver por escrito las ambigüedades que de otro modo se resuelven distinto cada vez.

Un skill que no es ninguno de los dos — un volcado de información sin procedimiento ni criterio — probablemente sea documentación de referencia, y le sirve mejor a tu proyecto como un `.md` en `docs/`.

### Skills que solo existen en tu proyecto

El paquete de inicio cubre lo transferible. Todo proyecto necesita además skills que **nadie más puede escribir por él**: el dominio de negocio, la arquitectura concreta, las integraciones externas, las reglas regulatorias.

El proyecto del que salió este paquete tiene 22 skills. Diez de las de aquí salieron de él —`protocolo-arranque` nació aparte, de lo que se hacía fuera del paquete—; el resto —motor de scoring, máquina de estados, aislamiento multi-tenant, marco regulatorio, integraciones con proveedores— no le sirve a nadie más, y son justamente las que más valor aportan ahí.

La proporción sana es esa: menos de la mitad heredado, el resto propio. Si todos tus skills son genéricos, la AI todavía no sabe nada específico de tu proyecto.

No todos los proyectos necesitan todos estos skills. Crear un skill solo cuando el conocimiento es lo suficientemente extenso como para inflar el AGENTS.md (más de 10-15 líneas de reglas sobre un tema específico).

### El principio agnóstico

Los skills son una feature de Claude Code, pero el concepto aplica a cualquier herramienta. En Cursor, el equivalente es `.cursorrules` con archivos adicionales referenciados. En Antigravity, es el contexto del proyecto con documentos adjuntos. El principio es el mismo: separar conocimiento general (siempre presente) de conocimiento especializado (disponible cuando se necesita).

Para herramientas que no soportan carga progresiva, la alternativa es mantener los documentos de conocimiento especializado como archivos .md en el repo e instruir a la AI a consultarlos cuando trabaje en ciertos tipos de tarea:

```markdown
# En el AGENTS.md
## Documentación especializada
- Antes de trabajar en backend, leer `docs/CLEAN_ARCHITECTURE.md`
- Antes de trabajar en tests, leer `docs/TESTING_PATTERNS.md`
- Antes de trabajar en UI, leer `docs/protocolo-ux.md`
```

No es tan elegante como la carga automática de skills, pero logra el mismo resultado.

***

## Hooks: automatización determinista

### El problema que resuelven

El AGENTS.md es advisory — la AI lo sigue la mayor parte del tiempo, pero no siempre. Hay un porcentaje de sesiones donde la AI ignora una instrucción, especialmente cuando el contexto se ha acumulado y las instrucciones del AGENTS.md compiten con los mensajes recientes.

Para reglas que deben cumplirse siempre, sin excepción, eso no es aceptable. “Ejecutar el formateador después de cada edición” no puede fallar el 5% de las veces — genera inconsistencias que se acumulan.

Los hooks resuelven esto: son scripts que se ejecutan automáticamente cuando ocurre un evento específico. No dependen de que la AI “decida” ejecutarlos — se ejecutan siempre, de forma determinista.

### Tipos de hooks

| Hook                 | Cuándo se ejecuta                        | Uso típico                                          |
| -------------------- | ---------------------------------------- | --------------------------------------------------- |
| **PreToolUse**       | Antes de que la AI use una herramienta   | Bloquear acciones peligrosas, validar permisos      |
| **PostToolUse**      | Después de que la AI usa una herramienta | Formatear código, ejecutar linter                   |
| **Stop**             | Cuando la AI termina de responder        | Verificar que los tests pasan, validar el resultado |
| **UserPromptSubmit** | Cuando el usuario envía un mensaje       | Preprocesar input, inyectar contexto                |

### El hook más útil: PostToolUse para formateo

Este es el hook que más impacto tiene con menos esfuerzo. Configura el formateador (Prettier, ESLint, etc.) para que se ejecute automáticamente después de cada edición de archivo:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILE_PATH"
          }
        ]
      }
    ]
  }
}
```

Con esto, cada archivo que la AI edita o crea se formatea automáticamente. No importa si la AI “olvidó” respetar las convenciones de formato — el hook lo corrige siempre.

### Hook de Stop para verificación

Un hook de Stop puede ejecutar verificaciones al final de cada turno de la AI:

```json
{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "npx tsc --noEmit --pretty 2>&1 | head -20"
      }
    ]
  }
}
```

Si hay errores de tipos después de que la AI terminó, el hook los muestra inmediatamente — antes de que el humano tenga que recordar ejecutar typecheck manualmente.

### Cuándo usar hook vs. regla en AGENTS.md

| Necesidad                     | Hook                        | AGENTS.md                        |
| ----------------------------- | --------------------------- | -------------------------------- |
| Formateo de código            | ✓ (determinista)            |                                  |
| Linting automático            | ✓ (determinista)            |                                  |
| Ejecutar typecheck            | ✓ (Stop hook)               |                                  |
| No hardcodear colores         |                             | ✓ (guía, no automatizable)       |
| Seguir clean architecture     |                             | ✓ (conceptual, no automatizable) |
| No modificar ciertos archivos | ✓ (PreToolUse bloqueante) o | ✓ (instrucción en contexto)      |

**La regla:** Si se puede automatizar con un script, es un hook. Si requiere juicio de la AI, es una instrucción en el AGENTS.md.

### El principio agnóstico

Los hooks del agente no son un estándar. A diferencia de las skills, que varias herramientas leen desde la misma carpeta, cada herramienta que tiene hooks los configura en su propio formato y con sus propios nombres de evento, y algunas sólo admiten plugins en vez de scripts. El principio subyacente es universal: lo que debe pasar siempre, debe ser automático — no depender de la buena voluntad de la AI.

Para herramientas sin hooks nativos, la alternativa es incluir los comandos de verificación en el Protocolo de Cierre de Sesión como pasos que el humano ejecuta manualmente. Es menos elegante, pero cumple la función.

Lo que instala el paquete

`npx @falcux/ai-first@latest init` deja un hook, pero **de git, no del agente**: un `pre-push` que corre el detector antes de publicar y un flujo que lo corre en cada pull request. Cubre el mismo principio —lo que debe pasar siempre, automático— en el único punto que todas las herramientas comparten, que es el repositorio. Los hooks de este capítulo, los del agente, se siguen configurando a mano en cada herramienta: el paquete no instala ninguno. Qué escribe `init` está en [Qué deja init en tu repo](/docs/empezar/que-instala/), y cómo se usa el punto de control, en [Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/).

***

## Gestión de contexto: la ventana finita

### El problema

Cada AI coding agent tiene un contexto finito — una cantidad máxima de texto que puede “tener en mente” al mismo tiempo. Cuando la conversación crece (más mensajes, más archivos leídos, más código generado), las instrucciones del inicio — incluyendo el AGENTS.md — pierden peso relativo.

Esto explica un patrón que todo usuario de AI coding agents ha experimentado: la primera hora de una sesión produce excelentes resultados, y la tercera hora produce inconsistencias. No es que la AI se “canse” — es que el contexto se saturó y las instrucciones tempranas quedan enterradas bajo capas de conversación.

### Técnica 1: Sesiones limpias por tarea

La técnica más simple y efectiva: cada tarea significativa se hace en una sesión nueva.

```plaintext
Sesión 1: Planificar + escribir spec → produce SPEC.md
    ↓ (cerrar sesión)
Sesión 2: Implementar backend → lee SPEC.md, implementa
    ↓ (cerrar sesión)
Sesión 3: Implementar frontend → lee SPEC.md + SESSION_LOG, implementa
```

La sesión 2 arranca con contexto limpio, enfocado enteramente en implementación. No arrastra los intercambios de planificación de la sesión 1. Tiene toda la ventana de contexto disponible para el AGENTS.md + la spec + el código.

**Cuándo aplicar:** Siempre que cambies de tipo de tarea (planificar → implementar, backend → frontend, implementar → debuggear). Si vas a seguir haciendo lo mismo, mantener la sesión está bien.

### Técnica 2: Compactar contexto (/compact)

Cuando la sesión se extiende y no quieres cerrarla, la compactación resume la conversación previa manteniendo lo esencial. El punto óptimo es compactar al alcanzar el 50% del contexto disponible — antes de que la degradación se note.

El truco está en decirle a la AI qué preservar:

```plaintext
/compact preserva: la lista de archivos modificados, el estado actual del feature,
y los errores que ya corregimos
```

Sin esa instrucción, la compactación puede descartar contexto que necesitas. Con ella, la AI sabe qué es prioritario retener.

**Cuándo aplicar:** Sesiones largas donde has estado iterando sobre un feature y no quieres perder el hilo.

### Técnica 3: Limpiar contexto (/clear)

Cuando necesitas un reset total dentro de la misma sesión — por ejemplo, terminaste un feature y vas a empezar otro — limpiar el contexto es más efectivo que compactar:

```plaintext
/clear
```

El AGENTS.md se recarga. Los skills relevantes se recargan. Pero la conversación anterior desaparece. Es como abrir una sesión nueva sin cerrar la ventana.

**Cuándo aplicar:** Al cambiar de tarea dentro de una sesión. Terminaste el backend de un feature y vas a empezar el frontend del mismo: `/clear` para que el contexto de la implementación backend no interfiera con las decisiones de frontend.

### Técnica 4: Plan mode (revisión antes de ejecución)

Antes de que la AI ejecute una tarea compleja, activar el modo de planificación le obliga a presentar un plan que puedes revisar y editar antes de que escriba código.

El flujo:

```plaintext
1. Activar plan mode (Shift+Tab ×2 en Claude Code, o instrucción explícita)
2. La AI presenta un plan con pasos numerados
3. Revisar el plan — ¿los pasos son correctos? ¿falta algo? ¿sobra algo?
4. Editar el plan si es necesario (Ctrl+G abre en editor)
5. Aprobar → la AI ejecuta paso a paso
```

**Cuándo aplicar:** Features complejos (3+ archivos), cambios que afectan arquitectura, y cualquier tarea donde el costo de un error es alto. Para tareas simples (fix de un bug, ajuste cosmético), el plan mode es overhead innecesario.

**El principio agnóstico:** No todas las herramientas tienen un “plan mode” formal. Pero el principio — pedirle a la AI que planifique antes de ejecutar — funciona en cualquier herramienta con un prompt:

```plaintext
Antes de implementar, dame un plan con:
1. Qué archivos vas a modificar
2. En qué orden
3. Qué resultado esperas de cada paso


NO implementes nada hasta que yo apruebe el plan.
```

### Técnica 5: Rewind (deshacer con contexto)

Cuando la AI tomó un camino incorrecto y quieres volver al estado anterior — no solo del código, sino de la conversación:

```plaintext
Esc → detiene la acción actual (el contexto se preserva, puedes redirigir)
Esc + Esc → abre el menú de rewind para restaurar un punto anterior
```

Esto es más poderoso que un `git checkout` porque restaura tanto el código como el estado de la conversación. La AI “olvida” el intento fallido y puede intentar de nuevo con dirección diferente.

**Cuándo aplicar:** Cuando la AI empezó a modificar archivos incorrectos, cuando un enfoque de implementación no funcionó, o cuando quieres probar una alternativa sin arrastrar el contexto del intento anterior.

***

## Las tres capas de optimización

Estas tres herramientas forman capas sobre el AGENTS.md:

```plaintext
Capa 3: Gestión de contexto (sesiones limpias, /compact, /clear, plan mode)
         → Cuándo y cómo la AI trabaja


Capa 2: Hooks (PostToolUse, Stop, PreToolUse)
         → Qué pasa automáticamente, siempre, sin excepción


Capa 1: Skills (conocimiento on-demand)
         → Qué sabe la AI cuando trabaja en un área específica


Base:    AGENTS.md (reglas universales del proyecto)
         → Qué sabe la AI siempre
```

No es necesario implementar las tres capas desde el día uno. La progresión natural es:

1. **Semana 1:** AGENTS.md bien escrito (\~150 líneas). Suficiente para empezar.
2. **Semana 2-3:** Primer skill (el conocimiento que más inflaba el AGENTS.md). Sesiones limpias por tarea.
3. **Semana 4+:** Hook de PostToolUse para formateo. /compact cuando las sesiones se alargan. Plan mode para features complejos.
4. **Mes 2+:** Más skills conforme el proyecto crece. Hook de Stop para verificación. Rewind cuando hay que explorar alternativas.

***

## Errores comunes

### “Meto todo en el AGENTS.md y funciona”

Funciona al inicio. Deja de funcionar cuando el archivo pasa de 200 líneas. La AI tiene un límite práctico de instrucciones que puede seguir consistentemente — sobrepasar ese límite no produce errores explícitos, sino degradación silenciosa. La AI simplemente empieza a ignorar reglas, especialmente las del final del archivo.

### “Configuro 10 skills desde el día uno”

Skills vacíos o con contenido genérico son peores que no tener skills — ocupan el presupuesto de carga sin aportar valor. Crear un skill solo cuando hay contenido real y probado que mover desde el AGENTS.md o desde la experiencia de implementación.

### “Los hooks resuelven todo”

Los hooks resuelven lo automatizable. No resuelven “seguir clean architecture” ni “mantener consistencia de UX” — esas son decisiones que requieren juicio y van en el AGENTS.md o en skills. Usar hooks para lo que se puede automatizar y dejar el resto como instrucciones.

### “No necesito gestionar el contexto, mis sesiones son cortas”

Si todas tus sesiones son menores a 30 minutos, probablemente no necesitas /compact ni /clear. Pero si alguna vez te encuentras pensando “la AI estaba funcionando bien al inicio y ahora está produciendo cosas raras”, la respuesta casi siempre es saturación de contexto. Compactar o limpiar resuelve el problema inmediatamente.

***

## Resumen accionable

1. **Empieza con el AGENTS.md.** No agregues skills ni hooks hasta que el AGENTS.md funcione bien por sí solo.

2. **Crea el primer skill cuando el AGENTS.md pase de 150 líneas.** Mueve el bloque de conocimiento más extenso a un skill — típicamente arquitectura backend o patrones de testing.

3. **El primer hook debe ser PostToolUse para formateo.** Es el de mayor impacto con menor esfuerzo. Elimina una categoría entera de inconsistencias.

4. **Usa sesiones limpias como regla, no como excepción.** Una tarea = una sesión. Es la técnica de gestión de contexto más simple y más efectiva.

5. **Plan mode para lo complejo, ejecución directa para lo simple.** No todo necesita un plan. Un fix de CSS no necesita plan mode. Un módulo nuevo con 5 archivos sí.

6. **Adapta a tu herramienta.** Skills, hooks, /compact, plan mode son features específicas. Los principios detrás de ellos (conocimiento on-demand, automatización determinista, gestión de contexto finito, planificación antes de ejecución) son universales.

# Protocolo UX

> Patrones de comportamiento e interacción para que la AI produzca interfaces consistentes

Nota

**Este protocolo también existe como skill ejecutable.** El capítulo explica el criterio detrás de cada regla; el skill es el procedimiento que la AI carga y ejecuta sola cuando detecta la tarea. Tiene un eslabón previo: la skill `information-architecture` decide qué es cada cosa, cómo se llama y dónde vive; este protocolo decide cómo se comporta.

`init` no la instala por defecto. Se agrega con `npx @falcux/ai-first@latest init --skills protocolo-ux`, que salta lo que ya existe; en un producto con interfaz, la entrevista de `init` ya la incluye. Qué hace cada skill y cuándo se activa: [Las 11 skills](/docs/referencia/skills/).

[Ver `protocolo-ux/SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-ux/SKILL.md)

> Este documento define los patrones de experiencia de usuario que DEBEN respetarse en toda implementación de interfaz. Si un componente no está listado aquí, buscar el patrón más cercano y seguir sus principios. Ante la duda, preguntar antes de implementar.

## 1. Arquitectura de navegación

### 1.1 Separación por dominio

La navegación se divide en dos dominios. NUNCA mezclarlos en el mismo nivel.

**Sidenav (navegación principal):**

* Contiene SOLO features del negocio — lo que el usuario final usa para cumplir sus objetivos.
* Ejemplos: Decisiones, Proyectos, Reportes, Contrapartes, Documentos.
* Cada ítem del sidenav lleva a una vista de nivel 1 (browse/listado).

**Settings / Avatar del usuario:**

* Contiene SOLO features de administración y gestión del sistema.
* Ejemplos: Gestión de usuarios, Roles y permisos, Configuración de cuenta, Facturación, Integraciones, Preferencias.
* Acceso desde el avatar del usuario o un ícono de configuración, NUNCA desde el sidenav principal.

**Regla de decisión:** Si la feature responde a “¿qué hace el negocio?”, va en el sidenav. Si responde a “¿cómo se configura/administra el sistema?”, va en settings.

### 1.2 Navegación por capas (layouts contextuales)

La aplicación maneja tres capas de navegación. Cada capa tiene su propio layout. NUNCA mostrar el layout de una capa en el contexto de otra.

**Capa 1 — Browse (exploración):**

* Layout: completo con sidenav visible.
* Propósito: el usuario explora módulos y listados.
* Ejemplo: lista de decisiones, dashboard principal, listado de contrapartes.
* El sidenav permanece visible y funcional.

**Capa 2 — Create / Edit (procesos):**

* Layout: limpio, SIN sidenav.
* Propósito: el usuario está en un flujo de creación o edición paso a paso.
* Navegación: stepper/wizard con indicador de progreso.
* Acciones: “Siguiente”, “Anterior”, “Cancelar” (con confirmación si hay cambios sin guardar).
* Al completar o cancelar, regresa a Capa 1.
* NUNCA mostrar el sidenav durante un flujo de creación — distrae y rompe el foco.

**Capa 3 — Detail (profundización):**

* Layout: limpio, SIN sidenav.
* Propósito: el usuario está viendo el detalle de un registro o información expandida.
* Navegación: botón “Volver” o “Salir” (iconografía + texto) en la parte superior.
* Al salir, regresa a la vista de origen (Capa 1 o el contexto que lo invocó).
* Puede contener tabs internos para organizar información del detalle.
* NUNCA mostrar el sidenav en la vista de detalle.

**Regla de navegación entre capas:**

```plaintext
Capa 1 (Browse) → click en registro → Capa 3 (Detail)
Capa 1 (Browse) → click en "Crear nuevo" → Capa 2 (Create)
Capa 3 (Detail) → click en "Editar" → Capa 2 (Edit)
Capa 2/3 → "Volver" / "Cancelar" → Capa anterior
```

## 2. Patrones de interacción

### 2.1 Tablas y listados

**Acceso al detalle:**

* SIEMPRE usar un ícono de acción (ojo, chevron, o botón “Ver”) en la columna de acciones.
* NUNCA hacer el texto de una celda clickeable como mecanismo de navegación al detalle.
* Razón: el texto clickeable no es discoverable y rompe la expectativa de selección.

**Columna de acciones:**

* Posición: SIEMPRE última columna a la derecha.
* Contenido: íconos de acción con tooltip (ver, editar, eliminar).
* Si hay más de 3 acciones, agrupar en un menú contextual (tres puntos verticales).
* Orden consistente: Ver → Editar → Más opciones (menú) → Eliminar.

**Selección en tablas:**

* Checkbox en la primera columna si se requiere selección múltiple.
* Barra de acciones bulk aparece al seleccionar al menos un registro.

**Ordenamiento y filtros:**

* Columnas ordenables muestran ícono de flechas (↕) en el header.
* Filtros van encima de la tabla, nunca dentro del header de columna.

### 2.2 Formularios

**Layout de campos:**

* Máximo 2 columnas en desktop, 1 columna en mobile.
* Labels SIEMPRE encima del campo (top-aligned), nunca inline/placeholder-only.
* Campos obligatorios marcados con asterisco (\*) junto al label.

**Validación:**

* Validar al salir del campo (on blur), no en tiempo real mientras el usuario escribe.
* Mensajes de error debajo del campo, en rojo, con texto descriptivo.
* Al enviar formulario con errores, scroll automático al primer campo con error.

**Acciones de formulario:**

* Botón primario (Guardar/Crear/Enviar) a la derecha.
* Botón secundario (Cancelar) a la izquierda del primario.
* Si el formulario tiene cambios sin guardar y el usuario intenta salir, mostrar diálogo de confirmación.

### 2.3 Modales y diálogos

**Cuándo usar modal vs. nueva página:**

* Modal: confirmaciones, formularios cortos (≤5 campos), alertas.
* Nueva página (Capa 2 o 3): formularios largos, vistas de detalle, flujos multi-paso.

**Anatomía del modal:**

* Header: título descriptivo + botón X para cerrar.
* Body: contenido.
* Footer: acciones (Cancelar a la izquierda, Acción primaria a la derecha).
* Cerrar con X, con botón Cancelar, o con click en el overlay — los tres deben funcionar.
* Cerrar con Escape SIEMPRE habilitado.

**Modales de confirmación destructiva:**

* Título claro: “¿Eliminar \[nombre del recurso]?”
* Descripción del impacto: “Esta acción no se puede deshacer.”
* Botón destructivo en rojo, con texto explícito (“Eliminar”, no “Aceptar”).

### 2.4 Feedback y estados

**Todo componente que carga datos debe manejar estos 4 estados:**

1. **Loading:** skeleton o spinner. Preferir skeleton para layouts conocidos.
2. **Empty:** mensaje + ilustración/ícono + CTA para crear el primer registro.
3. **Error:** mensaje descriptivo + acción de reintentar.
4. **Success:** los datos se muestran. Transición suave desde skeleton.

**Notificaciones (toast/snackbar):**

* Posición: esquina superior derecha.
* Duración: 5 segundos para info/success, persistente para errores.
* Acciones dentro de toast solo para “Deshacer”.

## 3. Layout y espaciado

### 3.1 Sistema de espaciado

Usar múltiplos de 4px como unidad base. Valores permitidos:

| Token     | Valor | Uso                                    |
| --------- | ----- | -------------------------------------- |
| `space-1` | 4px   | Separación entre ícono y texto         |
| `space-2` | 8px   | Padding interno de badges/pills        |
| `space-3` | 12px  | Gap entre campos de formulario inline  |
| `space-4` | 16px  | Padding interno de cards y secciones   |
| `space-5` | 20px  | Gap entre secciones dentro de una card |
| `space-6` | 24px  | Padding de página, gap entre cards     |
| `space-8` | 32px  | Separación entre secciones principales |

### 3.2 Breakpoints

| Nombre    | Ancho      | Columnas | Comportamiento                      |
| --------- | ---------- | -------- | ----------------------------------- |
| `mobile`  | < 768px    | 1        | Sidenav colapsado/drawer            |
| `tablet`  | 768–1024px | 1–2      | Sidenav colapsado, contenido adapta |
| `desktop` | > 1024px   | 2–3      | Sidenav visible, layout completo    |

### 3.3 Grid y contenedores

* Contenido principal: máximo 1200px de ancho, centrado.
* Formularios de creación/edición: máximo 800px de ancho, centrado.
* Cards dentro de dashboards: grid responsivo con gap de 24px.

## 4. Reglas cross-stack

Estos principios aplican independientemente de si se usa PrimeNG (Angular) o Shadcn UI (React):

### 4.1 Mapeo de componentes equivalentes

| Patrón             | PrimeNG        | Shadcn UI              |
| ------------------ | -------------- | ---------------------- |
| Tabla de datos     | `p-table`      | `DataTable` (tanstack) |
| Modal              | `p-dialog`     | `Dialog`               |
| Toast/notificación | `p-toast`      | `Sonner` o `Toast`     |
| Formulario         | Reactive Forms | React Hook Form        |
| Stepper/wizard     | `p-steps`      | Custom stepper         |
| Menú contextual    | `p-menu`       | `DropdownMenu`         |
| Sidebar/sidenav    | `p-sidebar`    | `Sheet` + custom nav   |

### 4.2 Regla de consistencia cross-stack

Si un patrón de interacción se define en este protocolo, DEBE implementarse de la misma manera conceptual en ambos stacks. La implementación técnica cambia, el comportamiento del usuario NO.

Ejemplo: “El detalle de un registro en tabla se accede con ícono de ojo” aplica tanto si la tabla es `p-table` como si es un `DataTable` de tanstack.

## 5. Checklist de verificación

Antes de dar por terminada cualquier implementación de UI, verificar:

* [ ] ¿La navegación respeta las 3 capas (Browse → Create → Detail)?
* [ ] ¿Las features de admin están en settings, NO en el sidenav?
* [ ] ¿Las tablas usan ícono de acción para navegar al detalle?
* [ ] ¿Los formularios tienen labels visibles (no solo placeholders)?
* [ ] ¿Los 4 estados (loading, empty, error, success) están cubiertos?
* [ ] ¿El espaciado usa múltiplos de 4px?
* [ ] ¿La vista se ve correcta en mobile, tablet y desktop?
* [ ] ¿Los modales se cierran con X, Cancelar, overlay y Escape?
* [ ] ¿El comportamiento de interacción es idéntico al patrón equivalente en el otro stack?

## 6. Cómo usar este protocolo

### Como skill

Copiar la skill `protocolo-ux` a `.agents/skills/protocolo-ux/`. La AI la carga sola cuando trabaja en componentes de UI.

### Como sección en CLAUDE.md

Agregar un resumen de las reglas más críticas (secciones 1 y 2) directamente en el CLAUDE.md del proyecto. No copiar todo el documento — solo los principios que más se violan.

### Como referencia en AGENTS.md (herramienta agnóstica)

Guardar el `SKILL.md` de `protocolo-ux` como `docs/protocolo-ux.md` y referenciarlo desde el AGENTS.md: «Para cualquier implementación de UI, consultar `docs/protocolo-ux.md` antes de generar código.»

### Para herramientas que no usan archivos .md (Antigravity, Lovable, etc.)

Copiar las secciones relevantes en el prompt inicial o en la descripción del proyecto dentro de la herramienta.

# Protocolo de gestión de cambios

> Cómo modificar lo que ya funciona sin romperlo: clasificación, análisis de impacto e implementación por pasos

Nota

**Este protocolo también existe como skill ejecutable.** El capítulo explica el criterio detrás de cada regla; el skill es el procedimiento que la AI carga y ejecuta sola cuando detecta la tarea.

Ya la tienes si corriste `npx @falcux/ai-first@latest init`: la instala por defecto en `.agents/skills/`. Cómo se usa en una sesión: [Gestionar un cambio](/docs/guias/gestionar-un-cambio/).

[Ver `protocolo-cambios/SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cambios/SKILL.md)

> Este documento define el proceso para gestionar cambios de requerimientos en proyectos construidos con AI coding agents. El objetivo es que los cambios se implementen sin romper lo existente, con documentación trazable y contexto claro para la AI.

## Principio fundamental

**Un cambio sin evaluación de impacto es una apuesta.** Antes de pedirle a la AI que modifique algo, el equipo humano debe entender qué se toca, qué se puede romper, y qué documentación debe actualizarse. La AI ejecuta; el humano decide.

***

## 1. Tipos de cambio

Cada tipo tiene un flujo diferente. Identificar el tipo ANTES de actuar.

### 1.1 Clasificación

| Tipo                        | Origen                           | Ejemplo                                              | Riesgo                                      |
| --------------------------- | -------------------------------- | ---------------------------------------------------- | ------------------------------------------- |
| **Corrección**              | La AI implementó algo incorrecto | Tabla con texto clickeable en vez de ícono           | Bajo — scope limitado                       |
| **Ajuste de diseño**        | Descubrimiento en práctica       | Un patrón no funciona en mobile                      | Bajo-medio — puede tocar varios componentes |
| **Cambio de requerimiento** | Cliente/PO pide algo diferente   | “Ya no queremos wizard, queremos formulario directo” | Medio-alto — puede afectar arquitectura     |
| **Cambio de prioridad**     | Re-priorización del backlog      | Feature X se pospone, Feature Y se adelanta          | Variable — depende de dependencias          |

### 1.2 Regla de decisión rápida

* **Si el cambio toca 1-2 archivos y no modifica el schema de BD** → flujo corto (sección 3)
* **Si el cambio toca 3+ archivos, modifica schema, o cambia flujos de navegación** → flujo completo (sección 4)

***

## 2. Estructura de documentación de cambios

### 2.1 Carpeta de cambios

```plaintext
docs/
├── changes/                    ← carpeta de cambios
│   ├── CHANGE_LOG.md           ← registro histórico (permanente)
│   └── pending/                ← cambios en proceso (temporal)
│       └── CHG-001_nombre.md   ← documento de cambio individual
├── PRD.md                      ← se actualiza al cerrar el cambio
├── ARCHITECTURE.md             ← se actualiza si aplica
└── ...
```

### 2.2 Anatomía de un documento de cambio (CHG-XXX\_nombre.md)

```markdown
# CHG-001: [Nombre descriptivo del cambio]


## Metadata
- **Fecha:** YYYY-MM-DD
- **Solicitado por:** [Cliente / PO / Dev / Descubrimiento propio]
- **Tipo:** [Corrección / Ajuste de diseño / Cambio de requerimiento / Cambio de prioridad]
- **Estado:** [Pendiente / En análisis / En implementación / Completado / Descartado]


## Qué cambia
[Descripción clara de qué se quiere diferente. Incluir capturas o referencias si aplica.]


## Por qué cambia
[Contexto de negocio o técnico que justifica el cambio.]


## Estado actual
[Cómo funciona HOY lo que se va a cambiar. Ser específico: rutas, componentes, archivos.]


## Estado deseado
[Cómo debe funcionar DESPUÉS del cambio. Ser específico.]


## Análisis de impacto
[Se llena durante el análisis — ver sección 4.2]


### Archivos afectados
- [ ] `ruta/archivo1.tsx` — [qué cambia en este archivo]
- [ ] `ruta/archivo2.tsx` — [qué cambia en este archivo]


### Dependencias
- [ ] ¿Requiere migración de BD? [Sí/No — detalle]
- [ ] ¿Afecta otros features? [Sí/No — cuáles]
- [ ] ¿Requiere actualizar tests? [Sí/No — cuáles]
- [ ] ¿Afecta la API/endpoints? [Sí/No — cuáles]


### Documentación a actualizar
- [ ] PRD.md — [qué sección]
- [ ] GUIA_DISENO.md — [qué sección]
- [ ] CLAUDE.md / AGENTS.md — [si aplica]
- [ ] Schema de BD — [si aplica]


## Plan de implementación
[Se llena durante la planificación — ver sección 4.3]


1. Paso 1: ...
2. Paso 2: ...
3. Paso N: ...


## Verificación post-cambio
- [ ] Feature modificado funciona según estado deseado
- [ ] Features adyacentes no se rompieron
- [ ] Tests pasan
- [ ] Documentación actualizada
- [ ] Documento de cambio movido a CHANGE_LOG.md
```

### 2.3 CHANGE\_LOG.md (registro permanente)

Este archivo es el registro histórico de todos los cambios. NUNCA se borra. Cuando un cambio se completa, su resumen se mueve aquí y el archivo individual en `pending/` se elimina.

```markdown
# Change Log


## CHG-001: Cambiar navegación de wizard a formulario directo
- **Fecha:** 2025-03-15
- **Tipo:** Cambio de requerimiento
- **Archivos:** 8 archivos modificados, 2 eliminados
- **Migración BD:** No
- **Resumen:** El flujo de creación pasó de wizard 3 pasos a formulario directo...
- **Lecciones:** Documentar siempre el estado anterior antes de modificar...


## CHG-002: ...
```

***

## 3. Flujo corto (cambios de bajo riesgo)

Para correcciones y ajustes menores que tocan 1-2 archivos y no modifican schema.

```plaintext
Detectar problema → Documentar en 1 párrafo → Implementar → Verificar → Actualizar docs
```

### 3.1 Pasos

1. **Documentar:** Crear un CHG-XXX mínimo (solo metadata + qué cambia + estado actual + estado deseado).
2. **Implementar en sesión limpia:** Abrir nueva sesión. Dar contexto: “El archivo X actualmente hace Y. Necesito que haga Z. No modifiques ningún otro archivo.”
3. **Verificar:** Probar que funciona Y que no rompió nada adyacente.
4. **Cerrar:** Pedirle a la AI que actualice la documentación relevante. Mover resumen a CHANGE\_LOG.md. Eliminar el archivo en `pending/`.

### 3.2 Prompt template para la AI (flujo corto)

```plaintext
CONTEXTO: Estoy haciendo un ajuste menor al feature [nombre].


ESTADO ACTUAL: [Describir cómo funciona hoy, incluir ruta del archivo]


CAMBIO REQUERIDO: [Describir qué debe cambiar]


RESTRICCIONES:
- Solo modificar [archivo(s) específico(s)]
- No tocar [archivos que NO deben cambiar]
- Mantener [patrones, convenciones, estilos existentes]


Implementa el cambio paso a paso. Después de cada paso, muéstrame qué modificaste para que yo valide antes de continuar.
```

***

## 4. Flujo completo (cambios de medio-alto riesgo)

Para cambios de requerimiento, cambios que tocan 3+ archivos, o cualquier cosa que modifique schema de BD o flujos de navegación.

```plaintext
Documentar → Analizar impacto → Planificar → Implementar por pasos → Verificar → Actualizar docs → Cerrar
```

### 4.1 Paso 1: Documentar el cambio

El PO o quien detecta el cambio crea el documento CHG-XXX en `docs/changes/pending/` con las secciones: metadata, qué cambia, por qué cambia, estado actual, estado deseado.

**Regla:** No avanzar a implementación sin documento de cambio. Si el cambio es verbal, documentarlo primero.

### 4.2 Paso 2: Analizar impacto (con ayuda de la AI)

Abrir una sesión DEDICADA al análisis, NO a la implementación.

**Prompt template para análisis de impacto:**

```plaintext
Necesito que analices el impacto de un cambio ANTES de implementar nada. NO modifiques ningún archivo.


Lee el documento de cambio en docs/changes/pending/CHG-XXX_nombre.md


Luego analiza:
1. ¿Qué archivos se ven afectados directamente por este cambio?
2. ¿Qué archivos se ven afectados indirectamente (importan o dependen de los directos)?
3. ¿Se requiere migración de base de datos?
4. ¿Hay tests que van a fallar?
5. ¿Este cambio contradice algo definido en CLAUDE.md, GUIA_DISENO.md, o el PRD?


Dame el análisis en formato lista. NO implementes nada todavía.
```

Con el análisis, llenar la sección “Análisis de impacto” del documento de cambio.

### 4.3 Paso 3: Planificar la implementación

Con el impacto claro, definir el plan de implementación ANTES de ejecutar.

**Regla de secuencia:** Implementar en este orden estricto:

1. Schema de BD (si aplica) → migración primero
2. Backend (API, servicios, tipos) → la base
3. Frontend (componentes, páginas) → lo visible
4. Tests → validar todo
5. Documentación → cerrar el loop

**Regla de granularidad:** Cada paso del plan debe ser lo suficientemente pequeño para validarlo individualmente. Si un paso toca más de 3 archivos, subdividirlo.

### 4.4 Paso 4: Implementar por pasos

Abrir una NUEVA sesión limpia para la implementación. No reutilizar la sesión de análisis.

**Prompt template para implementación por pasos:**

```plaintext
Vamos a implementar el cambio CHG-XXX documentado en docs/changes/pending/CHG-XXX_nombre.md


Lee el documento completo, incluyendo el análisis de impacto y el plan de implementación.


Implementa SOLO el paso [N] del plan: [descripción del paso].


RESTRICCIONES:
- Solo modificar los archivos listados para este paso
- Seguir los patrones definidos en [CLAUDE.md / GUIA_DISENO.md / skill protocolo-ux]
- Después de implementar, muéstrame exactamente qué cambió para validar


NO avances al siguiente paso hasta que yo confirme.
```

**Entre pasos:**

* Verificar que lo implementado funciona.
* Verificar que lo anterior no se rompió.
* Confirmar para continuar o corregir antes de avanzar.

### 4.5 Paso 5: Verificar el cambio completo

Después de todos los pasos de implementación:

```plaintext
El cambio CHG-XXX está implementado. Necesito que verifiques:


1. Lee el "estado deseado" del documento de cambio. ¿La implementación actual lo cumple?
2. Revisa los archivos listados en "dependencias". ¿Alguno tiene errores o inconsistencias?
3. Ejecuta los tests relevantes.
4. ¿Hay algo que debería funcionar diferente a lo implementado?


Dame un reporte de verificación.
```

### 4.6 Paso 6: Actualizar documentación y cerrar

**Prompt para cierre:**

```plaintext
El cambio CHG-XXX fue implementado y verificado. Necesito que:


1. Actualices la documentación principal del proyecto con los cambios realizados:
   - PRD.md: [secciones específicas a actualizar]
   - GUIA_DISENO.md: [si aplica]
   - CLAUDE.md / AGENTS.md: [si aplica]
   - Schema documentation: [si aplica]


2. Agregues un resumen del cambio al CHANGE_LOG.md con formato:
   ## CHG-XXX: [nombre]
   - Fecha, tipo, archivos afectados, si hubo migración, resumen, lecciones aprendidas


3. Confirma cuando hayas terminado para que yo elimine el archivo pending.
```

**Después de que la AI actualiza:**

* Revisar que las actualizaciones son correctas.
* Eliminar `docs/changes/pending/CHG-XXX_nombre.md`.
* El registro en CHANGE\_LOG.md queda como evidencia permanente.

***

## 5. Regla del lifecycle de documentos de cambio

Este es el flujo de vida de cada documento de cambio:

```plaintext
CREACIÓN                  → docs/changes/pending/CHG-XXX.md (estado: Pendiente)
ANÁLISIS completado       → mismo archivo (estado: En análisis → En implementación)
IMPLEMENTACIÓN completada → mismo archivo (estado: Completado)
DOCS actualizadas         → resumen migrado a CHANGE_LOG.md
CIERRE                    → archivo pending/ ELIMINADO


Resultado final:
- CHANGE_LOG.md tiene el resumen (permanente, trazable)
- docs/changes/pending/ queda limpio (sin archivos huérfanos)
- Documentación principal está al día
```

**Regla de limpieza:** Un archivo en `pending/` que lleve más de 2 semanas sin actividad debe ser revisado. Si el cambio ya no aplica, moverlo a CHANGE\_LOG.md con estado “Descartado” y eliminarlo de pending.

***

## 6. Patrones anti-regresión

Estos patrones previenen que la AI rompa cosas al implementar cambios.

### 6.1 Dar contexto explícito de lo que NO debe cambiar

Siempre incluir en el prompt una sección de restricciones:

```plaintext
RESTRICCIONES — NO MODIFICAR:
- Archivos en [rutas]
- Patrones de [navegación / interacción / diseño] existentes
- Schema de BD (a menos que el plan lo indique explícitamente)
- Configuración de [auth / routing / middleware]
```

### 6.2 Validar después de cada paso

No implementar más de un paso sin validar. La secuencia es:

```plaintext
Implementar paso → Revisar diff → Probar manualmente → Ejecutar tests → Aprobar → Siguiente paso
```

### 6.3 Sesiones limpias para cambios

NUNCA implementar un cambio en una sesión donde ya se estaba trabajando en otra cosa. Siempre:

1. Cerrar o limpiar la sesión actual.
2. Abrir sesión nueva.
3. Dar contexto del cambio (documento CHG-XXX).
4. Implementar.

### 6.4 Branch por cambio (si usan Git)

Cada cambio de tipo “Cambio de requerimiento” o “Cambio de prioridad” debería tener su propia branch:

```plaintext
git checkout -b change/CHG-XXX-nombre-descriptivo
```

Esto permite revertir el cambio completo si algo sale mal, sin afectar main.

***

## 7. Cuándo NO usar este protocolo

* **Bug fixes simples** (un botón no funciona, un texto está mal): corregir directamente, no hace falta documento de cambio.
* **Refactors internos que no cambian comportamiento**: usar proceso de refactor estándar, no este protocolo.
* **Nuevos features que no modifican nada existente**: usar el flujo normal de implementación (PRD → Arquitectura → Schema → Implementar).

Este protocolo es SOLO para cuando algo que ya existe necesita cambiar.

***

## 8. Checklist rápido de gestión de cambios

Antes de implementar cualquier cambio, verificar:

* [ ] ¿Tengo un documento CHG-XXX creado con estado actual y estado deseado?
* [ ] ¿Sé cuántos archivos se afectan? (determina flujo corto vs completo)
* [ ] ¿Tengo análisis de impacto? (para flujo completo)
* [ ] ¿Tengo un plan de pasos secuenciales?
* [ ] ¿Voy a usar una sesión limpia?
* [ ] ¿Definí explícitamente qué NO debe cambiar?

Después de implementar:

* [ ] ¿El feature modificado funciona según el estado deseado?
* [ ] ¿Los features adyacentes siguen funcionando?
* [ ] ¿Los tests pasan?
* [ ] ¿La documentación principal está actualizada?
* [ ] ¿El resumen está en CHANGE\_LOG.md?
* [ ] ¿Eliminé el archivo de pending/?

***

## 9. Cómo usar este protocolo

### Como skill

Copiar la skill `protocolo-cambios` a `.agents/skills/protocolo-cambios/`. La AI la carga sola cuando detecta que se está modificando algo que ya funciona.

### Como referencia en CLAUDE.md

Agregar al CLAUDE.md del proyecto:

```plaintext
## Gestión de cambios
Para cualquier cambio de requerimiento post-implementación, seguir el protocolo en docs/CHANGE_MANAGEMENT.md. NUNCA implementar un cambio sin documento CHG-XXX previo.
```

### Para herramientas agnósticas

Los principios (documentar antes de cambiar, analizar impacto, implementar por pasos, verificar, actualizar docs) aplican sin importar la herramienta. Los prompt templates se adaptan al formato de la herramienta.

# Protocolo de cierre de sesión

> Las tres fases del cierre y por qué solo la primera es delegable a la AI

Nota

**Este protocolo también existe como skill ejecutable.** El capítulo explica el criterio detrás de cada regla; el skill es el procedimiento que la AI carga y ejecuta sola cuando detecta la tarea.

Ya la tienes si corriste `npx @falcux/ai-first@latest init`: la instala por defecto en `.agents/skills/`. Cómo se usa en una sesión: [Cerrar la sesión](/docs/guias/cerrar-la-sesion/).

[Ver `protocolo-cierre/SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cierre/SKILL.md)

> Este documento define el proceso para cerrar correctamente una sesión de implementación con AI coding agents. El objetivo: que la siguiente persona (o tú mismo mañana) pueda retomar sin perder contexto.

## Principio fundamental

**Una sesión sin cierre es deuda de contexto.** Cada sesión que termina sin documentar qué se hizo, qué cambió, y qué quedó pendiente le cuesta tiempo a la siguiente sesión. El cierre no es burocracia — es inversión.

***

## 1. Cuándo usar este protocolo

* Al terminar una sesión de implementación de features
* Al terminar una sesión de corrección de bugs que modificó comportamiento
* Al terminar una sesión de gestión de cambios (protocolo CHG-XXX)
* Al terminar una sesión de refactoring que afectó la arquitectura

**NO es necesario para:**

* Sesiones exploratorias o de investigación sin cambios de código
* Sesiones de solo lectura/análisis
* Fix de typos o cambios cosméticos menores

***

## 2. El cierre en 3 fases

```plaintext
Fase A: La AI documenta (automatizable)
    ↓
Fase B: El humano verifica (no delegable)
    ↓
Fase C: El humano cierra (commit + sync)
```

***

## 3. Fase A — La AI documenta

Pedirle a la AI que ejecute las siguientes actualizaciones. Usar este prompt o uno equivalente adaptado a la herramienta:

### Prompt de cierre

```plaintext
La sesión de implementación terminó. Necesito que hagas el cierre de documentación:


1. RESUMEN DE SESIÓN: Crea o actualiza `docs/SESSION_LOG.md` agregando una entrada
   con fecha, qué se implementó, qué archivos se modificaron, y qué quedó pendiente.


2. DOCUMENTACIÓN DEL PROYECTO: Revisa y actualiza los siguientes documentos
   SOLO si los cambios de esta sesión los afectan:
   - AGENTS.md — ¿cambió alguna regla, comando, o estructura?
   - docs/GUIA_DISENO.md — ¿se crearon componentes nuevos o patrones nuevos?
   - docs/PRD.md — ¿se completó algo que estaba como pendiente?
   - docs/ARQUITECTURA.md — ¿cambió la arquitectura o se agregó un módulo?
   - docs/changes/CHANGE_LOG.md — ¿se completó algún cambio CHG-XXX?


3. ANTI-PATRONES: Si durante la sesión descubriste un gotcha o un error que
   la AI cometió y tuviste que corregir, agrégalo a la sección "What NOT to Do"
   del AGENTS.md o a la sección "Gotchas" de GUIA_DISENO.md.


4. PENDIENTES: Si quedó algo sin terminar, documéntalo claramente con:
   - Qué falta hacer
   - En qué archivo(s)
   - Cualquier contexto que la siguiente sesión necesite


NO hagas cambios de código. Solo documentación.
```

### SESSION\_LOG.md — formato de entrada

```markdown
## YYYY-MM-DD — [Descripción breve de la sesión]


**Implementado:**
- [Feature o cambio 1]
- [Feature o cambio 2]


**Archivos modificados:**
- `ruta/archivo1.tsx` — [qué cambió]
- `ruta/archivo2.ts` — [qué cambió]


**Documentación actualizada:**
- [Doc 1] — [qué sección se actualizó]
- [Doc 2] — [qué sección se actualizó]


**Anti-patrones descubiertos:**
- [Gotcha o error descubierto, si aplica]


**Pendiente para siguiente sesión:**
- [ ] [Tarea pendiente 1 — contexto necesario]
- [ ] [Tarea pendiente 2 — contexto necesario]


**Tests:** [X] passing / [Y] total
```

***

## 4. Fase B — El humano verifica

Esta fase NO es delegable a la AI. El humano revisa lo que la AI documentó.

### Checklist de verificación (5 puntos)

#### 4.1 ¿El resumen de sesión es correcto?

Abrir `docs/SESSION_LOG.md` y verificar:

* [ ] ¿La descripción refleja lo que realmente se hizo?
* [ ] ¿Los archivos modificados son los correctos? (cruzar con `git diff --name-only`)
* [ ] ¿Los pendientes están claros para alguien que no estuvo en la sesión?

**Error común de la AI:** Listar archivos que no se modificaron, u omitir archivos que sí cambiaron. Siempre cruzar con el diff de git.

#### 4.2 ¿La documentación actualizada es precisa?

Para cada documento que la AI dice haber actualizado:

* [ ] Abrir el documento y leer la sección modificada
* [ ] ¿La información agregada es correcta? (no inventó features, no cambió datos existentes)
* [ ] ¿Mantuvo el formato y tono del resto del documento?

**Error común de la AI:** Agregar información redundante, cambiar secciones que no debía tocar, o describir la implementación de forma imprecisa. Especial atención a números (endpoints, conteos de tests, versiones).

#### 4.3 ¿Los anti-patrones son reales?

Si la AI agregó algo a “What NOT to Do” o “Gotchas”:

* [ ] ¿Es un error real que ocurrió, o es una precaución genérica?
* [ ] ¿La descripción es suficientemente específica para ser útil?

**Regla:** Solo agregar anti-patrones que realmente ocurrieron en esta sesión. No permitir que la AI agregue advertencias genéricas del tipo “NO usar eval()”.

#### 4.4 ¿Los tests pasan?

* [ ] Ejecutar la suite de tests completa (no solo los tests nuevos)
* [ ] Si algún test falla, NO cerrar la sesión — corregir primero

```bash
# Ejemplo
pnpm test                    # toda la suite
pnpm typecheck               # verificación de tipos
pnpm lint                    # lint
```

#### 4.5 ¿Quedó algo sin documentar?

Revisar mentalmente:

* [ ] ¿Se tomó alguna decisión de arquitectura que no quedó escrita?
* [ ] ¿Se descubrió algo sobre el comportamiento del sistema que otros deberían saber?
* [ ] ¿Cambió algún flujo de usuario que debería reflejarse en el PRD o la guía de diseño?

Si la respuesta es sí a cualquiera, agregar manualmente antes de cerrar.

***

## 5. Fase C — El humano cierra

### 5.1 Commit de código + documentación

Hacer commit de todo junto (código + docs actualizados) para que el historial de git refleje qué cambio de código motivó qué cambio de docs.

```bash
# Patrón de commit recomendado
git add .
git commit -m "feat: [descripción del feature]


- [Cambio principal 1]
- [Cambio principal 2]
- docs: actualizado [docs afectados]
- pending: [pendiente si aplica]"
```

**Regla:** El código y su documentación se commitean juntos. Nunca commitear código en un commit y docs en otro — pierdes la trazabilidad.

### 5.2 Sincronizar espejo en Notion (si aplica)

Actualizar el espejo de documentación en Notion con los cambios relevantes. No es necesario copiar todo — solo:

* Estado de features (completado, en progreso, pendiente)
* Decisiones de producto tomadas
* Pendientes que el equipo debe conocer

**Regla:** Notion es el espejo para humanos, no la fuente de verdad técnica. Si hay conflicto entre lo que dice Notion y lo que dice el repo, el repo gana.

### 5.3 Cerrar cambios pendientes (si aplica)

Si la sesión completó un cambio del protocolo de gestión de cambios:

* [ ] Verificar que el CHG-XXX en `docs/changes/pending/` está marcado como completado
* [ ] Mover resumen a `docs/changes/CHANGE_LOG.md`
* [ ] Eliminar el archivo de `pending/`

***

## 6. SESSION\_LOG.md — reglas del documento

### Estructura del archivo

```markdown
# Session Log


> Registro cronológico de sesiones de implementación. Cada entrada documenta
> qué se hizo, qué cambió, y qué quedó pendiente.


---


## YYYY-MM-DD — [Sesión más reciente arriba]
...


## YYYY-MM-DD — [Sesión anterior]
...
```

### Reglas

* **Orden:** sesión más reciente arriba (cronológico inverso)
* **Una entrada por sesión:** no agrupar múltiples sesiones en una entrada
* **Formato consistente:** usar siempre la plantilla de la sección 3
* **Limpieza:** cuando el archivo supere \~50 entradas, archivar las más antiguas en `docs/SESSION_LOG_ARCHIVE.md` y mantener solo las últimas 20

### Cuándo consultar el SESSION\_LOG

Al iniciar una nueva sesión, la AI (o el humano) debería leer las últimas 2-3 entradas del SESSION\_LOG para:

* Saber qué se hizo en la sesión anterior
* Retomar pendientes
* No duplicar trabajo ya hecho

**Tip:** Agregar al AGENTS.md del proyecto:

```markdown
### Inicio de sesión
Al comenzar cualquier sesión de implementación, leer las últimas 3 entradas
de `docs/SESSION_LOG.md` para tener contexto de sesiones anteriores.
```

***

## 7. División de responsabilidades

| Tarea                        | ¿Quién?                        | ¿Por qué?                                             |
| ---------------------------- | ------------------------------ | ----------------------------------------------------- |
| Escribir resumen de sesión   | AI                             | Tiene el contexto fresco de todo lo que hizo          |
| Actualizar docs del proyecto | AI                             | Sabe qué archivos modificó                            |
| Agregar anti-patrones        | AI (propone) + Humano (valida) | La AI puede proponer pero el humano decide si es real |
| Verificar precisión de docs  | Humano                         | La AI puede inventar o ser imprecisa                  |
| Cruzar con git diff          | Humano                         | Verificación objetiva de qué cambió                   |
| Ejecutar tests               | Humano (o CI)                  | Validación definitiva                                 |
| Hacer commit                 | Humano                         | Decisión de qué entra y qué no                        |
| Sincronizar Notion           | Humano                         | Requiere criterio de qué es relevante para el equipo  |
| Cerrar CHG-XXX               | Humano                         | Decisión de lifecycle de documentación                |

***

## 8. Modo rápido (sesiones cortas)

Para sesiones menores a 30 minutos o cambios muy pequeños, el protocolo completo puede ser excesivo. Usar este checklist reducido:

* [ ] Tests pasan
* [ ] Agregar entrada mínima al SESSION\_LOG (1-2 líneas: qué se hizo + pendiente)
* [ ] Commit con mensaje descriptivo
* [ ] Si se descubrió un gotcha → agregar a “What NOT to Do”

No es necesario pedir a la AI que actualice toda la documentación si el cambio fue menor. Usar criterio.

***

## 9. Inicio de sesión (el complemento)

Este protocolo funciona en par con un **ritual de inicio de sesión**:

```plaintext
Al comenzar una sesión de implementación:


1. Leer las últimas 2-3 entradas de docs/SESSION_LOG.md
2. Verificar si hay pendientes de la sesión anterior
3. Si se va a trabajar en un cambio: leer el CHG-XXX correspondiente
4. Si es un feature nuevo: seguir el Protocolo de Desarrollo de Features
```

Agregar esto al AGENTS.md del proyecto para que la AI lo haga automáticamente.

***

## 10. Cómo usar este protocolo

### Como skill

Copiar la skill `protocolo-cierre` a `.agents/skills/protocolo-cierre/`. La AI la carga sola al detectar que la sesión está terminando o cuando le pidas cerrar.

### Como referencia en AGENTS.md

```markdown
## Cierre de sesión
Al terminar cualquier sesión de implementación, se activa la skill protocolo-cierre.
Incluye: documentar → verificar → commit.
```

### Para herramientas agnósticas

Los principios (documentar qué se hizo, verificar, commitear junto) aplican sin importar la herramienta. El prompt de cierre se adapta al formato de cada una.

***

## 11. Checklist imprimible

```plaintext
CIERRE DE SESIÓN — CHECKLIST


Fase A (AI documenta):
□ Entrada en SESSION_LOG.md con resumen, archivos, pendientes
□ Docs del proyecto actualizados (si aplica)
□ Anti-patrones agregados a "What NOT to Do" (si aplica)


Fase B (Humano verifica):
□ Resumen de sesión es correcto (cruzar con git diff)
□ Docs actualizados son precisos (leer secciones modificadas)
□ Anti-patrones son reales (no genéricos)
□ Tests pasan (suite completa)
□ Nada quedó sin documentar


Fase C (Humano cierra):
□ Commit de código + docs juntos
□ Notion sincronizado (si aplica)
□ CHG-XXX cerrado (si aplica)
```

# Protocolo de desarrollo de features

> De la spec a la verificación: pre-implementación, secuencia estricta y checklists

Nota

**Este protocolo también existe como skill ejecutable.** El capítulo explica el criterio detrás de cada regla; el skill es el procedimiento que la AI carga y ejecuta sola cuando detecta la tarea.

Ya la tienes si corriste `npx @falcux/ai-first@latest init`: la instala por defecto en `.agents/skills/`. Cómo se usa en una sesión: [Desarrollar una feature](/docs/guias/desarrollar-una-feature/).

[Ver `protocolo-features/SKILL.md`](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-features/SKILL.md)

> Este documento define el proceso para implementar features nuevos con AI coding agents. No reemplaza la creatividad ni la velocidad — la estructura existe para que la AI produzca mejor resultado desde el primer intento.

## Principio fundamental

**La AI implementa mejor cuando sabe QUÉ construir, CÓMO debe verse, y QUÉ NO hacer.** Invertir 15 minutos en contexto ahorra 2 horas de correcciones. La documentación previa no es overhead — es el prompt más importante que vas a escribir.

***

## 1. Entradas: cómo llega un feature

Un feature puede llegar de múltiples fuentes. El protocolo funciona con todas.

| Fuente                      | Ejemplo                                   | Qué hacer primero                                |
| --------------------------- | ----------------------------------------- | ------------------------------------------------ |
| Documento de requerimientos | Archivo .docx/.xlsx del cliente           | Convertir a spec implementable (paso 2)          |
| PRD existente               | docs/PRD.md con el feature descrito       | Verificar que la spec es suficiente (paso 2)     |
| Definición del PO           | Google Doc, ticket, conversación          | Documentar como spec mínima (paso 2)             |
| Idea propia / mejora        | “Esto debería funcionar diferente”        | Documentar como spec mínima (paso 2)             |
| Feature generado por AI     | PRD generado por LLM desde requerimientos | Validar con humano antes de implementar (paso 2) |

**Regla:** Sin importar de dónde venga, todo feature pasa por el mismo protocolo antes de llegar a código. La fuente varía; el proceso no.

***

## 2. Pre-implementación: los 7 pasos antes de código

### Paso 1 — Asegurar que existe una spec implementable

Verificar que tienes documentación suficiente para que la AI entienda qué construir.

**Spec mínima viable (lo que necesitas como mínimo):**

```markdown
## Feature: [Nombre]


### Qué hace
[1-3 párrafos describiendo el comportamiento desde la perspectiva del usuario]


### Criterios de aceptación
- [ ] [El usuario puede hacer X]
- [ ] [El sistema responde con Y]
- [ ] [En caso de error, ocurre Z]


### Alcance
- Incluye: [qué sí]
- NO incluye: [qué no — esto es crítico para la AI]


### Dependencias
- [Módulos, endpoints, o componentes que ya existen y que este feature usa]
- [Módulos que este feature NO debe modificar]
```

**Si la spec no existe:** Usar la AI para generarla a partir de la fuente original (requerimiento del cliente, PRD, etc.), pero SIEMPRE validar con el PO o decisor antes de implementar. La AI es buena generando specs, pero puede inventar requerimientos que nadie pidió.

**Si la spec fue generada por AI:** Leerla completa. Verificar que no agregó features que no se pidieron. Confirmar con el PO si hay dudas.

### Paso 2 — Inventario de reuso y lógica compartida

Es el paso que más deuda evita y el que más se salta. Se responde en las dos direcciones:

**a) ¿Qué existe que se pueda reusar?** Buscar por concepto de dominio —notificación, validación, scoring, exportación—, no por nombre de módulo. Un agente que busca «módulo de facturación» no encuentra la lógica de cálculo que vive en «pedidos».

**b) ¿Lo que se va a construir le sirve a otro módulo?** Si la lógica nueva tiene relación con otro módulo, actual o del backlog, se diseña compartida desde el inicio: servicio de dominio reutilizable, puerto común o paquete compartido. No enterrada dentro del módulo que la estrena.

**Salida obligatoria del paso.** Una tabla que va en el plan y se puede auditar:

| Pieza                  | Decisión                                                  | Justificación |
| ---------------------- | --------------------------------------------------------- | ------------- |
| \[lógica / componente] | Reusa `X` / Extiende `X` / Nueva compartida / Nueva local | \[por qué]    |

Toda pieza marcada «Nueva local» justifica por qué no se pudo reusar ni conviene compartir. Sin esta tabla, el plan está incompleto.

Unificar después siempre cuesta más que diseñar compartido al inicio. La duplicación no duele el día que se escribe: duele el día que las dos copias divergen.

Si alguna fila de esa tabla es una decisión difícil de revertir —un paquete compartido nuevo, un límite entre capas, una dependencia de producción que entra—, no basta con justificarla en el plan, que se archiva. Va como fila en el `docs/ADR.md`, con lo que se descartó. Ver [Gobierno del contexto](/docs/parte-2/gobierno-del-contexto/).

### Paso 3 — Leer la documentación de diseño

Antes de que la AI escriba una línea de código:

* [ ] Leer `docs/GUIA_DISENO.md` — tokens, componentes, patrones de layout, dark mode
* [ ] Consultar la skill `protocolo-ux` — navegación por capas, interacciones estándar

**Preguntas clave de diseño:**

* ¿En qué capa de navegación vive este feature? (Browse, Create, Detail)
* ¿Usa componentes existentes o necesita nuevos?
* ¿Cómo se ve el estado vacío, loading, error?
* ¿Tiene vista mobile?

Si las respuestas no están claras, definirlas ANTES de implementar.

### Paso 4 — Validar enfoque UX (recomendado)

Antes de construir, validar que el enfoque de UX es correcto. Dos opciones:

**Opción A — Agente especializado (si la herramienta lo soporta):** Lanzar un agente `ux-ui-critic` o equivalente con el prompt:

```plaintext
Revisa la spec del feature [nombre] y la guía de diseño del proyecto.
Evalúa:
1. ¿El flujo de usuario es coherente con los patrones de navegación existentes?
2. ¿Los componentes propuestos son consistentes con lo que ya existe?
3. ¿Hay edge cases de UX no contemplados? (empty state, error, mobile)
4. ¿La interacción propuesta sigue el protocolo UX del proyecto?


NO implementes nada. Solo dame tu evaluación y recomendaciones.
```

**Opción B — Revisión mental (siempre disponible):** Revisar la spec contra el [checklist de verificación](/docs/parte-3/protocolo-ux/#5-checklist-de-verificaci%C3%B3n) del protocolo UX. Si algún punto no se cumple, ajustar la spec antes de implementar.

**Cuándo es obligatorio vs. recomendado:**

* Feature con UI nueva (página, modal, formulario) → obligatorio
* Feature solo backend (endpoint, use case, migración) → omitir
* Fix de UI existente → obligatorio si cambia interacción, omitir si es cosmético

### Paso 5 — Verificar dependencias técnicas

Antes de implementar, confirmar:

* [ ] ¿Se requiere migración de BD? → planificarla primero
* [ ] ¿Se necesitan schemas de validación nuevos? → crearlos en packages/shared
* [ ] ¿Hay endpoints que este feature necesita y no existen? → implementar backend primero
* [ ] ¿Hay claves de i18n que crear? → prepararlas en archivos de mensajes
* [ ] ¿Este feature afecta features existentes? → si sí, usar protocolo de cambios

### Paso 6 — Preparar el contexto para la AI

Construir el prompt de implementación con contexto completo:

```plaintext
FEATURE: [Nombre del feature]


SPEC: [Referencia a la spec o resumen breve]


DOCUMENTACIÓN A CONSULTAR:
- docs/GUIA_DISENO.md — para tokens, componentes, patrones visuales
- skill protocolo-ux — para interacciones y navegación
- [Otros docs relevantes]


ARQUITECTURA:
- [Dónde vive este feature en la estructura del proyecto]
- [Qué módulos/componentes existentes debe usar]
- [Patrón de arquitectura a seguir — ej: Clean Architecture 3 capas]


RESTRICCIONES:
- NO modificar [archivos/módulos que no deben cambiar]
- NO implementar [funcionalidad fuera de alcance]
- Seguir los patrones de [navegación/interacción/diseño] existentes


IMPLEMENTA paso a paso. Después de cada paso, muéstrame qué hiciste
para que yo valide antes de continuar.
```

### Paso 7 — Definir la secuencia de implementación

El orden importa. Implementar en esta secuencia:

```plaintext
1. Schema/Migración BD (si aplica)
    ↓
2. Domain (entities, ports, value objects)
    ↓
3. Application (use cases, DTOs)
    ↓
4. Infrastructure — Backend (repositories, controllers, servicios externos)
    ↓
5. Shared (schemas Zod, tipos, constantes)
    ↓
6. Infrastructure — Frontend (páginas, componentes, formularios)
    ↓
7. Tests (unit + E2E backend, componentes frontend)
    ↓
8. Verificación final (typecheck, lint, tests completos)
```

**No todos los features necesitan todos los pasos.** Un feature solo-frontend empieza en el paso 6. Un feature solo-backend termina en el paso 4. Pero el ORDEN dentro de los pasos aplicables es estricto.

***

## 3. Implementación: durante la sesión

### 3.1 Una sesión = un feature

Cada feature se implementa en una sesión limpia dedicada. Esto significa:

* Contexto fresco (no arrastrar contexto de otro feature)
* La spec del feature es el primer input
* El SESSION\_LOG.md de la sesión anterior se leyó para tener contexto

### 3.2 Con equipos de agentes (si la herramienta lo soporta)

Para features que tocan backend + frontend + tests, los agentes especializados paralelizar el trabajo:

| Agente         | Scope                                         | Pasos que ejecuta |
| -------------- | --------------------------------------------- | ----------------- |
| Backend Agent  | apps/api/ + packages/prisma + packages/shared | 1-5               |
| Frontend Agent | apps/web/ + packages/ui                       | 6                 |
| Test Agent     | apps/api/test/ + apps/web/\*\*/*.test.*       | 7                 |

**Reglas de coordinación:**

* Backend Agent completa primero (crea endpoints que Frontend consume)
* Frontend Agent trabaja después (usa los endpoints y schemas compartidos)
* Test Agent valida al final (verifica que todo funciona junto)
* Schemas compartidos (packages/shared) los crea Backend Agent
* Si hay conflicto en un archivo, el agente owner del scope tiene prioridad

**Configuración (Claude Code):**

```plaintext
# En .claude/settings.json o por sesión
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

**Sin equipos de agentes:** Seguir la secuencia del paso 7 manualmente, validando después de cada paso antes de continuar.

### 3.3 Validación incremental

Después de CADA paso de la secuencia:

```plaintext
Implementar paso N
    ↓
¿Compila? (typecheck)
    ↓
¿Los tests existentes siguen pasando?
    ↓
¿El comportamiento es el esperado? (prueba manual rápida)
    ↓
Confirmar → siguiente paso
```

**Si algo falla:** Corregir ANTES de avanzar. No acumular errores.

### 3.4 Señales de que algo va mal

Detener la implementación y reevaluar si:

* La AI modifica archivos que no están en el scope del feature
* La implementación requiere cambiar la arquitectura existente (→ es un cambio, no un feature)
* Aparecen más de 3 archivos que no estaban en la spec
* Los tests existentes empiezan a fallar sin razón aparente

***

## 4. Post-implementación: verificación

### 4.1 Checklist técnico

```bash
# Ejecutar en orden
pnpm typecheck              # 0 errores de tipos
pnpm lint                   # 0 warnings/errores
pnpm test                   # todos los tests pasan (incluyendo los nuevos)
```

### 4.2 Checklist de UX (para features con interfaz)

Referencia: el [checklist del protocolo UX](/docs/parte-3/protocolo-ux/#5-checklist-de-verificaci%C3%B3n), que la skill `protocolo-ux` ejecuta.

* [ ] ¿La navegación respeta las capas (Browse → Create → Detail)?
* [ ] ¿Las interacciones son consistentes con componentes existentes?
* [ ] ¿Los 4 estados están cubiertos? (loading, empty, error, success)
* [ ] ¿Funciona en mobile?
* [ ] ¿Dark mode funciona correctamente?
* [ ] ¿Los textos están en archivos de i18n, no hardcodeados?

### 4.3 Checklist de completitud

* [ ] ¿Todos los criterios de aceptación de la spec se cumplen?
* [ ] ¿Se crearon tests para el feature nuevo?
* [ ] ¿El feature NO rompe features existentes?
* [ ] ¿Lo que está fuera de alcance NO se implementó?

### 4.4 Cierre

Seguir el **Protocolo de cierre de sesión**, que ejecuta la skill `protocolo-cierre`:

* AI documenta en SESSION\_LOG.md
* Humano verifica
* Commit de código + docs juntos

***

## 5. Casos especiales

### Feature que resulta ser más grande de lo esperado

Si durante la implementación descubres que el feature requiere más de una sesión:

1. Parar la implementación en un punto estable (que lo hecho funcione por sí solo)
2. Hacer cierre de sesión con lo completado
3. Documentar en SESSION\_LOG.md qué falta exactamente
4. La siguiente sesión retoma desde los pendientes

**Regla:** Nunca dejar código a medio implementar sin cierre. Si hay que dividir, cada parte debe ser funcional por separado.

### Feature que requiere cambios en features existentes

Si el feature nuevo necesita modificar algo que ya funciona:

1. Separar: implementar la parte nueva primero (sin tocar lo existente)
2. Después: usar el **Protocolo de gestión de cambios** para las modificaciones
3. Nunca mezclar feature nuevo + cambios en existente en el mismo paso

### Feature solo-backend (sin UI)

Simplificar: omitir pasos 2, 3 de pre-implementación y checklist de UX en post-implementación. El resto del protocolo aplica igual.

### Feature solo-frontend (sin backend nuevo)

Simplificar: la secuencia de implementación empieza en el paso 6. Los pasos de pre-implementación aplican completos (especialmente diseño y UX).

***

## 6. Spec mínima viable — template

Para features que llegan sin documentación formal. Llenar este template ANTES de pedirle a la AI que implemente:

```markdown
# Feature: [Nombre]


## Contexto
[¿Por qué se necesita este feature? ¿Qué problema resuelve?]


## Comportamiento esperado
[Describir desde la perspectiva del usuario — qué hace, qué ve, qué resultado obtiene]


## Criterios de aceptación
- [ ] [Criterio 1]
- [ ] [Criterio 2]
- [ ] [Criterio 3]


## Alcance
**Incluye:**
- [Lo que sí se implementa]


**NO incluye:**
- [Lo que queda fuera — ser explícito]


## Diseño
**Capa de navegación:** [Browse / Create / Detail]
**Componentes:** [Existentes que reutiliza / Nuevos que necesita]
**Estados:** [Loading / Empty / Error / Success — cómo se ve cada uno]


## Dependencias técnicas
- [ ] Migración de BD: [Sí/No — detalle]
- [ ] Endpoints necesarios: [Existentes / Nuevos]
- [ ] Schemas Zod: [Existentes / Nuevos]
- [ ] Claves i18n: [Nuevas que crear]


## Archivos que NO deben modificarse
- [Lista explícita de archivos/módulos fuera de scope]
```

***

## 7. Conexión con otros protocolos

```plaintext
                    ┌────────────────────────────────┐
                    │  ESTE PROTOCOLO                │
                    │  (Feature Development)         │
                    └──────┬──────────────┬──────────┘
                           │              │
              ┌────────────▼──┐    ┌──────▼──────────────┐
              │ UX Protocol   │    │ Change Management   │
              │ (Consistencia │    │ (Si el feature      │
              │  visual)      │    │  modifica algo      │
              │ Pre-impl: ✓   │    │  existente)         │
              └───────────────┘    └─────────────────────┘
                                          │
                              ┌───────────▼────────────┐
                              │ Session Closure        │
                              │ (Al terminar la sesión │
                              │  de implementación)    │
                              └────────────────────────┘
```

* **UX Protocol** se consulta en el paso 3 y 4 de pre-implementación
* **Change Management** se activa si el feature nuevo requiere modificar algo existente
* **Session Closure** se ejecuta al terminar la sesión de implementación

***

## 8. Cómo usar este protocolo

### Como skill

Copiar la skill `protocolo-features` a `.agents/skills/protocolo-features/`. La AI la carga sola al detectar que se va a implementar un feature nuevo.

### Como referencia en AGENTS.md

```markdown
## Protocolo de Desarrollo de Features (OBLIGATORIO)
Antes de implementar cualquier feature nuevo, se activa la skill protocolo-features.
Incluye: spec → reuso → diseño → UX → implementar → verificar.
```

### Para herramientas agnósticas

Los principios (documentar antes de codear, validar UX, implementar en secuencia, verificar post-implementación) aplican sin importar la herramienta.

# Escalar al equipo y costos

> Cómo llevar la metodología de individual a equipo, y comparación de herramientas y costos

> *La metodología funciona para una persona. Pero el valor real aparece cuando todo el equipo la adopta — y ahí es donde la mayoría falla.*

***

## La adopción nunca es simultánea

En AutenTIC, la adopción de AI coding agents empezó con 2-3 personas experimentando al mismo tiempo. No fue una decisión organizacional top-down ni un rollout formal. Fue un grupo pequeño probando herramientas, compartiendo resultados, y aprendiendo de los errores.

Esa es la ruta que funciona. Los equipos que intentan adoptar AI coding agents como una decisión organizacional de un día para otro chocan con dos barreras que no son técnicas: desconfianza en la calidad del código generado, y resistencia natural al cambio.

La solución no es convencer — es demostrar. Y para demostrar, necesitas un caso de éxito interno antes de escalar.

***

## Las fases de adopción

### Fase 1: El explorador (1 persona, 1-2 semanas)

Una persona del equipo — típicamente quien tiene más curiosidad o experiencia con AI — empieza a usar un AI coding agent en un proyecto real. No en un toy project ni en un hackathon: en trabajo de producción.

**Qué hace:**

* Configura el AGENTS.md del proyecto usando el template
* Implementa un feature completo con AI
* Documenta el resultado: tiempo invertido, calidad, problemas encontrados

**Qué produce:**

* El primer caso de éxito (o de fracaso honesto) con datos reales
* Un AGENTS.md funcional que otros pueden reutilizar
* Conocimiento de primera mano sobre qué funciona y qué no

**Señal para avanzar:** El explorador completó un feature de producción con AI más rápido que sin ella, con calidad aceptable. Si no, iterar en la metodología antes de escalar.

### Fase 2: La pareja (2 personas, 2-4 semanas)

El explorador suma a una segunda persona — idealmente alguien con un rol diferente (si el explorador es developer, sumar al PO o al designer; si es designer, sumar un developer).

**Qué hacen:**

* Trabajan juntos en un feature usando la cadena de artefactos completa
* El PO o designer produce la spec, el developer la implementa con AI
* Ambos validan que los protocolos funcionan para más de una persona

**Qué descubren:**

* Cómo comunicar contexto entre roles (no solo dentro de una sesión)
* Qué información necesita el PO vs. qué necesita el developer
* Si la documentación producida por uno es útil para el otro

**Señal para avanzar:** La pareja completó un feature con la metodología y ambos consideran que fue más eficiente que sin ella.

### Fase 3: El equipo piloto (3-5 personas, 4-8 semanas)

Sumar al resto del equipo técnico. Aquí es donde aparecen los problemas reales de adopción.

**El kit de onboarding para nuevos miembros:**

1. **Lectura obligatoria** (30 min): Capítulos 1 y 2 de Falcux AI-First — el caso de negocio y qué es AI-First
2. **Setup técnico** (1 hora): Instalar la herramienta, clonar el proyecto, verificar que el AGENTS.md carga correctamente
3. **Primera sesión guiada** (2 horas): El explorador hace pair programming con el nuevo miembro usando AI. El nuevo miembro observa el flujo: cómo se prepara el contexto, cómo se dirige la sesión, cómo se valida
4. **Primera sesión solo** (2 horas): El nuevo miembro implementa un feature simple (idealmente un fix o mejora menor) siguiendo el protocolo de features. El explorador está disponible para preguntas
5. **Retrospectiva** (30 min): ¿Qué funcionó? ¿Qué fue confuso? ¿Qué documentación faltaba?

**Errores comunes en esta fase:**

* **“Es más rápido hacerlo a mano”** — Aparece cuando el feature es simple y el developer es experimentado. Es cierto para features triviales. La respuesta: “prueba con un feature de 3+ archivos y compara”.
* **“La AI produce código malo”** — Casi siempre es un problema de contexto, no de la AI. Verificar que el AGENTS.md tiene las reglas correctas y que los skills están configurados.
* **“No confío en lo que genera”** — Legítimo. La respuesta no es “confía” sino “verifica sistemáticamente” — para eso existen los checklists post-implementación.

### Fase 4: Adopción completa (equipo entero, ongoing)

La metodología se convierte en el flujo estándar del equipo. Los protocolos están activos. La documentación se mantiene al día.

**Señales de que la adopción funciona:**

* El equipo usa el SESSION\_LOG sin que nadie lo recuerde
* Los anti-patrones nuevos se agregan al AGENTS.md naturalmente
* Las sesiones de implementación producen resultados consistentes independientemente de quién las ejecute
* El tiempo de onboarding de nuevos miembros baja con cada incorporación

**Señales de que la adopción no funciona:**

* Solo 1-2 personas usan la metodología y el resto “vibecodeá”
* La documentación no se actualiza después de las sesiones
* Cada developer tiene su propio flujo en vez de seguir los protocolos
* Los mismos errores se repiten porque nadie los documenta

**Lo que no depende de la memoria de nadie.** Con más de una persona, la documentación se degrada en los huecos entre una y otra, y ahí conviene que la verificación sea del repositorio y no de cada quien. `init` deja un hook de git `pre-push` que sólo corta ante un P0 y un flujo de integración continua que corre `audit --estricto` en cada pull request. Cómo montarlos y cómo leer lo que reportan está en [Auditar en local y en CI](/docs/guias/auditar-en-local-y-en-ci/). Si el equipo adopta la metodología sobre un proyecto que ya tiene código y documentación, empieza por [Adoptar en un proyecto existente](/docs/empezar/proyecto-existente/).

***

## El caso del tech lead de las 11 horas

Este caso es un anti-patrón de onboarding. El tech lead recibió acceso a la herramienta pero no al contexto del proyecto — no había AGENTS.md, no había documentación de arquitectura, no había guía de diseño.

El resultado: 11 horas construyendo un prompt que un AGENTS.md de 150 líneas hubiera resuelto en segundos.

La lección: **el onboarding de una persona a AI coding agents en un proyecto existente empieza por la documentación del proyecto, no por la herramienta.** Darle a alguien Claude Code sin darle el AGENTS.md es como darle un martillo sin decirle dónde están los clavos.

***

## Métricas de adopción

Para saber si la metodología está funcionando en el equipo, medir:

| Métrica              | Cómo medir                                                      | Meta                                  |
| -------------------- | --------------------------------------------------------------- | ------------------------------------- |
| Tiempo por feature   | Comparar sprints pre y post adopción                            | Reducción de 30%+                     |
| Restarts             | ¿Cuántas veces se reinicia una implementación?                  | Tender a 0                            |
| Consistencia de UX   | ¿Los features nuevos se ven y se comportan como los existentes? | Sin correcciones de diseño post-merge |
| Calidad de docs      | ¿El AGENTS.md y la guía de diseño están al día?                 | Actualizados en cada sprint           |
| Tiempo de onboarding | ¿Cuánto tarda un nuevo miembro en ser productivo con AI?        | Menos de 1 día                        |

***

# Capítulo 12: Costos y herramientas — la decisión pragmática

> *La metodología es agnóstica. La factura no. Elegir la herramienta correcta para tu equipo es una decisión de costo, no solo de features.*

***

## El paisaje en 2026

El mercado de AI coding agents evoluciona mensualmente. Cualquier tabla de precios que escriba aquí puede quedar obsoleta en semanas. Lo que no cambia son los principios para elegir.

Dicho esto, así está el panorama a marzo de 2026:

### Claude Code (Anthropic)

| Plan                | Precio        | Qué incluye                               |
| ------------------- | ------------- | ----------------------------------------- |
| Pro                 | $20/mes       | Acceso a Claude Code, límites moderados   |
| Max 5x              | $100/mes      | 5x uso de Pro, acceso a Opus              |
| Max 20x             | $200/mes      | 20x uso de Pro, para uso intensivo diario |
| Team (Standard)     | $25/seat/mes  | Colaboración, sin Claude Code             |
| Team (Premium)      | $150/seat/mes | Todo + Claude Code                        |
| API (pay-as-you-go) | Variable      | Sonnet 4.6: $3/$15 por MTok in/out        |

**Fortalezas:** El agente más capaz para razonamiento complejo. Terminal-nativo, se integra con cualquier workflow. Context window de 1M tokens con Opus 4.6. Sistema de skills, hooks, y subagentes maduro.

**Debilidades:** Costo alto para equipos grandes. Los planes por suscripción tienen rate limits que pueden interrumpir sesiones largas.

**Costo real por developer:** Un developer que usa Claude Code como herramienta principal de tiempo completo necesita típicamente el plan Max 5x ($100/mes) o Max 20x ($200/mes). El plan Pro ($20/mes) funciona para uso ligero o sesiones cortas.

### Google Antigravity

| Plan            | Precio           | Qué incluye                        |
| --------------- | ---------------- | ---------------------------------- |
| Individual      | Gratis (preview) | Acceso a Gemini 3, Claude, GPT-OSS |
| Pro (Google AI) | $20/mes          | Límites más altos + créditos       |
| Ultra           | \~$250/mes       | Límites altos, uso intensivo       |

**Fortalezas:** Acceso gratuito a múltiples modelos (incluyendo Claude Opus). IDE visual (fork de VS Code) con Agent Manager para orquestar agentes en paralelo. Soporte para AGENTS.md. Arquitectura multi-agente nativa.

**Debilidades:** Situación de precios inestable — en marzo 2026 hay quejas significativas de la comunidad por recortes de quotas no anunciados y lockouts de cuentas de hasta 7 días. Los límites del plan gratuito son impredecibles y han cambiado varias veces. La documentación de quotas usa términos vagos como “generoso” sin definir números concretos.

**Precaución:** Antigravity es prometedor como concepto pero su modelo de precios no está estabilizado. Evaluar con cautela antes de depender de él para trabajo de producción.

### Otras herramientas relevantes

| Herramienta    | Precio aprox         | Modelo             | Notas                                          |
| -------------- | -------------------- | ------------------ | ---------------------------------------------- |
| Cursor         | $20/mes (Pro)        | IDE (VS Code fork) | Popular, buen balance precio/features          |
| Windsurf       | $15/mes              | IDE                | Alternativa económica a Cursor                 |
| GitHub Copilot | $10/mes (individual) | Extensión de IDE   | 15M+ developers, autocompletado más que agente |
| Aider          | Gratis (open source) | Terminal           | Git-nativo, paga solo API del modelo           |
| OpenCode       | Gratis (open source) | Terminal           | 95K+ GitHub stars, 75+ proveedores LLM         |
| Cline          | Gratis (open source) | Extensión VS Code  | 5M installs, BYOM (trae tu modelo)             |

### Herramientas BYOM (Bring Your Own Model)

Aider, OpenCode, y Cline son gratuitas como herramientas, pero el costo real es el uso de API del modelo que elijas. Un developer usando Claude Sonnet 4.6 via API a través de estas herramientas gasta aproximadamente $3-8/hora en uso intensivo. Con Opus, 5-10x más.

***

## Cómo elegir: el framework de decisión

La decisión depende de tres variables: tamaño del equipo, presupuesto mensual, y nivel de experiencia.

### Para 1 persona (solopreneur, freelancer)

**Si el presupuesto no es problema:** Claude Code Max 5x ($100/mes). Es la herramienta más capaz y la metodología se desarrolló principalmente con ella.

**Si el presupuesto importa:** Claude Code Pro ($20/mes) para sesiones focalizadas + Antigravity gratis para exploración. O Aider/OpenCode (gratis) + API de Sonnet ($3/MTok), controlando el gasto por sesión.

**Opción experimental:** Antigravity gratis da acceso a Opus, pero la estabilidad de las quotas es incierta.

### Para equipo de 2-5 personas

**Costo con Claude Code Team Premium:** $150/seat × 5 = $750/mes. Significativo pero justificable si la productividad mejora 30%+.

**Alternativa mixta:** 1-2 seats Premium ($150) para los developers principales + Pro ($20) para PO/designers que usan la herramienta ocasionalmente. Total: $340-360/mes.

**Alternativa económica:** Antigravity gratis o BYOM tools para todo el equipo, con un presupuesto compartido de API. Total: variable, pero típicamente $200-400/mes para 5 personas con uso moderado.

### Para equipo de 5+ personas

A esta escala, el costo por seat se vuelve el factor dominante. Evaluar:

* **Claude Code Enterprise:** Precios custom, incluye compliance, SSO, auditing
* **Antigravity Team:** Precios por definir, potencialmente más económico
* **BYOM + API compartida:** Máximo control de costos, mínimo lock-in

***

## El principio que no cambia

Independientemente de la herramienta que elijas:

**La metodología es agnóstica.** El AGENTS.md funciona en Claude Code, Antigravity, Cursor, Aider, o lo que venga después. Los protocolos de UX, cambios, cierre, y features no dependen de ninguna herramienta. La guía de diseño es un archivo markdown que cualquier agente puede leer.

**Invierte en contexto, no solo en herramientas.** Un AGENTS.md bien escrito con un plan Pro de $20/mes produce mejores resultados que un plan Max de $200/mes sin documentación. La herramienta más cara del mundo no compensa la falta de contexto — el caso del tech lead (11 horas) lo demuestra.

**Empieza barato, escala con evidencia.** Pro ($20/mes) o incluso herramientas gratuitas son suficientes para validar la metodología. Solo escala el gasto cuando tienes datos que justifiquen la inversión: “con Max 5x implementamos features 2x más rápido que con Pro, el ROI es positivo.”

***

## Herramientas complementarias (todas gratuitas)

Falcux AI-First no solo usa AI coding agents. Estas herramientas complementarias son parte del ecosistema y todas tienen tier gratuito:

| Herramienta   | Función                                             | Costo                                         |
| ------------- | --------------------------------------------------- | --------------------------------------------- |
| Notion        | Gestión de producto (PRDs, backlog, sprints)        | Gratis para uso individual                    |
| NotebookLM    | Consulta en lenguaje natural sobre la documentación | Gratis                                        |
| Docusaurus    | Sitio web de documentación de la metodología        | Gratis (open source, deploy en Vercel gratis) |
| GitHub/GitLab | Control de versiones + CI/CD                        | Gratis para repos privados                    |

**El costo total de Falcux AI-First** (excluyendo el AI coding agent) es $0. Toda la infraestructura de documentación, gestión, y publicación es gratuita.

***

## Resumen: la tabla de decisión

| Tu situación                         | Herramienta recomendada                 | Costo/mes           |
| ------------------------------------ | --------------------------------------- | ------------------- |
| Empezando solo, presupuesto limitado | Claude Pro o BYOM + API                 | $20-50              |
| Solo, uso intensivo diario           | Claude Max 5x                           | $100                |
| Equipo 2-3, evaluando                | Mix de Pro + 1 Premium                  | $190-340            |
| Equipo 3-5, adopción seria           | Claude Team Premium o Enterprise        | $450-750            |
| Equipo 5+, escala                    | Enterprise o BYOM con API compartida    | Custom              |
| Experimentando sin costo             | Antigravity gratis (con cautela) + BYOM | $0 (+ API variable) |

Recuerda: la herramienta es el 20% de la ecuación. El contexto — AGENTS.md, protocolos, guía de diseño — es el 80%.

# Casos de estudio

> 3 casos reales: los 5 restarts, AutenTIC Sign (2h vs 1 sprint), y POCs del PO

> Tres casos reales que fundamentan Falcux AI-First. Cada uno ilustra un punto diferente de la metodología.

***

## Caso 1: Los 5 restarts — el origen de la cadena de artefactos

### Contexto

Un product designer con experiencia en UX decide explorar AI coding agents para construir MVPs. Su objetivo: validar si una sola persona puede construir un producto funcional usando AI como builder principal.

**Stack:** Next.js + NestJS + Prisma + Supabase + Shadcn UI. **Herramienta:** Claude Code (terminal). **Experiencia previa con AI coding agents:** Ninguna.

### Qué hizo

El designer inicializó un proyecto con su stack, escribió una descripción breve de la idea, y le pidió al agente que implementara.

El flujo era directo: describir → generar → probar → ajustar.

No había PRD. No había documento de arquitectura. No había archivo de contexto para la AI. No había guía de diseño. Solo una idea y un prompt.

### Qué pasó

**Primer intento:** La AI generó una interfaz que se veía completa. Menús, botones, formularios, navegación. Al probar, la mayoría era decorativo — botones sin funcionalidad, formularios que no enviaban, menús que no navegaban. Al pedir que implementara las features reales, la AI cambiaba el diseño con cada iteración.

**Segundo intento:** Restart completo. Esta vez, el designer dio más contexto en el prompt inicial. Funcionó mejor al principio, pero al tercera sesión la AI había perdido contexto de lo implementado anteriormente. Features nuevas aparecían en la UI sin funcionalidad, mientras features anteriores dejaban de funcionar.

**Tercer y cuarto intento:** Más restarts. Cada vez el designer intentaba dar más contexto, pero siempre llegaba un punto donde la AI no podía mantener la coherencia entre lo existente y lo nuevo.

**Quinto intento:** El designer cambió de enfoque. En vez de darle contexto en el prompt, creó documentos previos: un PRD describiendo qué se construía, un archivo de contexto con las reglas del proyecto, y una estructura de carpetas clara. La AI recibió estos documentos al inicio de cada sesión.

El quinto intento funcionó. No porque la AI fuera diferente, sino porque tenía contexto persistente que no dependía de la conversación.

### Datos

| Métrica                | Valor                                                |
| ---------------------- | ---------------------------------------------------- |
| Intentos (restarts)    | 5                                                    |
| Tiempo total invertido | \~2 sprints                                          |
| Tiempo productivo real | Último intento (\~20% del total)                     |
| Causa raíz             | Falta de artefactos de contexto persistente          |
| Solución               | Cadena de artefactos: PRD → Arquitectura → AGENTS.md |

### Lección para la metodología

**Capítulo que ilustra:** Capítulo 3 — La cadena de artefactos.

La AI no “olvida” — simplemente no tiene acceso a lo que no se le dio. Cada sesión empieza sin memoria de la anterior. Sin documentos persistentes, cada sesión es un restart parcial.

La cadena de artefactos no es burocracia — es memoria externa para un agente que no tiene memoria propia.

**Anti-patrón documentado:** Implementar directamente desde una descripción verbal sin documentación previa.

**Principio extraído:** “El costo de documentar siempre es menor que el costo de reiniciar.”

***

## Caso 2: AutenTIC Sign — 2 horas vs. 1 sprint

### Contexto

Un equipo de tres personas necesita implementar una mejora en su producto de firma electrónica. El cliente solicita replicar una experiencia de usuario que ya existe en otro módulo de la aplicación.

**Equipo:** Product designer (líder), product owner, tech lead. **Stack:** Angular + PrimeNG (producto existente). **Herramienta:** Claude Code. **Estado del proyecto:** Producto en producción con documentación completa — PRD, specs por módulo, guía de diseño, archivo de contexto para la AI.

### Qué hicieron

El equipo configuró la sesión de Claude Code con el contexto del proyecto: AGENTS.md con las reglas del producto, referencia a las specs del módulo que se iba a modificar, y la guía de diseño con los patrones visuales existentes.

El requerimiento era claro: replicar una experiencia que ya existía en otro módulo. La spec estaba escrita. Los patrones de diseño estaban documentados. La arquitectura era conocida.

Los tres trabajaron juntos en la sesión: el PO validaba que el comportamiento fuera correcto, el tech lead revisaba la calidad técnica, y el designer verificaba la consistencia visual.

### Qué pasó

En 2 horas, la mejora estaba implementada, probada, y lista para producción. La AI generó código que seguía los patrones existentes porque los tenía documentados en el AGENTS.md y la guía de diseño. No hubo inconsistencias de UI porque los patrones estaban explícitos. No hubo sorpresas de arquitectura porque la estructura estaba documentada.

El equipo estimó que sin AI, la misma mejora hubiera ocupado un sprint completo: estimación, diseño detallado, desarrollo, testing, iteración con el cliente.

### Datos

| Métrica               | Con AI + docs  | Sin AI (estimado)      |
| --------------------- | -------------- | ---------------------- |
| Tiempo total          | 2 horas        | 1 sprint (\~2 semanas) |
| Personas involucradas | 3 (simultáneo) | 2-3 (secuencial)       |
| Restarts              | 0              | N/A                    |
| Inconsistencias de UX | 0              | N/A                    |
| Documentación previa  | Completa       | N/A                    |

### Por qué funcionó

Tres factores convergieron:

1. **Documentación completa previa.** El proyecto tenía PRD, specs, guía de diseño, y AGENTS.md. La AI no tuvo que adivinar nada.

2. **Requerimiento claro y acotado.** “Replicar esta experiencia en este otro módulo” no deja espacio para ambigüedad. La AI sabía exactamente qué producir.

3. **Tres roles validando en tiempo real.** Producto, técnica, y diseño revisaban simultáneamente. Los errores se atrapaban en segundos, no en días de review.

### Lección para la metodología

**Capítulos que ilustra:** Capítulo 1 (ROI medible), Capítulo 4 (AGENTS.md como cerebro), Capítulo 10 (protocolo de features).

El caso demuestra que la inversión en documentación previa tiene un retorno medible: la misma tarea que toma un sprint sin contexto documentado toma 2 horas con contexto completo.

**Principio extraído:** “La AI implementa a la velocidad del contexto que recibe.”

***

## Caso 3: El PO y los POCs de integración — AI como acelerador de validación

### Contexto

El product owner de un equipo de desarrollos a la medida necesita validar la viabilidad técnica de integrar APIs externas para un cliente. Son pruebas de concepto (POCs) — no producción, sino validación rápida de que la integración funciona antes de comprometer un sprint de desarrollo.

**Rol:** Product owner (no developer). **Herramienta:** AI coding agent. **Objetivo:** Demostrar que la integración es viable en horas, no en días.

### Qué hizo

El PO, sin ser developer, usó un AI coding agent para implementar POCs de integración de APIs. Su flujo:

1. Documentó qué API quería integrar y qué resultado esperaba
2. Le pidió al agente que implementara la integración
3. Probó el resultado
4. Iteró hasta tener un POC funcional

### Qué pasó

El PO logró implementar POCs funcionales que demostraban la viabilidad de las integraciones. Esto permitió al equipo tomar decisiones de producto informadas sin esperar a que un developer construyera la prueba.

El tiempo de validación se comprimió de días (esperar a que un developer tenga disponibilidad) a horas (el PO lo hace directamente).

### Datos

| Métrica              | Con AI                    | Sin AI                                    |
| -------------------- | ------------------------- | ----------------------------------------- |
| Quién implementa     | PO directamente           | Developer (cuando tiene disponibilidad)   |
| Tiempo de validación | Horas                     | Días (depende del backlog del dev)        |
| Costo de oportunidad | Bajo (PO tiene autonomía) | Alto (developer detenido de otras tareas) |
| Calidad del POC      | Suficiente para validar   | Más robusta pero innecesaria para un POC  |

### Lección para la metodología

**Capítulo que ilustra:** Capítulo 2 (AI-First no es solo para developers), Capítulo 11 (adopción por roles).

Este caso demuestra que AI-First no es exclusivo de developers. Un PO con specs claras puede producir POCs funcionales que aceleran decisiones de producto. El rol del PO no cambia (sigue definiendo qué se construye), pero gana una herramienta para validar viabilidad sin depender del backlog de desarrollo.

**Principio extraído:** “AI-First reduce la barrera de quién puede construir software, pero no la barrera de quién debe decidir qué construir.”

**Precaución:** Los POCs del PO son para validación, no para producción. Cuando la decisión es “sí, esto es viable”, la implementación de producción la hace el equipo de desarrollo con la cadena de artefactos completa.

***

## Resumen comparativo

| Caso          | Sin metodología       | Con metodología        | Factor clave                  |
| ------------- | --------------------- | ---------------------- | ----------------------------- |
| 5 restarts    | 2 sprints perdidos    | Último intento exitoso | Cadena de artefactos          |
| AutenTIC Sign | 1 sprint (estimado)   | 2 horas                | Documentación completa previa |
| POCs del PO   | Días (esperar al dev) | Horas (PO autónomo)    | AI accesible a roles no-dev   |

**El patrón común:** En los tres casos, la diferencia no fue la herramienta ni el modelo de AI. Fue la calidad del contexto que recibió.

***

## Cómo usar estos casos

### Para justificar la inversión ante stakeholders

El caso de AutenTIC Sign tiene los números más claros: 2h vs 1 sprint. Eso es \~97% de reducción de tiempo en una tarea específica y acotada. No todos los features van a tener esa mejora, pero demuestra el techo.

### Para convencer a un equipo escéptico

El caso de los 5 restarts es el más identificable. Casi todo developer que ha usado AI coding agents tiene una versión de esta historia. “Yo también reinicié 3 veces” genera empatía inmediata y abre la conversación sobre qué hacer diferente.

### Para expandir quién usa AI

El caso del PO demuestra que no es una herramienta solo para developers. Útil para convencer a POs y designers de que la metodología también les da superpoderes.

# Glosario

> 30+ términos clave de Falcux AI-First con definiciones y referencias

> Términos clave de Falcux AI-First. Cada entrada incluye una definición concisa y el capítulo donde se explica en detalle.

***

## A

**ADR.md (registro de decisiones)** Registro de las decisiones difíciles de revertir: qué se eligió, qué se descartó y por qué. Una fila por decisión, que no se edita al cambiar de opinión: se agrega otra que la supera. `ai-first init` lo crea vacío en `docs/ADR.md`, y la verificación «Decisión sin fila en ADR» avisa cuando una decisión llega al código sin llegar al registro. → Cap 5

**AGENTS.md** Archivo markdown en la raíz del proyecto que contiene el contexto completo para AI coding agents: descripción del proyecto, stack, comandos, reglas críticas, documentación referenciada, y anti-patrones. Es la fuente de verdad cross-tool — funciona con Claude Code, Antigravity, Cursor, y cualquier herramienta que lea archivos de contexto. Máximo recomendado: \~150 líneas. → Cap 4

**AI-First (enfoque)** Enfoque de desarrollo donde la AI es el builder principal del código (80-90%) y el humano actúa como arquitecto, director, curador, y validador. Se diferencia del vibe coding (sin estructura) y del desarrollo tradicional (el humano escribe todo). → Cap 2

**AI-FIRST.md** Archivo en la raíz del proyecto que declara qué lo gobierna —Zonas Prohibidas, superficies de decisión, alcance del cambio en curso y artefactos— en un frontmatter que `ai-first audit` verifica. Lo escribe `ai-first init`. A diferencia del AGENTS.md, no da órdenes al agente: es para las herramientas. → Cap 5

**Anti-patrón** Error recurrente descubierto durante la implementación con AI. Se documenta en la sección “What NOT to Do” del AGENTS.md para que la AI no lo repita. Cada anti-patrón existe porque la AI ya cometió ese error al menos una vez. → Cap 4

**Artefacto** Documento producido en la cadena de artefactos: PRD, arquitectura, schema, AGENTS.md, GUIA\_DISEÑO.md, o documentación post-implementación. Cada artefacto alimenta al siguiente eslabón de la cadena. → Cap 3

## B

**BYOM (Bring Your Own Model)** Categoría de herramientas de AI coding (Aider, OpenCode, Cline) que son gratuitas pero requieren que el usuario pague por el uso de API del modelo LLM que elija. El costo varía según el modelo y la intensidad de uso. → Cap 12

## C

**Cadena de artefactos** El flujo completo desde la idea hasta el código: Idea → PRD → Arquitectura → Schema → Contexto AI → Implementación → Documentación post-implementación. Cada eslabón produce un artefacto que el siguiente consume. Romper la cadena significa que la AI trabaja con información incompleta. → Cap 3

**Capa 1 (principios agnósticos)** La capa de documentación de UX que contiene principios universales — navegación por capas, patrones de interacción, estados de UI. No cambia entre proyectos ni stacks. Vive en la skill `protocolo-ux`. → Cap 6, Cap 8

**Capa 2 (specs de proyecto)** La capa de documentación de UX que contiene especificaciones técnicas concretas — tokens de color, tipografía, componentes específicos, gotchas del framework. Es única por proyecto. Vive en GUIA\_DISEÑO.md. → Cap 6

**CHANGE\_LOG.md** Registro permanente de todos los cambios implementados en un proyecto. Cada entrada incluye fecha, tipo, archivos afectados, y lecciones aprendidas. No se borra. Los documentos temporales en `pending/` se eliminan después de migrar su resumen aquí. → Cap 9

**CHG-XXX** Documento individual de cambio con formato numerado (CHG-001, CHG-002). Documenta qué cambia, por qué, análisis de impacto, plan de implementación, y verificación. Vive en `docs/changes/pending/` mientras está activo y se elimina al cerrarse. → Cap 9

**CLAUDE.md** Archivo específico de Claude Code que se lee al inicio de cada sesión. En Falcux AI-First, contiene únicamente la referencia `@AGENTS.md`, actuando como puntero liviano. La fuente de verdad es el AGENTS.md. → Cap 4

**Compactación (/compact)** Técnica de gestión de contexto que resume la conversación previa manteniendo lo esencial. Se aplica cuando la sesión alcanza \~50% del contexto disponible. Se puede especificar qué preservar. → Cap 7

**Contexto como producto** Concepto central de Falcux AI-First: en desarrollo AI-First, el contexto (documentación, reglas, patrones) es el producto principal — el código es el subproducto. La AI genera código a velocidades que ningún humano iguala, pero la calidad depende enteramente del contexto que recibe. → Cap 1

**Curador (rol)** Uno de los 4 roles del developer AI-First. Mantiene el contexto del proyecto vivo y actualizado: AGENTS.md, guía de diseño, anti-patrones, gotchas. Sin el curador, cada sesión empieza un poco más perdida que la anterior. → Cap 2

## D

**DEV AI First** El enfoque de desarrollo dentro de Falcux AI-First. Significa diseñar todo el flujo de desarrollo asumiendo que la AI es el builder principal. La documentación se escribe para que la AI la entienda, la arquitectura se define antes del código, y las convenciones se codifican explícitamente. → Cap 2

**Director (rol)** Uno de los 4 roles del developer AI-First. Define qué se construye en cada sesión, en qué orden, con qué restricciones. Prepara los prompts de implementación y detiene la sesión cuando la AI va por mal camino. → Cap 2

**Documentación evolutiva** Patrón donde la guía de diseño crece orgánicamente con el proyecto. No se escribe completa al inicio — se empieza con las secciones obligatorias y se agregan componentes, patrones, y gotchas conforme se implementa. Demostrado por la GUIA\_DISEÑO.md de Virso (1134 líneas). → Cap 6

## E

**Entropía documental** La distancia entre lo que el proyecto documenta y lo que el proyecto es. `ai-first audit` la mide con cinco verificaciones y la resume en un puntaje de 0 a 100 donde más alto es peor: `min(100, 40·P0 + 20·P1 + 8·P2)`. → Cap 5

## F

**Falcux AI-First** Metodología para equipos mixtos (diseño + desarrollo) que construyen productos con AI coding agents. Define una cadena de artefactos, protocolos operativos, templates reutilizables y un paquete que los instala. Agnóstica de herramienta. Hasta el 2026-09-21 se llamó «Blueprint AI-First»; el nombre vigente es éste, también en el paquete `@falcux/ai-first`. → Toda la metodología

**Flujo corto** Proceso simplificado de gestión de cambios para correcciones menores que tocan 1-2 archivos y no modifican schema de BD. Documentar → Implementar → Verificar → Actualizar docs. → Cap 9

**Flujo completo** Proceso completo de gestión de cambios para cambios de medio-alto riesgo. Documentar → Analizar impacto → Planificar → Implementar por pasos → Verificar → Actualizar docs → Cerrar. → Cap 9

## G

**Gotcha** Bug, comportamiento inesperado, o incompatibilidad descubiertos durante la implementación real con AI. Se documentan en la sección de gotchas de la GUIA\_DISEÑO.md o en “What NOT to Do” del AGENTS.md. Tienen alto valor porque previenen que la AI (o el equipo) repita el mismo error. → Cap 6, Cap 7

**GUIA\_DISEÑO.md** Documento de especificaciones visuales y técnicas de un proyecto. Incluye paleta de colores, tipografía, espaciado, componentes, patrones de página, gotchas del framework CSS, y checklist. Es la Capa 2 (específica por proyecto) que complementa a la skill `protocolo-ux` (Capa 1, agnóstico). → Cap 6

## H

**Hook** Script que se ejecuta automáticamente cuando ocurre un evento específico en el AI coding agent. A diferencia del AGENTS.md (advisory), los hooks son deterministas — se ejecutan siempre. Tipos: PreToolUse, PostToolUse, Stop. → Cap 7

## N

**Navegación por capas** Patrón de UX donde la aplicación tiene tres layouts contextuales. Capa 1 (Browse): layout con sidenav para explorar. Capa 2 (Create): layout limpio sin sidenav para flujos de creación. Capa 3 (Detail): layout limpio sin sidenav para ver detalle. → Cap 8

## P

**Plan mode** Técnica donde la AI presenta un plan de implementación antes de ejecutar. El humano revisa, edita, y aprueba antes de que se escriba código. Útil para features complejos. En Claude Code: Shift+Tab ×2. → Cap 7

**PRD (Product Requirements Document)** Documento que describe el producto desde la perspectiva del usuario. Qué hace, para quién, qué problema resuelve, y cuáles son los límites. Es el eslabón más crítico de la cadena — el único que no debería saltarse nunca. → Cap 3

**Punto de control** Los dos sitios donde `ai-first init` deja corriendo el detector: el hook de git `.githooks/pre-push`, que sólo interrumpe el push ante un P0, y el flujo `.github/workflows/ai-first.yml`, que corre con `--estricto` en cada pull request. Es un hook de git, no del agente. → Cap 5

**Protocolo de cierre de sesión** Proceso de 3 fases al terminar una sesión de implementación: la AI documenta (SESSION\_LOG, docs actualizados, anti-patrones) → el humano verifica (5 puntos de checklist) → el humano cierra (commit, sync Notion, cerrar CHG-XXX). → Cap 10

**Protocolo de desarrollo de features** Proceso de 6 pasos antes de implementar un feature: asegurar spec → leer diseño → validar UX → verificar dependencias → preparar contexto AI → definir secuencia de implementación. → Cap 11

**Protocolo de gestión de cambios** Proceso para modificar requerimientos post-implementación sin romper lo existente. Incluye clasificación de cambios, documento CHG-XXX, análisis de impacto, implementación por pasos, y patrones anti-regresión. → Cap 9

**Protocolo de consistencia UX** Documento con los patrones de experiencia de usuario que toda implementación debe respetar. Navegación por capas, separación negocio vs admin, interacciones en tablas, formularios, modales, y estados de UI. → Cap 8

## R

**Restart** Momento donde un proyecto se vuelve tan inconsistente que la única opción es empezar de cero. Causado típicamente por falta de contexto persistente. Falcux AI-First existe para que los restarts no sean necesarios. → Cap 1, Cap 3

## S

**Sesión limpia** Técnica de gestión de contexto donde cada tarea significativa se ejecuta en una sesión nueva con contexto fresco. La sesión anterior produce un artefacto (spec, SESSION\_LOG) que la nueva sesión consume. Previene degradación de contexto. → Cap 7

**SESSION\_LOG.md** Registro cronológico de sesiones de implementación. Cada entrada documenta qué se implementó, qué archivos se modificaron, anti-patrones descubiertos, y pendientes para la siguiente sesión. Sesión más reciente arriba. → Cap 10

**Skill** Archivo markdown con conocimiento especializado que la AI carga on-demand, solo cuando es relevante para la tarea actual. Vive en `.agents/skills/{nombre}/SKILL.md`, donde la deja `ai-first init`; Claude Code la lee por el enlace `.claude/skills`. Permite mantener el AGENTS.md ligero sin perder conocimiento especializado. → Cap 7

**Spec mínima viable** El documento más corto que todavía le da a la AI suficiente contexto para implementar: qué hace el feature, criterios de aceptación, alcance (incluye/no incluye), y dependencias. Se usa cuando no hay PRD formal. → Cap 11

**Superficie de decisión** Archivo o patrón donde un cambio se presume decisión arquitectónica: el esquema, los puntos de entrada de los paquetes, las configuraciones. Se declara en `AI-FIRST.md`; si se toca y el ADR no gana una fila, `ai-first audit` emite un P1. → Cap 5

## V

**Validador (rol)** Uno de los 4 roles del developer AI-First. Revisa lo que la AI produce: verifica que cumple la spec, que los tests pasan, que el diseño es consistente, y que no se rompió nada existente. Ejecuta los checklists post-implementación. → Cap 2

**Vibe coding** Enfoque de desarrollo donde el humano describe una idea y la AI genera todo sin planificación previa. Funciona para prototipos desechables pero no para productos de producción. Se diferencia de AI-First por la ausencia de estructura y documentación. → Cap 2

## W

**“What NOT to Do” (sección)** Sección del AGENTS.md que lista anti-patrones como prohibiciones explícitas. Cada línea existe porque la AI ya cometió ese error. Es una de las secciones de mayor valor del AGENTS.md — la AI atiende prohibiciones explícitas mejor que sugerencias implícitas. → Cap 4

## Z

**Zona Prohibida** Ruta o patrón del repositorio que el agente no modifica sin aprobación explícita. El criterio es el costo de revertir un error ahí, no la importancia del archivo. No impide el cambio: lo hace visible, porque tocarla es un P0 en `ai-first audit`. Se declara en `AI-FIRST.md` y se enuncia como regla en el AGENTS.md. → Cap 5

# Consulta interactiva

> Explora la documentación de Falcux AI-First a través de preguntas con NotebookLM

## Pregúntale a la documentación

Nota

**NotebookLM** es una herramienta de Google que te permite hacer preguntas directamente sobre el contenido de Falcux AI-First y obtener respuestas contextualizadas con referencias.

En lugar de buscar entre capítulos, puedes hacer preguntas como:

* *“¿Qué debe contener un AGENTS.md?”*
* *“¿Cuál es la diferencia entre el protocolo de cambios y el de features?”*
* *“¿Cómo mido el ROI de documentar?”*
* *“¿Qué hago al cerrar una sesión con AI?”*

[Abrir consulta interactiva](https://notebooklm.google.com/notebook/9d5a4df3-4614-4eb6-beca-d936b632648b?authuser=1)Ir a NotebookLM con la documentación cargada

Consejo

Esta es la **capa de consulta interactiva** de Falcux AI-First. La documentación completa sigue disponible en la pestaña Metodología para lectura secuencial.

# Sobre este proyecto

> Quién construyó Falcux AI-First y de dónde viene esta metodología

## Autor

**Charlie Herrera** — Lead Product Designer especializado en UX, AI e Interaction Design. Diseña experiencias de usuario para productos web y soluciones agénticas, liderando la integración de inteligencia artificial como herramienta transversal en equipos de producto — desde el diseño de interfaces hasta la automatización de flujos de trabajo y la adopción de AI coding agents en procesos de desarrollo.

[falcux.com](https://falcux.com)

## Origen

Falcux AI-First nació de experiencia directa con proyectos reales donde se aplicaron estas prácticas. No es un framework teórico — cada protocolo, template y recomendación fue validado en contextos de producción antes de ser documentado aquí.

## Contribuir

Si aplicaste Falcux AI-First en tu equipo y quieres compartir tu experiencia o sugerir mejoras, puedes abrir un issue o pull request en el [repositorio del proyecto](https://github.com/HoruxDeEdfu/falcux-ai-first-package).

# Novedades

> Qué cambió en cada versión de @falcux/ai-first publicada en npm, de la más reciente a la primera.

Qué cambió en cada versión de `@falcux/ai-first` que se puede instalar desde npm, de la más reciente a la primera. Para saber cuál tienes:

```bash
npx @falcux/ai-first@latest --version
```

Nota

Dos versiones se etiquetaron y nunca llegaron a npm: la 0.5.0, cuyo contenido entero trae la 0.5.1, y la 0.1.4, que incluye la 0.2.0. Por eso no aparecen como versiones propias.

## 0.5.1 — 2026-09-22

Es la versión vigente. Trae el punto de control, que se etiquetó como 0.5.0 y no llegó a publicarse.

* **`init` escribe el punto de control.** `.githooks/pre-push` corre `audit` sobre lo que vas a publicar, sin `--estricto`: sólo un P0 interrumpe el push. `.github/workflows/ai-first.yml` lo corre con `--estricto` en cada pull request.
* **`core.hooksPath` sólo se fija si estaba vacío.** Uno de husky o lefthook no se pisa: se reporta como sugerido.
* **Tres opciones nuevas para `init`:** `--hook-local`, `--sin-hook` y `--sin-ci`.
* **El hook no frena un push cuando no encuentra `node`.** Un push desde un cliente gráfico o un IDE no hereda el PATH del shell. Ahora el hook busca `node` en las rutas habituales y en `nvm.sh`, y si no lo encuentra avisa en una línea y deja pasar.
* **El hook no habla con la red.** Usa el `ai-first` del proyecto o del PATH, o `npx --no-install`, que no descarga.

## 0.4.0 — 2026-09-21

* **La entrevista de `init`.** Pregunta fase, perfil del producto, comandos de verificación, secuencia de implementación, agentes en paralelo y manifiesto de versión, y escribe las respuestas en `AI-FIRST.md` y en cada skill instalada, entre marcas.
* **`protocolo-arranque`, la undécima skill.** Conduce la definición del proyecto hasta el PRD, la arquitectura y las specs.
* **El perfil del proyecto** en `AI-FIRST.md`: `producto` y `repositorio`. Decide qué skills se instalan. Es opcional.
* **`--entrevista` y `--sin-entrevista`.** Un proyecto ya documentado no se entrevista salvo que lo pidas, y sin terminal interactiva no se entrevista nunca.
* **`init` sobre una carpeta que no es repositorio la inicializa** y sigue, en vez de salir con código 2.

## 0.3.0 — 2026-09-21

* `ai-first --version` y `-v` imprimen la versión instalada. Antes, `--version` terminaba en error.

## 0.2.1 — 2026-09-21

* El README publicado lleva un badge de npm en vez de un número de versión escrito a mano.

## 0.2.0 — 2026-09-18

* **`init` completo.** Además de `AI-FIRST.md` y el registro de decisiones, instala las skills en `.agents/skills/`, crea el enlace `.claude/skills`, crea `docs/SESSION_LOG.md`, `docs/changes/CHANGE_LOG.md` y `docs/changes/pending/`, y mantiene un bloque delimitado en `AGENTS.md`.
* **`--skills <lista>|todas`** elige qué skills instalar; por defecto, las cinco sin interfaz.
* **`--enlazar`** instala enlaces simbólicos en vez de copias.
* **`init` salta lo que ya existe y sigue**, en vez de detenerse si `AI-FIRST.md` estaba presente.

## 0.1.3 — 2026-09-18

* El molde del documento de cambio pasó de `templates/` a la carpeta de `protocolo-cambios`. El paquete queda en ocho templates.

## 0.1.2 — 2026-09-18

* La instalación que enseñaba el README podía pisar la skill de un proyecto que ya tuviera una con el mismo nombre. Ahora se copia carpeta por carpeta, se salta entera la que ya existe y se dice cuál se saltó.

## 0.1.1 — 2026-09-18

* Se quitaron los cuatro templates de protocolo, que repetían lo que las skills ya dicen.

## 0.1.0 — 2026-09-18

Primera versión pública.

* `ai-first audit`: las cinco verificaciones, el puntaje de entropía y los códigos de salida, en modo árbol de trabajo y con `--base` para CI. Código puro: git, sistema de archivos y expresiones regulares.
* `ai-first init` mínimo: escanea el repo y escribe `AI-FIRST.md` y el registro de decisiones.
* Las skills y los templates de la metodología.

## Relacionado

[Solución de problemas](/docs/guias/solucion-de-problemas/)Los problemas conocidos y qué hacer con cada uno.

[ai-first init](/docs/referencia/init/)Todas las opciones de la versión vigente.

[ai-first audit](/docs/referencia/audit/)Modos, opciones y códigos de salida.