planf3 na prática: a skill que transforma planos de IA em HTML executável

Ontem eu escrevi que planejar é engenharia — que o plano, e não o prompt, é o artefato que decide se um agente acerta ou patina. Hoje quero ir direto na ferramenta que pega essa tese e transforma em código de verdade: o planf3, do IndyDevDan (disler). É uma skill do Claude Code que escreve, mantém e executa planos de engenharia em HTML — e depois de cavar o repositório, eu acho que ele resolve o problema mais chato da engenharia com agentes de um jeito quase óbvio que ninguém tinha empacotado direito.

De ideia para repositório: o que o planf3 realmente é

O nome é “Plans for Fable 5” — planos feitos para a geração de modelos potente o bastante para engolir um prompt denso e cuspir exatamente o resultado especificado. A API é uma linha: você roda /planf3 "<seu prompt>" e o agente lê o seu código, opcionalmente os diretórios AI_DOCS/ e APP_DOCS/, e gera um arquivo .html autossuficiente dentro de specs/. A prioridade declarada do projeto é Performance > Velocidade ≥ Custo: ele gasta token de propósito para entregar um plano rico, com diagramas embutidos e metadados estruturados.

É o que o autor chama de meta-skill: uma skill que não produz código terminal, mas produz outro artefato — o plano — que por sua vez guia o código. Se você quiser a fundamentação conceitual disso, eu destrinchei a tese no post Planejamento é engenharia: a meta-skill de planos pra agentes de IA. Aqui o foco é a mecânica.

Os 5 workflows que fazem o plano virar artefato vivo

O planf3 não é um gerador de plano de uma tacada só. Ele tem cinco fluxos dedicados, e é essa separação que faz o plano sobreviver ao ciclo de vida do código: (1) Create Plan escreve um plano novo do zero; (2) Update Plan revisa um plano existente de forma cirúrgica, com histórico append-only; (3) Update References atualiza metadados e religa os links bidirecionais entre planos relacionados; (4) Build Plan é onde a mágica acontece — um agente novo executa as fases; e (5) Image Generation é o subfluxo que cria um diagrama por seção, em paralelo, via gpt-image-2.

Reparou na sacada? O plano não é descartável. Ele nasce, é revisado, é construído e é emendado — sempre dentro do mesmo arquivo, sem perder o rastro do que mudou. É a diferença entre um rascunho e uma planta de obra.

Por que gastar token escrevendo o plano em HTML compensa

O template do plano é, nas palavras do repo, “o coração da skill”. Cada plano traz metadados atualizáveis (data de criação, logs append-only de modificações, commits, agente e sessão), blocos de Purpose/Problem/Solution com um diagrama focado cada, uma lista de arquivos relevantes separando os existentes dos novos — para você enxergar o raio de impacto antes de uma linha ser tocada — e as fases de implementação com checklists por tarefa.

Os marcadores de status moram dentro do checklist: [] ocioso, [wip] em andamento, [x] concluído, [f] falhou. Não é um board separado que desincroniza do trabalho real — o progresso vive no próprio artefato. HTML é caro em token, sim, mas é legível por humano e acionável por agente ao mesmo tempo. Esse é o trade-off que o planf3 faz de olhos abertos.

Build Plan: o loop de validação que se fecha sozinho

Para mim o ponto alto é o Build Plan. Um agente fresco abre o plano e executa as fases de cima para baixo, rodando os testes em loop até passarem, e marcando [x] ou [f] direto no plano conforme avança. O template tem um Validation Loop com critério de saída explícito: “não saia até que toda caixa esteja marcada”. É um loop fechado — o próprio artefato impede o agente de declarar vitória cedo demais.

Isso conversa direto com a ideia de níveis de abstração que eu já tinha defendido em Loop Engineering: os 4 níveis de abstração que mudaram como eu construo com IA. O planf3 é, na prática, um loop de execução com critério de parada embutido no plano em vez de na sua cabeça.

Como instalar e o custo real de rodar

Os pré-requisitos são o CLI do Claude Code (ou Pi/Codex/opencode), o gerenciador uv, e uma OPENAI_API_KEY para gerar os diagramas com gpt-image-2. A instalação tem dois caminhos: o agêntico, em que você pede para um agente ler o SKILL.md e se autoinstalar em ~/.claude/skills/planf3; ou o manual, copiando o diretório da skill e setando a chave no .env.

Honestidade sobre limitações: o planf3 é afinado para modelos de ponta — modelos menores se afogam no custo de token do prompt. Sem a OPENAI_API_KEY os diagramas ficam vazios. E o autor avisa de dois efeitos colaterais clássicos de agente: o over-reach (o modelo edita além do escopo) e o context bleed (outros specs na pasta acabam referenciados sem querer). Nada disso é defeito fatal, mas você precisa saber antes de rodar em produção.

Por que isso importa para você, dev

Três coisas que eu tiro disso. (1) Planejar deixou de ser “escrever um prompt bonito” e virou “templatizar a sua engenharia uma vez” — você define as seções, os loops e a identidade visual, e todo plano nasce igual, para sempre. (2) O ganho de investir no plano cresce conforme o modelo melhora: quanto mais capaz o agente, mais ele aproveita um plano denso, e menos tempo você gasta revisando depois. (3) Um mesmo artefato precisa servir três públicos ao mesmo tempo — você, o time e o agente de IA. O planf3 é uma aposta concreta de que dá para escrever um plano que satisfaça os três sem virar burocracia.

Conclusão

Ontem foi a tese; hoje é a ferramenta que prova a tese. O planf3 não inventou planejamento — ele só recusou tratar plano como saída de caixa-preta e transformou em artefato versionado, executável e vivo. Se você leva agentes a sério, vale clonar e rodar uma vez para sentir a diferença. O repositório está aberto no planf3 no GitHub, e o IndyDevDan aprofunda o método no Tactical Agentic Coding e no canal IndyDevDan no YouTube.