Zonas Prohibidas
Declaras qué partes del repositorio el agente no toca: migraciones, infraestructura, secretos, licencias. Deja de ser una advertencia enterrada en un prompt y pasa a ser una regla que se verifica sola.
P0 · se detiene
Tus agentes ya leen algo. Nadie eligió ese contexto.
Una metodología de gobierno del contexto para equipos que construyen con AI coding agents. Se adopta con un comando.
npx @falcux/ai-first@latest init
Por Charlie Herrera, Lead Product Designerfalcux.com
# AGENTS.md
Contexto durable del proyecto. Lo lee cualquier agente,
en cualquier herramienta, al abrir la sesión.
## Zonas Prohibidas
No se modifican sin aprobación explícita:
/migrations esquema vivo en producción
/infra terraform, DNS y secretos
.env* credenciales
## Verificación
pnpm build && npx @falcux/ai-first audit
✓ Entropía: 0 / 100
## Decisiones
Toda decisión arquitectónica va como fila nueva
en ADR.md, con contexto y consecuencias.
Los agentes de código no pierden capacidad entre una sesión y la siguiente. Pierden contexto. Y no lo pierden de golpe: se degrada de a poco, en silencio, mientras el proyecto avanza.
Al principio nadie lo nota. Una decisión que no quedó escrita. Un archivo que la spec menciona y que ya no existe. Una convención que la mitad del equipo sigue y la otra mitad no. Cada una es barata por separado. Juntas son la razón por la que el mismo agente que la semana pasada entendía el proyecto hoy propone reescribir algo que ya funcionaba.
Un framework de workflow asume que tu contexto está sano. Falcux AI-First resuelve el problema anterior. No reemplaza tu forma de construir: se instala encima.
Tabla ADR
Toda decisión arquitectónica deja una fila con su contexto y sus consecuencias. Seis meses después nadie tiene que reconstruir por qué se eligió esto en vez de aquello — y el agente tampoco.
P1 · requiere fila
Matriz de permisos
Quién puede modificar qué, explícito y versionado junto al código. Es el documento que permite que tres personas y dos agentes trabajen sobre el mismo proyecto sin pisarse.
la lee el equipo
Entropía documental
El nombre del problema: la distancia que se abre entre lo que el proyecto documenta y lo que el proyecto es. Se mide con verificaciones que corren en código puro —sin modelo y sin API key— y salen con exit code, así que sirven igual en un hook local y en integración continua.
la mide audit
La metodología, instalada en un comando.
init deja en tu repo lo que los protocolos dan por hecho, y audit comprueba que siga siendo verdad. Se instala sobre el flujo que tu equipo ya tiene, sin reemplazarlo.
Una vez, al entrar al proyecto
ai-first init
Escanea el repositorio y escribe el contexto base: Zonas Prohibidas sugeridas, superficies de decisión y los documentos que ya existen. Si el proyecto no está documentado y hay terminal, te entrevista para elegir las skills y adaptarlas a tu producto.
AI-FIRST.mddocs/ADR.mdskillshook + CI
El lazo, en cada push
ai-first audit
Corre el detector y devuelve los hallazgos con su severidad y un puntaje. Código puro: sin modelo, sin API key.
reporte + score
el punto de control
El hook de git corre audit antes de cada push y sólo lo detiene un P0. El flujo de CI lo corre en cada pull request en modo estricto: ahí cualquier hallazgo hace fallar la verificación.
.githooks/pre-pushai-first.yml
Mientras trabajas
12 skills
Le dicen al agente cómo arrancar un producto, desarrollar una feature, gestionar un cambio y cerrar la sesión. Cinco de ellas le mandan cada decisión a ADR.md como fila nueva.
Ver las skills8 templates
AGENTS.md, PRD, arquitectura, guía de diseño y los demás. Ya no se copian a mano: protocolo-arranque escribe cada documento a partir del suyo.
Ver los templatesUn escaneo, y el proyecto queda descrito.
init lee el repositorio y escribe lo que dedujo: Zonas Prohibidas sugeridas, superficies de decisión y los documentos que ya existen, en un AI-FIRST.md para que lo revises. Instala además las skills, abre el registro de decisiones y el log de sesión, y mantiene en tu AGENTS.md un bloque entre marcas sin tocar una línea fuera de ellas. Si el proyecto no está documentado y hay terminal, antes te entrevista; si no, lo dice y sigue. Nunca sobreescribe: lo que ya existe lo salta y te lo dice.
$ npx @falcux/ai-first init
ai-first init — falcux-ai-first-site
escrito AI-FIRST.md
saltado ADR.md (ya existe)
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
saltado .claude/skills (es un directorio real, no un enlace; se deja como está)
escrito .githooks/pre-push
escrito core.hooksPath
escrito .github/workflows/ai-first.yml
escrito AGENTS.md
Sin entrevista: no hay terminal interactiva.
2 Zonas Prohibidas sugeridas: LICENSE, .env*
2 superficies de decisión: **/*.config.*, wrangler.*
3 artefactos declarados
Revisa AI-FIRST.md —sobre todo las razones de cada zona— y AGENTS.md, y luego corre `ai-first audit`.
Salida real · 0.8.1 sobre una copia de este repositorio
El detector corre en código, no en un modelo.
Sin API key, sin tokens y sin esperar. Son verificaciones sobre git y el sistema de archivos que salen con exit code, así que el mismo comando sirve en un hook local y en integración continua.
5verificaciones
Cada una emite su propia severidad.
0tokens
Corre sin modelo y sin conexión.
3severidades
En el hook sólo P0 corta el push; P1 y P2 avisan y dejan seguir.
P0
Se tocó una Zona Prohibida.
Migraciones, infraestructura, secretos. Es la única severidad que no admite seguir de largo.
corta el flujo · exit 1
Avisan, y dejan seguir
P1
Se tomó una decisión arquitectónica sin fila nueva en ADR.
La decisión existe en el código y no existe en el registro.
P1
Se tocaron más archivos de los que la spec declaraba.
El alcance creció y nadie lo midió.
P2
Hay un artefacto huérfano: referenciado y inexistente.
Un documento apunta a un archivo que ya nadie mantiene.
P2
Cambió la librería de componentes sin actualizar su inventario.
La guía de diseño empezó a mentir.
Un reporte que se lee de arriba abajo.
Cada hallazgo trae su severidad, el archivo exacto y por qué importa. El puntaje de entropía resume qué tan lejos quedó la documentación del proyecto real, y el exit code decide si el flujo sigue.
$ npx @falcux/ai-first audit
ai-first audit — tu-proyecto
árbol de trabajo contra HEAD · 4 archivos tocados
✗ Zona Prohibida tocada
P0 Zona Prohibida «migrations/» tocada — sin aprobación explícita
migrations/0042_add_index.sql
✗ Decisión sin fila en ADR
P1 Hay señales de decisión arquitectónica y ADR.md no ganó ninguna fila
src/lib/queue.ts (superficie «src/lib/*.ts»)
– Alcance excedido — omitido: no hay «alcance.spec» declarado
✗ Artefacto huérfano
P2 PRD.md menciona specs/checkout.md, que no existe
✓ Inventario de componentes desactualizado
Entropía: 68 / 100 (1 P0 · 1 P1 · 1 P2)
exit 1
Ejemplo · formato del reporte de la 0.8.1, hallazgos inventados
Nada de esto es difícil de entender. Es difícil de sostener.
Un equipo adopta la mitad de los documentos, los mantiene dos meses, y después una semana apurada se los come. Por eso la metodología dedica más páginas a los protocolos —cuándo se actualiza qué, y quién responde— que a los formatos, y por eso el paquete los instala como skills y los vigila con un hook, en vez de confiar en que alguien se acuerde.
Cuatro partes, doce capítulos.
De la justificación económica a la adopción en equipo, y cada capítulo remite a la pieza del paquete que lo ejecuta. Se lee en orden, o entras directo por el protocolo que necesitas hoy.
I¿Por qué?El caso de negocio de documentar antes de codear, con casos reales.2 caps.IIFundamentosLa cadena de artefactos, AGENTS.md, el gobierno del contexto, la guía de diseño evolutiva, skills y contexto.5 caps.IIIProtocolosLos cuatro protocolos operativos: UX, cambios, cierre de sesión y features.4 caps.IVEscalarDe individual a equipo: onboarding, métricas, costos y herramientas.1 cap.
Qué existe hoy y qué todavía no.
La metodología está escrita y en uso; el paquete que la vuelve ejecutable está publicado en npm, con tres comandos que corren y tres mapeados sin escribir. Preferimos decir exactamente qué corre y qué no, antes de que lo descubras en la terminal.
Publicado — @falcux/ai-first 0.8.1
- Los doce capítulos de la metodología, completos y en español — se leen ahora. Y la documentación del paquete: inicio rápido, guías por caso de uso y la referencia de cada comando.
- init, que escanea el repositorio, te entrevista, instala las skills y escribe el contexto base, audit, con las cinco verificaciones y su exit code, y skill, que instala una skill suelta sin adoptar la metodología. init deja además el punto de control: un hook de git que lo corre antes de cada push y un flujo que lo corre en cada pull request.
- Doce skills que init instala por vos, y ocho templates que ya no se copian a mano: los escribe protocolo-arranque.
Mapeado, sin escribir
- sync, que repara lo que audit encontró; adr, que registra una decisión en el momento en que se toma, y handoff, que empaqueta el contexto para otro agente o persona. Si los invocas, el binario te dice que están mapeados y no existen, en vez de fingir que corren.
- Los adaptadores por herramienta: un hook del agente, sobre el evento de cierre, empezando por Claude Code. El que existe hoy es de git, no del agente.
Preguntas antes de empezar.
¿Esto reemplaza mi framework de trabajo?
No. Se instala encima del flujo que ya tienes. Falcux AI-First no decide cómo construyes un feature: decide qué no se toca, qué queda registrado y quién puede cambiar qué. Si ya usas un ciclo de comandos para construir, sigue igual.
¿Funciona con Cursor y Codex, o solo con Claude Code?
El contexto durable vive en AGENTS.md, que es un formato cross-tool: lo lee cualquier agente, y lo que init escribe —AI-FIRST.md, el registro de decisiones, el log de sesión y la carpeta de cambios— tampoco depende de ninguna herramienta. Las skills se instalan en .agents/skills/, el directorio del estándar Agent Skills que leen Codex, Cursor y OpenCode, con un enlace para Claude Code. Los adaptadores por herramienta siguen mapeados y sin escribir.
¿Y si mi proyecto ya tiene un AGENTS.md?
El comando init lo detecta y lo declara en AI-FIRST.md como artefacto existente. Dentro de él sólo mantiene un bloque entre dos marcas, ai-first:inicio y ai-first:fin, con las skills instaladas y cuándo se invoca cada una; fuera de las marcas no cambia una letra. El resto de lo que ya existe lo salta y te lo dice. La metodología entera parte de que la documentación existente es evidencia, no ruido.
¿El detector necesita una API key?
No. Corre sobre git y el sistema de archivos con expresiones regulares: sin modelo, sin conexión y sin costo por token. Sale con exit code, así que el mismo comando sirve en un hook local y en integración continua.
¿Qué cambia en mi repo al correr init?
Escribe AI-FIRST.md, el mapa que el detector verifica; abre docs/ADR.md, el log de sesión y la carpeta de cambios; instala las skills en .agents/skills/, con un enlace para Claude Code; deja un hook de git en .githooks/pre-push y un flujo de integración continua en .github/workflows/ai-first.yml, y mantiene su bloque en AGENTS.md. Nunca sobreescribe: lo que ya existe lo salta y te lo dice.
¿Sirve si trabajo solo?
Sirve, pero está pensado para equipos. El dolor que resuelve —que cada quien prompee distinto y que las decisiones se pierdan entre sesiones— se multiplica cuando hay más de una persona y más de un agente sobre el mismo repositorio.
Instálalo en el proyecto que más te duela hoy.
Un comando en la raíz del repo. No sobreescribe nada, y el primer audit te dice dónde está parado tu contexto.
npx @falcux/ai-first@latest init
$ npx @falcux/ai-first audit
ai-first audit — falcux-ai-first-site
árbol de trabajo contra HEAD · 0 archivos tocados
✓ Zona Prohibida tocada
✓ Decisión sin fila en ADR
– Alcance excedido — omitido: no hay «alcance.spec» declarado
✓ 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)
exit 0
Salida real · 0.8.1 sobre este repositorio