Commitea Los Specs De Superpowers, Gobiérnalos Como ADR

Superpowers es un plugin de Claude Code (286.000 estrellas en GitHub) cuyas skills escriben specs y planes de implementación como archivos markdown y los commitean al repositorio. Por defecto, cada uno de esos archivos cae en una sola carpeta, docs/superpowers/. En junio, los mantenedores de Okama, una librería de Python para finanzas, descubrieron que ocho planes de implementación que un agente había escrito ahí, commiteados exactamente como el plugin lo pretende, habían sido renderizados como páginas web públicas en Read the Docs. Se dieron cuenta después del release.

Ahora escala eso: un equipo de front-end de diez developers, cuatro squads, un repositorio, y cada developer generando estos archivos. Tres preguntas caen sobre el escritorio del lead. Qué versionamos exactamente. Es un problema el drift cuando un spec nombra una ruta que se borró hace dos sprints. Y quién gobierna la carpeta. El leak de Okama no lo causó el hecho de commitear. Lo causó commitear sin una regla. Este artículo te da cinco.

Superpowers nunca pregunta si debe commitear. La línea 18 de su skill de planning guarda cada plan bajo docs/superpowers/plans/, con fecha, un archivo por feature. La skill de brainstorming escribe el documento de diseño y lo commitea en el mismo paso, antes de que hayas visto el plan.

Esto no es una rareza de Superpowers. Cada herramienta importante de spec-driven development toma la misma decisión:

Tool	Publisher	Where specs live
Superpowers (286,000 stars)	obra	docs/superpowers/, one folder for everything
Spec Kit (136,000 stars)	GitHub	one numbered folder per feature, on that feature's branch
Kiro	Amazon	.kiro/specs/, one folder per feature
AI-native SDLC playbook	Anthropic	one committed artifact per stage: intent, spec, plan, diff, review findings, incident record

Kiro vende las carpetas por feature como una forma de que los compañeros de equipo colaboren en distintas features a la vez. El playbook de Anthropic, publicado en agosto, va más allá: cada etapa commitea un artefacto que la siguiente etapa puede leer. Así que la pregunta nunca fue si commitear, y dónde la responde cada herramienta. Quién es dueño del archivo, y cuándo está muerto, no. Ese vacío es lo que cubren las cinco reglas.

Los planes commiteados fallan de tres formas distintas.

Fallo 1: el generador de docs. Un build de documentación que renderiza cada archivo markdown bajo docs/, esté o no listado en una tabla de contenidos, embarca la carpeta de planes junto con el manual. Eso es exactamente lo que le pasó a Okama.

Fallo 2: la rama. El issue 1246 de Superpowers reporta que el brainstorm commitea el plan directo a main. Un usuario cuenta de 10 a 15 commits por sesión, uno nuevo cada pocos cambios. El pedido del thread cabe en una línea: nada de plans y specs en la rama main.

Fallo 3: el drift. El drift de specs es el fallo silencioso: el código evoluciona y el spec no. Birgitta Böckeler, de Thoughtworks, nombra tres niveles de spec-driven development:

Level	Meaning
Spec-first	Written, used once
Spec-anchored	Kept and maintained for the feature's life
Spec-as-source	The human only ever edits the spec

Superpowers escribe documentos spec-first y los conserva para siempre. Por defecto obtienes almacenamiento spec-anchored con mantenimiento de primer borrador: nadie actualiza el archivo, y un agente lo lee el próximo trimestre como si fuera la verdad. TrueFoundry lo dice sin vueltas: el drift es inevitable en la práctica spec-first y manejable en la práctica spec-anchored, pero solo si la divergencia es detectable.

Un repositorio con 41 specs y 9 archivos de agente no tiene un problema de orden. Tiene 41 entradas de comportamiento sin versionar. La reacción de Böckeler: prefiere revisar código antes que todos esos archivos markdown. Un plan que nadie vuelve a cargar es ruido. Un plan que un agente carga es una instrucción, y una instrucción vieja es una instrucción equivocada.

