Planning With Files

Planejamento com Arquivos

Trabalhe como Manus: Use arquivos markdown persistentes como sua "memória de trabalho no disco".

Importante: Onde os Arquivos Ficam

Ao usar esta habilidade:

• Templates são armazenados no diretório de habilidade em ${CLAUDE_PLUGIN_ROOT}/templates/
• Seus arquivos de planejamento (task_plan.md, findings.md, progress.md) devem ser criados em seu diretório de projeto — a pasta onde você está trabalhando

Isto garante que seus arquivos de planejamento fiquem ao lado do seu código, não enterrados na pasta de instalação da habilidade.

Início Rápido

Antes de QUALQUER tarefa complexa:

1. Crie task_plan.md em seu projeto — Use templates/task_plan.md como referência
2. Crie findings.md em seu projeto — Use templates/findings.md como referência
3. Crie progress.md em seu projeto — Use templates/progress.md como referência
4. Releia o plano antes de decidir — Atualiza metas na janela de atenção
5. Atualize após cada fase — Marque como concluído, registre erros

Nota: Os três arquivos de planejamento devem ser criados em seu diretório de trabalho atual (raiz do seu projeto), não na pasta de instalação da habilidade.

O Padrão Principal

Janela de Contexto = RAM (volátil, limitada)
Sistema de Arquivos = Disco (persistente, ilimitado)

→ Qualquer coisa importante é escrita em disco.

Propósitos dos Arquivos

Regras Críticas

1. Crie o Plano Primeiro

Nunca inicie uma tarefa complexa sem task_plan.md. Inegociável.

2. A Regra de 2 Ações

"Após cada 2 operações de visualização/navegador/busca, IMEDIATAMENTE salve descobertas-chave em arquivos de texto."

Isto evita que informações visuais/multimodais sejam perdidas.

3. Leia Antes de Decidir

Antes de decisões importantes, leia o arquivo do plano. Isto mantém metas em sua janela de atenção.

4. Atualize Após Agir

Após completar qualquer fase:

• Marque status da fase: in_progress → complete
• Registre erros encontrados
• Anote arquivos criados/modificados

5. Registre TODOS os Erros

Cada erro vai no arquivo do plano. Isto constrói conhecimento e previne repetição.

## Erros Encontrados
| Erro | Tentativa | Resolução |
|-------|---------|------------|
| FileNotFoundError | 1 | Criado arquivo config padrão |
| API timeout | 2 | Adicionada lógica de retry |

6. Nunca Repita Falhas

if ação_falhou:
    próxima_ação != mesma_ação

Rastreie o que você tentou. Mute a abordagem.

O Protocolo de 3 Tentativas para Erros

TENTATIVA 1: Diagnosticar e Corrigir
  → Leia o erro cuidadosamente
  → Identifique a causa raiz
  → Aplique correção direcionada

TENTATIVA 2: Abordagem Alternativa
  → Mesmo erro? Tente método diferente
  → Ferramenta diferente? Biblioteca diferente?
  → NUNCA repita a ação exata que falhou

TENTATIVA 3: Reavaliação Mais Ampla
  → Questione pressupostos
  → Busque soluções
  → Considere atualizar o plano

APÓS 3 FALHAS: Escale para o Usuário
  → Explique o que você tentou
  → Compartilhe o erro específico
  → Peça orientação

Matriz de Decisão Leitura vs Escrita

O Teste de Reinicialização de 5 Perguntas

Se você conseguir responder estas, seu gerenciamento de contexto está sólido:

Quando Usar Este Padrão

Use para:

• Tarefas multi-etapas (3+ etapas)
• Tarefas de pesquisa
• Construir/criar projetos
• Tarefas que abrangem muitas chamadas de ferramentas
• Qualquer coisa que exija organização

Pule para:

• Perguntas simples
• Edições de arquivo único
• Consultas rápidas

Templates

Copie estes templates para começar:

• templates/task_plan.md — Rastreamento de fases
• templates/findings.md — Armazenamento de pesquisa
• templates/progress.md — Log de sessão

Scripts

Scripts auxiliares para automação:

• scripts/init-session.sh — Inicializar todos os arquivos de planejamento
• scripts/check-complete.sh — Verificar todas as fases concluídas

Tópicos Avançados

• Princípios Manus: Veja reference.md
• Exemplos Reais: Veja examples.md

Anti-Padrões