Extensão de workflow que impõe um ciclo de desenvolvimento estruturado ao agente de código Pi

Hoje em dia estão surgindo várias ferramentas de agentes de codificação com IA, e está na moda a abordagem de modificar vários arquivos ao mesmo tempo com agentes paralelos. Mas, quando você usa na prática, percebe rapidamente uma coisa — o resultado fica uma bagunça.
O agente despeja código sem planejamento, a consistência entre módulos se quebra e os mesmos erros se repetem a cada sessão. “Gerar muito e rápido” nem sempre é algo bom. Por mais alta que seja a velocidade de geração, não faz sentido se depois uma pessoa gasta ainda mais tempo arrumando tudo.
Por isso mudei a abordagem. E se desacelerarmos intencionalmente o agente, mas impusermos uma estrutura — será que a qualidade final não melhora?
Criei uma extensão de workflow para o agente de código Pi (@mariozechner/pi-coding-agent), e o ponto central é impor ao agente um ciclo de desenvolvimento de 6 etapas:
📝 Plan → 🔍 Verify Plan → 🔨 Implement → ✅ Verify Impl → 🧠 Compound → 🎉 Done

1. Bloqueio de ferramentas por etapa
   Fora da etapa de implementação (Implement), as próprias ferramentas de edição de arquivos ficam bloqueadas. Comandos bash como rm, mv, sed -i também são bloqueados em etapas somente leitura. A IA simplesmente não consegue mexer no código antes de montar um plano.
2. Verificação adversarial paralela com múltiplos modelos
   Vários LLMs verificam simultaneamente o plano e o resultado da implementação. Não é apenas um code review simples, mas uma abordagem de ataque que cria cenários concretos para quebrar o código. A severidade é classificada como 🔴 CRITICAL / 🟡 WARNING / 🔵 INFO, e se houver ao menos um CRITICAL, a etapa não pode ser aprovada.
3. Aprendizado Compound e memória do projeto
   Ao fim de cada ciclo, padrões, erros recorrentes (gotchas) e decisões de arquitetura são registrados automaticamente. Essa memória é salva em .pi/workflow-memory.json e continua disponível mesmo quando a sessão muda. Assim, fica possível algo como “ontem quebramos a cabeça nessa parte, então hoje não vamos repetir isso”.
4. Repo Map (AST + PageRank)
   Com web-tree-sitter, os símbolos de todo o projeto (funções, classes, interfaces etc.) são extraídos, um grafo de imports é criado, e o PageRank é usado para atribuir importância a cada arquivo. Como isso permite entender a estrutura do projeto dentro do orçamento de tokens (padrão de 2048), o agente trabalha já entendendo “como este projeto é organizado”. Suporta 18 linguagens.
   Outros recursos

• Sistema de TODO — divide tarefas grandes em unidades de TODO, e para cada TODO executa de forma independente o ciclo Implement → Verify → Compound
• Automação com Git — commit/push automáticos em cada limite de TODO; se a árvore estiver dirty, a limpeza é exigida primeiro
• Checks customizados — ao colocar arquivos Markdown em docs/checks/, é possível adicionar critérios de validação específicos do projeto
• Gerenciamento de contexto — separa o contexto mínimo sempre injetado do contexto sob demanda buscado quando necessário, evitando desperdício de tokens
  Filosofia
  Não é que agentes paralelos sejam algo ruim. Mas geração paralela sem estrutura, na minha visão, é praticamente o mesmo que criar dívida técnica em paralelo. Esta extensão nasceu da ideia de “deixar a IA trabalhar, mas aplicando a ela a mesma disciplina com que humanos trabalham”.
  Foi escrita 100% em TypeScript e pode ser instalada com npm install + um symlink.
  GitHub: https://github.com/popododo0720/pi-stuff
  Feedback é bem-vindo!