Inicio rápido

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:

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

De cero a primer audit

1. Crea la carpeta del proyecto.

   mkdir mi-proyecto && cd mi-proyecto

2. Corre init.

   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.

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:

   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.

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:

   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.

5. Corre el primer audit.

   npx @falcux/ai-first@latest audit

   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.

   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 repoCada pieza, qué hace y qué skill o check la usa.

Arrancar un producto desde ceroDe la idea al PRD, la arquitectura y las specs.

ai-first auditModos, opciones y códigos de salida.