Por dentro do AI-DLC no Kiro: agentes, escopos e a trilha de auditoria
Neste post, explico como o AI-DLC v2 funciona internamente: a divisão entre engine e conductor, o elenco de 14 agentes, como os escopos decidem quais arquivos são criados, os controles de profundidade e estratégia de testes, e como o arquivo de estado e a trilha de auditoria tornam cada decisão rastreável e cada sessão retomável.
Series: AI-DLC explicado em português (2 articles)
- 2Por dentro do AI-DLC no Kiro: agentes, escopos e a trilha de auditoria This article
Por dentro do AI-DLC no Kiro: agentes, escopos e a trilha de auditoria
Entender como o AI-DLC (AI-Driven Development Life Cycle) funciona dentro do Kiro — seus agentes, escopos e trilha de auditoria — é o que separa confiar na saída de simplesmente torcer pelo melhor. Na Parte 1 , mostrei como instalar o AI-DLC Workflows 2.0 no Kiro e executar seu primeiro workflow. Aquele post tratava a metodologia como uma caixa-preta: você descreve uma intenção, aprova alguns gates e um código funcional aparece. Este post abre a caixa.
A McKinsey descreve o novo papel do engenheiro como direcionar em vez de programar — mas você só consegue direcionar um sistema que entende. Neste post, explico como o AI-DLC v2 funciona internamente: a divisão entre engine e conductor, o elenco de 14 agentes, como os escopos decidem quais arquivos são criados, os controles de profundidade e estratégia de testes, e como o arquivo de estado e a trilha de auditoria tornam cada decisão rastreável e cada sessão retomável.
Visão geral da solução
O AI-DLC v2 se apoia em uma única ideia arquitetural: uma engine determinística decide o que acontece em seguida, e um conductor (a sessão
/aidlc) executa isso. A engine é o árbitro — não é possível convencê-la a mudar uma decisão, e ela registra cada evento em uma trilha de auditoria. O conductor é o jogador: executa os estágios, delega aos agentes e apresenta os gates de aprovação a você.
Esse núcleo é neutro em relação ao harness: a mesma metodologia se renderiza no Claude Code, Kiro IDE, Kiro CLI, Codex CLI e opencode. Este post foca no Kiro, onde as ferramentas da engine rodam como comandos
bun .kiro/tools/<tool>.ts. Vamos percorrer cada parte.O elenco de 14 agentes
O AI-DLC entrega 14 personas de agentes: 11 especialistas de domínio que executam o trabalho dos estágios, 2 agentes somente de revisão e 1 compositor de adaptive-workflows. A filosofia de design é "Small Mob, Broad Agents" (mob (grupo) pequeno, agentes amplos): em vez de dezenas de especialistas restritos — o que recria as cadeias de handoff do waterfall — usam-se 11 agentes amplamente capazes, cada um participando de muitos estágios, espelhando um mob humano de três a cinco pessoas cobrindo uma feature inteira. Menos agentes significa menos handoffs, e cada handoff é um potencial ponto de perda de informação.
Aqui estão os 11 especialistas de domínio e onde cada um lidera:
| Agente | Domínio | Lidera (exemplos) |
|---|---|---|
aidlc-product-agent | Requisitos, user stories, escopo | Captura de intenção, requisitos, user stories |
aidlc-design-agent | Experiência do usuário/interface do usuário (UX/UI), wireframes, acessibilidade | Mockups iniciais e refinados |
aidlc-delivery-agent | Formação de time, sequenciamento de entregas | Formação de time, planejamento de entrega |
aidlc-architect-agent | Design de aplicação, requisitos não funcionais (NFRs), decomposição | Viabilidade, design de aplicação, geração de units |
aidlc-aws-platform-agent | Infraestrutura AWS, AWS Cloud Development Kit (AWS CDK), custo | Design de infraestrutura, provisionamento de ambiente |
aidlc-compliance-agent | Varredura regulatória, risco | Nenhum (apenas suporte consultivo) |
aidlc-devsecops-agent | Threat modeling, pipelines de segurança | Estágios relevantes para segurança |
aidlc-developer-agent | Implementação, código | Geração de código |
aidlc-quality-agent | Qualidade, testes | Build e testes |
aidlc-pipeline-deploy-agent | Integração contínua e entrega contínua (CI/CD), deployment | Pipeline de deployment, execução |
aidlc-operations-agent | Operações em runtime, monitoramento | Observabilidade, resposta a incidentes |
Os três agentes finais não são de domínio:
- 2 agentes somente de revisão (
aidlc-product-lead-agenteaidlc-architecture-reviewer-agent). Eles nunca escrevem artefatos de produto por si mesmos — seu único trabalho é revisar o trabalho dos agentes de domínio, atuando como um segundo par de olhos independente nos checkpoints de qualidade. Entre os dois, cobrem todo estágio que exige uma revisão. - 1 compositor de adaptive-workflows. Em vez de executar uma lista fixa de estágios, o compositor analisa sua solicitação específica e propõe um plano personalizado — quais estágios executar, em que ordem — adaptado à tarefa em questão.
Como vários agentes trabalham juntos em um único estágio é decidido pelo mode (modo) daquele estágio — uma configuração declarada na definição do estágio que o framework já traz (você não a configura). O mode define o "formato" da colaboração:
inline— o conductor interpreta cada agente de apoio ele mesmo, uma voz por vez, no seu próprio contexto.subagent(hub-and-spoke) emob(mesh) — cada agente de apoio é despachado como um colaborador separado e independente que escreve seu próprio arquivo de contribuição, que o agente líder então integra.pipeline(chain) — os agentes passam o trabalho adiante numa linha, cada um avançando os artefatos na sua vez.
Em todos os modes, o conductor realiza cada handoff — os agentes nunca chamam uns aos outros diretamente.
Os cinco harnesses
O AI-DLC é um único núcleo neutro em relação ao harness renderizado sobre a interface de linha de comando (CLI) ou o ambiente de desenvolvimento integrado (IDE) que você usa. A metodologia — fases, estágios, agentes, gates — é idêntica em todos os lugares. O que difere é o shell: como os gates se renderizam, como os subagents são despachados, quais eventos de sessão disparam e onde a configuração vive.
| Harness | Invoque com |
|---|---|
| Claude Code | /aidlc |
| Kiro IDE | /aidlc |
| Kiro CLI (≥ 2.6) | /aidlc |
| Codex CLI (≥ 0.145.0) | $aidlc |
| opencode (≥ 1.17) | /aidlc |
No Kiro, o núcleo compartilhado vive sob
.kiro/ e as ferramentas da engine rodam como bun .kiro/tools/<tool>.ts. Todo o resto neste post — escopos, profundidade, estado, auditoria — se comporta de forma idêntica em todos os harnesses.Escopos: quais estágios rodam e quais arquivos cada um produz
Um escopo controla quais estágios executam. O AI-DLC entrega 9 escopos principais, desde a execução completa de 32 estágios do
enterprise até um bugfix de 7 estágios. O conductor detecta automaticamente um escopo a partir da sua intenção em texto livre, e você pode sobrescrevê-lo.
Os escopos diferem em uma ordem de grandeza em cerimônia: o
poc roda 8 estágios com 5 gates de aprovação, enquanto o feature roda todos os 32 com 29 gates. Antes de um workflow começar, a linha de confirmação nomeia a contagem exata de estágios e gates, para que você saiba com o que está consentindo.Aqui está a tabela completa de roteamento:
| Escopo | Estágios | Profundidade | Estratégia de testes | Caso de uso |
|---|---|---|---|---|
enterprise | 32 / 32 | Abrangente | Abrangente | Feature regulada, trilha de auditoria completa |
feature | 32 / 32 | Padrão | Padrão | Padrão para novas features |
mvp | 22 / 32 | Padrão | Padrão | Greenfield, pula operações tardias |
poc | 8 / 32 | Mínima | Mínima | Provar viabilidade rapidamente |
bugfix | 7 / 32 | Mínima | Mínima | Corrigir um bug específico |
refactor | 8 / 32 | Mínima | Mínima | Refatorar código existente |
infra | 13 / 32 | Padrão | Padrão | Mudança de infraestrutura |
security-patch | 10 / 32 | Mínima | Mínima | Resposta a Common Vulnerabilities and Exposures (CVE) |
workshop | 25 / 32 | Padrão | Mínima | Sessão de treinamento |
Quais arquivos cada escopo cria
Como um escopo decide quais estágios rodam, ele também decide quais arquivos aterrissam no dir. de registro (record dir) da sua intenção em
aidlc/spaces/<space>/intents/<YYMMDD>-<label>/. Todo workflow compartilha uma espinha comum — o arquivo de estado, a trilha de auditoria e as verificações de fronteira de fase — e cada fase que seu escopo inclui adiciona sua própria pasta de artefatos.
Um escopo
bugfix produz um registro enxuto — captura de intenção, requisitos, geração de código e artefatos de build-and-test, sem pasta operation/, pesquisa de mercado ou mockups. Um escopo enterprise produz a árvore completa: todos os artefatos de ideação (análise competitiva, viabilidade e um RAID log — um registro de gerenciamento de projeto de Riscos, Premissas [Assumptions], Problemas [Issues] e Dependências), o conjunto completo de inception, pastas de construção por unit e toda a fase operation/ (deployment, observabilidade, resposta a incidentes, validação de performance).Duas coisas vivem fora do record dir por design: os entregáveis de reverse-engineering (compartilhados entre intenções em um store por repositório) e o conhecimento de time que se acumula por todo o space. O código da aplicação nunca vive na árvore
aidlc/ — ele aterrissa nos seus repositórios de código reais.Além dos 9 escopos de fábrica, o compositor adaptativo (
/aidlc compose) propõe um plano de estágios personalizado — reduzindo para comprimir uma triagem a Fix → Test → PR, ou expandindo para adicionar estágios nas fronteiras de fase.Níveis de profundidade e estratégias de teste
Mais dois controles ajustam finamente uma execução, e são deliberadamente independentes entre si e do escopo.
Profundidade controla quanto detalhe cada artefato carrega:
- Mínima — artefatos concisos, apenas o conteúdo essencial.
- Padrão — detalhe equilibrado; o padrão para a maioria dos escopos.
- Abrangente — artefatos exaustivos com racional completo, para trabalho regulado ou de alto risco.
Estratégia de testes controla quantos testes são gerados — e é independente da profundidade, então você pode combinar documentação enxuta com testes minuciosos, ou o contrário:
- Mínima — a cobertura mais leve que ainda mostra os caminhos críticos.
- Padrão — cobertura equilibrada de componentes e integrações.
- Abrangente — cobertura exaustiva.
Por que separar os dois controles? Porque profundidade de documentação e rigor de testes respondem a perguntas diferentes. Um protótipo em ritmo acelerado pode querer testes minuciosos, mas documentação enxuta; um artefato de compliance pode precisar de documentação exaustiva, mas de um conjunto de testes modesto.
O escopo
workshop mostra por que a separação importa: ele roda 25 estágios em profundidade Padrão, mas estratégia de testes Mínima, mantendo a documentação útil enquanto mantém o ritmo rápido. Cada escopo entrega um padrão sensato para ambos os controles, e você pode mudar qualquer um no meio do workflow — a engine registra a mudança para que ela permaneça auditável.Estado e a trilha de auditoria
Dois arquivos persistentes dão ao AI-DLC total rastreabilidade da intenção à produção.
O arquivo de estado (
aidlc-state.md) é a única fonte da verdade para o progresso de um workflow — a engine o lê a cada início de sessão para ver o que está feito, em andamento e por vir. O progresso do estágio usa uma notação de checkbox de seis estados:| Checkbox | Significado |
|---|---|
[ ] | Não iniciado |
[-] | Em andamento |
[?] | Aguardando sua aprovação (gate aberto) |
[R] | Revisando (você rejeitou o gate) |
[x] | Concluído |
[S] | Pulado (excluído pelo escopo ou saltado) |
No caminho feliz, um estágio se move de
[ ] → [-] → [?] → [x]. Quando você rejeita em um gate, ele vai para [R] enquanto é revisado, volta para [?] quando está pronto e, por fim, para [x] na aprovação.A trilha de auditoria é um livro-registro automático e à prova de adulteração de tudo o que acontece durante um workflow. Cada entrada é sempre apenas adicionada, nunca editada ou excluída — de modo que o histórico é completo e confiável. Para manter tudo organizado quando várias pessoas (ou várias cópias de um projeto) trabalham em paralelo, cada contribuidor escreve no seu próprio arquivo de log separado; o AI-DLC costura todos eles de volta em ordem cronológica quando você lê o histórico, então as entradas de ninguém sobrescrevem as de outra pessoa. O log é deliberadamente detalhado: 82 tipos de evento em 21 categorias, capturando o início e o fim de cada fase e estágio, cada sessão, cada mudança de escopo ou profundidade, cada aprovação ou rejeição que você faz em um gate, cada artefato criado e as lições que o sistema aprende ao longo do caminho.
Os dois são complementares: o arquivo de estado é sobrescrito a cada mudança e lido pela engine para roteamento; a trilha de auditoria é somente de adição (append-only), para rastreabilidade. Cada arquivo que um agente escreve no record dir é registrado automaticamente, então nada escapa do registro.
Retomada de sessão
Um workflow pode se estender por muitas sessões, porque todo o progresso persiste em disco. Quando você executa
/aidlc e um arquivo de estado anterior existe, o AI-DLC mostra um resumo de status e oferece quatro opções:| Opção | O que acontece | O que se perde |
|---|---|---|
| Retomar do último checkpoint | Continua do estágio em andamento ou do próximo pendente | Apenas a conversa em memória da sessão anterior |
| Refazer o estágio atual | Reseta e reexecuta o estágio atual do zero | O status de conclusão daquele estágio e o trabalho parcial |
| Saltar para um estágio | Pula para um estágio específico (os estágios intermediários são marcados como [S]) | Nada em disco; os estágios pulados são sinalizados |
| Começar do zero | Inicia uma nova intenção ao lado da existente | Nada — a intenção anterior permanece retomável |
Essa resiliência se estende à compactação de contexto — quando o harness resume a conversa anterior para liberar espaço. Antes de fazê-lo, um hook escreve um breadcrumb de recuperação oculto com o estágio atual; no próximo
/aidlc, o AI-DLC o compara com o arquivo de estado e o avisa se eles divergirem. Tudo em disco sobrevive — apenas a discussão em memória é perdida.Por fim, três skills de sessão somente de leitura relatam sobre um workflow sem alterá-lo:
/aidlc-session-cost imprime uma visão de custo e progresso, /aidlc-replay narra a sessão para stakeholders que não estavam presentes, e /aidlc-outcomes-pack escreve um documento de handover (OUTCOMES.md). Nenhum avança o workflow ou registra um evento, então é seguro executá-los a qualquer momento.Conclusão
Neste post, expliquei como o AI-DLC v2 funciona dentro do Kiro: uma engine determinística que arbitra enquanto um conductor executa, um grupo de 14 agentes que mantém o contexto em vez de repassá-lo, escopos que decidem quais estágios rodam e quais arquivos aterrissam no seu record dir, controles independentes de profundidade e estratégia de testes, e um arquivo de estado somado a uma trilha de auditoria de 82 eventos que tornam cada workflow rastreável e retomável. É essa arquitetura que permite que você direcione com confiança — você vê exatamente o que o sistema decidiu, por quê, e onde você aprovou.
Para se aprofundar:
- Siga a Parte 1 para instalar o AI-DLC no Kiro e executar seu primeiro workflow
- Explore o Guia do Usuário do AI-DLC para a referência completa de estágios e agentes
- Leia o capítulo State and Audit para a taxonomia completa de eventos
Como você está adaptando os escopos e agentes do AI-DLC aos seus próprios projetos? Compartilhe sua experiência nos comentários.
Series: AI-DLC explicado em português (2 articles)
- 2Por dentro do AI-DLC no Kiro: agentes, escopos e a trilha de auditoria This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article