AI-DLC com Claude Code: um setup que funciona

Instalar o AI-DLC no Claude Code leva quatro comandos. Rodar bem leva um repositório que o agente consiga ler e a disciplina de parar nos gates.

O AI-DLC 2 roda dentro de sete agentes de código, e o Claude Code é o que a própria documentação usa em todos os exemplos. O README recomenda o Claude Opus 4.8 como modelo. Ele também é um dos dois agentes que eu uso todo dia, junto com o pi, então este é o setup que eu entregaria para um time que quer testar o método na segunda-feira. Rodei cada passo abaixo num projeto de teste limpo com a release 2.10.0 antes de escrever.

Se você ainda não leu o que é o método, comece por o que é AI-DLC. Se você conhece a versão 1 e quer saber o que mudou, leia o que o AI-DLC 2 mudou. Este artigo é a parte prática: os comandos da documentação oficial, na ordem, mais os hábitos que a documentação deixa por sua conta.

Antes de instalar: dê ao agente algo para ler

Uma das primeiras coisas que o AI-DLC faz num projeto existente é a engenharia reversa. Um agente de desenvolvimento varre o código e um agente de arquitetura escreve o que encontrou, e cada requisito, história e Unit depois disso é construído em cima desse texto. Se o repositório é difícil de ler, o texto é um chute, e tudo o que vem depois também.

Então o primeiro passo não tem nada a ver com o AI-DLC. Coloque um AGENTS.md ou CLAUDE.md curto na raiz do repo com quatro coisas: a stack e as versões, os padrões que o time usa, as bibliotecas proibidas e o porquê, e um exemplo de cada padrão (um endpoint típico, uma função de domínio típica, um teste típico). Escrevi um guia inteiro sobre o AGENTS.md como memória do agente. Cada lacuna que você preenche aqui é uma pergunta que o agente não vai precisar te fazer no meio de uma sessão de mob.

O AI-DLC escreve o próprio onboarding em .claude/CLAUDE.md quando você configura o projeto. Esse arquivo ensina o método ao Claude Code. O seu arquivo da raiz ensina o seu sistema. Mantenha os dois separados.

A segunda coisa também não tem a ver com a ferramenta. O seu time já deveria estar escrevendo spec antes de deixar um agente construir. Se não está, o AI-DLC vai te entregar uma fila de documentos de requisitos para aprovar que ninguém no time sabe julgar. Comece por como escrever uma spec e volte quando isso parecer normal. O raciocínio está em AI-DLC vs Spec-Driven Development.

Passo 1: instale o motor

O instalador acrescenta um comando nativo, aidlc, e o runtime de todos os agentes suportados. Ele não precisa de Bun nem de Node.js.

Instalar o AI-DLC

1. macOS, Linux ou 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

Se o seu shell não encontrar o aidlc depois disso, siga a instrução de PATH que o instalador imprime, ou abra um terminal novo no Windows. Rode numa janela normal do PowerShell, não numa aberta como administrador.

No Linux tem uma pegadinha que a mensagem do instalador não explica. Os hooks que movem o AI-DLC são iniciados pelo Claude Code, não pelo seu shell interativo, então eles não leem o seu .bashrc. Se o aidlc só está no PATH do seu terminal, o aidlc doctor avisa que ele é “interactive-only”. Coloque ~/.local/bin no PATH que a sua sessão herda (um arquivo em ~/.config/environment.d/ resolve), ou deixe o aidlc config runtime cuidar disso.

Passo 2: configure o projeto

Configurar o projeto

1. Ir para a raiz do projeto

   $ cd /path/to/your-project

2. Instalar a integração com o Claude Code

   $ aidlc config --harness claude

3. Conferir o setup

   $ aidlc doctor

O aidlc config é local e transacional. Ele escreve a integração com o Claude Code, cria um workspace aidlc/, mescla o que precisa nos arquivos do projeto e grava uma linha de base para que as próximas atualizações saibam o que é dele. Se você quiser ver o plano antes de qualquer coisa ser escrita:

aidlc config --dry-run

Duas opções valem saber na primeira rodada. O AI-DLC pode instalar cinco servidores MCP no Claude Code: o Context7, para documentação de bibliotecas, e quatro servidores da AWS (acesso a API, preços, infraestrutura como código, serverless). Credencial faltando deixa o servidor indisponível sem travar o workflow, mas se você não constrói na AWS não há motivo para carregar esses servidores.

