Pular para o conteúdo

Builder OS

&
Builder · OS
L06 · Artefato durável
PRÓXIMA L07
~11 MIN DE LEITURA

Lição 6 de 8: O plano como artefato durável

lição 6/8 do Módulo 2
AO FIM, VOCÊ VAI TER
  • O feat-<nome>.md da fatia 1 confirmado como artefato versionado em plans/ (commitado, não em rascunho de chat)
  • Um teste de sobrevivência: você roda /clear, abre sessão nova, e ela continua a fatia lendo só o plano
  • Critério pessoal de quando escrever spec antes de mexer no código (toca usuário, dinheiro ou dado → spec primeiro)

A L05 te ensinou as 5 seções do plano. Esta lição é sobre o que esse arquivo é depois de escrito: o input que o /work vai executar no M3, e que precisa fazer sentido mesmo pra uma sessão que nunca viu a conversa onde ele nasceu.

Por que a intenção da fatia mora num arquivo, não no chat

No M1/L06 você encheu uma janela de contexto até ela ficar longa demais e viu o Claude esquecer uma regra que estava nas instruções. Foi uma demonstração de que a sessão se degrada conforme enche (o context rot). Aqui o foco é o outro lado da mesma moeda. A sessão é volátil: esvazia no /clear, perde qualidade conforme enche, some quando você fecha a janela. Então a intenção do que você está construindo não pode morar só na conversa. Ela mora num arquivo.

Esse arquivo é o plans/feat-<nome>.md. Ele é versionado no git, relido sob demanda, e independente da sessão que o escreveu. Quando você roda /clear no meio de uma fatia, perde o histórico do chat. Mas o plano continua no disco, e a próxima sessão o lê e retoma. É isso que faz dele um : o trabalho da fatia fica registrado no arquivo, que permanece depois que a memória da sessão já resetou.

Spec antes de "vibar": para qualquer coisa que toca usuário, dinheiro ou dado

Tem um modo de trabalhar que funciona bem pra explorar: você abre o Claude, descreve a ideia em uma frase, e vai acertando junto, sem plano escrito. Isso é vibe coding, e tem lugar: um protótipo descartável, um script de uma vez só, uma página que você vai jogar fora amanhã.

O critério pra sair desse modo é concreto: se a fatia toca usuário (alguém de verdade vai usar), dinheiro (valor monetário, cobrança, recibo) ou dado (persiste em banco, migra schema, altera registro; e, quando o dado é pessoal ou de fonte oficial, carrega regra de retenção, origem e LGPD junto), você escreve o primeiro. A razão é que o vibe coding deixa a intenção dispersa na conversa. E conversa não sobrevive a um /clear, não entra no git, e não dá pra outro contribuidor (nem você daqui a duas semanas) reconstruir o porquê de cada decisão.

Pro recibo em PDF da L05, que valida CPF e numera sequencialmente por contador, a regra de numeração é uma decisão: reinicia a cada ano fiscal ou segue contínua? As duas opções existem em sistemas reais. O risco do vibe coding está em deixar essa escolha implícita: o código sai com alguma numeração que ninguém decidiu de propósito, e você só descobre qual foi quando um recibo duplica na virada do ano. O spec é onde você fixa a regra antes de o código inventar uma sozinho.

O teste que prova que o plano é durável: ele sobrevive a um reset?

Um spec é durável quando uma sessão que nunca viu a conversa original consegue continuar a fatia lendo só ele. Isso é testável, e vale a pena testar antes de chegar no /work do M3. Um plano que só faz sentido pra quem estava no chat vai falhar exatamente no momento em que você mais precisa dele: depois de um /clear, no meio de uma sessão longa.

Confirme que o plano é artefato, não rascunho de chat. O feat-<nome>.md da L05 está commitado em plans/? Se as 5 seções moram numa resposta do Claude que você ainda não salvou no arquivo, elas vão embora no próximo /clear. Salve e comite primeiro: o artefato durável é o arquivo no git, não o texto na conversa.

Force o reset. Rode /clear. A sessão atual perde tudo: o histórico de como você chegou no plano, as decisões que discutiram, o contexto que você acumulou. Sobrou o que está no disco.

