# 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 `` y ``. 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](https://ai-first.falcux.com/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](https://ai-first.falcux.com/docs/empezar/que-instala/)Cada pieza y quién la lee. [Adaptar las skills](https://ai-first.falcux.com/docs/guias/adaptar-las-skills/)La entrevista y lo que queda por hacer a mano. [Auditar en local y en CI](https://ai-first.falcux.com/docs/guias/auditar-en-local-y-en-ci/)El hook, el flujo de CI y cómo leer lo que reportan.