Spec-Driven Development en equipo: el workflow de spec compartida

Solo, la spec es disciplina contra tu propia deriva. En equipo, se convierte en el contrato que todos leen en lugar de intentar leerse la mente. Mismo documento, un trabajo más grande.

Quien busca Spec-Driven Development para equipos normalmente ya lo usó solo. Leyó el caso de estudio, lo probó en una feature, vio a un agente construir lo correcto a partir de una buena spec, y ahora quiere llevarlo a la gente con la que trabaja. La pregunta de fondo es si el método sobrevive al contacto con un segundo dev, un revisor y una codebase compartida.

Sobrevive. Pero algo cambia, y no verlo es como terminas en teatro de procesos: una carpeta de specs que nadie lee y un ritual en el que nadie cree. Solo, la spec es tu disciplina contra tu propia deriva y la del agente. En equipo, la spec suma un segundo trabajo. Se convierte en un contrato, entre personas y entre squads. El documento es el mismo. El trabajo es más grande.

Este es el complemento práctico del caso de estudio en solitario y de cómo escribir una spec. Cubre lo que realmente cambia cuando una spec tiene más de un lector: versionarla como contrato compartido, revisarla por pull request, mantener las convenciones en la herramienta en lugar de en la cabeza de la gente, poner el gate en un board, y la razón por la que todo el workflow vale la pena, que es que el cuello de botella pasa de escribir código a integrarlo.

Qué cambia cuando la spec tiene más de un lector

Solo, la spec hace un trabajo. Es la única memoria que recibe el agente y es la disciplina que te impide alejarte de lo que realmente querías decir. En equipo mantiene ese trabajo y suma dos más.

Los tres trabajos de una spec de equipo

El documento no cambia. Cambia el número de lectores, y esa es toda la diferencia.

La spec está entre	Qué lleva	Solo o equipo
Humano y agente	La única memoria que recibe el agente. Limita su deriva.	Ambos
Humano y humano	Lo que un compañero lee en lugar de intentar leerte la mente.	Solo equipo
Squad y squad	El contrato en la frontera donde se integran dos equipos.	Solo equipo

El modo de falla es tratar una spec de equipo como una spec individual con más autores. Sigues escribiendo notas privadas, agregas una carpeta compartida y lo llamas práctica. Las notas siguen dando por sentado todo lo que vive en tu cabeza. Un compañero abre el archivo, choca con la primera regla implícita y adivina, que es exactamente el problema que las specs existen para eliminar.

Versiona la spec, o no tienes una práctica de equipo

Git es lo que convierte una spec de memoria privada en contrato compartido. La spec vive en el repo, junto al código que gobierna, versionada con él. Una fuente de verdad, un historial, un lugar donde mirar.

Eso quizá ya lo hagas solo. El paso que lo convierte en práctica de equipo es el que nadie menciona: la spec entra a review antes de que exista el código.

Un code review después de la implementación atrapa errores de tipeo en una decisión que ya estaba mal. Un review de spec atrapa la decisión equivocada antes de que una sola línea la codifique. Así que los requisitos llegan como pull request, un revisor los lee, y solo cuando los aprueba el .status pasa a requirements:approved y empieza el diseño. Lo mismo con el diseño. Lo mismo con las tareas.

El canon va en la herramienta, no en la cabeza

Solo, tus convenciones viven en ti. La vara del Smart Kid, la gramática EARS, la costumbre de escribir un alcance negativo explícito: las aplicas sin pensar porque son tuyas. En equipo, si eso vive solo en la cabeza de la gente, el SDD de cada dev deriva hacia su propio lado y terminas con cinco dialectos de spec que no se parecen en nada.

La solución es poner el canon donde lo lee la herramienta, no donde lo recuerda una persona. Los archivos de steering compartidos guardan el contexto de producto y las reglas. Las skills llevan el formato y la vara al agente de cada dev. El sistema de contexto en tres capas que un dev en solitario mantiene para sí pasa a ser lo que comparte todo el equipo.

El canon compartido, versionado para todos

• .ai/
  • steering/
    • product.md// qué estamos construyendo y para quién
    • tech-stack.md// el stack y las reglas que atan al agente
    • conventions.mdla vara// formato de spec, gates, reglas de código, compartidos por todos
  • sdd/specs/012-login-otp/
    • .statusgate// stage:state, el gate legible por máquina
    • requirements.md// el QUÉ, revisado por PR antes del diseño
    • design.md// el CÓMO
    • tasks.md// el CUÁNTO

Así cambia también el onboarding. Un dev nuevo lee el corpus de specs y los archivos de steering, no una página de wiki y una palmadita en el hombro. Las specs son el material de orientación, porque son el registro de cada decisión y de su porqué. La vara viaja en la herramienta, así que alguien que entró ayer escribe una spec que parece de alguien que lleva dos años ahí.

