AIDiveDez desenvolvedores, uma pasta de docs
Superpowers é um plugin do Claude Code (286.000 estrelas no GitHub) cujas skills escrevem specs e planos de implementação como arquivos markdown e os commitam no repositório. Por padrão, todos esses arquivos caem numa única pasta, docs/superpowers/. Em junho, os mantenedores do Okama, uma biblioteca Python de finanças, descobriram que oito planos de implementação que um agente havia escrito ali, commitados exatamente como o plugin pretende, tinham sido renderizados como páginas públicas no Read the Docs. Eles notaram depois do release.
Agora escale isso: um time de front-end com dez desenvolvedores, quatro squads, um repositório, e cada desenvolvedor gerando esses arquivos. Três perguntas caem na mesa do líder. O que exatamente versionamos? Drift é um problema quando uma spec cita um caminho apagado duas sprints atrás? E quem governa a pasta? O vazamento do Okama não foi causado por commitar. Foi causado por commitar sem uma regra. Este artigo te dá cinco.
Toda ferramenta commita os arquivos
Superpowers nunca pergunta se deve commitar. A linha 18 da sua skill de planejamento salva todo plano em docs/superpowers/plans/, datado, um arquivo por feature. A skill de brainstorming escreve o documento de design e o commita no mesmo passo, antes de você ter visto o plano.
Isso não é uma peculiaridade do Superpowers. Toda ferramenta importante de spec-driven development faz a mesma escolha:
| Ferramenta | Publisher | Onde as specs moram |
|---|---|---|
| Superpowers (286.000 estrelas) | obra | docs/superpowers/, uma pasta para tudo |
| Spec Kit (136.000 estrelas) | GitHub | uma pasta numerada por feature, na branch daquela feature |
| Kiro | Amazon | .kiro/specs/, uma pasta por feature |
| Playbook de SDLC nativo em IA | Anthropic | um artefato commitado por etapa: intent, spec, plan, diff, review findings, incident record |
O Kiro vende pastas por feature como forma de os colegas colaborarem em features diferentes ao mesmo tempo. O playbook da Anthropic, publicado em agosto, vai mais longe: toda etapa commita um artefato que a próxima etapa consegue ler. Então a pergunta nunca foi se commitar, e onde é respondida por toda ferramenta. Quem é dono do arquivo, e quando ele está morto, não são. Essa lacuna é o que as cinco regras cobrem.
Três formas de dar errado
Planos commitados falham de três formas distintas.
Falha 1: o gerador de docs. Um build de documentação que renderiza todo arquivo markdown sob docs/, esteja ou não listado num índice, publica a pasta de planos junto com o manual. Foi exatamente o que aconteceu com o Okama.
Falha 2: a branch. A issue 1246 do Superpowers relata que o brainstorm commita o plano direto na main. Um usuário conta de 10 a 15 commits por sessão, um novo a cada poucas mudanças. O pedido da thread cabe numa linha: nenhum plano ou spec na branch main.
Falha 3: drift. Spec drift é a falha silenciosa: o código evolui e a spec não. Birgitta Böckeler, da Thoughtworks, nomeia três níveis de spec-driven development:
| Nível | Significado |
|---|---|
| Spec-first | Escrita, usada uma vez |
| Spec-anchored | Mantida ao longo da vida da feature |
| Spec-as-source | O humano só edita a spec |
Superpowers escreve documentos spec-first e os mantém para sempre. Por padrão você obtém armazenamento spec-anchored com manutenção de primeiro rascunho: ninguém atualiza o arquivo, e um agente o lê no trimestre seguinte como verdade. A TrueFoundry coloca isso claramente: drift é inevitável na prática spec-first e administrável na prática spec-anchored, mas só se a divergência for detectável.
Um repositório com 41 specs e 9 agent files não tem um problema de organização. Tem 41 inputs de comportamento não versionados. A própria reação de Böckeler: ela preferiria revisar código a todos esses arquivos markdown. Um plano que nunca mais é carregado é lixo. Um plano que um agente carrega é uma instrução, e uma instrução obsoleta é uma instrução errada.
Regra 1: uma casa por squad, com donos
Regra 1: a pasta tem um dono, e o dono é um squad, não o plugin. Desde a versão 5, o Superpowers respeita as instruções do CLAUDE.md do seu projeto acima dos próprios defaults. Diga onde os planos vão e é lá que eles vão.
Uma tabela de caminhos não basta, porém. Na issue 939, um usuário escreveu uma tabela de output paths e o modelo seguiu o caminho concreto na skill e ignorou a tabela. A própria nota de override da skill é um parêntese. Uma linha em negrito e imperativa resolveu isso na primeira tentativa: specs devem ser salvas aqui, não ali, com o default nomeado como a coisa a evitar.
O layout é uma pasta por squad (checkout, search, accounts, design-system), cada uma com suas próprias specs e planos. Num monorepo, coloque a linha no CLAUDE.md do próprio pacote. O Claude Code carrega o arquivo de um subdiretório sob demanda quando lê ali, e a documentação diz que o dono de cada diretório costuma manter o próprio arquivo. Engenheiros que nunca instalaram o plugin não são afetados: a linha só entra em ação quando uma skill pergunta onde salvar.
Depois, deixe a plataforma reforçar a propriedade. Uma linha de CODEOWNERS por pasta de squad, e toda review de spec cai com as pessoas que vão viver com ela. Uma ressalva: o override é um prompt, não uma configuração. Confira a primeira spec depois de todo release do plugin.
Regra 2: pessoal versus compartilhado
Regra 2: nem todo plano é um artefato de time. A primeira pessoa a pedir ao Superpowers uma localização configurável (issue 337) disse isso da melhor forma: arquivos de plano podem ser documentos de trabalho pessoais em vez de artefatos do projeto.
O lado pessoal tem um arquivo feito para isso. CLAUDE.local.md fica ao lado do arquivo compartilhado, carrega depois dele, e a documentação diz para você mesmo colocá-lo no .gitignore. Seu redirecionamento para uma pasta privada mora ali e ninguém mais vê. Para a pasta em si, o Git tem um arquivo de ignore que nunca toca a árvore compartilhada: .git/info/exclude é por clone, nunca é commitado, e não precisa de pull request. O próprio plugin já faz isso com o seu espaço de rascunho: desde a versão 6.0.3, seu diretório de trabalho cria um .gitignore contendo * dentro de si mesmo, então ele se auto-ignora sem tocar em um arquivo versionado.
O lado compartilhado é o que passou pelo gate de review que o próprio brainstorm já executa: spec escrita, review solicitada, aprovada por uma segunda pessoa. Aprovada, ela se move para a pasta do squad. Não aprovada, fica local. Ambas são escritas numa branch, nunca na main. Duas linhas no CLAUDE.md compartilhado fazem isso: tratar specs e planos como o início de uma feature, e criar o worktree antes de escrevê-los.
Um limite: uma spec no .gitignore não viaja. Os mantenedores do Okama tentaram ignorar a pasta primeiro e revertaram, porque os planos pararam de sincronizar entre máquinas e agentes. Pessoal significa pessoal.
Regra 3: um ciclo de vida, como ADRs
Regra 3: uma spec tem um status, e uma spec morta diz isso. A ideia tem 15 anos. Michael Nygard, em 2011, propôs manter architecture decision records (ADRs) no repositório, um arquivo numerado para cada uma. Uma decisão é proposta, depois aceita. Quando um registro posterior a muda, o antigo é marcado como deprecated ou superseded com uma referência ao seu substituto. Se uma decisão é revertida, o registro antigo é mantido, mas marcado como superseded.
Aplicado a specs, toda spec compartilhada abre com um cabeçalho de cinco linhas que o agente já lê:
| Campo | Propósito |
|---|---|
| status | proposed, accepted, superseded |
| superseded-by | a spec substituta |
| owner | o squad |
| touches | os caminhos sobre os quais a spec faz afirmações |
| review date | quando foi verificada por último |
Nunca edite uma spec accepted transformando-a numa decisão diferente. Escreva a próxima, aponte-a de volta, e o histórico permanece honesto. Uma exceção, declarada no playbook da Anthropic: quando a implementação se desvia do plano, atualize o plano no mesmo commit. O plano viaja junto com o diff que o quebrou, e um hook pode reforçar isso.
Spec Kit nomeia três formas de uma spec viver. Flow-forward: uma pasta nova por feature, as antigas mantidas como histórico. Living spec: a spec é o contrato e o resto é regenerado. Flow-back: o build remodela a spec. A regra deles é não deixar uma mudança em tasks ou código se a spec ainda disser algo diferente. Isso é escolher spec-anchored de propósito.
O limite: status é metadado que um humano define. O agente não vai marcar a própria spec como superseded a menos que seu CLAUDE.md diga isso, e mesmo assim a review precisa notar.
Regra 4: um drift gate no CI
Regra 4: uma spec que mente sobre a árvore de arquivos falha o build. O paper que nomeou o problema, publicado em junho, chama isso de silent spec-code drift: o código evolui, a especificação não, e a divergência fica invisível até ficar cara de corrigir. A resposta dele é um drift gate, uma condição bloqueante de merge.
A checagem é menor do que parece. Para toda spec cujo cabeçalho diz accepted, extraia os caminhos que ela cita, em backticks ou na linha touches, e teste se cada um existe. Caminho ausente, build falha, com o nome da spec no log. Arquivos superseded e proposed são ignorados: só specs accepted fazem afirmações sobre a árvore, então só specs accepted são checadas. A TrueFoundry enquadra isso como um diff agendado em vez de arqueologia pós-incidente: uma spec é scaffold, e uma mudança de spec é uma mudança de política.
As pessoas já rodam a versão manual disso. Um comentarista faz o Claude comparar os arquivos de spec com a base de código e abrir tickets para o que está faltando. O script faz isso em todo pull request, de graça.
A segunda proteção é a que o Okama implementou: excluir a pasta do build de docs. Uma linha na configuração do Sphinx mantém os arquivos no Git, mas fora do HTML.
O limite: uma checagem de caminho pega arquivos apagados, não comportamento mudado. Uma spec pode citar todo arquivo existente e ainda descrever uma API que já não existe. É para isso que servem a review e a regra do mesmo commit.
Regra 5: um orçamento de tamanho, e o custo
Regra 5: a maior parte do trabalho não merece uma spec. A evidência sobre o overhead de spec-driven development é consistente:
| Experimento | Resultado |
|---|---|
| Marmelab, Spec Kit numa feature que mostra a data atual | 8 arquivos, 1.300 linhas de texto de especificação |
| Bake-off do OpenSpec, mesmos requisitos com uma spec tool vs. Claude Code puro | 50% mais código, 50% mais complexidade ciclomática, o dobro do tempo, o triplo do custo |
| Um time rodando spec-driven development por meses | 2 a 3 vezes mais tokens, cerca do dobro do tempo, alto custo de coordenação para mudanças que não precisavam disso; nenhuma prova de que o código melhorou |
O bake-off é um experimento, não um benchmark, e o próprio autor diz isso. Mas a direção se mantém. Então a regra: escreva uma spec quando o trabalho cruza a fronteira de um squad ou vai ser lido de novo em 90 dias. Todo o resto é um prompt.
Superpowers já classifica todo pedido em três caminhos: spike, bounded, architectural. Só o caminho architectural escreve uma spec. Mantenha o caminho bounded bounded, e mantenha a spec perto de 300 linhas. Praticantes acrescentam duas linhas: não faça spec grande demais, e leia as specs geradas.
O limite corta dos dois lados. O mesmo bake-off encontrou três lacunas que a execução simples deixou passar. A spec compra cobertura, não velocidade. Pague por ela onde a cobertura importa.
Veredito: commite, depois governe
Voltando às três perguntas do líder. O que versionamos: specs e planos aprovados, numa branch, na pasta do squad. Drift: um cabeçalho de status e um gate de CI. Governança: donos e uma regra de tamanho.
Cinco regras, e nenhuma delas é reforçada por uma ferramenta hoje. A issue de override está aberta. A issue da branch main está aberta. O pull request que reordenou a instrução foi fechado sem merge. O time que se queimou manteve a prática: 8 planos e 6 specs, commitados, excluídos do build de docs.
A objeção de Böckeler se mantém. Com um cabeçalho de status e um orçamento de tamanho, você lê só as specs accepted, e menos delas. O que você ganha de volta é o que o playbook da Anthropic chama de audit trail: quem pediu o quê, o que o agente produziu, e quem aprovou.
Isso é processo, não ferramenta: um arquivo CLAUDE.md, um arquivo CODEOWNERS, um cabeçalho, e um script de quinze linhas. E se o time não vai revisar um pedido de CODEOWNERS, também não vai revisar uma spec. Nesse caso, o .gitignore era a escolha honesta.
