Lição 4 de 8: Nomear o plano da fatia 1

A fatia 1 do roadmap vira agora um arquivo de planoO documento que detalha como construir uma fatia: um arquivo `feat-<algo>.md` em `plans/` com seções fixas: contexto, Goal, Acceptance criteria (verificáveis), Out of scope e task list. É o input do comando `/work` do Claude Code. em plans/, com nome feat-<algo>.md. Esta lição é só sobre o nome desse arquivo. A próxima (L05) escreve o conteúdo.

O nome do arquivo é um dos dados que Claude usa para decidir o nível de especificidade do conteúdo. Nome vago tipo feat-add-recibo.md → Claude assume que o escopo ainda não foi decidido e responde genérico. Nome específico tipo feat-pdf-recibo-MEI-com-CPF-validado.md → Claude trata os elementos do nome como parte do escopo mínimo.

Comparação: dois planos para a mesma fatia

Mesma entrega da fatia 1 do roadmap; dois nomes possíveis.

Nome vago

Nome do arquivo (em plans/):

feat-add-recibo.md

Conteúdo gerado por Claude com esse nome:

Goal

Adicionar funcionalidade de emissão de recibo ao sistema.

Acceptance criteria

• Usuário consegue criar um recibo
• Recibo é exportado em PDF
• Sistema funciona corretamente

Dois problemas concretos. Os critérios de aceitação não são verificáveis ("funciona corretamente" não dá pra testar com sim/não). E o escopo não cobre validação de CPF, numeração padronizada, lógica de dias úteis nem formato fiscal, coisas que vão aparecer durante a implementação como retrabalho.

Nome específico

Mesma fatia, nome diferente:

feat-pdf-recibo-MEI-com-CPF-validado-e-numeracao-sequencial.md

Conteúdo gerado por Claude com esse nome:

Goal

Permitir que contador autônomo emita recibo em PDF para cliente MEI, com CPF validado na entrada (formato + dígito verificador) e numeração sequencial automática por contador.

Acceptance criteria

• CPF inválido (ex: 000.000.000-00) é rejeitado com mensagem clara
• Numeração reinicia em 0001 a cada virada de ano fiscal (1/1)
• PDF gerado tem layout fixo: logo do contador no topo, dados do cliente, valor por extenso, assinatura digital opcional
• Performance: PDF gerado em menos de 2 segundos para recibo simples (sem assinatura)

Mesma fatia, conteúdo proposto totalmente diferente. A diferença está no nome do arquivo.

As 3 perguntas que tornam um nome específico

Para qualquer fatia, você responde três perguntas no nome.

Passo 1: decida o nome do arquivo

Pegue a entrega da fatia 1 do seu docs/roadmap.md (você já viu o nome ⭐ proposto pelo Claude no fim da L03). Cole no Claude com as 3 perguntas:

Leia o `docs/product.md` e o `docs/roadmap.md` deste projeto. Considerando a entrega da fatia 1:

> [DELIVERABLE_FATIA_1]

Proponha **um único nome** para o arquivo de plano (que vai morar em `plans/`, no formato `feat-<algo>.md`) que implementa essa fatia, respondendo as 3 perguntas no próprio slug:

1. **Entrada exata.** Qual é o input? CPF? CNPJ? Upload de CSV? Formulário preenchido?
2. **Saída exata.** Qual é o output? PDF? Email? Link? Notificação?
3. **Edge case brasileiro.** Algum case BR está dentro do escopo (ex: validação na Receita, NFS-e, Pix com fallback)? Algum está EXPLICITAMENTE fora (ex: `-sem-nfse`)?

Regras:
- kebab-case
- até 12 palavras (cerca de 70 caracteres depois do prefixo)
- prefixo `feat-` (Conventional Commits)
- não use palavras vagas: `add`, `implement`, `build`, `create`, `feature`

Saída: o nome único + 1 linha justificando cada uma das 3 perguntas (entrada / saída / edge BR). Não escreva o conteúdo do plano ainda, apenas o nome.

