Gobernar specs y planes de IA en Git: cinco reglas, drift gate, fuentes y checklist

TL;DR

Haz commit de las specs y planes escritos por la IA. Todas las herramientas ya lo hacen por defecto; la cuestión abierta es el gobierno.
Dale a cada squad una carpeta con una línea de CODEOWNERS, para que un cambio de spec pida revisión a los dueños del código.
Pon una cabecera estilo ADR en cada spec compartida: status, superseded-by, owner, paths afectados, fecha de revisión. Nunca reescribas una spec aceptada para convertirla en otra decisión.
Ejecuta un drift gate en CI: para cada spec aceptada, haz fallar el build cuando una ruta que menciona ya no existe.
Redirige la ruta de salida con una línea imperativa en negrita en CLAUDE.md, guarda los planes personales en CLAUDE.local.md y .git/info/exclude, y escribe en una rama, nunca en main.
Especifica solo el trabajo que cruza la frontera de un squad o que se releerá dentro de 90 días. Las ejecuciones guiadas por specs cuestan el doble de tiempo y el triple de tokens.

Qué dicen las fuentes

Los valores por defecto: todos hacen commit

El skill writing-plans de Superpowers guarda los planes en docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, con una línea debajo que dice que las preferencias del usuario sobre la ubicación de los planes anulan este valor por defecto s1. El skill brainstorming escribe el diseño validado en docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md y termina con "Commit the design document to git" s2. Spec Kit organiza specs/[branch-name]/ con spec.md, plan.md y tasks.md, numerados 001, 002, más una constitución en memory/constitution.md s6. Kiro mantiene .kiro/specs/ con una carpeta por feature e invita a los equipos a "collaborate with team members on different features simultaneously" s8. El playbook de Anthropic es explícito: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md" y "When implementation departs from the plan, update plan.md in the same commit" s5.

Ninguno de estos documentos dice quién es el dueño de una spec commiteada ni cuándo deja de ser cierta. Los tres fallos documentados viven en ese hueco.

Fallo 1: la fuga pública

La issue 1690, abierta el 2026-06-05, informa de que la ubicación por defecto docs/superpowers/ puede filtrar planes internos a la documentación publicada mediante Sphinx y Read the Docs s15. El proyecto afectado fue okama, una librería de Python con 273 stars. Su commit de arreglo volvió a añadir 5 planes y 3 specs, quitó una línea de .gitignore y dice "track superpowers plans/specs in git, excluded from the Sphinx build" s21. La línea 84 de docs/conf.py tiene ahora exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Hoy la carpeta contiene 8 planes y 6 specs s15. El equipo mantuvo la práctica y arregló el build.

Fallo 2: planes en main

La issue 1246, abierta el 2026-04-22 y todavía abierta, pregunta por qué el plan se commitea antes de que exista una rama de desarrollo. Un usuario cuenta "I'm getting 10 to 15 commits"; otro: "Yes please, no plans and specs on main branch!" s16. El plugin no impone ninguna regla de rama; la checklist de abajo sí.

Fallo 3: overrides que el modelo se salta

La issue 337 se cerró el 2026-03-10 con la nota del mantenedor de que desde la v5.0 el plugin da prioridad al CLAUDE.md de tu proyecto sobre sus propios valores por defecto, con esta línea de ejemplo: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. La issue 939, en la v5.0.6, muestra el límite: una tabla "Output Paths" en CLAUDE.md fue ignorada y las specs seguían cayendo en docs/superpowers/specs/. El apaño que funcionó es una línea imperativa en negrita bajo la tabla: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. La pull request 1020, que reordenaba la instrucción, se cerró sin merge s19. El override es un prompt, no un ajuste: vuelve a comprobarlo tras cada release del plugin. Para los archivos temporales del propio plugin, la issue 1780 se cerró con la v6.0.3 y una carpeta .superpowers/sdd/ que se autoignora al crear su propio .gitignore con * s20.

Personal frente a compartido

Claude Code documenta la separación: "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. Los CLAUDE.md por directorio se cargan bajo demanda, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", y un ajuste claudeMdExcludes oculta los archivos de otros equipos en un monorepo s4. Git ofrece tres capas de ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude y .gitignore s24; la del medio oculta una carpeta personal de planes sin tocar ningún archivo compartido. CODEOWNERS cubre la mitad de la propiedad: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Ciclo de vida, como los ADR

