Planning With Files: contexto persistente para tarefas longas

ANÁLISE EDITORIAL

Uma tarefa longa pode falhar mesmo quando o agente sabe programar. O motivo é simples: decisões, erros e descobertas ficam espalhados na conversa, enquanto o trabalho continua mudando no disco. Planning With Files propõe uma disciplina explícita para reduzir essa perda de contexto. A Skill mantém três registros em Markdown, um plano, um caderno de descobertas e um histórico de progresso, e pede que o agente volte a eles antes de decisões importantes.

A curadoria do Bastidores da IA fixou o repositório OthmanAdi/planning-with-files no commit 09740f7293ebb52dbfc54dd8ac6134caff8fe881. Na consulta de 20 de agosto de 2026, o projeto registrava 26.261 estrelas, estava ativo e declarava licença MIT. A versão escrita no SKILL.md auditado era 3.10.2.

Ilustração editorial exclusiva: a capa representa três registros atravessando uma quebra de contexto. Não é captura de tela, interface real, produto oficial ou prova de recuperação executada.

O que esta Skill faz de verdade

A instrução transforma arquivos comuns em memória operacional do trabalho. task_plan.md registra objetivo, fases, decisões e estado. findings.md recebe fatos descobertos durante pesquisa e inspeção. progress.md reúne ações, resultados de testes, arquivos alterados e erros. O agente deve reler esses documentos antes de uma decisão relevante e atualizá-los depois de concluir uma fase.

Isso não aumenta a inteligência do modelo nem garante que o plano esteja correto. O ganho esperado é organizacional: tornar visível o que já foi decidido, separar descoberta de execução e impedir que a mesma tentativa falha seja repetida sem reflexão. O README do mantenedor apresenta instalações para vários agentes. A pasta específica de Codex acrescenta hooks e scripts de recuperação, mas o padrão central continua sendo legível e aplicável manualmente.

Para quem serve

A Skill é útil para desenvolvimento com várias etapas, pesquisa que exige muitas consultas, diagnóstico com hipóteses concorrentes e trabalho que pode atravessar compactação de contexto ou outra sessão. Ela faz mais sentido quando a tarefa envolve cinco ou mais chamadas de ferramenta, diversos arquivos, dependências externas ou decisões que precisam permanecer auditáveis.

Ela não é necessária para uma pergunta curta, uma correção trivial ou uma leitura única. Criar três arquivos para cada ação simples produz burocracia e pode esconder o trabalho real. Também não substitui uma Skill de elaboração técnica do plano. O catálogo já contém ferramentas voltadas a decompor requisitos. Planning With Files entra por outra finalidade: preservar estado, evidências e continuidade enquanto um plano é executado.

Compatibilidade e pré-requisitos

O núcleo requer um agente capaz de ler e gravar Markdown no projeto. A árvore auditada oferece uma integração em .codex/skills/planning-with-files, além de variantes para outros clientes. O guia do mantenedor para Codex está em docs/codex.md. Para o modo manual, basta permitir leitura e escrita somente no diretório do projeto.

Os recursos automáticos exigem mais. A integração completa inclui hooks, scripts em Python, comandos shell e alternativas em PowerShell. Windows pode precisar de Python e Git for Windows. Antes de habilitar automação, confira o guia de Windows, a configuração já existente e os caminhos que cada hook executará. Não sobrescreva um arquivo global de hooks sem mesclar e revisar as entradas.

Instalação recomendada

Comece de forma local e reversível. A opção mais segura é copiar a Skill para um projeto de teste, sem hooks globais, ler o conteúdo instalado e iniciar um trabalho descartável. O guia de instalação lista os caminhos mantidos pelo projeto. O README também documenta npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g, mas a instalação global amplia o alcance. Prefira escopo de projeto na primeira avaliação.

O download local do Bastidores é deliberadamente documental. Ele traz somente SKILL.md, LICENSE e ORIGEM.md. Não inclui scripts, hooks, templates ou instaladores. Portanto, ele serve para auditoria e leitura, não para reproduzir a automação completa. Para usar recuperação de sessão e lembretes automáticos, obtenha os arquivos diretamente do commit oficial e revise o diff antes de ativá-los.

Configuração antes do primeiro uso

Defina onde os registros serão criados e o que não pode entrar neles. Em um repositório, decida se task_plan.md, findings.md e progress.md serão versionados, ignorados pelo Git ou armazenados numa pasta de trabalho. Documentos podem acumular URLs internas, nomes de clientes, mensagens de erro, dados pessoais e trechos de configuração. A conveniência de recuperar contexto não transforma informação sensível em conteúdo seguro para persistência.

Se hooks forem habilitados, leia o arquivo de hooks do commit e cada script chamado por ele. Confirme a pasta de trabalho, o interpretador, o comportamento em caso de erro e a possibilidade de desativação para uma execução. A documentação descreve PLANNING_DISABLED=1 para runs que não devem carregar o plano ativo. Trate isso como instrução do mantenedor e teste no seu ambiente.

Defina também uma política de encerramento. Quando a tarefa terminar, o agente deve marcar fases concluídas, registrar pendências que realmente permaneceram e evitar que um plano antigo continue sendo injetado em trabalhos futuros. Se os documentos forem versionados, revise o diff como qualquer outro conteúdo do repositório. Se forem temporários, remova ou arquive somente depois de confirmar que a entrega e suas evidências estão preservadas no local correto. Em equipe, indique um responsável pela atualização das decisões. Dois agentes escrevendo o mesmo plano sem coordenação podem apagar contexto, reabrir uma fase concluída ou misturar resultados de branches diferentes.