Peça pra sessão nova retomar lendo só o plano. Depois do /clear, a sessão atual já está limpa: ela não enxerga mais nada da conversa anterior, é como começar do zero no mesmo projeto. Sem reabrir o histórico antigo, peça pro Claude ler o plans/feat-<nome>.md e descrever a primeira tarefa, o primeiro arquivo a tocar, e o que ainda está ambíguo. Se ele consegue descrever um próximo passo coerente, o plano carrega contexto suficiente pra ser retomado sozinho. Se ele trava ou pede contexto que só existia no chat antigo, o plano dependia da conversa. E você acabou de achar a lacuna antes da execução achar por você.

prompt · text
Esta é uma sessão nova. Você não tem nenhum contexto anterior sobre este projeto além do que está no disco.

Leia `plans/.md` e, lendo apenas esse arquivo (mais o que ele apontar), me diga:

1. Qual é a primeira tarefa que você executaria.
2. Qual arquivo ou diretório você tocaria primeiro.
3. O que, no plano, está ambíguo o suficiente pra você precisar me perguntar antes de começar, ou "nada, o plano está claro" se for o caso. Não force ambiguidade pra parecer crítico.

Se você precisou de informação que não está no plano nem em arquivos que ele aponta, me diga exatamente qual: é uma lacuna que o plano deveria cobrir.
NOME_DO_PLANO[NOME_DO_PLANO]— o nome do arquivo de plano da fatia 1 (sem prefixo plans/ e sem .md). Ex: feat-pdf-recibo-MEI-sem-nfse-com-cpf-validado.

Se a sessão nova retoma com um próximo passo claro, o plano é durável de verdade. Se ela pede algo que só existia na conversa antiga, volte ao plano e escreva essa informação dentro dele: é literalmente o que significa fazer o spec sobreviver ao reset.

A cadeia de artefatos, do produto ao código

O Módulo 2 inteiro é uma cadeia de artefatos duráveis, cada um alimentando o próximo. O docs/product.md guarda o wedge e quem você serve. O docs/roadmap.md guarda as fatias verticais. O plans/feat-<nome>.md guarda como construir a fatia 1. (Se você chegou aqui sem o docs/product.md ou o docs/roadmap.md montados, eles vêm das lições L02 e L03 deste módulo; vale ter os dois antes de seguir, porque o plano da fatia se apoia neles.) Nenhum desses arquivos vive numa sessão de chat: todos são versionados, relidos sob demanda. É por isso que você consegue fechar a janela hoje e retomar amanhã. A intenção está no disco, em camadas, da estratégia do produto até a tarefa concreta.

No M3, o /work lê o plans/feat-<nome>.md e o executa tarefa por tarefa. O teste desta lição prova uma coisa específica: que o plano carrega contexto suficiente pra ser retomado sem a conversa original. Isso é pré-requisito pro /work funcionar bem, não garantia: um plano completo ainda pode ser mal executado, e por isso o M3 tem suas próprias checagens. Mas um plano que falha no teste de sobrevivência tende a falhar no /work pela mesma razão: falta contexto que só existia no chat. Passar no teste remove esse modo de falha antes de chegar lá.

Takeaways

  • O plano é um artefato durável: arquivo versionado em plans/ que sobrevive ao /clear, é relido sob demanda e independe da sessão que o escreveu.
  • O critério pra sair do vibe coding e escrever o spec primeiro: a fatia toca usuário, dinheiro ou dado. Aí a intenção precisa ficar no arquivo, não na conversa.
  • Teste de sobrevivência: depois de um /clear, uma sessão nova retoma a fatia lendo só o plano. Se ela pede contexto que só existia no chat, esse contexto vira uma linha no plano (ou no CLAUDE.md).
  • O Módulo 2 inteiro é uma cadeia de artefatos: docs/product.md → docs/roadmap.md → plans/feat-<nome>.md. O /work do M3 lê o último e executa tarefa por tarefa.

Você terminou quando

O feat-<nome>.md da fatia 1 está commitado em plans/, e você rodou o teste de sobrevivência: depois de um /clear, uma sessão nova leu só o plano e descreveu um próximo passo coerente, sem pedir nada que só existia na conversa anterior.