aidlc config --harness claude --mcp none

E o AI-DLC não escolhe o seu provedor de modelo. Ele mantém o que o Claude Code já usa. Se você quiser Amazon Bedrock, o aidlc config providers te guia; caso contrário, deixe como está.

O que o aidlc config escreveu num projeto limpo

• your-project/
  • AGENTS.mdseu// stack, padrões, bibliotecas proibidas
  • .claude/
    • CLAUDE.mdaidlc// o onboarding do método
    • settings.json// hooks, barra de status, banner de boas-vindas
    • agents/// as 14 personas de agente
    • skills/aidlc/// o comando /aidlc
    • hooks/// auditoria, guardas, recuperação, barra de status
    • tools/// o motor determinístico
  • aidlc/spaces/default/memory/commit// regras de organização, time, projeto e fase
  • .gitignore// um bloco do AI-DLC que diz o que commitar

As pastas de registro de cada peça de trabalho (aidlc/spaces/default/intents/) aparecem no seu primeiro /aidlc, e uma pasta knowledge/ para documentos do time aparece quando você acrescenta algum. Commite a pasta aidlc/ conforme ela enche. O doctor lembra você se não fizer isso, porque esses registros viajam entre as pessoas do time pelo git: as regras, o estado de cada workflow, os artefatos e a trilha de auditoria. O bloco que o AI-DLC acrescenta ao .gitignore lista exatamente o que deve ser commitado e o que é local da máquina.

Passo 3: aprove os hooks e reinicie

Esse é o passo que as pessoas pulam, e aí nada funciona. O AI-DLC no Claude Code roda em hooks: scripts que o Claude Code dispara em eventos, que gravam a trilha de auditoria, validam o estado antes da compactação, aplicam as guardas de aprovação e alimentam a barra de status. O motor liga 17 deles.

O Claude Code não roda hooks de projeto que você não aprovou. Abra o Claude Code no projeto, rode /hooks, aprove, e reinicie o Claude Code por completo. Depois rode aidlc doctor de novo.

Se o doctor continuar reclamando dos hooks, duas causas cobrem a maioria dos casos. Ou os hooks estão desativados em alguma camada de configuração do Claude Code, ou as configurações gerenciadas da sua empresa só permitem hooks gerenciados, e aí só quem administra o Claude Code consegue liberar. O doctor diz qual das duas é.

Passo 4: comece um workflow

Abra o Claude Code no projeto e descreva o trabalho:

/aidlc Build a REST API for inventory management

O AI-DLC lê o pedido e propõe um perfil de workflow com a contagem de estágios e a profundidade. Você confirma ou troca. Também dá para escolher o perfil pelo nome:

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

Se você já tem um documento de visão ou um PRD no repo, aponte para ele pelo caminho exato e o workflow lê como entrada:

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

Daí em diante os agentes se revezam. Cada estágio interativo pergunta como você quer responder: Guide Me (o agente faz perguntas estruturadas), Edit File (você preenche o arquivo de perguntas) ou Chat (conversa livre, e o agente extrai as decisões). Todo estágio termina num gate em que você responde Approve ou Request Changes com as suas palavras. “Looks good but split the tests” conta como pedido de mudança, e essas palavras viram o feedback.

O Claude Code também ganha uma barra de status no rodapé do terminal: a fase atual, o estágio, uma barra de progresso, o agente líder, quanto de contexto sobra e um custo estimado em tokens. O custo é uma estimativa pelo preço de tabela, não a sua fatura, mas acompanhe nas primeiras rodadas. Um workflow de AI-DLC lê e escreve muito.

Disciplina de contexto: a parte que a documentação deixa com você

Uma janela de um milhão de tokens parece espaço infinito. Não é. No rollout que acompanhei, uma Inception num repositório real usava metade ou mais da janela sozinha: a engenharia reversa, as perguntas, os requisitos, o design. E a qualidade das respostas caía visivelmente quando a janela passava de uns três quartos. O agente não travava. Ficava desleixado, e desleixo num gate é como decisão errada é aprovada.

