Um documento de plano é o artefato errado para trabalho de IA que abrange múltiplas sessões. Aprendi isso da maneira cara: o raciocínio que produziu um plano vive na conversa, e a conversa morre quando a sessão termina. A próxima sessão lê seu belo plano em markdown e reconstrói com confiança uma suposição que você já havia descartado dois dias atrás. A skill Wayfinder, do pack de engineering skills do Matt Pocock, é a primeira ferramenta que vi que trata isso como o problema central em vez de uma nota de rodapé.
Uso Claude Code diariamente em uma monorepo Laravel, builds de clientes e pipelines de conteúdo, e quase tudo que vale a pena fazer é maior que uma sessão. Aqui está como o Wayfinder realmente funciona, o que meu próprio workflow de múltiplas sessões me ensinou antes de encontrá-lo, e os casos específicos onde recorrer a ele é um erro.
O que um projeto multi-sessão me ensinou antes do Wayfinder existir
No mês passado reescrevi 84 posts do blog neste site em sete lotes e mais de uma dúzia de sessões do Claude Code. O que impediu que desmoronasse não foi um documento de plano. Foi um arquivo bobo chamado REWRITE-STATUS.json — um manifesto listando cada ID de post com uma flag DONE ou PENDING, atualizado por um script mark_done.php depois que cada lote era aplicado e verificado.
Qualquer sessão nova podia ler esse manifesto em dois segundos e saber exatamente onde o projeto estava. Sem resumir a conversa anterior, sem re-derivar estado do histórico do git. O manifesto era a memória do projeto; as sessões eram descartáveis.
Mas um manifesto só rastreia trabalho. Não pode dizer a uma nova sessão por que o lote três mudou os formatos de link, ou por que paramos de confiar em uma categoria de fontes. Essas foram decisões, debatidas em conversas que não existem mais. Essa lacuna — decisões duráveis, não apenas status durável — é precisamente o que o Wayfinder preenche.
O que a skill Wayfinder realmente faz
O Wayfinder mapeia um grande esforço como um mapa de tickets de decisão no issue tracker do seu repo, então os resolve um de cada vez ao longo de quantas sessões forem necessárias. Duas ideias fazem funcionar:
O ticket é uma pergunta, não uma tarefa. Um ticket do Wayfinder nunca é "construa o motor de rateio." É "como lidamos com mudanças de plano no meio do ciclo quando o cliente tem crédito não utilizado?" Resolver um ticket produz uma decisão, registrada permanentemente no ticket. Não é uma fatia do build.
O mapa é um índice, não um armazenamento. O mapa é uma única issue rotulada wayfinder:map. Issues filhas são os tickets. Cada decisão vive em exatamente um lugar — seu próprio ticket — e o mapa apenas a resume e linka. Sem cópias duplicadas divergindo.
A issue do mapa contém cinco seções: Destination (uma ou duas linhas nomeando o ponto final), Notes (contexto do domínio que cada sessão precisa), Decisions so far (tickets fechados, resumidos e linkados), Not yet specified (a névoa), e Out of scope (trabalho explicitamente excluído).
A linha de Destination faz mais trabalho do que aparenta. Deixe-a vaga e cada ticket descendente herda a imprecisão.
Fog of war: o teste que se transfere para todo lugar
O Wayfinder empresta o conceito de fog of war dos jogos de estratégia. Seus tickets são a área iluminada — perguntas que você pode formular com precisão hoje. Além deles está a névoa: "há algo sobre jurisdições fiscais aqui, ainda não consigo formular." Você não planeja uma rota pela névoa. Você avança até a fronteira, revela mais terreno, depois decide.
O teste para névoa versus ticket é direto: você consegue formular a pergunta com precisão, agora? Sim significa ticket. Não significa névoa.
Agora aplico esse teste fora do Wayfinder por completo. Metade dos tickets que eu costumava escrever para projetos de clientes era névoa fantasiada de ticket — vagos o suficiente para que quem os pegasse passasse a primeira hora re-derivando qual era a pergunta sequer.
Mais dois termos importam. A frontier é o conjunto de tickets abertos, não bloqueados, não reivindicados — decisões que realmente podem ser tomadas agora. Reivindicar significa atribuir um ticket a si mesmo antes de trabalhar nele, para que duas sessões paralelas não resolvam a mesma pergunta de duas maneiras diferentes. Eu rodo agentes paralelos em git worktrees constantemente, e a falha recorrente é exatamente essa: dois agentes tomando decisões incompatíveis nos mesmos vinte minutos.
Os quatro tipos de ticket, e o que dá errado
Cada ticket carrega um rótulo de tipo que determina qual skill o resolve e se você precisa estar presente:
| Tipo | Modo | O que resolve |
|---|---|---|
grilling |
Humano no loop | Perguntas resolvidas por conversa — o padrão |
prototype |
Humano no loop | Perguntas comportamentais ou estéticas que precisam de um artefato real |
research |
Agente trabalha sozinho | Fatos externos que bloqueiam uma decisão; roda em paralelo |
task |
Ambos | Pré-requisitos manuais que desbloqueiam uma decisão |
Grilling é o cavalo de batalha — um Q&A adversarial que pressiona seu plano até que o ramo se resolva. Tenho grill-me e grill-with-docs do mesmo pack instalados nesta máquina e os uso semanalmente; grill-with-docs também atualiza CONTEXT.md e ADRs conforme as decisões cristalizam, que é exatamente o que um ticket de decisão deveria alimentar.
Research muda a economia. Estes disparam como subagentes, em paralelo, enquanto você está em outro lugar. Quatro tickets de research se resolvem no tempo que uma sessão de grilling leva.
Prototype existe porque algumas perguntas não podem ser respondidas em prosa. "Wizard ou formulário único?" se resolve com um artefato descartável — sem testes, sem abstrações, deletado assim que respondeu a pergunta.
Task é o tipo que mais dá errado, e a própria documentação da skill admite. Um ticket de task é trabalho manual que desbloqueia uma decisão — provisionar o banco de dados de staging, buscar credenciais de API. Agentes consistentemente o reinterpretam como um passo de implementação e começam a construir código de produção dentro do limite de planejamento. Vigie seus tickets task.
Como uma execução acontece, sessão por sessão
Sessão um: mapear. Você chega com um destino difuso — "migrar cobrança para baseado em uso neste trimestre." O agente te interroga até que o Destination seja uma ou duas linhas concretas, mapeia a frontier breadth-first (mapear depth-first te arrasta por um ramo até que um ramo irmão o invalide), cria a issue do mapa e os tickets que você pode formular hoje, conecta arestas reais de bloqueio entre eles, coloca o resto na névoa, e dispara os subagentes de research. Então para. Mapear é uma sessão.
Sessões dois a N: trabalhar o mapa. Cada sessão carrega o mapa em baixa resolução — Destination, Notes, Decisions so far, frontier — não cada corpo de ticket. Você reivindica um ticket da frontier. O agente o resolve com a skill correspondente, posta a resolução como comentário, fecha o ticket, o resume em Decisions so far, cria quaisquer tickets que a resolução revelou, gradua névoa que agora é precisa o suficiente para formular. E para.
Esse "e para" sustenta todo o sistema. Uma decisão por sessão significa que cada decisão recebe uma janela de contexto fresca de capacidade de julgamento. Sessões que continuam tomam três decisões em uma janela que só tinha bom julgamento para uma. Esta é a mesma disciplina que meu manifesto de reescrita impôs por acidente: incrementos pequenos e verificados, estado escrito, sessão descartada.
O mapa se resolve. Eventualmente a frontier se esvazia e a névoa desaparece. O que você tem é uma rede de decisões linkadas com os argumentos intactos — não um plano de build. O passo final o converte: na versão atual do pack, /to-spec colapsa as decisões em uma especificação e /to-tickets a corta em trabalho de implementação. Minha própria instalação ainda mostra os antigos /to-prd e /to-issues em ~/.claude/skills/, o que me diz claramente que meu pack é anterior a essa renomeação — vale a pena verificar qual par você tem antes de assumir que o Wayfinder está instalado.
A configuração é um único passo: instale o pack do repo mattpocock/skills ou do marketplace de plugins do Claude Code, depois execute /setup-matt-pocock-skills uma vez por repo. Ele registra qual issue tracker o repo usa (GitHub via gh, GitLab via glab, markdown local para repos sem remote, ou uma descrição em prosa do seu workflow de Jira/Linear), seus rótulos de triagem, e onde vivem os docs do domínio. Essa opção de prosa é por que chamá-lo de agnóstico de tracker é justo: ele não entrega uma integração com Jira, entrega um lugar para escrever como seu tracker funciona.
Uma decisão de design que vale destacar: relações de bloqueio usam os recursos nativos de dependência do tracker, nunca uma convenção no corpo da issue. Se "Blocked by: #42" é texto em uma descrição, apenas o agente que o escreveu o entende. Se é uma aresta real de bloqueio, o GitHub renderiza o grafo de dependências e a frontier se torna algo que você pode ver.
Como difere do desenvolvimento dirigido por spec
Frameworks dirigidos por spec — Spec Kit, Kiro, OpenSpec, que usei como ferramenta diária por um período — tratam a spec como a fonte persistente de verdade. O Wayfinder se posiciona a montante de todos eles: é o que você roda quando há névoa demais para escrever uma spec de qualquer forma. E sua saída de spec é deliberadamente descartável — um marco, não um documento mantido.
Essa é a inversão que vale a pena manter: desenvolvimento tradicional dirigido por spec diz que o documento é permanente e o raciocínio é descartável. O Wayfinder diz que o raciocínio é permanente e o documento é descartável. Tendo visto o que acontece com documentos de spec após seis meses, acho que o Wayfinder tem a ordem certa.
Quando eu não recorreria a ele
O planejamento cabe em uma sessão. A maioria do trabalho se qualifica. Use /grill-with-docs e termine em quarenta minutos; um mapa, quatro tipos de ticket e convenções de reivindicação são pura sobrecarga para uma feature delimitada.
A rota é clara e apenas o trabalho é grande. Grande não é o gatilho — nebuloso é. Minha reescrita de 84 posts foi grande mas nunca nebulosa; um manifesto e disciplina de lotes cobriram. Uma migração de doze semanas onde você conhece cada passo precisa de agentes de implementação paralelos, não mapeamento.
Você não tem um tracker que realmente usa. O fallback de markdown local funciona, mas você perde arestas nativas de bloqueio e a frontier visível, que é a maior parte do valor mecânico.
Você acha Q&A adversarial cansativo. O grilling é exaustivo — cada pergunta chega como três parágrafos. Uma instrução no CLAUDE.md para fazer uma pergunta curta por vez ajuda, mas não resolve completamente. Planeje isso antes de mapear um mapa de vinte tickets.
Para continuidade sessão a sessão em trabalho que não precisa de um mapa completo de decisões, a skill handoff é a ferramenta mais leve, e nada disso substitui o gerenciamento básico de contexto em sessões longas — uma janela maior compra espaço, não continuidade.
O reenquadramento que mantenho de qualquer forma: pare de escrever planos, comece a fechar perguntas. Um plano é uma afirmação sobre um futuro que você não pode ver. Um ticket de decisão fechado é um fato com o argumento anexado, e sobrevive cada reset de contexto. Abra o documento de plano do seu projeto atual e conte quais linhas são decisões com raciocínio por trás e quais são palpites em voz confiante. Os palpites são sua névoa — e agora você sabe quanto do mapa você nunca mapeou.
O Wayfinder é uma de dezenas de skills que avaliei contra trabalho real de projetos. Se você está decidindo quais merecem um lugar na sua própria configuração, meu agent skills marketplace é onde guardo as que ganharam seu lugar.
