O uso de Inteligência Artificial no desenvolvimento de software deixou de ser experimental. Hoje, a IA escreve código, sugere arquiteturas, cria testes e participa ativamente da evolução de sistemas reais.
Mas, conforme a IA passa de “assistente” para agente ativo, um novo problema surge: perda de contexto e de intenção ao longo do tempo.
Este artigo apresenta o ai-cldd (AI Change-Log Driven Development), um padrão de design criado para resolver exatamente esse problema.
Repositório oficial:
https://github.com/cesarpaulomp/ai-cldd
O problema: quando a IA esquece o porquê
Prompts são efêmeros.
Código não explica decisões.
E a próxima IA (ou desenvolvedor) quase nunca sabe por que algo foi feito.
Alguns sintomas comuns em projetos com IA:
- Funcionalidades implementadas sem contrato explícito
- Decisões arquiteturais incoerentes ao longo do tempo
- Dificuldade de evoluir código gerado por outra IA
- Falta de rastreabilidade entre intenção e implementação
- Alto risco de regressão conceitual
O problema não é a IA gerar código errado.
O problema é não existir um histórico confiável de intenção e decisão.
A ideia central do ai-cldd
O ai-cldd parte de um princípio simples:
Nenhuma mudança sem intenção documentada.
Nenhuma intenção sem registro do que foi aplicado.
Na prática:
- A intenção é escrita em um documento
- A IA aplica essa intenção no código
- A IA registra exatamente o que foi feito
Esse ciclo cria continuidade cognitiva, mesmo quando múltiplas IAs ou desenvolvedores trabalham no mesmo projeto ao longo do tempo.
SYSTEM_BASE e FEATURE: separando contrato de mudança
SYSTEM_BASE (SB-*)
Documentos SYSTEM_BASE definem o contrato técnico global do sistema.
Eles descrevem:
- O que o sistema é e faz
- Tecnologias obrigatórias
- Padrões arquiteturais
- Restrições que não podem ser violadas
- Estrutura do projeto
- Padrões de comunicação
Esses documentos usam o prefixo SB- e sempre têm prioridade máxima.
Exemplo:
SB-000 – System Base
FEATURE Use Cases (UC-*)
Documentos FEATURE descrevem mudanças ou adições de comportamento.
Eles definem:
- O que deve ser implementado
- O que está dentro e fora de escopo
- Estruturas de dados envolvidas
- Endpoints ou interfaces
- Tarefas objetivas de implementação
Esses documentos usam o prefixo UC- e devem sempre ser aplicados junto a um SYSTEM_BASE.
Exemplo:
UC-002 – Endpoints para estado do jogo
Change-logs: a memória da IA
Toda aplicação de um SYSTEM_BASE ou FEATURE gera exatamente um change-log.
Esse change-log registra:
- Qual documento foi aplicado
- O checksum do conteúdo
- Quando a mudança ocorreu
- Qual agente de IA aplicou
- Quais alterações foram feitas
Esses registros são imutáveis e se tornam a memória auditável do sistema.
Estrutura esperada no projeto
/ai-cldd
/docs
SB-000 - System Base.md
UC-001 - Feature.md
UC-002 - Feature.md
/change-logs
SB-000.yaml
UC-001.yaml
UC-002.yaml
ai-cldd-v1.yaml
O papel do ai-cldd-v1.yaml
O arquivo ai-cldd-v1.yaml funciona como um manual de execução para a IA.
Ele define:
- Tipos de documentos
- Prioridade entre regras
- Ordem correta de execução
- Estrutura obrigatória de change-logs
- Ações proibidas e obrigatórias
Esse arquivo deve ser copiado para o projeto e explicitamente referenciado no prompt da IA.
O que o ai-cldd não é
- Não é um framework
- Não é uma metodologia ágil
- Não é uma ferramenta de prompt
- Não depende de linguagem ou stack
O ai-cldd é um padrão de design para desenvolvimento assistido por IA.
Por que esse padrão importa
À medida que a IA se torna parte do time, precisamos tratar decisões técnicas como ativos duráveis.
O ai-cldd permite:
- Evolução segura de sistemas complexos
- Rastreabilidade completa de decisões
- Menor acoplamento entre prompts e código
- Onboarding mais rápido de novas IAs ou desenvolvedores
- Continuidade arquitetural ao longo do tempo
Conclusão
O ai-cldd não tenta controlar a IA.
Ele cria contratos claros para que a IA opere com segurança.
Se você já usa IA no desenvolvimento, a pergunta não é se precisa de algo assim — é quando a falta disso vai começar a custar caro.
Top comments (0)