A pesquisa diz a mesma coisa por outro ângulo. Quando uma sessão longa compacta o histórico para abrir espaço, as restrições somem sem fazer barulho. Um estudo mediu agentes obedecendo uma regra 100% das vezes enquanto ela estava visível, e violando essa regra em 30% dos episódios depois da compactação, chegando a 59% em alguns modelos (Governance Decay). Outro descobriu que os compactadores guardam só 17% das restrições que o usuário definiu durante a sessão (Lost in Compaction).

O AI-DLC 2 protege o próprio estado contra isso. O workflow fica em disco, no arquivo de estado e na pasta de registro, e um hook grava um checkpoint de recuperação antes de o Claude Code compactar. O que ele não protege é a nuance que você discutiu e nunca escreveu. Então estes são os hábitos que funcionaram:

Hábitos de sessão para AI-DLC no Claude Code

1. 01

   Confira a janela antes de a Inception começar.

   A Inception é a fase mais pesada. Use um modelo com a maior context window que o seu plano oferece, e confirme quanto espaço você tem de verdade antes que a engenharia reversa coma tudo.

   Digite isto

   /context

2. 02

   Limpe só num gate, depois de commitar.

   Limpar no meio de um estágio joga fora trabalho que ainda não está em disco. Num gate, tudo o que importa está na pasta de registro. Commite e dê push no registro, depois limpe, depois retome pelo arquivo de estado.

   Digite isto

   /clear
   /aidlc --resume

3. 03

   Estacione em vez de forçar uma sessão cansada.

   Depois de uma hora lendo documentos gerados, as pessoas aprovam sem ler. Estacionar para na fronteira do estágio atual e não custa nada.

   Digite isto

   /aidlc park

4. 04

   Pergunte onde você está sem mexer em nada.

   O status só lê: fase, estágio, progresso, quais configurações estão ligadas e de onde veio cada uma.

   Digite isto

   /aidlc --status

5. 05

   Antes de limpar uma sessão travada, faça ela anotar o que aprendeu.

   Quando uma sessão anda em círculos, limpar também joga fora os becos sem saída que ela já descartou. Peça para escrever isso antes, depois recomece do zero a partir do arquivo.

   Digite isto

   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.

Quando você fecha o Claude Code e volta no dia seguinte, rode /aidlc sem nada. Ele lê o estado, confere o checkpoint de recuperação e oferece quatro opções: retomar do último checkpoint, refazer o estágio atual, pular para um estágio ou começar uma peça de trabalho nova em paralelo. Se o checkpoint e o estado discordam porque uma compactação caiu no meio do estágio, ele avisa, e a resposta segura é refazer aquele estágio.

Configurações de modelo que valem a pena mexer

O AI-DLC divide os 14 agentes em três grupos para a política de modelo: Deciding (nove agentes, de produto e arquitetura a desenvolvimento, segurança, qualidade e o composer), Reviewing (os dois revisores) e Writing up (entrega, pipeline e deploy, operações). Dá para definir o esforço por grupo, ou por agente, e commitar a política para o time inteiro.

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

O primeiro comando mostra com o que cada agente vai rodar e de onde veio essa configuração. O segundo é a primeira mudança que eu faria: os revisores são os agentes que pegam o que o construtor deixou passar, então dê mais raciocínio para eles, não menos. O assistente da primeira rodada usa um preset balanceado, com esforço médio em todos os grupos. Um preset thorough sobe os revisores para xhigh; um minimal baixa os agentes de Writing up.

Mais uma configuração pertence ao repo, não a cada notebook. Fixe a versão do motor para que todo mundo do time rode as mesmas definições de workflow:

aidlc config --pin 2.10.0

Isso escreve .aidlc-version no projeto. Commite.

Mantendo atualizado

O aidlc update atualiza o motor na sua máquina. Ele não mexe nos seus projetos. Atualize cada projeto entre um workflow e outro:

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

O aidlc config se recusa a atualizar um projeto enquanto há um workflow ativo, então termine ou estacione a peça de trabalho atual antes. Se você usa plugins, rode /aidlc plugin sync dentro do Claude Code depois da atualização.

Quando algo não funciona

Da tabela de troubleshooting do repositório. Rode aidlc doctor primeiro; ele diz o que resolve.

