AIDive

Pack de vídeo

Governar specs e planos de IA no Git: cinco regras, drift gate, fontes e checklist

11 min de leitura

TL;DR

  • Faça commit de specs e planos escritos por IA. Todas as ferramentas já fazem isso por padrão; a questão em aberto é a governança.
  • Dê a cada squad uma pasta com uma linha no CODEOWNERS, para que uma mudança de spec peça revisão aos donos do código.
  • Coloque um cabeçalho no estilo ADR em toda spec compartilhada: status, superseded-by, owner, caminhos tocados, data de revisão. Nunca reescreva uma spec aceita para virar uma nova decisão.
  • Rode um drift gate no CI: para cada spec aceita, quebre o build quando um caminho citado nela não existir mais.
  • Redirecione o caminho de saída com uma linha imperativa em negrito no CLAUDE.md, mantenha planos pessoais em CLAUDE.local.md e .git/info/exclude, e escreva em uma branch, nunca na main.
  • Faça spec só do trabalho que cruza a fronteira de um squad ou que será relido em 90 dias. Execuções spec-driven custam cerca de o dobro do tempo e o triplo de tokens.

O que dizem as fontes

Os padrões: todo mundo faz commit

A skill writing-plans do Superpowers salva os planos em docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, com uma linha logo abaixo dizendo que as preferências do usuário sobre o local do plano substituem esse padrão s1. A skill brainstorming grava o design validado em docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md e termina com "Commit the design document to git" s2. O Spec Kit organiza specs/[branch-name]/ com spec.md, plan.md e tasks.md, numerados 001, 002, além de uma constitution em memory/constitution.md s6. O Kiro mantém .kiro/specs/ com uma pasta por feature e convida os times a "collaborate with team members on different features simultaneously" s8. O playbook da Anthropic é explícito: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md" e "When implementation departs from the plan, update plan.md in the same commit" s5.

Nenhum desses documentos diz quem é dono de uma spec commitada nem quando ela deixa de ser verdadeira. As três falhas documentadas moram nessa lacuna.

Falha 1: o vazamento público

A issue 1690, aberta em 2026-06-05, relata que o local padrão docs/superpowers/ pode vazar planos internos para a documentação publicada via Sphinx e Read the Docs s15. O projeto afetado foi o okama, uma biblioteca Python com 273 estrelas. O commit de correção readicionou 5 planos e 3 specs, removeu uma linha do .gitignore e diz "track superpowers plans/specs in git, excluded from the Sphinx build" s21. A linha 84 de docs/conf.py agora tem exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Hoje a pasta tem 8 planos e 6 specs s15. O time manteve a prática e consertou o build.

Falha 2: planos na main

A issue 1246, aberta em 2026-04-22 e ainda aberta, pergunta por que o plano é commitado antes de existir uma branch de desenvolvimento. Um usuário relata "I'm getting 10 to 15 commits"; outro: "Yes please, no plans and specs on main branch!" s16. O plugin não impõe uma regra de branch; a checklist abaixo impõe.

Falha 3: overrides que o modelo ignora

A issue 337 foi fechada em 2026-03-10 com a nota do mantenedor de que, desde a v5.0, o plugin respeita o CLAUDE.md do seu projeto acima dos próprios padrões, com a linha de exemplo: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. A issue 939, na v5.0.6, mostra o limite: uma tabela "Output Paths" no CLAUDE.md foi ignorada e as specs continuaram caindo em docs/superpowers/specs/. O workaround que funcionou é uma linha imperativa em negrito abaixo da tabela: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. O pull request 1020, que reordenava a instrução, foi fechado sem merge s19. O override é um prompt, não uma configuração: confira de novo a cada release do plugin. Para os arquivos temporários do próprio plugin, a issue 1780 foi fechada pela v6.0.3 com uma pasta .superpowers/sdd/ que se auto-ignora, criando o próprio .gitignore contendo * s20.

Pessoal versus compartilhado

O Claude Code documenta a separação: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. Arquivos CLAUDE.md por diretório são carregados sob demanda, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", e uma configuração claudeMdExcludes esconde os arquivos de outros times em um monorepo s4. O Git oferece três camadas de ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude e .gitignore s24; a do meio esconde uma pasta de planos pessoais sem tocar em arquivo compartilhado. O CODEOWNERS cuida da metade da propriedade: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Ciclo de vida, como nos ADRs

O post de Michael Nygard, de 2011, é o modelo: uma decisão "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", e "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. A Thoughtworks divide o uso de specs em spec-first (escrita uma vez para a tarefa), spec-anchored (mantida para evoluir a feature) e spec-as-source (só a spec é editada), e o autor acrescenta: "I'd rather review code than all these markdown files" s10. O Superpowers escreve arquivos spec-first e os guarda para sempre: drift por padrão.

