Governare spec e piani AI in Git: cinque regole, drift gate, fonti e checklist

TL;DR

Fai il commit di spec e piani scritti dall'AI. Ogni strumento lo fa già di default; la questione aperta è la governance.
Dai a ogni squad una cartella con una riga CODEOWNERS, così una modifica alla spec richiede la review dei code owner.
Metti su ogni spec condivisa un header in stile ADR: stato, superseded-by, owner, percorsi toccati, data di review. Non riscrivere mai una spec accettata trasformandola in una nuova decisione.
Esegui un drift gate in CI: per ogni spec accettata, fai fallire la build quando un percorso che nomina non esiste più.
Reindirizza il percorso di output con una riga imperativa in grassetto in CLAUDE.md, tieni i piani personali in CLAUDE.local.md e .git/info/exclude, e scrivi su un branch, mai su main.
Scrivi una spec solo per il lavoro che attraversa il confine di una squad o che verrà riletto entro 90 giorni. Le esecuzioni spec-driven costano circa il doppio del tempo e il triplo dei token.

Cosa dicono le fonti

I default: tutti committano

La skill writing-plans di Superpowers salva i piani in docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, con una riga sotto che dice che le preferenze dell'utente sulla posizione dei piani prevalgono su questo default s1. La skill brainstorming scrive il design validato in docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md e termina con "Commit the design document to git" s2. Spec Kit organizza specs/[branch-name]/ con spec.md, plan.md e tasks.md, numerati 001, 002, più una constitution in memory/constitution.md s6. Kiro tiene .kiro/specs/ con una cartella per feature e invita i team a "collaborate with team members on different features simultaneously" s8. Il playbook di Anthropic è esplicito: "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.

Nessuno di questi documenti dice chi possiede una spec committata o quando smette di essere vera. I tre fallimenti documentati vivono in questo vuoto.

Fallimento 1: la fuga pubblica

La issue 1690, aperta il 2026-06-05, segnala che la posizione di default docs/superpowers/ può far trapelare piani interni nella documentazione pubblicata tramite Sphinx e Read the Docs s15. Il progetto colpito era okama, una libreria Python con 273 stelle. Il suo commit di fix ha riaggiunto 5 piani e 3 spec, ha rimosso una riga di .gitignore e dice "track superpowers plans/specs in git, excluded from the Sphinx build" s21. Alla riga 84 di docs/conf.py c'è ora exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Oggi la cartella contiene 8 piani e 6 spec s15. Il team ha mantenuto la pratica e sistemato la build.

Fallimento 2: piani su main

La issue 1246, aperta il 2026-04-22 e ancora aperta, chiede perché il piano venga committato prima che esista un branch di sviluppo. Un utente riferisce "I'm getting 10 to 15 commits"; un altro: "Yes please, no plans and specs on main branch!" s16. Il plugin non impone una regola sui branch; lo fa la checklist qui sotto.

Fallimento 3: override che il modello salta

La issue 337 è stata chiusa il 2026-03-10 con la nota del maintainer che dalla v5.0 il plugin dà priorità al CLAUDE.md del tuo progetto rispetto ai propri default, riga di esempio: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. La issue 939, sulla v5.0.6, mostra il limite: una tabella "Output Paths" in CLAUDE.md è stata ignorata e le spec continuavano a finire in docs/superpowers/specs/. Il workaround che ha funzionato è una riga imperativa in grassetto sotto la tabella: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. La pull request 1020, che riordinava l'istruzione, è stata chiusa senza merge s19. L'override è un prompt, non un'impostazione: ricontrollalo a ogni release del plugin. Per i file di scratch del plugin stesso, la issue 1780 è stata chiusa dalla v6.0.3 con una cartella .superpowers/sdd/ che si auto-ignora, creando il proprio .gitignore contenente * s20.

Personale contro condiviso

Claude Code documenta la separazione: "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. I CLAUDE.md per directory si caricano su richiesta, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", e un'impostazione claudeMdExcludes nasconde i file degli altri team in un monorepo s4. Git offre tre livelli di ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude e .gitignore s24; quello centrale nasconde una cartella di piani personali senza toccare un file condiviso. CODEOWNERS copre l'altra metà, la proprietà: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Ciclo di vita, come gli ADR