Leia o nome que Claude propôs. Se as 3 perguntas estão respondidas, siga. Se alguma está vaga, peça ajuste:

O nome que você propôs não responde a pergunta 3 (edge case brasileiro). Refaça incluindo um edge case específico, pode ser positivo (`com-validacao-cpf`) ou negativo (`-sem-nfse`). Se você não souber qual edge case se aplica, me pergunte antes de chutar.

Passo 2: renomeie ou crie o arquivo

Se você já criou um plano com nome vago e precisa renomear:

Renomeie o arquivo `plans/[NOME_ANTIGO].md` para `plans/[NOME_NOVO].md` usando `git mv` para preservar histórico:

`git mv plans/[NOME_ANTIGO].md plans/[NOME_NOVO].md`

Mostre o comando antes de executar.

Se você ainda não criou o arquivo, crie com o nome correto agora (Claude vai escrever o conteúdo na L05):

Crie o arquivo `plans/[NOME_NOVO].md` com este placeholder mínimo:

# [NOME_NOVO]

> Plano da fatia 1. Conteúdo escrito na L05.

Mostre o diff antes de criar.

Passo 3: faça o commit

Se você renomeou:

Faça commit com mensagem `chore(plans): rename feat-X to feat-Y` (substitua X e Y pelos nomes reais). O git mv já fez o stage; basta fazer o commit.

Se você criou novo:

Faça commit com mensagem `docs(plans): scaffold feat-Y plan for slice 1` (substitua Y pelo nome). Stage só esse arquivo.

Aprove git commit. Confira no GitHub.

Verificação: leia o nome em voz alta

Cubra a tela onde está o conteúdo do plano e leia apenas o nome do arquivo em voz alta. Você consegue explicar para um amigo, em até 30 segundos, exatamente o que vai construir?

Se sim, o nome está específico o suficiente. Se não, qual das 3 perguntas falta?

Build Diary: 3 nomes reais de planos do CEAP

A pasta de planos do CEAP tem 3 features documentadas:

feat-tcu-guide-tab
feat-operacao-galho-fraco-spotlight
feat-unified-email-service

Aplicando as 3 perguntas (entrada / saída / edge BR) em cada:

feat-tcu-guide-tab: entrega aba nova no dashboard. Audiência: TCU. Função: guia. Responde 2 das 3: saída (aba/guia) + edge (audiência específica do TCU). Entrada não está no nome, está no conteúdo do plano.

feat-operacao-galho-fraco-spotlight: entrega página de "spotlight" sobre uma operação policial específica (Galho Fraco). Responde as 3: entrada (dados da operação Galho Fraco), saída (spotlight = página dedicada), edge (operação real do PF).

feat-unified-email-service: entrega serviço unificado de envio de email. Responde 2 das 3: entrada (vários produtos enviando email separadamente), saída (serviço unificado). O edge BR fica de fora, e com razão: é infraestrutura interna, sem caso BR específico.

Nenhum deles é feat-add-feature ou feat-improve-X. Mesmo o feat-unified-email-service, que é o mais genérico dos três, ainda diz a entrada (vários produtos enviando email) e a saída (serviço unificado).

Takeaways

• O nome do arquivo é um dos dados que Claude usa para decidir o nível de especificidade do conteúdo. Um nome vago produz conteúdo genérico. Um nome específico produz escopo concreto.
• 3 perguntas separam vago de específico: entrada exata, saída exata, edge case brasileiro (positivo ou negativo).
• 2 das 3 perguntas no nome já bastam. A 3ª pode ficar no conteúdo do plano (Goal).
• Commit do arquivo vazio antes de escrever (L05): assim Claude lê o nome direto, sem precisar deduzir da sua descrição.

Você terminou quando

O nome do arquivo de plano (em plans/, com prefixo feat-) responde pelo menos 2 das 3 perguntas (entrada, saída, edge case brasileiro). O arquivo está commitado no GitHub.