No meu último post, mostrei por que a verificação é a base de tudo que faço com agentes e como começar a criar suas próprias habilidades de verificação. A principal lição foi que, se um agente não consegue verificar seu próprio trabalho, nada mais importa. Você continua sendo o gargalo, e seu dia inteiro será gasto cuidando dos seus agentes.
https://x.com/poteto/status/2094457600259842065
Mas, uma vez que a verificação está funcionando, a próxima pergunta é: como você descobre o que construir?
https://x.ai/bot/plugin/9717366
Neste post, vou te guiar por como faço pesquisa, planejamento, prototipagem e arquitetura com pstack. Este é o fluxo de trabalho exato que me permite enviar milhares de PRs por mês para produção, mantendo a qualidade do código extraordinariamente alta.
Encerrando o mês de agosto com 2.462 PRs em produção
A arte de supervisionar alguém mais inteligente que você
Nos velhos tempos de 2024, para fazer qualquer alteração em um sistema, primeiro você precisava ler o suficiente para construir um modelo mental do que estava acontecendo. Dependendo do tamanho e da complexidade do código, isso poderia levar de horas a dias e até meses. Com uma mudança pequena, você poderia se safar com um entendimento local de um pequeno subsistema. No entanto, se estivesse refatorando o núcleo, provavelmente precisaria de um modelo mental de como tudo funciona para fazer a refatoração correta e eficaz.
Os agentes obviamente removem essa barreira. Você pode fazer alterações em sistemas facilmente apenas dando instruções ao seu agente, e ele fará, independentemente de quanto você sabe ou não sobre o código. Mas manter a qualidade do código e da experiência do usuário ainda é difícil, especialmente se você não é um especialista no domínio que sabe o que procurar e perguntar.
Embora os modelos de fronteira tenham se tornado muito capazes, ainda existem 2 modos de falha que observo constantemente:
- Eles não conseguem entender completamente sua intenção porque estão mal ou insuficientemente especificados.
- Eles não têm contexto suficiente sobre como fazer o trabalho corretamente.
Ambos os problemas estão relacionados. Usar agentes bem se resume a quão bem você consegue preparar a janela de contexto do agente com contexto de alta qualidade. Você certamente pode escrever código que funciona sem fazer isso, mas acho que os resultados e a qualidade são muito melhores quando fiz o trabalho de fornecer aos meus agentes tudo o que precisam para fazer um trabalho de alta qualidade.
Em suas próprias palavras
Os modelos de fronteira são codificadores muito capazes. Enquanto com modelos mais antigos eu poderia dar instruções muito específicas sobre o que queria que ele fizesse, quase microgerenciando-os, os modelos mais recentes são capazes de escrever código melhor do que você ou eu. Portanto, há um equilíbrio delicado que quero alcançar ao dizer ao agente o que quero que ele realize, ao mesmo tempo que lhe dou a liberdade para resolver de maneiras que talvez eu não tenha pensado.
Esta é a arte de supervisionar alguém mais inteligente que você, em um código que você mesmo não escreveu, e onde os humanos não conseguem mais encaixar todo o modelo mental do código em suas cabeças.
Uma técnica que gosto de usar é o prompt indireto. Em vez de dizer exatamente o que quero ao agente, tento extrair isso dele – em suas próprias palavras.
Por exemplo, quando alguém relata um problema no Slack, muitas vezes peço ao agente para ler a thread e reformular o problema em suas próprias palavras antes de fazer qualquer outra coisa.
Por exemplo, posso dizer:
/poteto-mode leia esta thread do slack. reformule em suas próprias palavras e em português claro qual você acha que é o problema subjacente
Isso realiza três coisas:
Primeiro, força o agente a comprimir uma conversa ruidosa em uma declaração de problema estruturada. Segundo, me permite detectar mal-entendidos imediatamente. Se o agente se fixar em uma pista falsa na thread, posso corrigi-lo rapidamente antes que ele comece a escrever qualquer código.
E terceiro, não o levei potencialmente pelo caminho errado ao declarar minhas próprias suposições e hipóteses, que podem estar incorretas ou limitar o que o agente poderia alcançar.
Construindo um modelo mental
Pedir ao agente para se reformular de uma forma que você possa entender é uma parte importante do trabalho com alguém mais inteligente que você. Essa foi a inspiração para /teach, uma habilidade que ajuda seu agente a explicar as coisas para você de forma intuitiva. Eu a uso sempre que preciso ter certeza de que meu agente está fazendo algo que faz sentido para mim.
Nos bastidores, /teach chama /how e /why.
/how rastreia a mecânica de tempo de execução. Quando você pergunta /how, o agente avalia a complexidade do subsistema. Se o subsistema abranger vários diretórios ou serviços, ele gera agentes exploradores paralelos em modelos rápidos e eficientes como Grok.
/how a virtualização é implementada?
/why investiga motivação e intenção. O código diz o que acontece. Raramente diz por que alguém o escreveu daquela forma. Quando você executa /why, o pstack consulta evidências históricas em várias fontes em paralelo: histórico do Git e comentários de revisão de PR, tickets do Linear, documentos de design do Notion, conversas do Slack, monitores do Datadog, erros do Sentry, linhagem de código e eventos do warehouse de análise.
/why ainda estamos presos a uma versão antiga do node.js?
Eu uso /teach sempre que quero que o agente reformule algo para que eu possa entender e confiar melhor em seu trabalho.
/teach me por que você implementou desta forma e não de <outra forma>. quais foram os trade-offs que você fez e por quê?
Na prática, também descobri que a pesquisa feita pela habilidade /teach não é útil apenas para humanos, mas também para agentes. Mesmo com os modelos de fronteira mais recentes (isso também depende da qualidade do harness), em geral, acho que eles ainda costumam afirmar coisas com confiança sem respaldá-las com dados ou realmente ler o código necessário para construir um modelo mental de como funciona. Então, esse ato de te ensinar o que vai fazer e por que acaba ajudando o agente também.
Aprendendo com a história
Muitos dos meus projetos abrangem várias conversas. Por exemplo, alguns meses atrás, eu estava trabalhando na correção de bugs de virtualização e problemas de desempenho que as pessoas estavam relatando no Cursor. Percebi que toda vez que iniciava um novo chat, tinha que basicamente começar do zero para construir o contexto rico que meu agente tinha antes, quando estava resolvendo um problema semelhante.
O que percebi é que suas transcrições passadas são frequentemente uma mina de ouro para contexto rico. O pstack vem com a habilidade /recall para puxar seu contexto recente do histórico do chat, para que mesmo agentes novos tenham o contexto certo necessário para voltar a um bom estado.
/recall o trabalho que fiz ontem sobre virtualização e depois leia este relatório de bug no slack
Usar /teach, /recall, /how e /why é como mantenho meus próprios modelos mentais do código atualizados, comprimidos em uma forma que posso entender e lembrar facilmente. E também ajuda os agentes!
Trabalhando de trás para frente
Depois de entender o problema, como você especifica a solução?
Na minha opinião, a maioria dos harnesses que têm modos de plano tendem a especificar demais os detalhes de implementação e especificar de menos todo o resto. É por isso que no pstack, eu disse, de forma brincalhona, que "não acredito em planejamento". A verdade é que eu planejo, mas faço isso através do código.
Para certos tipos de trabalho, como criar código compartilhado ou pacotes que outros usarão, sou um grande defensor do desenvolvimento orientado por README. Se você não está familiarizado, é uma técnica de desenvolvimento que foi popular antigamente, onde você começa criando seu README primeiro. Isso te força a colocar o chapéu de experiência do desenvolvedor, onde você começa descrevendo as APIs para um usuário hipotético e trabalha de trás para frente até a implementação e arquitetura.
Por exemplo, quando estava construindo o Dune, nosso framework cliente interno para aplicativos desktop, comecei escrevendo um tutorial para ele, para entender como seria construir um aplicativo com ele. Ou pelo menos tentei. Foi uma verdadeira luta fazer o agente produzir algo bom ou legível. Então, tive que primeiro passar algum tempo afiando minha faca, criando a habilidade /technical-writing.
A primeira versão do README sem a habilidade /technical-writing era dolorosa de ler porque misturava objetivos diferentes. Tentava ser um tutorial, um guia de como fazer, uma explicação arquitetural e uma referência de API tudo no mesmo documento, escrito com aquele lixo de IA usual e prosa maneirista.
/technical-writing usa o framework Diátaxis para separar a documentação em quatro modos distintos:
- Tutorial: Aprender fazendo. Uma lição que guia um novato por uma série de passos para construir algo visível.
- Guia de como fazer: Passos para resolver um problema específico do mundo real para um usuário experiente.
- Referência: Descrições técnicas secas, completas e autoritativas de maquinários, APIs e flags de configuração.
- Explicação: Discussão de alto nível que esclarece e ilumina o contexto, escolhas de design e trade-offs.
Ele também usa /unslop, então produz documentação muito legível.
Escrever um plano dessa forma é muito útil porque também dá aos seus agentes um alvo e objetivo concreto contra o qual eles podem verificar seu próprio trabalho. E, claro, também é muito mais fácil entender exatamente o que o agente vai construir.
Muitas das habilidades do pstack se combinam aqui na fase de design. Por exemplo:
(1) /recall meu trabalho corrigindo bugs de virtualização e problemas de desempenho dos últimos 7 dias. use /how e /why para entender como nossa implementação de virtualização atual funciona.
(2) depois use /poteto-mode planning e /technical-writing para criar um novo mecanismo de virtualização que elimine categoricamente flickering e jittering. vamos começar escrevendo um tutorial sobre como eu usaria este novo pacote para virtualizar um aplicativo React
(3) depois de escrever o plano, /teach me e prove para mim por que esta nova abordagem é superior ao nosso mecanismo atual
A técnica aqui é realmente sobre extrair contexto interessante e rico que dá aos seus agentes a capacidade de ver o problema da mesma forma que você – não apenas como uma pequena fatia:
- A primeira parte do prompt recupera o contexto passado e presente relevante sobre como a virtualização é implementada no meu aplicativo.
- A segunda parte guia o agente a usar esse contexto, como bugs que ele corrigiu antes, para criar um novo design que elimine esses problemas completamente.
- A parte final é pedir ao seu agente que prove que este novo pacote é superior. É aqui que ferramentas de alta qualidade como habilidades de verificação são importantes de se ter.
Meça cem vezes, corte uma vez
Ao planejar, dois dos erros mais comuns que vejo são:
- Aceitar o primeiro design do agente.
- Cozinhar demais o plano sem evidências empíricas.
Quando humanos escreviam código, muitas vezes colaborávamos uns com os outros por meio de documentos de design. Esses eram documentos que falavam sobre arquitetura de alto nível, alternativas consideradas, trade-offs e quaisquer notas de implementação incomuns. Era muito comum passar por várias iterações desses documentos antes de chegar a um design finalizado.
Com agentes, embora possamos pular a cerimônia do documento de design, muitas vezes vejo o erro de aceitar a primeira coisa que o agente te devolve. Com o pstack, podemos, em vez disso, levar a abordagem "meça duas vezes, corte uma" ao limite, usando agentes paralelos.
Fazemos isso usando o playbook de prototipagem.
No pstack, playbooks não são habilidades, mas arquivos de referência dentro de /poteto-mode. Esses playbooks são carregados condicionalmente (para eficiência de tokens) dependendo do tipo de tarefa em que você está trabalhando. Esses 23 playbooks (a partir da versão 0.15.0) contêm cada um um fluxo de trabalho que uso quando estou fazendo uma tarefa.
Ao contrário das habilidades, os playbooks são usados automaticamente pelo agente como parte do /poteto-mode. Por exemplo:
/poteto-mode prototype algumas opções para o novo menu suspenso /poteto-mode corrija este bug /poteto-mode avalie esta mudança de habilidade
A prototipagem é um dos meus playbooks favoritos do pstack. Ele dá várias tentativas para um objetivo e ajuda o agente a raciocinar sobre a melhor opção. Isso é útil não apenas para prototipagem visual, mas também para prototipar diferentes soluções para funcionalidades, correções de bugs e assim por diante.
/poteto-mode prototype algumas opções para <solicitação de funcionalidade>. use /control-app* e tire vídeos/capturas de tela para eu revisar e escolher
\ nota: /control-app é a habilidade de verificação que criamos na [Parte 1*](https://x.com/poteto/status/2094457600259842065
Ao prototipar mudanças visuais, o agente constrói rascunhos descartáveis no seu aplicativo ou em um diretório de rascunho. Se está testando uma interação de UI, ele coloca duas ou três variações atrás de um simples alternador. Em seguida, ele conduz a interação com a habilidade /control-app, tira capturas de tela de cada variante e mede o tempo ou layout real.
Prototipar é planejar, mas com código. Permite que os agentes tenham a liberdade de explorar o espaço do problema e lhes dá a chance de te surpreender com algo que você não teria pensado. Os protótipos permitem que os agentes respondam suas próprias perguntas com evidências empíricas, em vez de esperar pela minha contribuição.
Arquitetando mudanças maiores
Como engenheiro na era dos agentes, é mais importante gastar meu tempo em arquitetura, escolher as estruturas de dados certas e pensar em como os sistemas que construo funcionarão juntos. Meus agentes preenchem os detalhes de implementação.
Outra habilidade útil que o pstack oferece é /architect. Ela estrutura o design em fases distintas e disciplinadas:
- Fundamentar o problema. O agente executa /how e /why sobre os sistemas afetados para construir um modelo mental preciso da propriedade e restrições existentes.
- Esboçar. O agente entra em uma arena de arquitetura. Ele gera executores de candidatos independentes em paralelo, muitas vezes em diferentes famílias de modelos. Cada executor recebe o briefing de fundamentação e elabora um pacote de design completo: o esboço de uso do chamador, as definições de tipo principais, as assinaturas de funções públicas e uma justificativa concisa. Isso geralmente é feito esboçando apenas as assinaturas de tipo, que derivam de como queremos que os locais de chamada se pareçam. Cada executor deve avaliar a profundidade da interface, examinar modos de falha em modelos fracos e verificar nosso catálogo de bandeiras vermelhas de design.
- Avaliação cruzada e Síntese. Um agente de avaliação cruzada usando um modelo diferente do agente principal avalia os candidatos contra uma rubrica estrita.
- Implementar contra o esboço. O agente substitui os corpos de espaço reservado do esboço por lógica real. Se o agente descobrir durante a implementação que uma função precisa de parâmetros inesperados ou estado extra, ele sinaliza a discrepância.
- Descartar quando o design está errado. Se durante a implementação descobrirmos que os esboços estavam errados, o agente joga tudo fora e começa de novo.
O ponto aqui é dar ao agente um mini-loop auto-contido onde ele pode sintetizar múltiplos designs concorrentes de diferentes famílias de modelos em uma abordagem ideal, e ter o cuidado de ser rigoroso e não ter medo de descartar seu design se descobrir que a arquitetura que ele criou está errada com base em provas empíricas. Se a mesma solução alternativa aparecer em locais de chamada não relacionados, ou se os tipos exigirem saídas de emergência como 𝚊𝚗𝚢 ou casts forçados, isso é prova empírica de que a arquitetura está errada.
/architect esta nova <solicitação de funcionalidade>
A grande lição aqui é que é muito mais eficaz planejar com código usando prototipagem /poteto-mode e /architect.
É também por isso que nunca me preocupo em revisar planos abstratos de forma adversarial. Os agentes começam a alucinar riscos teóricos e a inventar casos extremos complexos para se proteger contra problemas que nunca acontecerão. Não cozinhe demais seus planos quando eles ainda são abstratos: deixe o agente responder perguntas em aberto por conta própria através da prototipagem e verificação de seu próprio trabalho.
Ok, mas eu realmente quero um documento de planejamento
Embora o pstack não venha com uma habilidade de planejamento, ele vem com um playbook de planejamento multifásico. Normalmente uso isso depois que o agente criou um design com o qual estou satisfeito, como uma forma de criar um plano de execução tático.
/poteto-mode transforme este design em um plano
Cada tarefa no plano é estruturada em torno de prova e verificação. O playbook diz aos agentes que testes sozinhos não são verificação suficiente. Só é verificado quando ele realmente executou o código e verificou que funciona.
Cada plano é verificado por um script automatizado que valida sua estrutura e formatação. Uma vez aprovado, o plano é executado item por item. Cada PR é pequeno, auto-contido e facilmente revisado.
Para projetos realmente grandes (como um que pode me levar uma semana inteira), às vezes posso decidir confirmar os planos temporariamente no código para que outros agentes estejam cientes do trabalho em andamento. Mas normalmente os excluo quando termino para não deixar o código em um estado de confusão. Não acho valioso manter planos permanentemente.
O fluxo de trabalho na prática
Para ver como todas essas peças se encaixam, vamos percorrer três exemplos concretos de como faço prompts para esses fluxos de trabalho.
Exemplo 1: Pesquisando um bug ambíguo
Quando um problema aparece em produção e a causa raiz não está clara:
/poteto-mode investigue por que os workers em segundo plano falham periodicamente com erros de timeout. me dê um detalhamento do que sabemos, quais dados você usou e suas melhores hipóteses.
O agente explora o código, verifica métricas e commits históricos em paralelo e te dá seus melhores palpites sobre onde o problema pode estar.
Exemplo 2: Projetando um novo limite de serviço
Ao introduzir um novo subsistema do qual outros módulos dependerão:
/poteto-mode precisamos adicionar limitação de taxa para webhooks externos. /architect isso primeiro e responda a quaisquer perguntas em aberto com protótipos. deixe-me revisar antes de prosseguir.
O agente fundamenta a arquitetura de webhook existente, inicia executores de design concorrentes em vários modelos, faz benchmarks com protótipos descartáveis e produz uma interface limpa e verificada.
Exemplo 3: Executando uma migração de vários PRs
Ao executar uma refatoração complexa em muitos arquivos:
/poteto-mode crie um plano para migrar toda a nossa biblioteca de UI para StyleX. divida a migração em PRs pequenos e verificáveis. cada PR deve ter seus testes de regressão visual e etapas de verificação ao vivo. quero que o resultado final seja 100% idêntico ao original - bugs incluídos
O agente divide o trabalho em etapas independentes, escreve uma lista de verificação auditável e prepara cada unidade para que possa ser construída, verificada e implantada com segurança.
Exemplo 4: Corrigir coisas que as pessoas relatam no Slack
Se você já me viu no Slack em um de nossos canais de problemas ou feedback, provavelmente já viu esses clássicos:
# thread já tem contexto suficiente
/poteto-mode faça
/poteto-mode reproduza isso com /control-app. se reproduzir no main, corrija e me mostre um vídeo como prova
Muitas das habilidades sobre as quais falei aqui já são usadas automaticamente pelo /poteto-mode, então a grande maioria das vezes você pode apenas usar /poteto-mode e seguir com sua vida!
A arte do planejamento
O Modo Plano é frequentemente usado como uma forma de se convencer de que o agente vai fazer a coisa certa. Mas a realidade é que planos abstratos só te dão a ilusão de progresso. Um plano longo e extenso faz parecer que você e seu agente foram muito produtivos, mas provavelmente carece de substância.
pstack te dá ferramentas para combinar investigação completa, evidências empíricas e verificação rigorosa. Quando você planeja dessa forma, a engenharia com agentes deixa de parecer uma aposta. Torna-se previsível e repetível.
https://x.ai/bot/plugin/9717366
Obrigado por ler, e fique ligado na Parte 3!