Il post di Michael Nygard del 2011 è il modello: una decisione "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. Thoughtworks divide l'uso delle spec in spec-first (scritta una volta per il task), spec-anchored (mantenuta per far evolvere la feature) e spec-as-source (si modifica solo la spec), e il suo autore aggiunge: "I'd rather review code than all these markdown files" s10. Superpowers scrive file spec-first e li tiene per sempre: drift per default.

Drift e il gate

Il paper arXiv chiama il problema "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" e propone "a drift gate that makes spec-code divergence a blocking merge condition" s11. La guida di Spec Kit avverte: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry mette in chiaro il caso della governance: "forty-one specs and nine agent files aren't a tidiness problem", sono "forty-one unversioned behavior inputs and nine competing standing policies", e il drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". Lo stesso post suggerisce circa 300 righe per spec e un budget di 150-200 istruzioni permanenti s13. Un praticante descrive la versione manuale: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Quanto costa

Esperimento	Risultato	Fonte
Spec Kit su una feature che mostra la data corrente	8 file e 1,300 righe di testo	s14
Bake-off OpenSpec, stessi requisiti, strumento di spec contro Claude Code semplice	OpenSpec ha trovato 3 lacune in più; 50% di codice in più con 50% di complessità ciclomatica in più; il doppio del tempo e il triplo del costo	s12
Un team che pratica lo spec-driven development da mesi	"two to three times as many tokens and take about twice as long"; nessuna prova che il codice sia migliorato	s25

Il bake-off è un solo esperimento e il suo autore lo dice, ma la direzione è la stessa in tutti e tre. Quindi: scrivi la spec del percorso architetturale, tieni circoscritto il percorso circoscritto, e segui le due righe che i praticanti ripetono, "don t spec too big / read the generated specs" s26.

Da fare lunedì

Crea docs/specs/<squad>/ per ogni squad e aggiungi una riga CODEOWNERS per cartella che punti ai reviewer di quella squad.
Aggiungi al CLAUDE.md del progetto una riga imperativa in grassetto: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Esegui un brainstorming e controlla dove è finito il file.
Sposta i piani personali in una cartella elencata in .git/info/exclude e tieni le preferenze per sviluppatore in CLAUDE.local.md, a sua volta ignorato.
Metti un header su ogni spec condivisa: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
Scrivi il drift gate: per ogni spec con status: accepted, estrai i percorsi che nomina e fai fallire la pull request quando uno manca. Circa quindici righe di shell o Python.
Aggiungi una regola sui branch: nessun commit di spec o piano arriva su main fuori da una pull request.
Se il repo pubblica documentazione con Sphinx o simili, aggiungi oggi la cartella delle spec a exclude_patterns.
Fissa il budget di dimensione: una spec resta intorno alle 300 righe, e ne ha una solo il lavoro che attraversa il confine di una squad o che verrà riletto entro 90 giorni.

Per approfondire

Leggi le tre categorie d'uso delle spec (spec-first, spec-anchored, spec-as-source) prima di scegliere uno schema di header; il ciclo di vita conta solo per i file spec-anchored s10.
Il paper arXiv va oltre i controlli sui percorsi fino a un'architettura con drift imposto; utile quando il gate da quindici righe comincia a sembrare troppo grossolano s11.
La guida di Spec Kit nomina tre flussi di evoluzione (Flow-Forward, Living Spec, Flow-Back) che corrispondono alla regola dello stesso commit s7.
Il playbook suggerisce un hook per imporre la sincronizzazione tra piano e diff; il thread Reddit sul tema ha 43 punti e 27 commenti di resoconti sul campo s5, s27.
L'argomento di TrueFoundry, secondo cui una modifica alla spec è una modifica di policy e va quindi dietro un eval gate con metadati di run, è il passo successivo ai controlli di percorso in CI s13.
Segui le due issue aperte, 1246 (piani su main) e 939 (override ignorati); quando una chiude, una regola di questo pack diventa un default del plugin s16, s18.
L'articolo completo di Marmelab spiega perché sono comparse le 1,300 righe e dove Spec Kit vale la pena s14.