Regla 1: la carpeta tiene un dueño, y el dueño es un squad, no el plugin. Desde la versión 5, Superpowers respeta las instrucciones del CLAUDE.md de tu proyecto por encima de sus propios defaults. Dile dónde van los planes y ahí van.

Una tabla de rutas no basta, sin embargo. En el issue 939, un usuario escribió una tabla de rutas de salida y el modelo siguió la ruta concreta de la skill e ignoró la tabla. La nota de override de la propia skill es un paréntesis. Una línea en negrita e imperativa lo arregló al primer intento: los specs deben guardarse aquí, no allá, nombrando el default como lo que hay que evitar.

El layout es una carpeta por squad (checkout, search, accounts, design-system), cada una con sus propios specs y planes. En un monorepo, pon la línea en el CLAUDE.md propio del paquete. Claude Code carga el archivo de un subdirectorio a demanda cuando lee ahí, y la documentación dice que el dueño de cada directorio típicamente mantiene su archivo. Los ingenieros que nunca instalaron el plugin no se ven afectados: la línea solo se activa cuando una skill pregunta dónde guardar.

Después, deja que la plataforma haga cumplir la propiedad. Una línea de CODEOWNERS por carpeta de squad, y cada revisión de spec cae en manos de la gente que va a vivir con ella. Una advertencia: el override es un prompt, no un setting. Revisa el primer spec después de cada release del plugin.

Regla 2: no todo plan es un artefacto de equipo. La primera persona en pedirle a Superpowers una ubicación configurable (issue 337) lo dijo mejor que nadie: los archivos de plan pueden ser documentos de trabajo personales en vez de artefactos del proyecto.

El lado personal tiene un archivo hecho para eso. CLAUDE.local.md está junto al archivo compartido, se carga después de él, y la documentación te dice que lo pongas en gitignore tú mismo. Tu redirección a una carpeta privada vive ahí y nadie más la ve. Para la carpeta en sí, Git tiene un archivo de ignore que nunca toca el árbol compartido: .git/info/exclude es por clon, nunca se commitea, y no necesita pull request. El plugin ya hace esto para su propio espacio de trabajo temporal: desde la versión 6.0.3 su directorio de trabajo deja caer un .gitignore con * dentro de sí mismo, así que se autoignora sin tocar un archivo tracked.

El lado compartido es lo que sea que haya pasado el gate de revisión que el brainstorm ya corre: spec escrito, revisión solicitada, aprobada por una segunda persona. Aprobado, se mueve a la carpeta del squad. No aprobado, se queda local. Ambos se escriben en una rama, nunca en main. Dos líneas en el CLAUDE.md compartido lo logran: tratar specs y planes como el inicio de una feature, y crear el worktree antes de escribirlos.

Un límite: un plan en gitignore no viaja. Los mantenedores de Okama probaron ignorar la carpeta primero y lo revirtieron, porque los planes dejaron de sincronizarse entre máquinas y agentes. Personal significa personal.

Regla 3: un spec tiene un estado, y un spec muerto lo dice. La idea tiene 15 años. Michael Nygard, en 2011, propuso guardar los architecture decision records (ADR) en el repositorio, un archivo numerado por cada uno. Una decisión se propone, y después se acepta. Cuando un registro posterior la cambia, el viejo se marca deprecated o superseded con una referencia a su reemplazo. Si una decisión se revierte, el registro viejo se conserva pero se marca superseded.

Aplicado a specs, cada spec compartido abre con un header de cinco líneas que el agente ya lee:

Field	Purpose
status	proposed, accepted, superseded
superseded-by	the replacing spec
owner	the squad
touches	the paths the spec makes claims about
review date	when it was last checked

Nunca edites un spec accepted para convertirlo en otra decisión. Escribe el siguiente, apúntalo hacia atrás, y la historia queda honesta. Una excepción, señalada en el playbook de Anthropic: cuando la implementación se aparta del plan, actualiza el plan en el mismo commit. El plan viaja con el diff que lo rompió, y un hook puede hacerlo cumplir.

Spec Kit nombra tres formas en que un spec puede vivir. Flow-forward: una carpeta nueva por feature, las viejas se conservan como historia. Living spec: el spec es el contrato y el resto se regenera. Flow-back: el build reformula el spec. Su regla no es dejar un cambio en tasks o código si el spec todavía dice algo distinto. Eso es elegir spec-anchored a propósito.