El post de Michael Nygard de 2011 es la plantilla: una decisión "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", y "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks divide el uso de specs en spec-first (escrita una vez para la tarea), spec-anchored (mantenida para evolucionar la feature) y spec-as-source (solo se edita la spec), y su autor añade: "I'd rather review code than all these markdown files" s10. Superpowers escribe archivos spec-first y los conserva para siempre: deriva por defecto.

La deriva y el gate

El paper de arXiv llama al problema "silent spec-code drift, code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" y propone "a drift gate that makes spec-code divergence a blocking merge condition" s11. La propia guía de Spec Kit advierte: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry plantea el caso de gobierno sin rodeos: "forty-one specs and nine agent files aren't a tidiness problem", son "forty-one unversioned behavior inputs and nine competing standing policies", y la deriva "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". El mismo post sugiere unas 300 líneas por spec y un presupuesto de 150 a 200 instrucciones permanentes s13. Un profesional describe la versión manual: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Cuánto cuesta

Experimento	Resultado	Fuente
Spec Kit en una feature que muestra la fecha actual	8 archivos y 1,300 líneas de texto	s14
Bake-off de OpenSpec, mismos requisitos, herramienta de specs contra Claude Code a secas	OpenSpec detectó 3 huecos más; 50% más de código con 50% más de complejidad ciclomática; el doble de tiempo y el triple de coste	s12
Un equipo con spec-driven development durante meses	"two to three times as many tokens and take about twice as long"; sin pruebas de que el código mejorara	s25

El bake-off es un solo experimento y su autor lo dice, pero la dirección se repite en los tres. Así que: especifica el camino arquitectónico, mantén acotado el camino acotado y sigue las dos líneas que repiten los profesionales, "don t spec too big / read the generated specs" s26.

Haz esto el lunes

Crea docs/specs/<squad>/ por squad y añade una línea de CODEOWNERS por carpeta apuntando a los revisores de ese squad.
Añade una línea imperativa en negrita al CLAUDE.md del proyecto: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Haz un brainstorm y comprueba dónde cayó el archivo.
Mueve los planes personales a una carpeta listada en .git/info/exclude y guarda las preferencias de cada desarrollador en CLAUDE.local.md, también ignorado.
Pon una cabecera en cada spec compartida: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
Escribe el drift gate: para cada spec con status: accepted, extrae las rutas que menciona y haz fallar la pull request cuando falte alguna. Unas quince líneas de shell o Python.
Añade una regla de rama: ningún commit de spec o plan llega a main fuera de una pull request.
Si el repo publica docs con Sphinx o similar, añade hoy la carpeta de specs a exclude_patterns.
Fija el presupuesto de tamaño: una spec se queda en torno a 300 líneas, y solo el trabajo que cruza la frontera de un squad o se releerá dentro de 90 días recibe una.

Para ir más lejos

Lee las tres categorías de uso de specs (spec-first, spec-anchored, spec-as-source) antes de elegir un esquema de cabecera; el ciclo de vida solo importa para archivos spec-anchored s10.
El paper de arXiv va más allá de las comprobaciones de rutas hasta una arquitectura completa que impone cero deriva; útil cuando el gate de quince líneas se quede corto s11.
La guía de Spec Kit nombra tres flujos de evolución (Flow-Forward, Living Spec, Flow-Back) que encajan con la regla del mismo commit s7.
El playbook sugiere un hook para forzar la sincronización de plan y diff; el hilo de Reddit sobre él tiene 43 puntos y 27 comentarios con experiencias reales s5, s27.
El argumento de TrueFoundry de que un cambio de spec es un cambio de política, y por tanto va detrás de un eval gate con metadatos de ejecución, es el siguiente paso tras las comprobaciones de rutas en CI s13.
Sigue las dos issues abiertas, 1246 (planes en main) y 939 (overrides ignorados); cuando una se cierre, una regla de este pack pasa a ser valor por defecto del plugin s16, s18.
El artículo completo de Marmelab explica por qué aparecieron las 1,300 líneas y dónde sí compensa Spec Kit s14.

