A spec substitui o README e a documentação do projeto?

Fala aí, beleza? A spec ficou pronta, o agente rodou, a feature entrou no ar… e agora tem um spec.md e um README.md falando coisas parecidas sobre o mesmo sistema

Aí bate a dúvida: apaga o README? Deixa a spec como documentação? Mantém os dois e reza pra ninguém ler o errado?

A pergunta parece de ferramenta, mas não é

É decisão de arquivo: quem responde o quê, onde mora e por quanto tempo aquilo continua verdade

O que a spec responde e o que o README responde

A régua mais simples é olhar a PERGUNTA que cada arquivo atende

A spec responde "o que a gente vai construir agora"

Escopo, requisitos funcionais, cenários de usuário e critérios de sucesso da tarefa atual

No Spec Kit, o toolkit de spec-driven development mantido pela GitHub, isso é literal: o /specify foca no que e no porquê, sem detalhe técnico, e a direção técnica só entra depois, no /plan, onde aparecem arquitetura e restrições

Ou seja, a spec nem é o lugar da decisão técnica, quanto mais o lugar da explicação do sistema inteiro

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

A documentação responde "como isso funciona hoje"

O que o projeto é, como roda, como se instala, quais convenções o time segue

É o arquivo que a pessoa nova abre no primeiro dia, e é também o material que vira insumo quando você joga tudo num assistente pra entender um projeto novo pelos docs

A diferença que resolve quase toda a confusão é de TEMPO

A spec fala do futuro (o que ainda não existe)

A documentação fala do presente (o que já está rodando)

Quando a feature sobe, o futuro virou presente, e aí o conteúdo precisa mudar de casa

Spec, plano, documentação e regras permanentes: quem guarda o quê

O mais interessante é que essa separação já vem desenhada nas ferramentas, com pasta e nome próprios

O Spec Kit cria uma branch numerada e uma pasta por funcionalidade dentro de specs/, e guarda as regras permanentes do projeto FORA das specs

O Kiro, a IDE agentiva da AWS, faz a mesma divisão com outro vocabulário

Repara que nenhuma das três ferramentas jogou tudo num arquivo só

Cada uma criou um lugar separado pro que sobrevive à tarefa 🙂

O que acontece quando spec e documentação se misturam

O sintoma

Dois cenários, e os dois doem

No primeiro, a documentação descreve um comportamento que o código não tem mais, e alguém segue o README até bater numa parede

No segundo, a spec vira o único lugar onde alguém explicou o sistema, então pra entender o produto você precisa ler quinze pastas de tarefas antigas, cada uma descrevendo uma intenção de um mês diferente

A causa

Isso tem nome: spec drift

É o problema em que a implementação evolui e os contratos e docs internos ficam pra trás, abrindo uma lacuna entre o que está escrito e o que roda

E misturar spec com documentação PIORA isso por matemática pura: quanto mais arquivos respondem a mesma pergunta, mais lugares precisam ser atualizados quando o comportamento muda

Um deles sempre fica pra trás, e você nunca sabe qual

A solução

Uma fonte por pergunta, e um momento definido de fusão

O OpenSpec resolve tratando a mudança como artefato descartável e o conjunto de specs como documentação viva: ao arquivar, a pasta da mudança vai pra openspec/changes/archive/, numa pasta com a data e o nome da mudança, e os requisitos marcados como ADDED, MODIFIED ou REMOVED são mesclados nos arquivos de openspec/specs/

O arquivamento ainda verifica se todas as tarefas do tasks.md foram concluídas antes de deixar a mudança sair de circulação

Se liga no desenho: a mudança some, o requisito fica

É exatamente essa a régua que falta na maioria dos repositórios que só acumulam pasta de spec

O que jogar fora quando a tarefa termina

O descarte fica fácil quando você separa por TIPO de conteúdo, não por arquivo

• Tarefa concluída e checklist de implementação: saem de circulação, cumpriram o papel e não descrevem nada do sistema
• Requisito que virou comportamento permanente: migra pra documentação, porque agora ele responde "como funciona hoje"
• Regra que vale pras próximas tarefas também: vai pro arquivo de regras permanentes, constitution no Spec Kit, steering no Kiro, CLAUDE.md no Claude Code
• Decisão técnica pontual daquela feature: fica no plano, e o plano morre junto com a tarefa

Um detalhe muda a conversa: a documentação do Kiro orienta versionar os arquivos de spec no repositório, junto do código, por design

Então em vários fluxos a pergunta não é "apagar ou não"

É "arquivar onde", e o que importa passa a ser deixar claro que aquela pasta é histórico, não a verdade atual do sistema

Escrever antes de codar não é ideia nova

Antes de acharmos que a IA inventou isso, vale o crédito

Tom Preston-Werner publicou Readme Driven Development em 23 de agosto de 2010, com um argumento que envelheceu muito bem: uma implementação perfeita da especificação errada não vale nada

A intenção é a mesma que o spec-driven development herdou, alinhar o que vai ser feito ANTES de escrever código

O que mudou foi o artefato

Em 2010 o alinhamento morava no próprio README, o mesmo arquivo que documentava o projeto

Hoje o alinhamento ganhou pasta própria, ciclo próprio e, principalmente, descarte próprio

E é justamente esse descarte que impede o README de virar um museu de intenções antigas 😀

Como organizar isso no seu projeto hoje

Na prática, três lugares e um momento

1. Um lugar pro permanente: o que o sistema é e as regras que valem sempre (README e docs, mais constitution, steering ou CLAUDE.md, conforme a ferramenta que tu usa)
2. Um lugar pra tarefa atual: a pasta da feature, com a spec, o plano e as tarefas separados por etapa
3. Um momento de fusão: quando a tarefa fecha, o que virou comportamento permanente sobe pra documentação e o resto sai de circulação

No Spec Kit o fluxo é acionado por comandos de barra dentro do agente de código: /specify pra spec, /plan pro plano técnico e /tasks pra lista de tarefas, nessa ordem

A instalação e a inicialização do projeto saem pela CLI Specify, escrita em Python, via uvx:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Já se o teu fluxo é mais leve e você não quer estrutura de pasta nenhuma pro planejamento, dá pra manter o plano FORA dos arquivos de documentação usando o plan mode do Claude Code

O Shift+Tab cicla entre default, acceptEdits e plan

No plan mode o Claude lê arquivos e explora, escreve um plano e não altera o código-fonte

O Ctrl+G abre esse plano no teu editor de texto padrão pra você editar, e aprovar o plano sai do plan mode, com o prefixo /plan voltando a planejar quando tu precisar

O ganho aqui é o mesmo dos outros: o planejamento acontece num espaço próprio, sem contaminar o arquivo que descreve o sistema

Se essa separação já virou regra fixa no teu jeito de trabalhar, o passo natural é empacotar isso numa skill de spec-driven development e parar de reexplicar em cada projeto

Conclusão

Veredito curto: a spec NÃO substitui o README, os dois convivem porque respondem perguntas diferentes e têm tempos de vida diferentes

Spec é intenção com prazo de validade

Documentação é o presente do sistema

Regra permanente é o que vale pra toda tarefa futura, e por isso mora num terceiro arquivo

Próximo passo acionável e chato do jeito certo: abre o repositório, lista o que hoje mora no README e pergunta de cada trecho se aquilo descreve o sistema ATUAL ou uma intenção antiga

O segundo grupo é candidato a virar spec ou simplesmente a sair

Faça o teste, aposto que tem parágrafo lá descrevendo uma feature que mudou faz tempo…

Até o próximo post!