Nos últimos tempos eu venho estudando bastante desenvolvimento assistido por IA, agentes de código, SPECs, policy gates, revisão humana, evidências e fluxos de trabalho mais seguros antes de abrir um pull request.
Como parte desse estudo, criei um projeto pessoal chamado DevForge CLI.
A ideia inicial era ambiciosa:
E se existisse uma CLI local-first capaz de ajudar a governar mudanças feitas com IA antes do merge?
O fluxo que eu queria era mais ou menos este:
init -> scan -> specify -> plan -> implement -> policy check -> review -> evidence -> pr-ready
Ou seja:
- inicializar uma estrutura local de governança;
- escanear o projeto;
- transformar uma ideia em SPEC;
- gerar um plano;
- entregar um briefing para um agente de IA implementar;
- rodar um policy check no diff;
- registrar revisão humana quando necessário;
- gerar um pacote de evidências;
- preparar orientação de commit e pull request.
Na minha cabeça, isso parecia um fluxo bem lógico.
Mas, testando na prática, descobri que o problema real era mais difícil.
A ideia original
O DevForge CLI nasceu como uma tentativa de organizar o caos do desenvolvimento assistido por IA.
Hoje é muito fácil pedir para uma IA implementar uma feature. O problema começa depois:
- O que exatamente ela deveria implementar?
- Qual era o escopo?
- Ela tocou arquivos sensíveis?
- Ela inventou coisa fora da SPEC?
- Existe evidência de teste?
- Alguém revisou?
- O pull request está minimamente explicável?
- O que deve ou não entrar no commit?
Eu queria uma CLI que criasse uma trilha local, simples e auditável.
A ideia não era substituir Cursor, Copilot, Codex, Claude Code ou qualquer agente de código. A ideia era criar um “cinto de segurança” ao redor deles.
Algo como:
Agentes executam. DevForge governa.
Pelo menos essa era a ideia inicial.
O que funcionou bem
Algumas partes funcionaram melhor do que eu esperava.
1. SPECs e briefs ajudam muito
Uma das melhores descobertas foi que o valor não estava apenas no comando em si, mas nos artefatos gerados.
Por exemplo:
- Specification Brief;
- SPEC;
- Plan Pack;
- Context Pack;
- Implementation Brief;
- Agent Instructions;
- Policy Decision;
- Human Review;
- Evidence Pack;
- PR Ready guidance.
Esses arquivos em Markdown e JSON ajudam a tornar o processo mais explícito.
Em vez de simplesmente dizer para a IA:
implemente essa feature
o fluxo passa a gerar algo mais estruturado:
implemente a feature usando este briefing, dentro deste escopo, respeitando estas restrições, e depois rode policy check.
Isso já melhora bastante a qualidade do handoff entre humano e agente.
2. O Evidence Pack foi útil
Outra parte que fez sentido foi o pacote de evidências.
A ideia era simples: antes de abrir ou mergear um PR, gerar um resumo local com:
- diff analisado;
- policy decision;
- test report;
- revisão humana, se exigida;
- rollback plan, se exigido;
- audit log;
- decisão final.
Isso não prova que a mudança está perfeita, mas ajuda a responder:
O que foi feito, quais riscos foram identificados e quais evidências existem?
Para um projeto pessoal, isso já foi um aprendizado importante.
3. O PR Ready também fez sentido
Outra parte útil foi o comando que prepara orientação para commit e pull request.
Em vez de simplesmente mandar o usuário fazer:
git add .
git commit -m "..."
o DevForge passou a sugerir quais arquivos deveriam entrar e quais deveriam ficar fora.
Por exemplo:
Required files to commit:
- app.py
- db_create.py
- templates/index.html
- specs/SPEC-...
- docs/rollback/...
- .devforge/evidence/...
Do not commit:
- .venv/
- *.db
- *.sqlite
- __pycache__/
Isso parece pequeno, mas ajuda muito quando agentes de IA geram vários arquivos e artefatos.
Onde começou a quebrar
O problema apareceu quando tentei fazer o DevForge entender projetos diferentes de forma determinística.
No primeiro teste, usei um Todo App com Flask e SQLite.
A feature era simples:
Adicionar prioridade às tarefas: Baixa, Média e Alta.
Nesse caso, o DevForge até fazia sentido. A feature tocava formulário, template, código Python e banco SQLite. Então fazia sentido falar de schema, rollback plan, test report e revisão humana.
Mas depois testei em outro projeto: uma calculadora CLI simples em Python.
A nova feature era:
Adicionar histórico de cálculos durante a sessão.
Esse projeto não tinha:
- banco;
- autenticação;
- cloud;
- dados pessoais;
- schema;
- login;
- permissões.
Era apenas uma CLI local.
E aí os problemas apareceram.
O problema das heurísticas
O scanner e o planner começaram a confundir palavras.
Por exemplo:
-
input()parecia dado de usuário; -
userparecia dado pessoal; -
sessionparecia autenticação; - “no database” ainda continha a palavra
database; - “sem banco” ainda continha a palavra
banco.
Ou seja: o código estava tentando interpretar intenção usando heurísticas simples.
E isso é frágil.
A palavra “session” pode significar uma sessão autenticada em um sistema web, mas também pode significar apenas “sessão local de uso” em uma calculadora CLI.
A palavra “user” pode significar um usuário cadastrado, com dados pessoais e permissões, mas também pode significar apenas “a pessoa usando o terminal”.
A frase “no database” fala justamente que não tem banco, mas um scanner ingênuo pode ver a palavra “database” e classificar risco errado.
Esse foi o ponto em que ficou claro:
O problema não era só corrigir keywords. O problema era arquitetural.
A grande descoberta
A principal descoberta foi esta:
O DevForge não deveria tentar ser um scanner universal que entende qualquer projeto sozinho.
Ele deveria ser um harness de governança.
Ou seja, em vez de fingir que sabe tudo, ele deveria:
- coletar sinais determinísticos;
- gerar um Project Profile preliminar;
- expor assumptions e gray areas;
- permitir revisão ou refinamento por IA externa;
- exigir aprovação humana do perfil;
- gerar SPECs e planos como drafts revisáveis;
- registrar evidências e decisões.
A diferença é sutil, mas importante.
Antes eu pensava:
DevForge entende o projeto -> decide o risco -> gera o plano
Depois dos testes, passei a enxergar melhor assim:
DevForge coleta sinais -> gera artefatos revisáveis -> guia IA e humano -> registra decisões
Isso é muito mais realista.
O scanner não deve decidir sozinho
Um scanner determinístico é útil para coisas como:
- listar extensões;
- detectar arquivos
.py,package.json,pyproject.toml,go.mod; - encontrar migrations;
- detectar arquivos
.env; - detectar bancos locais;
- calcular diff;
- identificar arquivos gerados;
- registrar audit trail.
Mas ele não deveria concluir sozinho:
este projeto lida com dados pessoais
ou:
esta feature é autenticação
ou:
essa mudança exige aprovação humana
sem considerar contexto, SPEC e revisão.
A melhor função do scanner é gerar um draft.
Um draft pode estar errado.
E tudo bem — desde que o fluxo deixe isso claro.
O papel da IA nesse fluxo
Curiosamente, eu comecei tentando criar uma ferramenta para governar IA, mas acabei percebendo que a própria IA também pode ajudar no processo de governança.
Só que não como mágica escondida.
O uso mais interessante da IA aqui seria:
- revisar um Project Profile;
- identificar gray areas;
- melhorar uma SPEC;
- revisar um Implementation Brief;
- apontar riscos em um diff;
- sugerir evidências necessárias.
Mas sempre com uma regra:
A IA pode ajudar a raciocinar, mas a decisão importante precisa ser explícita, revisável e aprovada por humano.
No DevForge, isso levou à ideia de separar:
deterministic signals
agent-assisted reasoning
human-confirmed governance
Esse modelo é muito mais forte do que tentar fazer tudo com regras fixas.
O que eu aprendi com o projeto
Algumas lições ficaram bem claras.
1. Heurísticas são boas para sinais, não para verdade final
O scan pode dizer:
encontrei arquivos Python
encontrei SQLite
encontrei migrations
encontrei arquivos alterados
Mas não deveria dizer com confiança absoluta:
essa feature é de alto risco
sem contexto suficiente.
2. SPEC é mais importante do que parece
A SPEC virou o contrato da mudança.
Quando a SPEC era fraca, o plano ficava ruim.
Quando a SPEC tinha objetivo, fora de escopo, riscos, critérios de aceite e gray areas, o fluxo melhorava.
Isso me fez perceber que, em desenvolvimento com IA, especificar bem é quase tão importante quanto codar.
3. “Handoff” é uma palavra-chave
O maior valor do DevForge não foi automatizar tudo.
Foi criar handoffs melhores:
- da ideia para a SPEC;
- da SPEC para o plano;
- do plano para o agente;
- da implementação para o policy check;
- do policy check para a revisão;
- da revisão para o Evidence Pack;
- do Evidence Pack para o PR.
Esses handoffs tornam o processo mais rastreável.
4. Governança não é bloquear tudo
No começo, o fluxo tendia a exigir revisão humana e rollback plan em excesso.
Mas isso também é ruim.
Uma mudança local, simples, sem banco, sem auth e sem dados pessoais não deveria ter o mesmo peso de uma mudança em login, pagamento ou dados sensíveis.
Governança boa precisa ser proporcional.
5. Projeto experimental precisa dizer que é experimental
Esse talvez seja o ponto mais importante para um projeto público.
Depois dos testes, reposicionei o DevForge CLI como:
A local-first experiment for AI-assisted software governance.
E deixei claro:
- não é ferramenta de compliance;
- não é produto de produção;
- não é scanner universal;
- não garante segurança;
- outputs são drafts revisáveis.
Isso é mais honesto e, para mim, mais útil como projeto de aprendizado.
O estado atual do DevForge CLI
Hoje eu vejo o DevForge CLI como um laboratório pessoal.
Ele ainda tem comandos funcionais como:
devforge init
devforge scan
devforge profile approve
devforge specify --idea "Describe your feature idea"
devforge plan --spec specs/SPEC-ID.md
devforge implement --spec specs/SPEC-ID.md --agent custom --command "echo" --dry-run
devforge policy check --diff
devforge review --issue SPEC-ID
devforge evidence --issue SPEC-ID
devforge pr-ready --issue SPEC-ID
Mas tudo isso deve ser tratado como experimento.
Não é para confiar cegamente.
É para estudar o fluxo.
O que eu faria diferente se começasse de novo
Se eu fosse recomeçar do zero, eu faria diferente:
- começaria pelo modelo de artefatos, não pelo scanner;
- trataria todo scan como evidência bruta;
- colocaria Project Profile como etapa aprovada pelo usuário;
- usaria IA externa para refinar briefs e gray areas;
- manteria as decisões importantes sempre editáveis e auditáveis;
- evitaria qualquer promessa de produto antes de testar em muitos projetos reais.
Em resumo:
Eu não tentaria construir um scanner mágico. Eu construiria primeiro um sistema de handoffs.
Conclusão
O DevForge CLI não provou que uma CLI consegue governar automaticamente qualquer repositório.
Mas ele mostrou algo mais útil:
Desenvolvimento assistido por IA precisa de contexto, contratos, evidências, revisão humana e handoffs estruturados.
No fim, o valor não estava em fazer a ferramenta “entender tudo”.
O valor estava em organizar melhor a conversa entre humano, projeto, agente de IA e pull request.
E, para mim, isso já fez o projeto valer a pena.
Repositório: https://github.com/mffdeo/devforge-ai-cli
Landing page: https://mffdeo.github.io/devforge-ai-cli/
