AI-DLC con Claude Code: un setup que funciona

Instalar AI-DLC en Claude Code lleva cuatro comandos. Correrlo bien lleva un repositorio que el agente pueda leer y la disciplina de detenerse en los gates.

AI-DLC 2 corre dentro de siete agentes de código, y Claude Code es el que su propia documentación usa en todos los ejemplos. El README recomienda Claude Opus 4.8 como modelo. También es uno de los dos agentes que uso todos los días, junto con pi, así que este es el setup que le daría a un equipo que quiere probar el método el lunes. Corrí cada paso de abajo en un proyecto de prueba limpio con la release 2.10.0 antes de escribirlo.

Si todavía no leíste qué es el método, empieza por qué es AI-DLC. Si conoces la versión 1 y quieres saber qué cambió, lee qué cambió en AI-DLC 2. Este artículo es la parte práctica: los comandos de la documentación oficial, en orden, más los hábitos que la documentación deja en tus manos.

Antes de instalar: dale al agente algo para leer

Una de las primeras cosas que hace AI-DLC en un proyecto existente es la ingeniería inversa. Un agente de desarrollo recorre el código y un agente de arquitectura escribe lo que encontró, y cada requisito, historia y Unit que viene después se construye sobre ese texto. Si el repositorio es difícil de leer, el texto es una adivinanza, y todo lo que sigue también.

Así que el primer paso no tiene nada que ver con AI-DLC. Pon un AGENTS.md o CLAUDE.md corto en la raíz del repo con cuatro cosas: el stack y las versiones, los patrones que usa el equipo, las librerías prohibidas y por qué, y un ejemplo de cada patrón (un endpoint típico, una función de dominio típica, una prueba típica). Escribí una guía entera sobre AGENTS.md como la memoria del agente. Cada hueco que llenas aquí es una pregunta que el agente no va a tener que hacerte en medio de una sesión de mob.

AI-DLC escribe su propio onboarding en .claude/CLAUDE.md cuando configuras el proyecto. Ese archivo le enseña el método a Claude Code. Tu archivo de la raíz le enseña tu sistema. Mantenlos separados.

La segunda cosa tampoco tiene que ver con la herramienta. Tu equipo ya debería estar escribiendo specs antes de dejar que un agente construya. Si no lo hace, AI-DLC te va a entregar una fila de documentos de requisitos para aprobar que nadie en el equipo sabe juzgar. Empieza por cómo escribir una spec y vuelve cuando eso se sienta normal. El razonamiento está en AI-DLC vs Spec-Driven Development.

Paso 1: instala el motor

El instalador agrega un comando nativo, aidlc, y el runtime de todos los agentes soportados. No necesita Bun ni Node.js.

Instalar AI-DLC

1. macOS, Linux o WSL

   $ curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh

2. Windows PowerShell

   PS> irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex

Si tu shell no encuentra aidlc después, sigue la instrucción de PATH que imprime el instalador, o abre una terminal nueva en Windows. Córrelo en una ventana normal de PowerShell, no en una abierta como administrador.

En Linux hay una trampa que el mensaje del instalador no explica. Los hooks que mueven AI-DLC los inicia Claude Code, no tu shell interactivo, así que no leen tu .bashrc. Si aidlc solo está en el PATH de tu terminal, aidlc doctor avisa que es “interactive-only”. Pon ~/.local/bin en el PATH que hereda tu sesión (un archivo en ~/.config/environment.d/ sirve), o deja que aidlc config runtime se encargue.

Paso 2: configura el proyecto

Configurar el proyecto

1. Ir a la raíz del proyecto

   $ cd /path/to/your-project

2. Instalar la integración con Claude Code

   $ aidlc config --harness claude

3. Revisar el setup

   $ aidlc doctor

aidlc config es local y transaccional. Escribe la integración con Claude Code, crea un workspace aidlc/, mezcla lo que necesita en los archivos del proyecto y registra una línea base para que las próximas actualizaciones sepan qué es suyo. Si quieres ver el plan antes de que se escriba algo:

aidlc config --dry-run

Dos opciones vale la pena conocer en la primera corrida. AI-DLC puede instalar cinco servidores MCP para Claude Code: Context7, para documentación de librerías, y cuatro servidores de AWS (acceso a API, precios, infraestructura como código, serverless). Una credencial que falta deja el servidor no disponible sin bloquear el workflow, pero si no construyes sobre AWS no hay razón para cargarlos.

aidlc config --harness claude --mcp none