Quién es dueño de la spec

Solo, cumples los cuatro roles a la vez: escribes los requisitos, decides el diseño, cortas las tareas y revisas el resultado. En equipo esos roles se separan y, en cuanto lo hacen, la pregunta de quién es dueño se vuelve real.

Mapéalo a los roles que el SDD ya nombra. Quien escribe los requisitos es dueño del QUÉ. Un arquitecto, humano o agente, es dueño del diseño. Un revisor es dueño del gate. Nada de esto es pesado. Son las mismas personas que ya revisan código, haciéndolo un paso antes, sobre el documento en lugar del diff.

La pregunta que de verdad importa es qué pasa cuando dos devs quieren cosas distintas. Sin SDD, se enteran en el merge, o después, en producción, cuando los dos ya construyeron su versión. Con SDD, el desacuerdo aparece en el pull request de los requisitos, en los comentarios, antes de que ninguno escriba código.

Dónde aparece un desacuerdo, y cuánto cuesta

El valor de una spec en equipo no es la documentación. Es llevar la discusión a la capa más barata para tenerla.

Dónde aparece el conflicto	Cuánto cuesta resolverlo
En el PR de requisitos (SDD)	Un hilo de comentarios, antes de que exista código.
En el code review, después de implementar	Reescribir una feature que ya funciona.
En la integración, entre dos squads	Dos implementaciones que no encajan.
En producción	Un incidente, y después todo lo anterior.

Pon el gate en un board

El archivo .status es el gate. Es legible por máquina y hay uno por spec. Solo, lo lees tú mismo y alcanza. En equipo, un gate que solo vive en un archivo que nadie abre es un gate que se salta, porque la mayoría de la gente no lo ve.

Así que lo haces visible. Un board donde cada columna es una etapa de SDD. Una tarjeta es una feature. La tarjeta avanza cuando se aprueba su gate, y aprobar es moverla.

Cómo avanza una feature por el board

Entrada

Una feature nueva entra al backlog

↓

1. PRDEscribir y aprobar el QUÉ

   El requirements.md se abre como pull request. Un revisor lo aprueba. El .status pasa a requirements:approved. Nada de lo que sigue empieza hasta entonces.

   ↓
2. SPECDiseñar sobre el QUÉ aprobado

   El design.md mapea cada requisito a una decisión. Se aprueba igual, por review, en git, antes de cortar cualquier tarea.

   ↓
3. TASKSCortar el trabajo en gates

   El tasks.md divide el diseño en unidades de 2 a 4 horas, cada una testeable de forma independiente, cada una aprobada antes de escribir una línea de código.

   ↓
4. EXECConstruir, después revisar el diff

   El agente implementa a partir de la spec aprobada. El pull request es donde un humano revisa el diff contra la spec que debía cumplir.

↓

Salida

Cada cambio de columna es un gate que aprobó un humano. Saltarse uno lo bloquea la branch protection, no la confianza.

Hay un repo de referencia completo y funcionando justo para esto: acme-store-sdd. Corre este flujo en un board de GitHub Projects, con cada tarjeta avanzando a medida que se aprueba su gate .status, y branch protection en main que rechaza un merge sin review. Clónalo y lee .github/workflows junto con la carpeta .ai/sdd/specs. El board no es lo importante. El board es el gate hecho visible, y puedes verlo en vivo: siete columnas, una por etapa de SDD, cada tarjeta donde la pone el .status de su spec.

El cuello de botella pasa de escribir código a integrarlo

Esta es la razón por la que todo esto vale la pena en equipo, y no tiene nada que ver con la velocidad de tipeo.

Solo, tu cuello de botella era tu propio ciclo: tú, un agente, una feature a la vez. En equipo, generar código se abarata rápido, porque todos tienen un agente. El equipo puede producir varias veces más código que antes. Pero lo que realmente llega a producción no crece al mismo ritmo, porque la pared se movió. Ahora es el review, el deploy y la coordinación entre personas y squads.

Un equipo puede generar diez veces más código e integrar más o menos lo mismo de siempre, porque tipear nunca fue la restricción. Integrar sí. Revisar, conciliar, asegurarse de que lo que construyó una persona encaje con lo que construyó otra: ese es el trabajo que no se abarata solo porque el código aparezca más rápido.

El board lo dibuja en la pared. Pon un límite de WIP en la columna de review y mira cómo se acumulan ahí las tarjetas. Esa pila es tu restricción real, hecha visible. Ningún agente más rápido la despeja. Se despeja cuando la spec hizo su trabajo como capa de coordinación, para que el trabajo de muchos devs y muchos agentes encaje en lugar de chocar.