Drift e o gate

O paper do arXiv chama o problema de "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" e propõe "a drift gate that makes spec-code divergence a blocking merge condition" s11. O próprio guia do Spec Kit avisa: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. A TrueFoundry defende a governança sem rodeios: "forty-one specs and nine agent files aren't a tidiness problem", são "forty-one unversioned behavior inputs and nine competing standing policies", e o drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". O mesmo post sugere cerca de 300 linhas por spec e um orçamento de 150 a 200 instruções permanentes s13. Um praticante descreve a versão manual: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Quanto custa

Experimento Resultado Fonte
Spec Kit em uma feature que mostra a data atual 8 arquivos e 1,300 linhas de texto s14
Bake-off do OpenSpec, mesmos requisitos, ferramenta de spec vs Claude Code puro O OpenSpec achou 3 lacunas a mais; 50% mais código com 50% mais complexidade ciclomática; o dobro do tempo e o triplo do custo s12
Um time que usou spec-driven development por meses "two to three times as many tokens and take about twice as long"; sem prova de que o código melhorou s25

O bake-off é um único experimento e o autor admite isso, mas a direção se repete nos três. Então: faça spec do caminho arquitetural, mantenha o caminho delimitado delimitado, e siga as duas frases que os praticantes repetem, "don t spec too big / read the generated specs" s26.

Faça isto na segunda-feira

  • Crie docs/specs/<squad>/ para cada squad e adicione uma linha no CODEOWNERS por pasta apontando para os revisores desse squad.
  • Adicione uma linha imperativa em negrito ao CLAUDE.md do projeto: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Rode um brainstorm e confira onde o arquivo caiu.
  • Mova os planos pessoais para uma pasta listada em .git/info/exclude e mantenha as preferências de cada dev em CLAUDE.local.md, também ignorado.
  • Coloque um cabeçalho em toda spec compartilhada: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • Escreva o drift gate: para cada spec com status: accepted, extraia os caminhos citados e reprove o pull request quando algum estiver faltando. Cerca de quinze linhas de shell ou Python.
  • Adicione uma regra de branch: nenhum commit de spec ou plano entra na main fora de um pull request.
  • Se o repositório publica docs com Sphinx ou similar, adicione a pasta de specs ao exclude_patterns hoje.
  • Defina o orçamento de tamanho: uma spec fica perto de 300 linhas, e só o trabalho que cruza a fronteira de um squad ou será relido em 90 dias ganha uma.

Para ir além

  • Leia as três categorias de uso de spec (spec-first, spec-anchored, spec-as-source) antes de escolher um esquema de cabeçalho; o ciclo de vida só importa para arquivos spec-anchored s10.
  • O paper do arXiv vai além das checagens de caminho, até uma arquitetura com drift imposto; útil quando o gate de quinze linhas parecer grosseiro demais s11.
  • O guia do Spec Kit nomeia três fluxos de evolução (Flow-Forward, Living Spec, Flow-Back) que correspondem à regra do mesmo commit s7.
  • O playbook sugere um hook para impor a sincronia entre plano e diff; a thread do Reddit sobre ele tem 43 pontos e 27 comentários de relatos de campo s5, s27.
  • O argumento da TrueFoundry de que uma mudança de spec é uma mudança de política, portanto deve ficar atrás de um eval gate com metadados de execução, é o próximo passo depois das checagens de caminho no CI s13.
  • Acompanhe as duas issues abertas, 1246 (planos na main) e 939 (overrides ignorados); quando uma delas fechar, uma regra deste pack vira padrão do plugin s16, s18.
  • O texto completo da Marmelab explica por que apareceram as 1,300 linhas e onde o Spec Kit realmente compensa s14.

Fontes

FAQ

Preciso das cinco regras desde o primeiro dia?

Não. O redirecionamento no CLAUDE.md e a exclusão do Sphinx levam dez minutos. Adicione o CODEOWNERS e o cabeçalho quando uma spec cruzar squads pela primeira vez, e o drift gate quando uma spec aceita tiver envelhecido uma sprint.

O que o drift gate não pega?

Mudança de comportamento. Ele só verifica se um caminho citado ainda existe, então uma condição invertida passa. Combine com a regra do mesmo commit e com revisão.

Por que não simplesmente colocar a pasta no gitignore?

Porque o agente que lê a spec depois precisa dela, e a trilha de auditoria só funciona se as peças intermediárias forem versionadas. O time do okama tentou o gitignore e voltou a commitar com uma exclusão no build.