Modo de Planejamento
Use este skill quando o usuário quiser um plano em vez de execução.
Comportamento principal
Para esta interação, você está apenas planejando.
- Não implemente código.
- Não edite arquivos do projeto, exceto o arquivo de plano em markdown.
- Não execute comandos mutantes no terminal, faça commit, push ou realize ações externas.
- Você pode inspecionar o repositório ou outro contexto com comandos/ferramentas somente leitura quando necessário.
- Sua entrega é um plano em markdown salvo dentro do workspace ativo em
.hermes/plans/.
Requisitos de saída
Escreva um plano em markdown que seja concreto e acionável.
Inclua, quando relevante:
- Objetivo
- Contexto/suposições atuais
- Abordagem proposta
- Plano passo a passo
- Arquivos que provavelmente serão alterados
- Testes / validação
- Riscos, trade-offs e perguntas em aberto
Se a tarefa for relacionada a código, inclua caminhos de arquivo exatos, possíveis alvos de teste e etapas de verificação.
Local de salvamento
Salve o plano com write_file em:
.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md
Trate isso como relativo ao diretório de trabalho ativo / workspace do backend. As ferramentas de arquivo do Hermes são cientes do backend, portanto, usar esse caminho relativo mantém o plano no workspace nos backends local, docker, ssh, modal e daytona.
Se o runtime fornecer um caminho de destino específico, use esse caminho exato.
Se não, crie você mesmo um nome de arquivo com timestamp sensato em .hermes/plans/.
Estilo de interação
- Se a solicitação for clara o suficiente, escreva o plano diretamente.
- Se nenhuma instrução explícita acompanhar
/plan, infira a tarefa a partir do contexto atual da conversa. - Se for genuinamente subespecificado, faça uma breve pergunta esclarecedora em vez de adivinhar.
- Após salvar o plano, responda brevemente com o que foi planejado e o caminho salvo.
Escrevendo o Plano Bem
O restante deste skill é a arte de criar um bom plano de implementação — o conteúdo que vai dentro do arquivo markdown acima.
Visão geral
Escreva planos de implementação abrangentes assumindo que o implementador tem zero contexto sobre a base de código e gosto questionável. Documente tudo o que eles precisam: quais arquivos tocar, código completo, comandos de teste, documentações a verificar, como verificar. Dê a eles tarefas pequenas. DRY. YAGNI. TDD. Commits frequentes.
Assuma que o implementador é um desenvolvedor habilidoso, mas sabe quase nada sobre o conjunto de ferramentas ou domínio do problema. Assuma que eles não sabem muito bem projetar testes.
Princípio central: Um bom plano torna a implementação óbvia. Se alguém precisa adivinhar, o plano está incompleto.
Quando um Plano de Implementação Completo Ajuda
Sempre use antes de:
- Implementar funcionalidades com várias etapas
- Decompor requisitos complexos
- Delegar para subagentes via desenvolvimento orientado por subagentes
Não pule quando:
- A funcionalidade parece simples (suposições causam bugs)
- Você planeja implementar você mesmo (você futuro precisa de orientação)
- Trabalhando sozinho (a documentação é importante)
Granularidade de Tarefa Pequena
Cada tarefa = 2-5 minutos de trabalho focado.
Cada passo é uma ação:
- "Escrever o teste falhando" — passo
- "Executá-lo para garantir que falha" — passo
- "Implementar o código mínimo para fazer o teste passar" — passo
- "Executar os testes e garantir que passam" — passo
- "Fazer commit" — passo
Grande demais:
### Tarefa 1: Construir sistema de autenticação
[50 linhas de código em 5 arquivos]
Tamanho certo:
### Tarefa 1: Criar modelo User com campo email
[10 linhas, 1 arquivo]
### Tarefa 2: Adicionar campo de hash de senha ao User
[8 linhas, 1 arquivo]
### Tarefa 3: Criar utilitário de hash de senha
[15 linhas, 1 arquivo]
Estrutura do Documento do Plano
Cabeçalho (Obrigatório)
Todo plano DEVE começar com:
# [Nome da Funcionalidade] Plano de Implementação
> **Para Hermes:** Use o skill de desenvolvimento orientado por subagentes para implementar este plano tarefa por tarefa.
**Objetivo:** [Uma frase descrevendo o que isso constrói]
**Arquitetura:** [2-3 frases sobre a abordagem]
**Stack:** [Principais tecnologias/bibliotecas]
---
Estrutura da Tarefa
Cada tarefa segue este formato:
### Tarefa N: [Nome Descritivo]
**Objetivo:** O que esta tarefa realiza (uma frase)
**Arquivos:**
- Criar: `caminho/exato/para/novo_arquivo.py`
- Modificar: `caminho/exato/para/existente.py:45-67` (linhas, se conhecidas)
- Teste: `tests/caminho/para/teste_arquivo.py`
**Passo 1: Escrever teste falhando**
```python
def test_comportamento_especifico():
resultado = funcao(entrada)
assert resultado == esperado
```
**Passo 2: Executar teste para verificar falha**
Execute: `pytest tests/caminho/teste.py::test_comportamento_especifico -v`
Esperado: FAIL — "function not defined"
**Passo 3: Escrever implementação mínima**
```python
def funcao(entrada):
return esperado
```
**Passo 4: Executar teste para verificar passagem**
Execute: `pytest tests/caminho/teste.py::test_comportamento_especifico -v`
Esperado: PASS
**Passo 5: Fazer commit**
```bash
git add tests/caminho/teste.py src/caminho/arquivo.py
git commit -m "feat: adicionar funcionalidade específica"
```
Processo de Escrita
Passo 1: Entender Requisitos
Leia e entenda:
- Requisitos da funcionalidade
- Documentos de design ou descrição do usuário
- Critérios de aceitação
- Restrições
Passo 2: Explorar a Base de Código
Use ferramentas Hermes para entender o projeto:
# Entender estrutura do projeto
search_files("*.py", target="files", path="src/")
# Ver funcionalidades semelhantes
search_files("padrao_semelhante", path="src/", file_glob="*.py")
# Verificar testes existentes
search_files("*.py", target="files", path="tests/")
# Ler arquivos chave
read_file("src/app.py")
Passo 3: Projetar Abordagem
Decida:
- Padrão de arquitetura
- Organização dos arquivos
- Dependências necessárias
- Estratégia de teste
Passo 4: Escrever Tarefas
Crie tarefas em ordem:
- Setup/infraestrutura
- Funcionalidade central (TDD para cada)
- Casos de borda
- Integração
- Limpeza/documentação
Passo 5: Adicionar Detalhes Completos
Para cada tarefa, inclua:
- Caminhos de arquivo exatos (não "o arquivo de configuração" mas
src/config/settings.py) - Exemplos de código completos (não "adicione validação" mas o código real)
- Comandos exatos com saída esperada
- Etapas de verificação que provam que a tarefa funciona
Passo 6: Revisar o Plano
Verifique:
- Tarefas são sequenciais e lógicas
- Cada tarefa é pequena (2-5 min)
- Caminhos de arquivo são exatos
- Exemplos de código são completos (copiáveis)
- Comandos são exatos com saída esperada
- Nenhum contexto faltando
- Princípios DRY, YAGNI, TDD aplicados
Princípios
DRY (Don't Repeat Yourself)
Ruim: Copiar e colar validação em 3 lugares Bom: Extrair função de validação, usar em todos os lugares
YAGNI (You Aren't Gonna Need It)
Ruim: Adicionar "flexibilidade" para requisitos futuros Bom: Implementar apenas o necessário agora
# Ruim — violação YAGNI
class User:
def __init__(self, name, email):
self.name = name
self.email = email
self.preferences = {} # Não necessário ainda!
self.metadata = {} # Não necessário ainda!
# Bom — YAGNI
class User:
def __init__(self, name, email):
self.name = name
self.email = email
TDD (Test-Driven Development)
Cada tarefa que produz código deve incluir o ciclo completo de TDD:
- Escrever teste falhando
- Executar para verificar falha
- Escrever código mínimo
- Executar para verificar passagem
Veja o skill test-driven-development para detalhes.
Commits Frequentes
Faça commit após cada tarefa:
git add [arquivos]
git commit -m "tipo: descrição"
Erros Comuns
Tarefas Vagas
Ruim: "Adicionar autenticação" Bom: "Criar modelo User com campos email e password_hash"
Código Incompleto
Ruim: "Passo 1: Adicionar função de validação" Bom: "Passo 1: Adicionar função de validação" seguido do código completo da função
Verificação Faltando
Ruim: "Passo 3: Testar se funciona"
Bom: "Passo 3: Executar pytest tests/test_auth.py -v, esperado: 3 passaram"
Caminhos de Arquivo Faltando
Ruim: "Criar o arquivo de modelo"
Bom: "Criar: src/models/user.py"
Entrega de Execução
Após salvar o plano, ofereça a abordagem de execução:
"Plano completo e salvo. Pronto para executar usando desenvolvimento orientado por subagentes — despacharei um subagente novo por tarefa com revisão em dois estágios (conformidade com especificações, depois qualidade de código). Devo prosseguir?"
Ao executar, use o skill subagent-driven-development:
- Novo
delegate_taskpor tarefa com contexto completo - Revisão de conformidade com especificações após cada tarefa
- Revisão de qualidade de código após a especificação passar
- Prossiga apenas quando ambas as revisões aprovarem
Lembrete
Tarefas pequenas (2-5 min cada)
Caminhos de arquivo exatos
Código completo (copiável)
Comandos exatos com saída esperada
Etapas de verificação
DRY, YAGNI, TDD
Commits frequentes
Um bom plano torna a implementação óbvia.