A medida que los equipos empiezan a adoptar agentes a escala, el patrón es consistente, y no es el que venden los proveedores de herramientas. El agente casi nunca es el cuello de botella. La integración sí. Una spec compartida es cómo un equipo evita que la integración se convierta en la pared, porque es la interfaz que permite que el trabajo en paralelo encaje al primer intento en lugar de al tercero.

¿Estás haciendo SDD o solo archivando specs?

Gate de preparación del equipo

• ✓Obligatorio:
  Las specs viven en git, versionadas junto al código que gobiernan.Si viven en una wiki o en una laptop, no son un contrato compartido. Son notas privadas con pasos extra.
• ✓Obligatorio:
  Cada spec se revisa y se aprueba en un pull request antes de que empiece la implementación.Una spec mergeada que nadie revisó es un borrador con un check verde.
• ✓Obligatorio:
  Las convenciones viven en archivos de steering y skills compartidos, no en la cabeza de un dev senior.Si enseñarle a alguien a escribir specs requiere una palmadita en el hombro, la vara todavía no está en la herramienta.
• ✓Obligatorio:
  El gate es visible: cualquiera puede ver qué features están aprobadas y cuáles siguen en borrador.Un board, una columna por etapa. Si el gate solo vive en un archivo .status que nadie abre, no es visible.
• ✓Obligatorio:
  La branch protection bloquea un merge sin review.El gate tiene que ser físico, no una norma que la gente recuerda en sus días buenos.
• ✓Obligatorio:
  El desacuerdo sobre un requisito ocurre en la spec, no en la integración.Si dos devs descubren que construyeron cosas distintas al intentar hacer merge, la discusión apareció en la capa más cara.

FAQ

¿Quién aprueba el gate en un equipo?+

El rol de revisor: la misma persona que revisaría el código, solo que un paso antes, sobre el documento. En la práctica, un tech lead o un senior del squad aprueba requisitos y diseño, y cualquier persona competente puede aprobar las tareas. La aprobación es un acto humano con nombre, registrado en el pull request y en el archivo .status, no un 'se ve bien' implícito.

No necesitas un comité. Un revisor competente por gate alcanza. Lo que no puedes tener es a nadie, porque un gate sin aprobador no es un gate.

¿Qué pasa cuando dos devs no están de acuerdo sobre un requisito?+

El desacuerdo va al pull request de requisitos, como comentarios, y se resuelve antes de que cualquiera de los dos escriba código. Ese es todo el argumento económico para trabajar así.

El mismo desacuerdo descubierto en la integración cuesta dos implementaciones terminadas que no encajan. Descubierto en producción, cuesta un incidente. Lleva la discusión a la capa más barata para tenerla.

¿De verdad necesitamos un board, o alcanza con el archivo .status?+

Solo, alcanza con el archivo, porque lo lees tú mismo. En equipo el archivo es invisible, y un gate invisible se salta. El board es el .status visible para todos a la vez. Es una vista sobre los archivos, no una segunda fuente de verdad.

El board también deja a la vista el cuello de botella de integración, algo que un archivo no puede. Una columna que supera su límite de WIP es una restricción que puedes señalar.

Usamos Jira, no GitHub Projects. ¿Esto sigue funcionando?+

Sí. El principio es: las columnas son las etapas de SDD, y una tarjeta apunta a la spec en git. La marca del board no importa.

Lo que importa es que el board refleje el gate y nunca se convierta en el lugar donde vive la spec de verdad. Git guarda el artefacto, el board refleja el estado.

¿Toda feature necesita la spec completa de tres documentos en un equipo?+

No, la regla es la misma que cuando trabajas solo. Un fix de una hora no amerita un requirements.md. Lo que cambia en equipo es que el umbral es una decisión compartida, no personal.

Acuerden cuándo un cambio necesita spec, después escriban esa regla en las convenciones y pónganla en el archivo de steering, para que los humanos y el agente apliquen el mismo umbral en lugar de seis distintos.

¿Cómo escala esto más allá de un squad?+

La spec en la frontera del squad se convierte en el contrato entre squads. Cuando un equipo depende de otro, la interfaz es una spec que ambos lados aprueban, no un hilo de chat que ambos lados olvidan.

Es el mismo mecanismo un nivel más arriba: llevar la coordinación a un artefacto versionado que ambos lados revisan, para que la integración entre equipos se diseñe a propósito en lugar de descubrirse en el merge.

Por dónde seguir

El SDD no cambia cuando sumas personas. La spec hace lo mismo de siempre. Lo que cambia es que la disciplina tiene que salir de tu cabeza y convertirse en algo que un equipo pueda ver, revisar y hacer cumplir. Versiónala, revísala en un pull request, pon el gate en un board y deja que la branch protection sostenga la línea. El método siempre se trató de llevar las decisiones al lugar más barato para tomarlas, y en equipo es donde más rinde.