Y AI-DLC no elige tu proveedor de modelo. Mantiene el que Claude Code ya usa. Si quieres Amazon Bedrock, aidlc config providers te guía; si no, déjalo como está.

Lo que aidlc config escribió en un proyecto limpio

• your-project/
  • AGENTS.mdtuyo// stack, patrones, librerías prohibidas
  • .claude/
    • CLAUDE.mdaidlc// el onboarding del método
    • settings.json// hooks, barra de estado, banner de bienvenida
    • agents/// las 14 personas de agente
    • skills/aidlc/// el comando /aidlc
    • hooks/// auditoría, guards, recuperación, barra de estado
    • tools/// el motor determinístico
  • aidlc/spaces/default/memory/commit// reglas de organización, equipo, proyecto y fase
  • .gitignore// un bloque de AI-DLC que dice qué commitear

Las carpetas de registro de cada pieza de trabajo (aidlc/spaces/default/intents/) aparecen en tu primer /aidlc, y una carpeta knowledge/ para documentos del equipo aparece cuando agregas alguno. Commitea la carpeta aidlc/ a medida que se llena. El doctor te lo recuerda si no lo haces, porque esos registros viajan entre las personas del equipo por git: las reglas, el estado de cada workflow, los artefactos y el rastro de auditoría. El bloque que AI-DLC agrega al .gitignore lista exactamente qué se debe commitear y qué es local de la máquina.

Paso 3: aprueba los hooks y reinicia

Este es el paso que la gente se salta, y después nada funciona. AI-DLC en Claude Code corre sobre hooks: scripts que Claude Code dispara ante eventos, que escriben el rastro de auditoría, validan el estado antes de la compactación, aplican los guards de aprobación y alimentan la barra de estado. El motor conecta 17.

Claude Code no corre hooks de proyecto que no aprobaste. Abre Claude Code en el proyecto, corre /hooks, apruébalos y reinicia Claude Code por completo. Después vuelve a correr aidlc doctor.

Si el doctor sigue quejándose de los hooks, dos causas cubren la mayoría de los casos. O los hooks están desactivados en alguna capa de configuración de Claude Code, o la configuración administrada de tu empresa solo permite hooks administrados, y entonces solo quien administra Claude Code puede liberarlo. El doctor te dice cuál de las dos es.

Paso 4: empieza un workflow

Abre Claude Code en el proyecto y describe el trabajo:

/aidlc Build a REST API for inventory management

AI-DLC lee el pedido y propone un perfil de workflow con su cantidad de etapas y su profundidad. Lo confirmas o lo cambias. También puedes elegir el perfil por nombre:

/aidlc classic
/aidlc feature Add customer notifications
/aidlc bugfix Fix the login timeout

Si ya tienes un documento de visión o un PRD en el repo, apúntalo con la ruta exacta y el workflow lo lee como entrada:

/aidlc Read ./docs/vision.md and build what it describes

De ahí en adelante los agentes se turnan. Cada etapa interactiva pregunta cómo quieres responder: Guide Me (el agente hace preguntas estructuradas), Edit File (tú llenas el archivo de preguntas) o Chat (conversación libre, y el agente extrae las decisiones). Cada etapa termina en un gate donde respondes Approve o Request Changes con tus palabras. “Looks good but split the tests” cuenta como pedido de cambio, y esas palabras se vuelven el feedback.

Claude Code también suma una barra de estado al pie de la terminal: la fase actual, la etapa, una barra de progreso, el agente líder, cuánto contexto queda y un costo estimado en tokens. El costo es una estimación a precio de lista, no tu factura, pero vigílalo en las primeras corridas. Un workflow de AI-DLC lee y escribe mucho.

Disciplina de contexto: la parte que la documentación te deja a ti

Una ventana de un millón de tokens parece espacio infinito. No lo es. En el rollout que seguí, una Inception en un repositorio real usaba la mitad de la ventana o más por sí sola: la ingeniería inversa, las preguntas, los requisitos, el diseño. Y la calidad de las respuestas caía de forma visible cuando la ventana pasaba de unos tres cuartos. El agente no se caía. Se volvía descuidado, y el descuido en un gate es como se aprueban decisiones equivocadas.

La investigación dice lo mismo desde otro ángulo. Cuando una sesión larga compacta su historial para hacer lugar, las restricciones desaparecen sin hacer ruido. Un estudio midió agentes que obedecían una regla el 100% de las veces mientras era visible, y que la violaban en el 30% de los episodios después de la compactación, hasta el 59% en algunos modelos (Governance Decay). Otro encontró que los compactadores conservan solo el 17% de las restricciones que el usuario fijó durante la sesión (Lost in Compaction).

