24 horas, um CLI em produção e uma lição clara sobre trabalhar com IA
Cross-platform. TypeScript strict mode. 30 testes E2E. CI multi-OS. Avaliação técnica independente. Construído em menos de 24 horas, com IA.
Esta é a história da construção. O que aconteceu nos dias seguintes é outra história.
A dor que me acordou de manhã
Se você usa Claude, Codex, ou qualquer assistente de IA para programar, já viveu isso. Toda sessão começa igual: colar contexto, repetir regras, reforçar decisões já tomadas, avisar o que não pode ser feito, explicar o padrão do projeto mais uma vez. Não importa o quão boa a IA seja, ela sempre começa do zero.
“Ah, mas é só manter um CLAUDE.md, GEMINI.md, etc.” Sim, dá para fazer isso. Mas o que um único arquivo realmente consegue representar de um projeto vivo, com histórico, decisões acumuladas e estado atual? No fim das contas, é como trabalhar com um desenvolvedor extremamente capaz, mas com memória de peixe dourado.
Eu já tentava - e conseguia, com muito trabalho braçal - resolver isso há meses com Markdown feito à mão. Funcionava, mas era bruto. Cada novo projeto parecia recomeçar do zero, como se eu estivesse escrevendo decisões importantes na pedra toda vez.
O problema nunca foi a IA. Foi a ausência de memória persistente, histórico real e decisões que não se perdem entre sessões.
A ideia: external memory para IA
Depois de moldar e organizar as ideias na mente por um tempo, às 8h da manhã eu acordei decidido - é igual aquele dias que acordamos com o espírito de limpar a casa incorporado - estava tudo claro o suficiente para virar código.
Com isso, nasceu o AIPIM — AI Project Instruction Manager, que antes era AI Project Manager, depois AIPM, depois... Por um insight aleatório, mas valioso, AIPIM. Não como hype, mas como ferramenta prática. A proposta é simples: criar uma camada de memória externa entre o projeto e o assistente de IA.
Essa camada resolve duas dores centrais: manter contexto persistente entre sessões e registrar o histórico real do projeto, incluindo decisões, tarefas e estado atual. Tudo isso organizado em uma estrutura .project/, inteiramente em Markdown, que a IA consegue ler, respeitar e seguir.
context.mdvira a fonte da verdadecurrent-task.mddefine o focodecisions/guarda decisões arquiteturais imutáveisbacklog/comcompleted/registra o trabalho de forma honesta.
Eu já usava exatamente essa metodologia antes do AIPIM existir. A diferença é que agora isso virou um CLI automatizado.
Como trabalhei com IA (de verdade)
Não usei autocomplete passivo. Usei o Claude Code como pair programmer. Eu definia a direção, a IA executava, eu revisava tudo, corrigia bastante coisa e nada passava sem entendimento completo. Não havia “aceitar sugestão”. Havia diálogo técnico.
Um exemplo real: eu pedi um detector de framework. A IA propôs heurísticas com package.json e filesystem. Eu apontei os edge cases, como React com Vite versus CRA, e exigi fallback hierárquico. O fluxo foi contínuo, sem context switch, sempre com decisão humana no comando.
De tarde, o primeiro aipim install funcionou
Perto do fim da tarde, a primeira milestone estava de pé: CLI funcional. Não foi mágico. Teve bug, ajuste (minha nossa, muitos, se o Claude tivesse ouvidos, estariam doendo) e revisão. IA deixa rastros, principalmente em tarefas complexas, e alguém precisa seguir esses rastros com atenção. Desde o início, deixei claro que o projeto precisava ser cross-platform, com tratamento real de erros como EACCES e ENOSPC, funcionando em Windows, macOS e Linux.
Updates sem sobrescrever customização
Esse foi um ponto onde a IA sozinha não resolveria. O problema era atualizar templates base sem destruir customizações do usuário. A sugestão óbvia foi usar git diff. Minha resposta foi simples: e se não tiver git? E se o repositório estiver sujo?
A solução foi arquitetural. Cada arquivo gerado recebe uma assinatura criptográfica em SHA-256 embutida em comentário. Se o hash bate, o arquivo está pristine e pode ser atualizado. Se diverge, foi modificado e deve ser preservado. O Claude implementou perfeitamente, mas a decisão foi humana. Esse ponto, inclusive, foi um dos mais elogiados na análise técnica, comparado a estratégias usadas em manifests do Kubernetes.
Testes: onde a IA realmente brilhou
Eu não gosto de escrever testes (embora escreva), e aqui a IA foi absurda. Pedi testes unitários para o detector e, em minutos, havia 17 casos cobrindo todos os frameworks. Depois pedi mais: 30 cenários E2E, cross-platform. Vieram testes de instalação, atualização, validação e lifecycle de tarefas, rodando em Linux, Windows e macOS no CI. Isso seria dias de trabalho manual.
Levou poucas horas.
TypeScript Strict, sem concessões
Aqui eu fui chato, mas seria comigo mesmo de qualquer forma. Strict mode, zero any. A regra estava explícita e a IA respeitou. Na análise técnica, a nota de type safety foi 95/100.
O Feedback Brutal e Honesto
Os pontos fortes foram claros: arquitetura limpa, sistema de assinaturas SHA-256, 30 cenários E2E cross-platform e TypeScript estrito. As red flags também foram justas: comando diff anunciado e não implementado, dependência instalada e não usada, e poucos testes no updater, um módulo crítico.
A nota final foi 88/100.
O Que Aprendi Nessas Primeiras 24 Horas
IA não substitui julgamento; ela executa. Testes deixaram de ser desculpa; em 2026, não ter testes é escolha. E velocidade não precisa matar qualidade quando existe processo.
Números, 24 Horas Depois
Foram cerca de 2.000 linhas de core e 2.000 de testes, 30 cenários E2E, TypeScript strict sem any. Sem IA, isso teria levado de uma a duas semanas. Com IA, levou cerca de 24 horas reais — incluindo uma ida ao shopping com a família no meio do dia. O projeto estava funcional, testado e publicado no npm. Exatamente como eu queria: uma versão evoluída do meu antigo gerenciador jurássico em Markdown.
O Que Veio Depois
Nos dias seguintes, usei o AIPIM para gerenciar o próprio AIPIM:
- Documentei nove sessões
- Completei 31 tarefas
- Escrevi oito ADRs
- Corrigi todas as 16 red flags
- Subi a nota de 88 para 90.
Mas isso fica para um próximo post, porque esse já passou do limite saudável de longform (mesmo eu gostando).
Para Quem Quiser Ir Além
O relatório técnico completo está disponível no repositório, gerado com Claude Code (Sonnet 4.5), e pode ser lido na íntegra. O AIPIM já está no npm e no github.
O uso é fácil e está explicado no README.