Sintoma	O que resolve
O shell não encontra o aidlc	Aplique a instrução de PATH que o instalador imprimiu, ou abra um terminal novo no Windows.
O doctor diz que o aidlc é interactive-only	Os hooks não enxergam o PATH do seu shell. Acrescente ~/.local/bin ao PATH da sessão ou rode aidlc config runtime.
O doctor avisa de mudanças não commitadas em aidlc/	Commite e dê push na pasta aidlc/. É assim que o time compartilha regras, estado e a trilha de auditoria.
O doctor aponta descompasso de versão entre projeto e runtime	Termine o workflow ativo, depois rode aidlc config.
Os gates e a barra de status nunca aparecem	Aprove os hooks do projeto com /hooks e reinicie o Claude Code por completo.
Estágios de plugin sumiram depois de uma atualização	Rode /aidlc plugin sync.
Skills atualizadas não fazem efeito	Comece uma sessão nova do Claude Code.

Onde o pi entra

Eu uso o pi todo dia, e ele não está entre os sete harnesses que o AI-DLC 2 suporta. Não vou fingir o contrário nem inventar um contorno.

O que o pi tem é o pi-sdd-kit, o meu pacote de skills de Spec-Driven Development, e esse é o lugar honesto dele nesta história. A maioria dos times não está pronta para o AI-DLC no primeiro dia, porque ainda não especifica. Um workflow mais leve (escrever os requisitos, aprovar, desenhar, quebrar em tarefas, construir, revisar) é como um dev cria esse hábito sozinho, antes de um time construir um ciclo de vida em cima. Especifique no pi até virar rotina. Depois rode o AI-DLC no Claude Code no trabalho que precisa de mais de uma pessoa para decidir. Se você já vive no Claude Code, o mesmo hábito está em Spec-Driven Development com Claude Code.

A sua primeira semana

Um setup que te ensina alguma coisa

• ✓Obrigatório:
  AGENTS.md da raiz escrito: stack, padrões, bibliotecas proibidas, um exemplo de cada.
• ✓Obrigatório:
  Motor instalado, projeto configurado, hooks aprovados, doctor limpo.
• ✓Obrigatório:
  Versão do motor fixada com aidlc config --pin e commitada.
• •Opcional:
  Esforço dos revisores aumentado; servidores MCP que você não usa deixados de fora.
• ✓Obrigatório:
  Uma feature real rodada de ponta a ponta no perfil Classic.
• ✓Obrigatório:
  Sessões de mais ou menos uma hora, contexto limpo só nos gates, registro commitado antes de cada limpeza.
• ✗Anti-pattern:
  O perfil Feature inteiro, com 33 estágios, no primeiro dia.
• ✗Anti-pattern:
  Uma correção de uma linha rodada no AI-DLC só para testar.

Perguntas frequentes

O AI-DLC funciona com o Claude Code?+

Sim. O Claude Code é um dos sete harnesses que o AI-DLC 2 suporta, junto com Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode e GitHub Copilot. Configure o projeto com aidlc config --harness claude e comece os workflows com /aidlc.

Preciso de Amazon Bedrock para usar AI-DLC com Claude Code?+

Não. O AI-DLC mantém o provedor de modelo que o Claude Code já usa. O Bedrock é uma opção explícita que você escolhe com aidlc config providers.

Qual modelo devo usar?+

O README recomenda o Claude Opus 4.8. Em fases longas de Inception em repositórios grandes, o tamanho da context window importa tanto quanto o modelo, então use a maior janela que o seu plano oferece e acompanhe com /context.

Como retomo um workflow de AI-DLC depois de fechar o Claude Code?+

Rode /aidlc no projeto. Ele lê o arquivo de estado e oferece retomar do último checkpoint, refazer o estágio atual, pular para um estágio ou começar uma peça de trabalho nova. O /aidlc --resume pula o menu e continua direto.

Dá para usar AI-DLC com o pi?+

Não como harness suportado. O AI-DLC 2 sai para sete agentes e o pi não é um deles. O pi-sdd-kit dá ao pi um workflow mais leve de Spec-Driven Development, que é o hábito que o AI-DLC assume que o seu time já tem.

Como atualizo o AI-DLC?+

Rode aidlc update para atualizar o motor na sua máquina, depois atualize cada projeto entre um workflow e outro com aidlc doctor e aidlc config. Fixe uma versão por projeto com aidlc config --pin para o time inteiro ficar na mesma.

Para onde ir agora

A instalação é a parte fácil, e são mesmo quatro comandos. A parte difícil é tudo em volta: um repositório que o agente consiga ler, um time que saiba julgar uma spec e a paciência de parar no gate em vez de passar correndo.