Fonti

Superpowers writing-plans skill, GitHub. Perché leggerla: il percorso di default esatto e la clausola di override su una riga su cui fai affidamento.
Superpowers brainstorming skill, GitHub. Perché leggerla: dove finiscono le spec e il passaggio che le committa.
Claude Code memory, Anthropic. Perché leggerla: CLAUDE.local.md è il posto previsto per le preferenze personali.
Claude Code: working in large codebases, Anthropic. Perché leggerla: file per directory, owner e claudeMdExcludes per i monorepo.
The AI-native SDLC playbook, Anthropic. Perché leggerla: l'argomento dell'audit trail e la regola dello stesso commit, dal vendor.
Spec Kit repository, GitHub. Perché leggerla: un layout di spec per branch da confrontare con quello per squad.
Spec Kit: evolving specs, GitHub. Perché leggerla: l'affermazione più chiara che spec e codice non devono contraddirsi.
Kiro specs best practices, Kiro. Perché leggerla: un layout a cartelle per feature pensato per squad parallele.
Documenting architecture decisions, Michael Nygard. Perché leggerla: il vocabolario di stati che l'header prende in prestito.
Spec-driven development: the tools, Thoughtworks. Perché leggerla: la distinzione spec-first contro spec-anchored che decide cosa tenere.
The Spec Growth Engine, arXiv. Perché leggerla: il caso formale per un drift gate bloccante.
OpenSpec bake-off discussion, GitHub. Perché leggerla: le uniche cifre di costo affiancate, con le cautele dell'autore.
Spec-driven development for AI agents, TrueFoundry. Perché leggerla: le spec come policy versionata e il budget di 300 righe.
Spec-driven development: waterfall strikes back, Marmelab. Perché leggerla: come appaiono 1,300 righe di spec per una feature banale.
Superpowers issue 1690, GitHub. Perché leggerla: la segnalazione della fuga, passo per passo.
Superpowers issue 1246, GitHub. Perché leggerla: la lamentela su main, ancora aperta.
Superpowers issue 337, GitHub. Perché leggerla: l'affermazione del maintainer che CLAUDE.md vince dalla v5.0.
Superpowers issue 939, GitHub. Perché leggerla: l'override che è fallito e la formulazione che ha funzionato.
Superpowers pull request 1020, GitHub. Perché leggerla: il tentativo di fix, chiuso senza merge.
Superpowers issue 1780, GitHub. Perché leggerla: come il plugin auto-ignora la propria cartella di scratch.
okama fix commit, GitHub. Perché leggerla: un team reale che sceglie di tenere le spec e di escluderle dalla build.
okama docs/conf.py, GitHub. Perché leggerla: la riga di esclusione Sphinx da copiare.
About code owners, GitHub Docs. Perché leggerla: il meccanismo di richiesta review su cui poggia la regola di proprietà.
gitignore documentation, Git. Perché leggerla: info/exclude è il livello di ignore personale che la maggior parte degli sviluppatori dimentica.
We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. Perché leggerla: un resoconto di costi su scala di team senza vendor dietro.
Does spec-driven development actually work for you?, Reddit r/ClaudeCode. Perché leggerla: consigli su dimensioni e lettura delle spec da utenti quotidiani.
Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. Perché leggerla: resoconti sul campo del playbook in repo reali.

FAQ

Mi servono tutte e cinque le regole dal primo giorno?

No. Il reindirizzamento in CLAUDE.md e l'esclusione Sphinx richiedono dieci minuti. Aggiungi CODEOWNERS e l'header quando una spec attraversa per la prima volta più squad, e il drift gate quando una spec accettata ha l'età di uno sprint.

Cosa non vede il drift gate?

Il comportamento cambiato. Controlla solo che un percorso nominato esista ancora, quindi una condizione invertita passa. Abbinalo alla regola dello stesso commit e alla review.

Perché non mettere la cartella in gitignore?

Perché l'agente che legge la spec più tardi ne ha bisogno, e l'audit trail funziona solo se i pezzi intermedi sono versionati. Il team okama ha provato il gitignore ed è tornato a committare con un'esclusione dalla build.