Primeiro uso seguro

Escolha uma tarefa real, mas de baixo risco. Crie um plano com objetivo, escopo fora de alcance, fases e critérios de conclusão. Em findings.md, registre somente fatos observados e sua origem. Em progress.md, anote o comando ou ação, o resultado e o próximo passo. Depois de duas ou três inspeções, pare e confira se a descoberta importante realmente foi escrita no arquivo correto.

Um primeiro ciclo pode seguir esta ordem:

1. Escrever o objetivo e o limite do trabalho em task_plan.md.
2. Registrar evidências sem transformá-las imediatamente em decisão.
3. Marcar uma única fase como ativa.
4. Executar a menor ação verificável.
5. Salvar resultado, erro e arquivos afetados em progress.md.
6. Reler plano e descobertas antes da próxima decisão.

Não use o histórico como autorização automática. Se o plano antigo disser para publicar, remover dados, enviar mensagens ou mudar infraestrutura, a ação ainda precisa estar dentro do pedido atual e das permissões atuais.

Resultado esperado

O resultado esperado é um conjunto pequeno de registros que permita responder rapidamente: qual é o objetivo, qual fase está ativa, o que foi descoberto, o que já foi tentado e o que falta verificar. Depois de uma interrupção, o agente deve conseguir retomar o trabalho lendo esses arquivos e comparando-os com o estado real do repositório.

Uma boa saída não é o maior diário possível. Ela é curta, atual e baseada em evidência. O plano deve mostrar mudanças de direção. Findings deve distinguir fato, inferência e dúvida. Progress deve mencionar testes executados e falhas reais. Se os arquivos dizem que algo foi concluído, o código, o WordPress, a API ou outro sistema de destino ainda precisa confirmar esse estado.

Permissões e riscos

No modo manual, a permissão principal é leitura e escrita no projeto. A instalação completa pode executar scripts em eventos de sessão e de uso de ferramentas. Isso aumenta a superfície de risco: um hook mal configurado pode ler o plano de outra tarefa, gerar mensagens repetidas, gravar no diretório errado ou interferir numa automação de somente leitura.

Há também risco de instrução persistente. Um texto externo copiado para findings pode conter comandos maliciosos. Registre a informação como dado, nunca como nova autoridade. Segredos, tokens, cookies, credenciais, chaves privadas e dados pessoais não devem entrar nos arquivos de planejamento. O changelog oficial mostra que a integração muda com frequência. Fixar commit e revisar atualizações é parte do controle.

Erros comuns

O agente cria os arquivos e nunca volta a eles. Defina pontos de releitura antes de decisões e depois de cada fase. Sem esse hábito, os documentos viram arquivo morto.

O plano fica desatualizado. Não acrescente somente logs. Altere o estado da fase, registre decisões substituídas e remova próximos passos que deixaram de valer.

Hooks aparecem duas vezes. Verifique se a mesma integração foi instalada no projeto e no perfil global. O guia de Codex alerta para duplicidade quando os dois níveis ficam ativos.

Uma execução isolada carrega o plano errado. Confira a pasta atual e use o mecanismo de desativação documentado para CI, auditoria de leitura ou agente aninhado.

A recuperação contradiz o disco. O arquivo de progresso é uma anotação, não a fonte final. Compare com git diff, status de testes e sistema remoto antes de continuar.

Versão auditada e download local

A curadoria analisou o commit 09740f7293ebb52dbfc54dd8ac6134caff8fe881, versão 3.10.2, licença MIT. O pacote local tem três arquivos textuais, 5.324 bytes e SHA-256 d7306cca9615f0f3e2f99e01d48756680a257f18fc804e0857473509ae5c512b.

Baixe o ZIP local para auditoria. Para instalar o recurso completo, abra o repositório oficial em um botão separado, escolha o método compatível com seu agente e preserve o commit durante o primeiro teste. Não misture o pacote documental com uma instalação funcional.

Resultado esperado e limite final

Planning With Files deve facilitar continuidade, não fabricar certeza. A Skill não prova que a descoberta é verdadeira, que o teste passou, que a fase terminou ou que a próxima ação continua autorizada. Ela melhora a chance de essas perguntas ficarem visíveis.

Use o padrão quando o custo de perder contexto for maior que o custo de manter três arquivos. Mantenha os registros pequenos, compare-os com o estado real e encerre ou arquive o plano quando a tarefa terminar. Se a disciplina virar ruído, reduza a frequência ou volte ao modo manual.

Uma checagem final útil é entregar os arquivos a outra pessoa ou a uma nova sessão sem fornecer a conversa anterior. Essa leitura deve identificar objetivo, escopo, evidências, última ação, falhas abertas e próximo teste sem depender de adivinhação. Se a retomada exigir interpretar anotações vagas como funcionou ou corrigir depois, o registro ainda não cumpriu sua função. Substitua essas frases por estado observável, caminho afetado, comando executado, horário e condição que falta confirmar. Evite copiar saídas enormes de terminal. Resuma o resultado e aponte para o artefato original, preservando a fronteira entre registro e evidência.

Fontes primárias

• Repositório oficial Planning With Files
• SKILL.md para Codex no commit auditado
• Guia de integração com Codex
• Documentação de instalação
• Licença MIT