El límite: un status es metadata que pone un humano. El agente no va a marcar su propio spec como superseded a menos que tu CLAUDE.md se lo diga, y aun así la revisión tiene que notarlo.

Regla 4: un spec que le miente al árbol de archivos falla el build. El paper que nombró el problema, publicado en junio, lo llama silent spec-code drift: el código evoluciona, la especificación no, y la divergencia queda invisible hasta que es costosa de reparar. Su respuesta es un drift gate, una condición de merge bloqueante.

El check es más pequeño de lo que parece. Para cada spec cuyo header diga accepted, extrae las rutas que nombra, entre backticks o en la línea touches, y prueba que cada una exista. Ruta faltante, build en rojo, con el nombre del spec en el log. Los archivos superseded y proposed se saltan: solo los specs accepted hacen afirmaciones sobre el árbol, así que solo los specs accepted se chequean. TrueFoundry lo enmarca como un diff programado en vez de arqueología post-incidente: un spec es scaffold, y un cambio de spec es un cambio de policy.

La gente ya corre la versión manual. Un comentarista hace que Claude compare los archivos de spec contra el codebase y abra tickets por lo que falta. El script hace eso en cada pull request, gratis.

La segunda guardia es la que Okama implementó: excluir la carpeta del build de docs. Una línea en la configuración de Sphinx mantiene los archivos en Git pero fuera del HTML.

El límite: un check de rutas atrapa archivos borrados, no comportamiento cambiado. Un spec puede nombrar cada archivo existente y aun así describir una API que ya no existe. Para eso están la revisión y la regla del mismo commit.

Regla 5: la mayoría del trabajo no merece un spec. La evidencia sobre el overhead de spec-driven development es consistente:

Experiment	Result
Marmelab, Spec Kit on a feature that shows the current date	8 files, 1,300 lines of specification text
OpenSpec bake-off, same requirements with a spec tool vs Claude Code alone	50% more code, 50% more cyclomatic complexity, twice as long, three times the cost
A team running spec-driven development for months	2 to 3 times the tokens, about twice as long, large coordination cost for changes that needed none; no proof the code improved

El bake-off es un experimento, no un benchmark, y su autor lo dice. Pero la tendencia se mantiene. Entonces la regla: escribe un spec cuando el trabajo cruza un límite de squad o va a leerse otra vez en 90 días. Todo lo demás es un prompt.

Superpowers ya clasifica cada pedido en tres rutas: spike, bounded, architectural. Solo la ruta architectural escribe un spec. Mantén la ruta bounded acotada, y mantén el spec cerca de las 300 líneas. Los practitioners agregan dos líneas: no hagas specs demasiado grandes, y lee los specs generados.

El límite corta en ambos sentidos. El mismo bake-off encontró tres huecos que la corrida simple se saltó. El spec compra cobertura, no velocidad. Págalo donde la cobertura importa.

Volviendo a las tres preguntas del lead. Qué versionamos: specs y planes aprobados, en una rama, en la carpeta del squad. Drift: un header de estado y un gate de CI. Gobernanza: dueños y una regla de tamaño.

Cinco reglas, y ninguna la hace cumplir una herramienta hoy. El issue del override está abierto. El issue de la rama main está abierto. El pull request que reordenó la instrucción se cerró sin mergear. El equipo que se quemó mantuvo la práctica: 8 planes y 6 specs, commiteados, excluidos del build de docs.

La objeción de Böckeler se mantiene. Con un header de estado y un presupuesto de tamaño, lees solo los specs accepted, y menos de ellos. Lo que recuperas es lo que el playbook de Anthropic llama el audit trail: quién pidió qué, qué produjo el agente, y quién lo aprobó.

Esto es proceso, no tooling: un archivo CLAUDE.md, un archivo CODEOWNERS, un header, y un script de quince líneas. Y si el equipo no va a revisar un pull request de CODEOWNERS, tampoco va a revisar un spec. En ese caso, el .gitignore era la opción honesta.