AI-DLC 2 protege su propio estado contra esto. El workflow vive en disco, en el archivo de estado y en la carpeta de registro, y un hook escribe un checkpoint de recuperación antes de que Claude Code compacte. Lo que no puede proteger es el matiz que discutiste y nunca escribiste. Así que estos son los hábitos que funcionaron:

Hábitos de sesión para AI-DLC en Claude Code

1. 01

   Revisa la ventana antes de que empiece la Inception.

   La Inception es la fase más pesada. Usa un modelo con la context window más grande que ofrezca tu plan, y confirma cuánto espacio tienes de verdad antes de que la ingeniería inversa se lo coma.

   Escribe esto

   /context

2. 02

   Limpia solo en un gate, después de commitear.

   Limpiar en medio de una etapa tira trabajo que todavía no está en disco. En un gate, todo lo que importa está en la carpeta de registro. Commitea y haz push del registro, después limpia, después retoma desde el archivo de estado.

   Escribe esto

   /clear
   /aidlc --resume

3. 03

   Estaciona en lugar de forzar una sesión cansada.

   Después de una hora leyendo documentos generados, la gente aprueba sin leer. Estacionar se detiene en el borde de la etapa actual y no cuesta nada.

   Escribe esto

   /aidlc park

4. 04

   Pregunta dónde estás sin mover nada.

   El status solo lee: fase, etapa, progreso, qué ajustes están activos y de dónde salió cada uno.

   Escribe esto

   /aidlc --status

5. 05

   Antes de limpiar una sesión trabada, haz que anote lo que aprendió.

   Cuando una sesión da vueltas en círculo, limpiarla también tira los callejones sin salida que ya descartó. Pídele que los escriba primero, después empieza de cero desde el archivo.

   Escribe esto

   Write a summary of this problem to notes/handoff.md: what we found, the hypotheses we verified, the ones we discarded, and the next step. Do not change anything else.

Cuando cierras Claude Code y vuelves al día siguiente, corre /aidlc solo. Lee el estado, revisa el checkpoint de recuperación y ofrece cuatro opciones: retomar desde el último checkpoint, rehacer la etapa actual, saltar a una etapa o empezar una pieza de trabajo nueva en paralelo. Si el checkpoint y el estado no coinciden porque una compactación cayó a mitad de etapa, te avisa, y la respuesta segura es rehacer esa etapa.

Ajustes de modelo que vale la pena tocar

AI-DLC divide sus 14 agentes en tres grupos para la política de modelo: Deciding (nueve agentes, de producto y arquitectura a desarrollo, seguridad, calidad y el composer), Reviewing (los dos revisores) y Writing up (entrega, pipeline y despliegue, operaciones). Puedes definir el esfuerzo por grupo, o por agente, y commitear la política para todo el equipo.

aidlc config models --show
aidlc config models --reviewing-effort xhigh --project --yes

El primer comando muestra con qué va a correr cada agente y de dónde salió eso. El segundo es el primer cambio que yo haría: los revisores son los agentes que atrapan lo que el constructor dejó pasar, así que dales más razonamiento, no menos. El asistente de la primera corrida usa por defecto un preset balanceado, con esfuerzo medio en todos los grupos. Un preset thorough sube a los revisores a xhigh; uno minimal baja a los agentes de Writing up.

Un ajuste más pertenece al repo, no a cada laptop. Fija la versión del motor para que todo el equipo corra las mismas definiciones de workflow:

aidlc config --pin 2.10.0

Eso escribe .aidlc-version en el proyecto. Commitéalo.

Mantenerlo actualizado

aidlc update actualiza el motor en tu máquina. No toca tus proyectos. Actualiza cada proyecto entre un workflow y otro:

aidlc update
cd /path/to/your-project
aidlc doctor
aidlc config

aidlc config se niega a actualizar un proyecto mientras haya un workflow activo, así que termina o estaciona primero la pieza de trabajo actual. Si usas plugins, corre /aidlc plugin sync dentro de Claude Code después de la actualización.

Cuando algo no funciona

De la tabla de troubleshooting del repositorio. Corre aidlc doctor primero; te dice qué lo arregla.

