O método de codificação com IA de “guia curta” que vence o Fable
(blog.okturtles.org)- Para usar agentes de codificação com IA em software sensível à segurança, é necessário um método de guia curta no qual o desenvolvedor continua controlando as mudanças, em vez de delegar a execução autônoma
- A abordagem no estilo “vibe”, em que vários agentes criam e revisam código em paralelo, pode enfraquecer a compreensão da base de código e fazer com que os problemas só sejam descobertos depois que a IA já saiu off the rails
- O procedimento central segue por planejamento, decomposição em etapas, revisão de diff nos prompts de permissão, recusas e intervenções frequentes, commits por subtarefa e revisão final
- Em revisões de PR, usar IA e humanos juntos pode reduzir mais erros; a IA detecta erros comuns rapidamente, e os humanos avaliam problemas de nível mais alto e a direção do trabalho
- Se a IA participou da escrita, o autor do PR deve revisar pessoalmente cada linha e informar no PR description, em AI Disclosure, quais modelos foram usados para ganhar confiança
Pré-requisitos para usar agentes de codificação com IA
- Este método se baseia na experiência de usar agentes de IA para produzir software de alta qualidade em sistemas sensíveis à segurança
- O público-alvo não são desenvolvedores iniciantes, que deveriam ver a IA como inimiga do aprendizado, mas sim desenvolvedores especialistas que superam os “frontier AI models” em sua própria área de especialização
- O objetivo é usar a IA como ferramenta de aumento de desempenho sem sacrificar a qualidade do software
- O escopo da experiência inclui explorar os limites dos agentes de IA, criar ferramentas próprias de revisão com IA e manter um fork customizado do agente de codificação com IA Crush
Onde a abordagem no estilo “vibe” começa a falhar
- Em sessões com agentes de IA, dois problemas podem acontecer com frequência
- A ideia inicial é ruim, e só mais tarde se descobre que havia uma abordagem melhor
- O agente entra em estado off the rails e segue numa direção indesejada
- Quando vários agentes paralelos e um orquestrador trabalham ao mesmo tempo, e o desenvolvedor fica fora do processo de codificação, torna-se difícil construir entendimento direto da base de código
- Em contextos em que a qualidade não importa, esse método pode até servir, mas, quando a qualidade é importante, é preciso outra abordagem
- O código escrito ou revisado pelo Fable 5 pode funcionar, mas ainda assim ser ineficiente e feio de ler
- Em nichos onde há poucos dados de treinamento para o modelo se apoiar, esse problema pode aparecer com mais frequência
- Ao contrário do marketing de certos CEOs, esta visão entende que os modelos não conseguem raciocinar além de seus dados de treinamento
Como funciona o método de guia curta
- O método de guia curta não é algo que qualquer pessoa possa usar; ele foi pensado para desenvolvedores de software especialistas
- Uma vantagem é poder alcançar resultados melhores que o Fable mesmo sem usar um frontier model
- Antes de começar, há uma etapa de planejamento para pesquisar a tarefa e montar um plano
- Tarefas grandes são divididas em etapas e acompanhadas com ferramentas como tasks skill
- Nisso, há semelhanças com várias abordagens de “vibe engineering”
- Depois disso, o ponto central é manter a IA o tempo todo na guia curta
- Não usar o modo “YOLO” nem “dangerously skip permissions”
- Não deixar a IA trabalhando sozinha enquanto o usuário vai fazer outra coisa
- Usar agentes de codificação que mostrem o diff das mudanças pretendidas no prompt de permissão
- O desenvolvedor deve analisar de fato as mudanças propostas pela IA
- O diff no prompt de permissão serve para manter atualizada a compreensão da base de código e manter a IA sob controle
- Se a IA tentar fazer algo indesejado, a permissão deve ser negada
- É preciso intervir com frequência quando necessário para impedir que a IA perca o rumo
- Ao fim de cada subtarefa, cria-se um commit para evitar situações em que a IA estraga ou apaga trabalho anterior
- Isso pode acontecer de verdade, e houve casos observados no Opus
- A etapa final inclui uma revisão
Revisão com IA não substitui revisão humana
- Comparado a PRs revisados só por humanos ou só por IA, PRs revisados por humanos e IA juntos podem reduzir mais erros
- A IA pode ser tratada como um linter
- Detecta erros comuns rapidamente
- Os humanos avaliam problemas mais amplos e a necessidade de mudar a direção
- Recomenda-se que todo PR passe por revisão com IA
- A revisão com IA precisa de contexto suficiente
- issue
- descrição do PR
- base de código
- mudanças
- Recomenda-se usar, na revisão, o modelo mais recente disponível
AI Disclosure e responsabilidade do autor
- Se a IA foi usada para escrever o PR, o modelo exato utilizado deve ser informado na seção AI Disclosure da descrição do PR
- Essa divulgação tem vários objetivos
- Informar aos mantenedores que IA foi usada
- Se um modelo fraco foi usado, permitir que seja sugerido um modelo melhor
- Mostrar que não se está tentando introduzir IA às escondidas
- PRs com uso de IA devem ser revisados obrigatoriamente pelo próprio “autor” do PR
- Um PR com assistência de IA é, na prática, mais próximo de um PR da IA com ajuda humana; por isso, quem envia precisa entender o que está submetendo
- O autor deve revisar o próprio PR line-by-line, como se fosse o PR de outra pessoa
- Depois dessa auto-revisão, pode confirmar sua própria aprovação e pedir revisão aos mantenedores
- Esse processo serve para construir e demonstrar que o autor entende a base de código
Como a okTurtles aplica isso
- A okTurtles usa IA dessa forma
- A política oficial está resumida em AI Usage Policy
- O próprio texto foi escrito por um humano e inclui um AI Disclosure dizendo que, antes da publicação, só foi feita uma checagem ortográfica com estilo de IA
1 comentários
Opiniões no Hacker News
Esse método da “coleira curta” parece mais uma muleta do que uma ferramenta auxiliar, e soa como sinal de que o problema não foi explicado suficientemente bem à IA desde o início, ou de que a saída não foi revisada e iterada
Levar um modelo forte como o Fable pela mão na etapa de implementação é perda de tempo e desperdício do Fable. Quanto mais forte o modelo, mais sutis podem ser as discussões de design, e ele escreve código muito melhor do que antes. O próprio processo de discutir design e implementação, questionar partes que parecem estranhas e realmente ler as respostas da IA ajuda a encontrar soluções melhores
Antes, ao tentar criar uma solução com algoritmo guloso, durante uma discussão com o Opus recebi a sugestão de que o problema poderia ser resolvido exatamente com uma biblioteca MILP existente; eu nunca tinha ouvido falar de MILP, mas a implementação final ficou melhor e mais simples do que teria ficado se eu tivesse feito sozinho
Só que não funcionou; quando pedi que explicasse as etapas desse raciocínio a partir dos primeiros princípios, ele respondeu que, na verdade, tinha simplesmente inventado. Por isso é difícil acreditar nessa ideia de discussões sutis com o modelo
Se você investiu o suficiente na etapa de planejamento e a arquitetura e as convenções existentes do projeto são sólidas, talvez não seja necessário tanto acompanhamento na etapa de implementação quanto o texto sugere
A ideia de que “a ideia inicial era burra e dá para descobrir um jeito melhor” normalmente é descoberta em alto nível na etapa de planejamento e arquitetura
O problema de o agente “sair dos trilhos” em uma direção indesejada também não é tão ruim quanto antes, e mudanças com impacto deveriam ter ao menos uma cobertura mínima de testes. Mesmo que esse teste apenas “congele” o comportamento implementado. A discussão final de revisão é uma boa oportunidade para verificar além do que uma revisão, ou um agente de revisão adversarial, encontrou
O exemplo do MILP não é algo que essa abordagem impediria, e teria aparecido na etapa de planejamento
No fim, os detalhes importam, e a forma como você dá o prompt inicial da tarefa influencia. Ainda assim, conferir a saída, envolver-se no que o modelo está fazendo e perguntar insistentemente por que ele pretende fazer algo daquele jeito são processos indispensáveis
Mas as ideias desse funcionário não chegam à mesa, e contribuições que poderiam beneficiar a equipe inteira no longo prazo desaparecem
Isso me permite entender tudo o que é gerado e continuar mantendo conhecimento operacional da codebase. Também facilita redirecionar o rumo
Fiz isso por duas semanas em um projeto paralelo, mas no fim fiquei sem um modelo mental da codebase
Fiquei ainda mais convencido de que não há como construir esse modelo sem criar a coisa diretamente
Por causa da curva de esquecimento, meu modelo mental não dura muito além do período em que eu estava criando pela primeira vez. Ainda não descobri como reconstruí-lo
Ainda assim, concordo que não se desenvolve tão bem a “capacidade de eu mesmo construir” como quando você escreve diretamente
Por exemplo, eu sei que meu modelo mental funciona porque sei quais mudanças fazer para obter certo efeito e, quando as faço, o resultado esperado aparece. Mas, se me pedissem para criar algo parecido do zero, acho que eu não conseguiria. Parece que a abordagem está fora do alcance das minhas mãos, mas é difícil explicar
Achei que quem realmente sabe programar usa IA assim quando a usa para coisas importantes
Estou errado? Hoje em dia todo mundo simplesmente roda no modo YOLO?
É a diversão do funemployment. Quando eu voltar a trabalhar, deve ser uma mudança bem interessante
Por enquanto é simples: deixo rodando, tomo uma cerveja enquanto, por cerca de uma hora, ajusto críticas de alto nível e feedback de autoavaliação/loop fechado recém-configurado, depois deixo rodar livremente de novo
Fico curioso sobre como usar o Claude de outra forma que não seja com bypass-permissions. Tentei por bastante tempo gerenciar a lista de ferramentas que o Claude pode usar, mas, no fim, quando eu voltava, ele estava parado porque tinha tentado canalizar a saída de uma ferramenta para outra e isso não estava explicitamente permitido. Era algo simples como
grep, mas era irritante ver parar mesmo assimCom bypass-permissions, “simplesmente funciona”. Claro, eu uso apenas para analisar código existente e sugerir mudanças; se algo quebrar, é para isso que existe controle de versão
Concordo em grande parte com o autor. Acima de tudo, eu acrescentaria: não confie em nada que uma LLM faça ou diga
Hoje pedi ao Claude para unificar o comportamento de 3 componentes, e mandei fazer isso 5 vezes. Todas as vezes, no fim, ainda havia partes que não estavam corretas, e o Claude encontrava um jeito de racionalizar aquilo
Quando eu perguntava, ele respondia “a responsabilidade é minha” ou “achei que fosse uma escolha intencional”, mas nunca perguntou primeiro o que deveria fazer nem apontou o problema. Então é preciso mantê-lo na coleira curta, observar o processo de pensamento e corrigir as bobagens. Isso vale para o Sonnet 5 hoje; amanhã pode melhorar ou piorar. O tom que funciona com o Claude hoje pode produzir resultados diferentes amanhã
O problema em textos do tipo “como fazer X com IA” é que tudo varia conforme a situação. Por exemplo, a tarefa de atualizar um projeto Symfony da versão 3.1 para a 8.1 tem um caminho claro
Basta seguir os guias de migração escritos para cada versão major e testar todas as rotas, fluxos de autenticação etc. Esses testes também podem ser escolhidos manualmente; alguns podem retornar 200, outros 302
Opcionalmente, dá para criar primeiro uma rede de segurança para reduzir testes manuais e, por exemplo, definir uma baseline do PHPStan
Se as rotas funcionam de ponta a ponta como pretendido, acabou. Também dá para usar testes de snapshot aqui
Nesse caso, não é preciso ficar vigiando a IA. Dá para revisar o código no final, mas não é necessário aprovar manualmente no meio do caminho, então desativo os recursos de segurança
A maioria escreve a partir de uma única perspectiva, mas as perspectivas reais são amplas, e o que funciona em uma situação não funciona em outra. No fim, engenharia de software como um todo é quase o trabalho de entender o que aplicar, onde e quando, e ignorar o resto
Muitos posts em blogs de empresas fazem parecer que existe uma bala de prata que funciona para todos os casos, mas geralmente isso não é verdade
No fim, é mais próximo do que a engenharia de software sempre tratou: “certas coisas funcionam em certas situações”; não é tanto uma questão de certo ou errado, e sim de aplicação prática diferente conforme o contexto, o que é normal
A IA é algo entre um engenheiro júnior e um intermediário. Se você a tratar assim, consegue aproveitar tanto as vantagens do vibe coding quanto da engenharia rigorosa sem toda essa paranoia
Desde o começo rodei o Claude em modo YOLO dentro de uma VM isolada. É como dar um notebook próprio a um engenheiro. O Claude implementa a funcionalidade até um ponto em que ela pode virar PR, e eu reviso o diff como faria com qualquer outro engenheiro, ajusto para o formato adequado e sigo em frente
Engenheiros inexperientes cometem os mesmos erros. Já vi
rm -rf, embora não na raiz. Se eu ficasse micromanageando alguém e negando todas as permissões, acho que enlouqueceriaTambém concordo com a analogia do engenheiro júnior/intermediário, mas há uma ressalva enorme. A IA é como um engenheiro júnior que não sabe aprender
É como trabalhar com o protagonista de Memento. Todo dia, quando o LLM chega ao trabalho, ele não aprendeu nada do que fez até então; todo dia é o primeiro dia
Claro, como com o protagonista de Memento, dá para ajudar espalhando post-its e lembretes pelo workspace. Com esforço, dá para chegar perto de algo chamado “aprendizado”, que é literalmente a característica mais importante em todos os desenvolvedores de software da equipe
Mas não é fácil, e as ferramentas ainda são insuficientes. O melhor que consegui fazer foi algo próximo de um “segundo cérebro” usando ferramentas como o Obsidian. Infelizmente, acho que um segundo cérebro não substitui o primeiro. Sinceramente, se um engenheiro não conseguisse aprender e crescer como um agente de IA, ele teria sido demitido depois do primeiro mês em qualquer empresa em que já trabalhei
Ainda assim, estou bastante otimista de que os principais provedores de IA, ou alguém, vão melhorar isso no futuro. Se houver uma boa memória combinada com um sistema de raciocínio bem projetado que injete melhor as lembranças conforme o contexto, e se for possível capturar aprendizado real sem supervisão, não parece uma tarefa impossível
Leio textos assim esperando que alguém já tenha resolvido esse problema e que eu só esteja percebendo tarde, mas, por enquanto, minha capacidade de projetar agentes só melhorou um pouco em relação ao começo
Minha regra prática é que qualquer processo especial criado para a IA também deve fazer sentido para humanos; se não fizer, não tem valor. Boas ferramentas de linha de comando, resumos automáticos de saídas longas de comandos, documentação em Markdown e workflows também são úteis para pessoas
Para evitar erros e abuso, o caminho não é micromanagement, e sim sandboxing e permissões com escopo limitado
O que quero descobrir é um bom workflow de pair programming com um agente de IA. Dá para atribuir tarefas grandes a um modelo de alto desempenho, e isso funciona bem. Também dá para usar um modelo de baixo nível como assistente na IDE, e isso também funciona bem. Mas são dois workflows separados
O que seria realmente útil é trabalhar junto com um modelo de alto desempenho, alternando quem está no teclado. Só que isso não deve ser rodado em modo YOLO total na minha máquina. Essa é a diferença entre humanos e LLMs. Como ele é rápido demais, quando sai dos trilhos fica difícil puxar o teclado de volta a tempo
Ninguém sabe exatamente o que é a IA, mas ela não é um engenheiro júnior nem intermediário. Está mais para um staff engineer nuclear morando num barraco, sem contexto de domínio e acordando sem memória a cada 5 horas
LLMs continuam sendo preditores do próximo token. O fato de eles conseguirem encontrar os passos corretos mesmo quando você dá instruções mais ambíguas não significa que sejam inteligentes. Significa que você está falando a mesma linguagem do harness usado no treinamento do modelo
E há limites nisso. Se você fica no nível de prova de conceito ou de apps simples, talvez não perceba o quanto os modelos atuais ainda são limitados. Nesses casos, é preciso quebrar o trabalho em partes, não confiar em um preditor de tokens que enumera passos plausíveis
Em algum ponto, precisa haver necessariamente um humano no loop. Quando você começa a pular permissões, o melhor cenário é um grande acerto, mas o mais provável é uma solução subótima e desperdício de tokens. O que realmente assusta é o modelo ignorar instruções e fazer alguma bobagem que estrague o seu dia
Isso é afiado como uma máquina CNC. Não quer dizer que não seja útil, mas pode ser perigoso. Se você não consegue fazer baliza, é melhor não tentar entalhar madeira com uma máquina monstruosa nem estacionar uma Ferrari em um bairro apertado
Dizer que uma LLM consegue ou não consegue fazer algo por ser um “preditor de tokens” é um erro de categoria. A interface não é um limite rígido
Fico curioso para saber como seria possível uma definição que exclua modelos de linguagem e inclua humanos, sem partir do axioma de que LLMs não têm inteligência
Normalmente, o que se quer dizer com isso é “ela só prevê o próximo token dos dados de treinamento, ou seja, da internet”, o que pode ser verdade para modelos brutos. Mas os modelos passam por pós-treinamento, então nem essa descrição continua correta
Dizer “não é inteligência” não é útil e, na minha opinião, está errado. Quem se importa se isso se encaixa na sua definição de inteligência? Eles ainda fazem coisas impressionantes, e coisas muito mais incríveis do que você dá a entender
O post original parece ainda preso em 2025
Ele diz que “a IA vai sair dos trilhos várias vezes e só vai perceber quando de fato usar o software”, mas agora essa IA consegue usar o software diretamente para encontrar e corrigir bugs, além de impulsionar novos recursos
Agentes ainda começam a fazer coisas indesejadas, mas isso diminuiu muito em relação a antes, e o argumento a favor de agentes totalmente autônomos está ficando mais forte, não mais fraco
A afirmação de que “é humanamente impossível uma pessoa entender a base de código” também parece ultrapassada. Acho que estamos indo para uma direção em que humanos não precisam mais entender a base de código, e a IA passa a conduzir isso
Muita gente está entrando nessa, mas eu vejo como uma moda idiota
Mas de jeito nenhum para sistemas com alto risco de segurança. Em áreas como bancos, aviação e defesa, a IA certamente vai contribuir, mas não poderá operar independentemente da compreensão de engenharia humana
O método da coleira curta é uma forma de garantir bons resultados ao trabalhar fora dos dados de treinamento. Para qualquer programador só um pouco acima da média, essa é a única forma de garantir desenvolvimento rápido e de qualidade com LLMs, na minha visão
A ideia de que humanos não precisam mais entender a base de código parece vir de desconhecer o mundo da programação em que a IA ainda é desastrosamente ruim. Tenho visto ela errar com frequência no gerenciamento de memória em linguagens com gerenciamento manual de memória. Não é algo tão simples quanto colocá-la em um loop com Valgrind
Refinamos várias vezes as definições da API, os modelos de request/response, o schema do banco de dados e o fluxo completo, e eu fiz pessoalmente muita remoção de contradições e correção da documentação. O Opus continuava saindo dos trilhos, e o documento final passou de 500 linhas
Também tivemos idas e vindas nos testes de integração da API. Como a IA não conseguiu criar testes diretamente a partir da documentação, primeiro criei placeholders com comentários Given-When-Then, revisei e corrigi manualmente, e só na segunda iteração ela implementou os testes. Havia muitos erros que precisei corrigir após a revisão
Na etapa de implementação, forneci a documentação da API, testes funcionais, hooks de bloqueio de modificações, mais de 6 skills de “boas práticas”, agentes de “rubber duck” e “simplificação de código”, além de scripts para verificar testes, linter e erros de compilação. Depois de planejamento, execução, revisão e várias rodadas de correções, a funcionalidade foi implementada e todos os testes passaram
Na revisão de código, encontrei em média um problema a cada 20 linhas de código. Mesmo excluindo estilo de código, havia uso de semáforo em memória em um serviço Kubernetes, 8 chamadas ao banco para tentar atualizar o mesmo registro em uma única request, atualização de uma coluna por vez, leitura-modificação-salvamento sem transação, além de erros de lógica de negócio, recuperação e autorização
O resultado foi quase uma semana de trabalho, mais de 100 dólares em custos de tokens e apenas a sensação de “será que esse esforço valeu a pena?”. Tenho uma equipe com 2 desenvolvedores, e acabei de revisar o PR de um deles: 80% era slop
Tentei uma abordagem parecida, mas não funcionou bem para mim. O ganho de velocidade foi pequeno ou inexistente. Para obter produtividade, acho que é necessário algum grau de modo YOLO dentro de uma sandbox
O objetivo deve ser terceirizar para o modelo o máximo de trabalho possível, minimizando o esforço necessário para entender e revisar o resultado
Por exemplo, encarregar o modelo de encontrar a causa de um bug, criar uma prova de conceito de X, otimizar algo de forma incremental, fazer uma refatoração bem definida com orientação etc.
O que as pessoas chamam de criar loops também é muito parecido: maximizar o que o modelo faz e minimizar o que eu preciso fazer para controlá-lo
O texto não tinha muito conteúdo
No ano passado era “IA é apenas um papagaio estocástico”
Este ano é “IA até consegue escrever código, mas humanos ainda precisam revisar!”. Claro que também usam IA nessa revisão
Se passar só mais um ano, a narrativa vai virar “revisão de código só pode ser feita por IA, e só a IA pode revisar a revisão da IA. Para manter uma supervisão significativa, humanos só precisam ler a opinião final da IA”
As traves continuam mudando de lugar, mas a convicção nunca muda