# 001 · Arnés para los agentes

Estado: en curso · Fecha: 24-oct-2026 · Aprobada por Carla el 24-oct-2026

## Problema

Las reglas del proyecto viven solo como instrucciones en `AGENTS.md`: no tocar
secretos, mantener la documentación al día y no subir nada que no compile.
Funcionan mientras el agente, o la persona, se acuerde de ellas:

- Nada impide que Claude lea un `.env` o `DOCUMENTACION-TRASPASO.md` si se le
  pide por error.
- Nada avisa si se cambia código y no se actualizan `CHANGELOG.md` ni
  `docs/status.md`.
- Nada comprueba los enlaces de la documentación. El 24-oct se comprobaron a
  mano, con un script temporal.
- No hay CI: se puede subir a `main` algo que no compila, y el primer aviso
  llegaría al desplegar.

## Comportamiento esperado

1. **Secretos**
   - Si Claude intenta leer o modificar un `.env` (`.env`, `.env.*`,
     `env.production`), Claude Code pide confirmación a Carla antes.
   - `DOCUMENTACION-TRASPASO.md` no se puede modificar nunca. Leerlo con la
     herramienta de lectura pide confirmación.
   - Lo mismo vale si lo intenta desde la terminal (`cat`, `grep`, `sed`…),
     con una diferencia: desde la terminal no se puede saber con seguridad si
     un comando va a modificar el traspaso o solo a leerlo, así que cualquier
     comando que lo nombre se bloquea.
   - `env.example` sigue libre: es la plantilla y no tiene secretos.
2. **Documentación**
   - `npm run check:docs`, desde la raíz del repo, comprueba los enlaces de
     toda la documentación (archivos y anclas a secciones).
   - Cuando Claude edita un `.md`, se ejecuta esa comprobación. Si hay algún
     enlace roto, Claude recibe el aviso en ese momento.
3. **Cierre de tarea**
   - Si Claude termina habiendo cambiado código (`backend/`, `frontend/`,
     `prisma/` o scripts) sin tocar `CHANGELOG.md` ni `docs/`, recibe una vez
     el recordatorio de revisar si hay que actualizarlos.
4. **CI**
   - En cada push y cada pull request a `main`, GitHub compila el backend (con
     el cliente de Prisma generado) y el frontend, y comprueba los enlaces de
     la documentación. Si algo falla, el commit sale en rojo en GitHub y quien
     hizo el push recibe un aviso.

## Criterios de aceptación

- [ ] Pedirle a Claude que lea `.env` muestra la confirmación; si se contesta
  «no», no lo lee.
- [ ] Pedirle `cat .env` por terminal da el mismo resultado.
- [ ] Pedirle que edite `DOCUMENTACION-TRASPASO.md` queda bloqueado, con un
  mensaje que explica por qué.
- [ ] Leer `env.example` y el resto del repo no muestra ningún aviso.
- [ ] `npm run check:docs` da hoy 0 enlaces rotos. Con un enlace roto puesto a
  propósito, lo detecta y termina con error.
- [ ] Si Claude edita un `.md` y deja un enlace roto, recibe el aviso.
- [ ] Si Claude cambia un archivo de `backend/` sin tocar la documentación y
  termina, recibe el recordatorio una sola vez.
- [ ] Un push a `main` lanza la CI, que pasa en verde. Con un error de
  TypeScript puesto a propósito en una rama de prueba, falla.

## Fuera de alcance

- Arreglar el lint del backend o meter el lint en la CI. El del backend no
  arranca y el del frontend arrastra unos 230 errores antiguos. Es una tarea
  aparte, ya apuntada en `docs/status.md`.
- Tests automáticos: no hay framework de tests.
- Protecciones equivalentes para Codex. Codex no lee la configuración de
  Claude Code, así que sigue con las reglas de `AGENTS.md`. La CI sí vale para
  los dos.
- Despliegue automático desde la CI.

## Decisiones (Carla, 24-oct-2026)

- **D1. Secretos:** pedir confirmación, que es la regla de siempre («avísame
  antes»). La excepción es modificar `DOCUMENTACION-TRASPASO.md`, que se
  bloquea siempre.
- **D2. Dónde vive la configuración de Claude:** en `EWC-BOT/.claude/`, fuera
  del repo, porque es donde se abre Claude Code. Solo funciona si Claude Code
  se abre en `EWC-BOT/`. Si alguna vez se abre directamente en el repo, habría
  que copiarla también allí.
- **D3. Recordatorio de cierre:** automático al terminar.
- **D4. CI:** se activa, aunque gasta minutos de GitHub Actions de la
  organización (el repo es privado): unos 3–5 minutos por push.