Síntoma	Qué lo arregla
El shell no encuentra aidlc	Aplica la instrucción de PATH que imprimió el instalador, o abre una terminal nueva en Windows.
El doctor dice que aidlc es interactive-only	Los hooks no ven el PATH de tu shell. Agrega ~/.local/bin al PATH de la sesión o corre aidlc config runtime.
El doctor avisa de cambios sin commitear en aidlc/	Commitea y haz push de la carpeta aidlc/. Es como el equipo comparte reglas, estado y el rastro de auditoría.
El doctor reporta una diferencia de versión entre proyecto y runtime	Termina el workflow activo, después corre aidlc config.
Los gates y la barra de estado nunca aparecen	Aprueba los hooks del proyecto con /hooks y reinicia Claude Code por completo.
Las etapas de un plugin desaparecieron después de una actualización	Corre /aidlc plugin sync.
Las skills actualizadas no hacen efecto	Empieza una sesión nueva de Claude Code.

Dónde entra pi

Uso pi todos los días, y no está entre los siete harnesses que soporta AI-DLC 2. No voy a fingir lo contrario ni a inventar un parche.

Lo que pi sí tiene es pi-sdd-kit, mi paquete de skills de Spec-Driven Development, y ese es su lugar honesto en esta historia. La mayoría de los equipos no está lista para AI-DLC el primer día, porque todavía no especifica. Un workflow más liviano (escribir los requisitos, aprobarlos, diseñar, partir en tareas, construir, revisar) es como un dev forma ese hábito solo, antes de que un equipo construya un ciclo de vida encima. Especifica en pi hasta que se vuelva rutina. Después corre AI-DLC en Claude Code para el trabajo que necesita más de una persona para decidir. Si ya vives en Claude Code, el mismo hábito está en Spec-Driven Development con Claude Code.

Tu primera semana

Un setup que te enseña algo

• ✓Obligatorio:
  AGENTS.md de la raíz escrito: stack, patrones, librerías prohibidas, un ejemplo de cada uno.
• ✓Obligatorio:
  Motor instalado, proyecto configurado, hooks aprobados, doctor limpio.
• ✓Obligatorio:
  Versión del motor fijada con aidlc config --pin y commiteada.
• •Opcional:
  Esfuerzo de los revisores aumentado; servidores MCP que no usas, afuera.
• ✓Obligatorio:
  Una feature real corrida de punta a punta en el perfil Classic.
• ✓Obligatorio:
  Sesiones de alrededor de una hora, contexto limpio solo en los gates, registro commiteado antes de cada limpieza.
• ✗Anti-pattern:
  El perfil Feature completo, con 33 etapas, el primer día.
• ✗Anti-pattern:
  Una corrección de una línea pasada por AI-DLC solo para probar.

Preguntas frecuentes

¿AI-DLC funciona con Claude Code?+

Sí. Claude Code es uno de los siete harnesses que soporta AI-DLC 2, junto con Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode y GitHub Copilot. Configura el proyecto con aidlc config --harness claude y empieza los workflows con /aidlc.

¿Necesito Amazon Bedrock para usar AI-DLC con Claude Code?+

No. AI-DLC mantiene el proveedor de modelo que Claude Code ya usa. Bedrock es una opción explícita que eliges con aidlc config providers.

¿Qué modelo debería usar?+

El README recomienda Claude Opus 4.8. En fases largas de Inception sobre repositorios grandes, el tamaño de la context window importa tanto como el modelo, así que usa la ventana más grande que ofrezca tu plan y vigílala con /context.

¿Cómo retomo un workflow de AI-DLC después de cerrar Claude Code?+

Corre /aidlc en el proyecto. Lee el archivo de estado y ofrece retomar desde el último checkpoint, rehacer la etapa actual, saltar a una etapa o empezar una pieza de trabajo nueva. /aidlc --resume se salta el menú y sigue directo.

¿Puedo usar AI-DLC con pi?+

No como harness soportado. AI-DLC 2 sale para siete agentes y pi no es uno de ellos. pi-sdd-kit le da a pi un workflow más liviano de Spec-Driven Development, que es el hábito que AI-DLC asume que tu equipo ya tiene.

¿Cómo actualizo AI-DLC?+

Corre aidlc update para actualizar el motor en tu máquina, después actualiza cada proyecto entre un workflow y otro con aidlc doctor y aidlc config. Fija una versión por proyecto con aidlc config --pin para que todo el equipo quede en la misma.

A dónde ir ahora

La instalación es la parte fácil, y de verdad son cuatro comandos. La parte difícil es todo lo que la rodea: un repositorio que el agente pueda leer, un equipo que sepa juzgar una spec y la paciencia de detenerse en el gate en lugar de pasar corriendo.