Nesta série de posts, vou mostrar como uso o pstack, meu conjunto pessoal de habilidades para fazer trabalho de engenharia rigoroso. Ele me permitiu enviar 2.000 PRs por mês para produção com alta confiança.
Pessoalmente, nunca dei muita importância para quantas linhas de código ou quantos PRs eu estava entregando. Antes dos agentes, ninguém se importava, e com razão, já que produtividade bruta nem sempre significava qualidade ou um resultado visível para os usuários. Era simplesmente uma métrica de vaidade.
Mas descobri ao longo da construção do pstack que volume importa, especialmente quando você consegue manter ou até aumentar o nível de qualidade do produto com agentes. Por exemplo, comecei a trabalhar no Grok @Bot há cerca de 2 meses, quando ainda estava no início e a base de código era nova, mas começando a crescer. Apesar do time estar crescendo e agora entregando centenas de PRs por dia na base de código do Grok @Bot, o pstack me permitiu manter a qualidade do código alta para todos, enquanto monitoro constantemente o código, refatoro, adiciono novos lints e verificações, e também trabalho em funcionalidades.
https://x.com/poteto/status/2090546476464451907
https://x.com/poteto/status/2078527882499150286
Ser o jardineiro e mantenedor do Grok @Bot é algo que só consegui fazer através do pstack. Nosso ímpeto inicial após construir o protótipo era muito alto e muitas pessoas estavam entrando no time. Tive um momento crítico de oportunidade para refatorar toda a base de código, enquanto ela estava sendo construída e estendida e sem tempo de inatividade, em algo com bases sólidas. Uma base de código com alta qualidade que escala não importa quantos engenheiros (e mais importante, não-engenheiros) contribuam para ela. Todo esse trabalho exige que eu refatore e melhore as bases do Grok Bot enquanto ele está sendo construído, e você só consegue fazer isso quando as bases conseguem acompanhar o número de contribuições.
Grok Bot é um dos aplicativos de IA para desktop mais eficientes e performáticos do mercado
A prova está no próprio Grok @Bot. Nas próximas semanas, vou te contar tudo o que você precisa saber para construir e manter um aplicativo de alta qualidade usando o pstack.
Parte 1 – Verificação é tudo que você precisa
A habilidade mais crítica para se ter no seu kit de ferramentas é uma habilidade de verificação de alta qualidade. Essa habilidade é tão importante de ter e manter que penso nela mais como uma infraestrutura crítica do que "apenas" uma habilidade. Uma boa habilidade de verificação vai amplificar a produção de todo o seu time, incluindo não-engenheiros. Bem feita, você vai multiplicar por 100 a 1000 a produção de todo o seu time.
Se você não está familiarizado com o termo, verificação significa que um agente pode verificar seu próprio trabalho. Ele pode continuar até ter sucesso em sua tarefa, porque agora pode fechar o ciclo sem que você seja o gargalo. Se você quiser saber mais sobre a história de como criei minha primeira habilidade de verificação para o Cursor, confira meu post anterior Loops You Can Trust.
Vamos construir uma habilidade de verificação juntos
Para começar, instale o pstack e então execute /create-verification-skill. Também recomendo adicionar o Dr Eggbot, meu bot que ajuda você a criar bots de alta qualidade, ao seu time. O Dr Eggbot vem com o pstack. Ele vai ensinar bots de código a usá-lo, e também pode criar bots não-codificadores com o mesmo rigor.
Você pode pedir ao Dr Eggbot para criar um bot engenheiro para você, que você pode então pedir para executar /create-verification-skill e configurar uma rotina diária para executar /maintain-verification-skill.
amo o Dr Eggbot
Enquanto isso roda, vamos ver o que a habilidade faz e como ela cria uma habilidade de verificação de alta qualidade para você.
Destilei todas as nossas habilidades de verificação que usamos para construir o Grok @Bot e o Cursor nesta habilidade como uma espécie de meta-habilidade. Ela ensina seu agente a criar uma de alta qualidade para o seu próprio aplicativo.
Agora, é aqui que a escolha da stack de tecnologia é importante. Se você está construindo um aplicativo em Electron ou para a web, por exemplo, pode aproveitar as ferramentas de depuração ricas disponíveis no ecossistema JS. Por exemplo, o Chrome DevTools Protocol (CDP) permite que você use as mesmas ferramentas disponíveis nas ferramentas de desenvolvedor do seu navegador. Ou se você está construindo um aplicativo iOS, usando o simulador.
Você idealmente quer a capacidade de interagir com seu aplicativo, depurá-lo, fazer traces de performance, e qualquer outra ferramenta de depuração e desenvolvimento que você normalmente usaria se estivesse desenvolvendo o aplicativo manualmente. Se você não tem um runtime rico para usar, pode precisar pedir ao seu agente para criar ferramentas para você (por exemplo, usando lldb, ou um pacote personalizado que roda como um sidecar em ambientes de desenvolvimento), ou apenas usar o que você tem disponível.
Pessoalmente, acho a verificação agentica tão importante que sugeriria, sem ironia, construir suas próprias ferramentas de depuração ricas, ou até mesmo escolher uma stack de tecnologia diferente, para ter vantagens injustas e produtividade extrema na construção de software. Como mencionei antes, dar aos agentes a capacidade de verificar seu próprio trabalho desbloqueia todos na sua organização para poder contribuir e validar que suas mudanças realmente funcionam. Quanto mais difícil sua stack de tecnologia for de depurar e controlar, mais difícil será usar agentes produtivamente.
Torne Reprodutível
No pstack, temos um princípio chamado "Build the Lever". O que isso significa no contexto de criar uma habilidade é que preferimos dar ferramentas aos agentes em vez de apenas markdown. Para habilidades de verificação, isso significa criar uma pequena CLI que automatiza a interação e depuração do seu aplicativo em um utilitário pequeno e amigável para agentes. Isso significa que os agentes consomem menos tokens tentando fazer uma tarefa (executar um comando CLI em vez de escrever um script descartável para clicar em algo), e torna sua habilidade de verificação mais reprodutível e testável.
Aqui está um exemplo hipotético de uma CLI que seu agente pode criar para um aplicativo Electron:
1# health2node .cursor/skills/verify-atlas/control-atlas.mjs doctor34# open a blank thread and send5node .cursor/skills/verify-atlas/control-atlas.mjs new-session6node .cursor/skills/verify-atlas/control-atlas.mjs send "list open tasks in this project"78# keyboard path9node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+KeyN"1011# accessibility snapshot of the live UI12node .cursor/skills/verify-atlas/control-atlas.mjs snapshot1314# screenshot for evidence15node .cursor/skills/verify-atlas/control-atlas.mjs screenshot /tmp/atlas-proof.png1617# wait for streaming / layout to settle18node .cursor/skills/verify-atlas/control-atlas.mjs wait-settle1920# flip a feature flag for the session21node .cursor/skills/verify-atlas/control-atlas.mjs feature-flag rooms_v2 on
Agora, todos os agentes podem usar esta CLI para navegar e depurar rapidamente seu aplicativo. Você também vai querer começar a pensar na experiência de desenvolvimento (dev experience) de construir seu aplicativo:
- semear um banco de dados de desenvolvimento
- como lidar com autenticação, usuários de teste, chamadas de API contra um ambiente de teste/staging
- instalar e iniciar seu ambiente de desenvolvimento de forma consistente
Tudo isso são coisas que você provavelmente já precisou pensar quando estava escrevendo código você mesmo. Então pense nisso como o utilitário principal dos seus agentes para fazer trabalho de desenvolvimento no seu aplicativo. Mantenha-o bem cuidado e testado!
Alguns outros exemplos de comandos que você pode querer considerar:
1- **Inspeção:** `info`, `snapshot`, `screenshot`, `components`2- **Navegação:** `home`, `new-session`, `select-project`, `select-runtime`, `scroll`3- **Interação:** `send`, `click`, `click-xy`, `aria-click`, `type`, `press`, `eval`, `upload-image`, `add-context`, `feature-flag`4- **Performance:** `trace`, `profile`, `record`, `perf-metrics`, `wait-settle`5- **Streaming:** `console`, `network-log`, `network-summary`6- **Saúde e limpeza:** `doctor`, `cleanup`, `watch --restart`
Depois de ter essa configuração básica, você já deve começar a ver uma grande melhoria nos seus agentes. Eles devem ser capazes de navegar e depurar seu aplicativo com facilidade.
Recomendo passar um tempo aqui deixando esta CLI boa e sem erros antes de fazer algo mais avançado. Você também vai querer pensar (ou pedir ao seu agente) em projetar uma CLI amigável para agentes. Existem muitos recursos online para os quais você pode apontar seu agente, mas as principais propriedades que gosto são:
- a API é fácil de compor - pense na filosofia de módulos profundos de John Ousterhout
- qualquer comando com efeitos colaterais potencialmente destrutivos deve ter uma opção --dry-run
- use subcomandos para revelar funcionalidades gradualmente, em vez de tudo de uma vez
- as mensagens de erro devem ser muito descritivas e dizer ao agente o que ele deve fazer em vez disso
- texto --help rico
- saídas retornadas em formato legível por máquina (ex: JSON)
Acelere com paralelismo usando Cloud Agents em vez de worktrees
Quando você tiver tido algum sucesso executando sua habilidade de verificação para entregar alguns PRs, pode começar a se perguntar se consegue paralelizar mais. Por exemplo, se um agente agora pode pegar seu prompt e, na maioria das vezes, levá-lo a um estado mesclável, isso não te libera para executar mais agentes?
Seu primeiro instinto será adicionar suporte a worktree, o que significa que seus agentes podem usar git para criar uma cópia rastreada do repositório onde podem fazer alterações isoladas do checkout principal. Em teoria, isso permite que você execute vários agentes ao mesmo tempo sem que suas alterações se sobrescrevam.
Eu recomendaria não fazer isso. Primeiro, usa muito espaço de armazenamento e recursos na sua máquina. Você pode conseguir executar até 10 agentes em paralelo com worktrees, dependendo do tamanho do seu repositório e de quão potente é sua máquina. Mas há uma maneira muito melhor!
Os cloud agents do Cursor são agentes que rodam na nuvem, na infraestrutura do Cursor. Esses agentes têm acesso a um computador real, o que significa que podem instalar dependências, executar seu aplicativo, gravar vídeos e screenshots, e interagir com seu aplicativo como um usuário real. Se você investiu o suficiente no passo anterior para tornar sua experiência de desenvolvimento boa, não deve ser um grande esforço conseguir configurar cloud agents. Quando você configura seu ambiente de nuvem pela primeira vez, enviamos um agente para ajudá-lo a configurá-lo e fazê-lo funcionar corretamente. Após a primeira build, tiramos um snapshot, o que significa que as execuções subsequentes do cloud agent sempre iniciam rapidamente.
Recomendo fortemente dedicar um tempo para configurar cloud agents, pois isso desbloqueia um aumento massivo de produtividade em paralelismo. Em um post posterior, mostrarei como executo centenas de subagentes em paralelo na nuvem! Mas por enquanto, configure seu ambiente e deixe-o em um estado onde você possa começar a se sentir confiante sobre executar todos os seus agentes na nuvem.
Mantenha os agentes inteligentes com Feature Maps
À medida que seu aplicativo se torna mais complexo, os agentes precisam de mais orientação para encontrar funcionalidades e interagir com elas. Para fazer isso, criei algo que chamo de Feature Map. Como o nome sugere, é um mapa facilmente pesquisável de todas as funcionalidades disponíveis no seu aplicativo, o que elas fazem e como chegar até elas da perspectiva do usuário.
Aqui está um exemplo de Feature Map que preparei para um aplicativo fictício chamado Atlas. São apenas alguns arquivos markdown mencionados no SKILL.md da verificação.
Você pode colocar este arquivo em qualquer lugar, mas no /create-verification-skill criamos automaticamente um diretório references/features junto com um README.md. O readme é o mapa em si: uma visão geral de alto nível de todas as principais funcionalidades disponíveis, com links para detalhes específicos. Um exemplo de funcionalidade é mais ou menos assim:
1# Preferências23Overlay de preferências em tela cheia e seu conjunto de abas.45## Subfuncionalidades67- settings-overlay: overlay em tela cheia aberto pela engrenagem ou Cmd/Ctrl+,8- settings-nav: navegação à esquerda das abas (Geral, Aparência, Modelos, Plano e Uso, ...).9- settings-search: pesquisa no overlay (Cmd/Ctrl+K enquanto as configurações estão abertas).10- theme-picker: controle rápido de tema em Aparência.1112## Como chegar até ela (ponto de vista do usuário)1314Clique na engrenagem ao lado do avatar da conta, ou pressione Cmd/Ctrl+,. Escolha uma aba na navegação à esquerda. Digite na caixa de pesquisa de preferências para pular. Escape ou o controle de fechar dispensa.1516## Dirigindo com control-atlas1718bash19node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+Comma"20node .cursor/skills/verify-atlas/control-atlas.mjs snapshot21node .cursor/skills/verify-atlas/control-atlas.mjs press "Escape"2223- Raiz do overlay: procure por um diálogo/região chamado Preferências na árvore de acessibilidade.24- Abas: clique pelo nome visível. Plano e Uso pode estar ausente para alguns estados de conta.25- Enquanto as configurações estão abertas, Cmd/Ctrl+K é a pesquisa de preferências, não a paleta global (veja `multi-surface-journeys.md`).2627## Armadilhas2829- Fechar as configurações no meio de uma suíte pode deixar o foco em lugar nenhum útil. `new-session` ou `home` recupera.30- Algumas abas são restritas por permissão. Pule com um motivo de conta explícito.
Não se preocupe em escrever estes você mesmo! Quando você executa /create-verification-skill, seu agente vai automaticamente percorrer seu aplicativo e catalogar tudo e criar essas referências para você.
O Feature Map, quando combinado com a CLI, é uma das principais razões pelas quais as habilidades de verificação do pstack são tão boas. Os agentes agora têm contexto sobre cada funcionalidade e como chegar até ela, economizando tokens preciosos em sua janela de contexto e ensinando exatamente para que serve e como chegar lá.
Você pode pensar no Feature Map como uma forma de "memória materializada". Se você usa agentes há algum tempo, provavelmente está familiarizado com o conceito de memória - normalmente, elas podem ser armazenadas como arquivos markdown simples (ex: um cofre do Obsidian), ou até algo mais complexo como um banco de dados vetorial. Pessoalmente, acho que sua base de código é a forma definitiva de memória. Código é uma projeção da tomada de decisão que você e seu time fizeram e representa a fonte da verdade sobre o que aconteceu e como as coisas realmente funcionam. Um Feature Map é apenas uma forma mais compacta disso, projetada para economizar tokens. E como é apenas markdown dentro de uma habilidade, todos que contribuem para sua base de código se beneficiam dessa memória compartilhada.
Isso significa que manter a habilidade de verificação é realmente importante. Recomendo executar /maintain-verification-skill pelo menos uma vez por dia para garantir que seus agentes sempre tenham os detalhes mais recentes sobre como controlar seu aplicativo. Você também pode descobrir, à medida que usa mais sua habilidade de verificação, que os agentes as atualizarão automaticamente enquanto trabalham em seu aplicativo. O /maintain-verification-skill captura o que quer que seja perdido.
Como usar sua habilidade de verificação
Para referência, aqui está um exemplo de habilidade de verificação criada para um aplicativo fictício: https://github.com/poteto/verification-skill-example. Como lembrete, execute /create-verification-skill para criar uma, que inclui uma CLI básica e um Feature Map.
Aqui está como eu normalmente uso com o pstack.
Primeiro, claro, é começar seu prompt com /poteto-mode. Se você estiver usando o pstack através do Cursor, também pode pressionar Opt + Enter em vez de apenas Enter quando autocompletar /poteto-mode - isso adiciona a habilidade como um Custom Mode, que fixa a habilidade para que seu agente receba um lembrete para usar a habilidade em cada nova rodada.
Digite /poteto-mode e pressione Opt + Enter para fixá-lo como um Custom Mode
No Grok @Bot, instale o plugin, então digite /poteto-mode.
Você pode usar o pstack no Grok Bot também!
Exemplo: Construindo novas funcionalidades
Para construir novas funcionalidades, normalmente uso a habilidade de verificação junto com /poteto-mode para fazer o agente verificar seu trabalho. Por exemplo, posso dar um prompt como:
/poteto-mode build <descrição da funcionalidade, qualquer contexto útil>. use /control-app para verificar suas alterações e me mostre um vídeo e screenshots como prova
Sendo /control-app o resultado de /create-verification-skill. No Grok @Bot, eu daria um prompt como:
spawn um cloud agent para usar /poteto-mode para build <descrição da funcionalidade, qualquer contexto útil>. use /control-app para verificar suas alterações e me mostre um vídeo e screenshots como prova
A pequena diferença aqui é que no Grok @Bot você diz ao seu bot para spawnar um cloud agent em vez de fazer o trabalho ele mesmo. A principal razão pela qual prefiro fazer isso é porque libera seu bot para fazer outras coisas e mantém sua janela de contexto limpa. Nesse sentido, penso nos meus bots mais como coordenadores que gerenciam e supervisionam cloud agents. Cloud agents também significam que você pode aproveitar a gama completa de modelos disponíveis no Cursor que têm sua própria máquina separada, então o computador do seu bot fica livre para outras coisas.
Exemplo: Trabalho de performance
spawn um cloud agent para usar /poteto-mode para melhorar o tempo de carregamento inicial do nosso aplicativo. primeiro use /control-app para fazer um trace do status quo e identificar oportunidades de melhoria. depois faça uma correção direcionada e use /control-app +
/swarm para confirmar a vitória
/swarm é uma das melhores habilidades para combinar com sua habilidade de verificação. Ela distribui qualquer número de cloud agents para executar sua habilidade de verificação, para que você possa fazer coisas como confirmar uma vitória de performance com um tamanho de amostra grande o suficiente, ou fazer fuzz do seu aplicativo para garantir que não quebrou ou regrediu nada.
Exemplo: Reproduzir automaticamente relatos de usuários
Quando você estiver satisfeito com sua habilidade de verificação, pode colocá-los dentro de rotinas do Grok @Bot, ou Cursor Automations. Rotinas e automações permitem que você execute coisas em um cronograma, ou dispare sempre que um evento acontecer.
Por exemplo, se você canalizar feedback de usuários para o Slack, e/ou tiver seu próprio canal de feedback interno, pode fazer seus bots ouvirem cada relato e tentarem automaticamente reproduzi-los com um cloud agent. Se sua habilidade de verificação e Feature Map forem bons o suficiente, você pode até decidir corrigir problemas automaticamente também.
Há uma razão pela qual disse antes que a verificação é uma das habilidades mais importantes no seu kit de ferramentas. Ela te dá uma base para construir novas habilidades e rotinas em cima. E o mais importante, todos no seu time se beneficiam.
Invista na sua habilidade de verificação
Depois de criar sua habilidade de verificação, mantenha-a afiada com /maintain-verification-skill. Continue melhorando a CLI e invista na habilidade como faria com uma infraestrutura crítica. Você pode até querer colocar uma escala de plantão nela - é o quão importante é para desbloquear produtividade de 100 a 1000x para seu time.
Esta habilidade é a base para muitas outras habilidades que cobriremos no guia do pstack, e se compõe lindamente com todas elas.
- pstack: https://x.ai/bot/plugin/9717366 (link do github
- Dr Eggbot: https://x.ai/bot/93gOz3op1UQdBdbekQFLK
Recomendo adicionar o Dr Eggbot, meu bot que ajuda você a criar bots de alta qualidade, ao seu time. O Dr Eggbot vem com o pstack. Ele vai ensinar bots de código a usá-lo, e também pode criar bots não-codificadores com o mesmo rigor.
Você pode pedir ao Dr Eggbot para criar um bot engenheiro para você, que você pode então pedir para executar /create-verification-skill e configurar uma rotina diária para executar /maintain-verification-skill.
Obrigado por ler e fique ligado na Parte 2!