Fuentes

Superpowers writing-plans skill, GitHub. Por qué leerlo: la ruta por defecto exacta y la cláusula de override de una línea en la que te apoyas.
Superpowers brainstorming skill, GitHub. Por qué leerlo: dónde caen las specs y el paso que las commitea.
Claude Code memory, Anthropic. Por qué leerlo: CLAUDE.local.md es el lugar previsto para las preferencias personales.
Claude Code: working in large codebases, Anthropic. Por qué leerlo: archivos por directorio, dueños y claudeMdExcludes para monorepos.
The AI-native SDLC playbook, Anthropic. Por qué leerlo: el argumento de la pista de auditoría y la regla del mismo commit, desde el proveedor.
Spec Kit repository, GitHub. Por qué leerlo: una estructura de specs por rama para comparar con la de por squad.
Spec Kit: evolving specs, GitHub. Por qué leerlo: la afirmación más clara de que spec y código no deben contradecirse.
Kiro specs best practices, Kiro. Por qué leerlo: una estructura de carpetas por feature pensada para squads en paralelo.
Documenting architecture decisions, Michael Nygard. Por qué leerlo: el vocabulario de estados que toma prestado la cabecera.
Spec-driven development: the tools, Thoughtworks. Por qué leerlo: la distinción spec-first frente a spec-anchored que decide qué conservar.
The Spec Growth Engine, arXiv. Por qué leerlo: el argumento formal a favor de un drift gate bloqueante.
OpenSpec bake-off discussion, GitHub. Por qué leerlo: las únicas cifras de coste cara a cara, con las salvedades del propio autor.
Spec-driven development for AI agents, TrueFoundry. Por qué leerlo: las specs como política versionada y el presupuesto de 300 líneas.
Spec-driven development: waterfall strikes back, Marmelab. Por qué leerlo: cómo se ven 1,300 líneas de spec para una feature trivial.
Superpowers issue 1690, GitHub. Por qué leerlo: el informe de la fuga, paso a paso.
Superpowers issue 1246, GitHub. Por qué leerlo: la queja sobre main, todavía abierta.
Superpowers issue 337, GitHub. Por qué leerlo: la afirmación del mantenedor de que CLAUDE.md gana desde la v5.0.
Superpowers issue 939, GitHub. Por qué leerlo: el override que falló y la redacción que funcionó.
Superpowers pull request 1020, GitHub. Por qué leerlo: el intento de arreglo, cerrado sin merge.
Superpowers issue 1780, GitHub. Por qué leerlo: cómo el plugin autoignora su carpeta temporal.
okama fix commit, GitHub. Por qué leerlo: un equipo real que decide conservar las specs y excluirlas del build.
okama docs/conf.py, GitHub. Por qué leerlo: la exclusión de Sphinx de una línea para copiar.
About code owners, GitHub Docs. Por qué leerlo: el mecanismo de petición de revisión en el que se apoya la regla de propiedad.
gitignore documentation, Git. Por qué leerlo: info/exclude es la capa de ignore personal que la mayoría de los desarrolladores olvida.
We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. Por qué leerlo: un informe de costes a escala de equipo, sin proveedor detrás.
Does spec-driven development actually work for you?, Reddit r/ClaudeCode. Por qué leerlo: los consejos de tamaño y de leer la spec de usuarios diarios.
Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. Por qué leerlo: experiencias reales con el playbook en repos de verdad.

FAQ

¿Necesito las cinco reglas desde el primer día?

No. La redirección en CLAUDE.md y la exclusión de Sphinx llevan diez minutos. Añade CODEOWNERS y la cabecera cuando una spec cruce squads por primera vez, y el drift gate cuando una spec aceptada haya envejecido un sprint.

¿Qué se le escapa al drift gate?

El comportamiento cambiado. Solo comprueba que una ruta mencionada sigue existiendo, así que una condición invertida pasa. Combínalo con la regla del mismo commit y con la revisión.

¿Por qué no poner la carpeta en .gitignore?

Porque el agente que lea la spec después la necesita, y la pista de auditoría solo funciona si las piezas intermedias están versionadas. El equipo de okama probó el gitignore y volvió a hacer commit con una exclusión del build.