Planning with Files é uma skill para agentes criada por Ahmad Adi que guarda o plano, as conclusões e o progresso de uma tarefa em ficheiros do projeto. Use-a quando uma tarefa de programação ou investigação durar o suficiente para que uma nova conversa tivesse de reconstituir decisões anteriores. Os ficheiros dão ao agente um registo que pode ler e atualizar; a sua utilidade depende de os manter corretos.
O ponto de partida prático são três ficheiros Markdown: task_plan.md, findings.md, e progress.md. Dê a cada um uma função distinta. Um plano acompanha o que falta fazer, as conclusões explicam o que se aprendeu e o progresso regista o que efetivamente aconteceu. Colocar o mesmo parágrafo nos três dificulta a recuperação.
Exemplo fictício de planeamento da Apple; os comentários citados e as percentagens são ilustrativos. Abra a ilustração no tamanho original.
Instale a pasta completa da skill
A página da skill Planning with Files na Thrive disponibiliza a fonte do autor que foi revista. Instale-a no seu projeto:
npx usethrive add planning-with-files --agent claudePara Codex, altere --agent claude para --agent codex. O instalador copia a pasta completa da skill na revisão fixada, incluindo modelos e scripts. Não altera uma instalação existente, por isso reveja uma cópia instalada antes de a substituir.
Instalar uma skill e instalar um plugin no ambiente do agente são operações diferentes. O autor também disponibiliza integrações para hooks de ciclo de vida e recuperação de tarefas. Copiar uma pasta não regista automaticamente os hooks ao nível do plugin em todos os ambientes. Se pretender essas integrações, siga a documentação de instalação do autor para o seu agente e sistema operativo.
Mantenha a skill instalada separada dos ficheiros de planeamento do projeto. A pasta instalada contém scripts e modelos reutilizáveis. A pasta da tarefa contém os registos do trabalho atual. O fluxo atual do autor pode selecionar uma pasta de tarefa; use o respetivo inicializador e a identificação da tarefa apresentada quando esse modo estiver ativado, em vez de presumir que todas as tarefas escrevem na raiz do projeto.
Dê a cada ficheiro uma função útil
Ficheiro | Colocar aqui | Evitar colocar aqui |
|---|---|---|
| O objetivo, as fases, os critérios de aceitação e a próxima ação | Uma transcrição de todas as chamadas a ferramentas |
| Evidências, ligações às fontes, restrições e razões das decisões | Uma conclusão sem fundamento apresentada como facto |
| Etapas concluídas, resultados efetivos dos testes e falhas por resolver | Verificações planeadas descritas como concluídas |
Para uma edição breve, estes ficheiros podem criar mais trabalho do que poupam. Corrigir um único título raramente precisa de um sistema de recuperação. Uma migração, uma investigação com várias fontes ou uma funcionalidade com várias dependências são melhores candidatas, porque a próxima ação depende de evidências anteriores.
Exemplo: planear uma pequena migração de conteúdo
Suponha que está a transferir um arquivo de newsletters para um CMS. Precisa de mapear títulos, datas, etiquetas e o corpo do conteúdo sem publicar rascunhos privados. Comece por um plano que defina o resultado e as verificações:
# Newsletter archive migration
## Objective
Import the approved public archive and preserve draft visibility.
## Phases
- [ ] Inventory source records and classify their visibility.
- [ ] Map source fields to the target content model.
- [ ] Import a small sample and check formatting.
- [ ] Import the approved remaining records.
- [ ] Verify counts, visibility, and representative links.
## Acceptance criteria
- Source and imported approved-record counts match.
- Draft records have no public snapshot.
- Sample links, headings, and publication dates are preserved.
## Next step
Inspect five representative source records before writing the mapper.O exemplo é um modelo de planeamento, não uma afirmação de que alguma migração foi concluída. Substitua as verificações pelas que os sistemas de origem e destino exigem. Se um mapeamento precisar de uma decisão do editor, registe essa dependência em vez de deixar o agente adivinhar.
Em findings.md, explique uma decisão de mapeamento com evidências. Por exemplo, «A exportação contém published_at apenas nas entradas publicadas; mantenha o valor em falta nos rascunhos» é útil se tiver observado isso na exportação. Registe o ficheiro examinado e os campos relevantes. Não escreva essa conclusão apenas porque parece plausível num CMS.
Em progress.md, registe o resultado efetivo da amostra. «Importados cinco registos; um vídeo incorporado precisa de uma regra de conversão separada» indica à próxima sessão o que falta fazer. «A migração parece bem» não fornece informação suficiente para continuar com segurança.
Retome o trabalho após uma reposição do contexto
Peça ao agente que leia os três ficheiros da tarefa selecionada e indique a fase atual, as decisões por resolver e a próxima ação antes de editar. Compare esse relato com o repositório e com qualquer sistema externo usado pela tarefa. Uma caixa de seleção em Markdown pode estar desatualizada; o agente deve verificar o artefacto relevante antes de confiar nela.
Se o plano disser que os testes passaram, o registo de progresso deve identificar o comando e o resultado. Se disser que uma disponibilização foi concluída, preserve o identificador ou o URL dessa disponibilização. Mantenha os segredos fora destes ficheiros, sobretudo quando o repositório é partilhado. Registe os nomes das credenciais e os requisitos de acesso em vez de copiar tokens.
O autor inclui ferramentas de recuperação de sessões com modos explícitos. Use o modo adequado à tarefa e ao ambiente. Não interprete o acesso a uma pasta de projeto como autorização para recolher registos locais de conversas sem relação com a tarefa. Um plano de projeto é muitas vezes suficiente para repor o contexto útil da tarefa.
Evite planos desatualizados e edições concorrentes
Atualize o plano quando uma fase mudar e dê à próxima etapa um verbo concreto: examinar, comparar, implementar ou verificar. Uma instrução vaga como «continuar o desenvolvimento» obriga uma nova sessão a reconstituir novamente a decisão.
Quando vários agentes contribuem, escolha um responsável pelo plano partilhado. Os restantes agentes podem comunicar através dos ficheiros ou mensagens que lhes foram atribuídos. Isto facilita a conciliação entre uma tarefa concluída e uma falha recém-descoberta. Agentes independentes a reescrever o mesmo documento de estado podem ocultar acidentalmente o trabalho uns dos outros.
Antes de encerrar a tarefa, confira os critérios de aceitação com o resultado. Deixe os pontos por resolver visíveis. Planning with Files melhora a continuidade do trabalho de um agente; não comprova a correção só porque o seu script de conclusão aceita um plano.
O que experimentar primeiro
Instale a skill para uma tarefa que já prevê que vá decorrer ao longo de várias sessões. Comece com um objetivo breve, algumas fases e uma próxima ação verificável. Após a primeira sessão, abra os ficheiros e veja se outra pessoa conseguiria continuar a partir deles. Decisões em falta ou registos de estado vagos mostram o que deve melhorar antes de a tarefa crescer.
Para fluxos de trabalho que também produzem notas de investigação, consulte a skill Obsidian Markdown. Mantenha os registos de execução do projeto e as notas de referência pessoais separados quando tiverem responsáveis ou requisitos de privacidade diferentes.
