luismori.

AI Coding Workflows

Spec Kit Cursor Cursor Agent

Cómo integrar GitHub Spec Kit en repositorios existentes con Cursor IDE y Cursor Agent

Una guía basada en fuentes verificadas para agregar GitHub Spec Kit a un repositorio brownfield, integrarlo con Cursor IDE y Cursor Background Agents, y adaptar el flujo de trabajo para entregas en un entorno polyrepo.

40 min de lectura

Si llegaste aquí buscando “Speckit GitHub”, el nombre oficial es GitHub Spec Kit. Voy a usar el nombre oficial en todo el artículo para que los comandos y la documentación coincidan claramente.

El April 7, 2026, volví a contrastar este flujo de trabajo con el README y la documentación vigentes de GitHub Spec Kit, la documentación vigente de Cursor y algunas conversaciones de la comunidad que muestran las preguntas más frecuentes sobre proyectos brownfield y polyrepo. Una aclaración importante desde el principio: los pasos de instalación y las capacidades de las herramientas que se describen a continuación están respaldados por fuentes; el modelo operativo de extremo a extremo es una síntesis mía.

Esto importa porque la parte difícil ya no es “¿pueden coexistir estas herramientas en el mismo repositorio?”. La parte difícil es cómo usarlas sin convertir tu repositorio existente, tu flujo de PR o la coordinación entre repositorios en un desastre.

TL;DR

  • Sí, puedes agregar GitHub Spec Kit a un repositorio existente. La documentación actual de Spec Kit permite explícitamente inicializarlo en el directorio actual con specify init --here, y el README ahora indica explícitamente que Cursor es compatible mediante --ai cursor-agent.
  • Para un repositorio brownfield, la configuración más segura es: haz primero un commit, respalda tu constitución y tus plantillas si las personalizaste y luego ejecuta specify init --here --ai cursor-agent.
  • Cursor encaja bien en dos lugares:
    • Cursor IDE para aclaraciones, planificación y edición con contexto del repositorio
    • Cursor Background Agents / GitHub app para ejecución asíncrona con alcance definido y ciclos de PR
  • Para trabajo polyrepo, el patrón más claro suele ser un único lugar para las especificaciones canónicas, un ID de funcionalidad compartido y un agente/PR por repositorio, en vez de intentar que un agente edite varios repositorios sin relación al mismo tiempo.
  • Las principales dificultades que encuentran los equipos son previsibles: dónde debe vivir la especificación canónica, cuánto debe evolucionar después de comenzar a programar, qué se sobrescribe durante una actualización y cómo mantener coherentes las instrucciones compartidas entre repositorios.

Qué aprenderás aquí

  • Cómo agregar GitHub Spec Kit a un repositorio existente sin sobrescribir tu código
  • Cómo convertir Cursor IDE en una interfaz práctica para el flujo de trabajo de Spec Kit
  • Cómo encajan Cursor Agent y la integración de GitHub de Cursor en el ciclo de implementación
  • Cómo estructuraría un flujo de trabajo polyrepo cuando una funcionalidad abarca varios repositorios
  • Qué prácticas son seguras en términos generales y cuáles todavía requieren el criterio del equipo
  • Las preguntas más frecuentes que harán ingenieros y PMs antes de adoptar este flujo de trabajo

Lo que las fuentes confirman realmente

Antes de hablar del proceso, separemos los hechos documentados de las decisiones de diseño del flujo de trabajo.

1. GitHub Spec Kit funciona en el directorio actual

La guía de instalación permite explícitamente:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init .
# or
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here

Esto significa que Spec Kit no está limitado a repositorios greenfield.

La guía de actualización es todavía más clara: es esperable ver una advertencia sobre un directorio que no está vacío al agregar Spec Kit a una base de código existente. También indica explícitamente que tu directorio specs/, el código fuente y el historial de git permanecen intactos durante la fusión. El riesgo de sobrescritura se refiere a los archivos de infraestructura de Spec Kit, no al código de tu aplicación.

2. Cursor ahora es un destino explícito de Spec Kit

Un detalle sutil pero importante de la revisión de fuentes:

  • la página de instalación todavía enumera un conjunto más reducido de agentes de IA como ejemplos
  • el README actual es la fuente de verdad más completa e indica explícitamente que Cursor es compatible
  • el README también muestra el ejemplo de inicialización directa:
specify init my-project --ai cursor-agent

Así que, si estás adoptando esto en 2026, confiaría más en el README y en la referencia de la CLI que en fragmentos de configuración antiguos del sitio de documentación.

3. Cursor lee los mismos tipos de instrucciones del repositorio que ya te importan

La documentación de Cursor y sus ejemplos de CLI son importantes aquí porque permiten un modelo práctico de instrucciones compartidas:

  • Cursor admite reglas de proyecto en .cursor/rules
  • Cursor también admite AGENTS.md como un archivo más simple de instrucciones en Markdown
  • Cursor CLI lee AGENTS.md, CLAUDE.md y .cursor/rules

Eso es lo que hace viable un flujo de trabajo con Spec Kit + Cursor en repositorios reales: no estás limitado a comandos slash. Puedes añadir instrucciones estables del repositorio como una capa adicional.

4. La aplicación de GitHub de Cursor está diseñada para la ejecución en segundo plano y los ciclos de PR

La documentación de GitHub de Cursor indica explícitamente que la aplicación de GitHub es necesaria para que Background Agents y BugBot puedan clonar repositorios y hacer push de cambios. La misma documentación también indica que puedes iniciar trabajo desde un comentario en un PR o issue con:

@cursor [prompt]

Esto encaja muy bien con la implementación acotada a un repositorio cuando la especificación y el plan ya están definidos.

5. Ningún proveedor prescribe por completo el flujo de trabajo polyrepo

Aquí tenemos que ser honestos.

Spec Kit documenta los componentes básicos:

  • especificaciones con alcance por funcionalidad
  • comandos slash y fases estructuradas
  • estrategias de numeración de ramas
  • SPECIFY_FEATURE para configuraciones no estándar

Cursor documenta los entornos de ejecución:

  • reglas y comandos del IDE
  • Background Agents
  • integración con GitHub

Git documenta el mecanismo de aislamiento:

  • git worktree

Lo que ninguna de estas fuentes prescribe por completo es dónde vive la especificación canónica cuando una funcionalidad afecta a tres repositorios y dos equipos.

Esa parte necesita un modelo operativo. En el resto del artículo recomiendo uno que se mantiene cercano a los mecanismos documentados.

Paso 1: Agrega Spec Kit de forma segura a un repositorio existente

Si tu repositorio ya tiene código en producción, CI y convenciones de equipo, no trates specify init como un comando de demostración desechable.

Usa esta secuencia:

# 1. Install or run a pinned Spec Kit release
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 2. Inside the existing repository, add Spec Kit for Cursor
specify init --here --ai cursor-agent

# 3. Verify the setup
specify check
ls -la .cursor/commands
ls -la .specify/scripts

Si el repositorio ya contiene archivos antiguos de Spec Kit o estás actualizándolo, usa:

specify init --here --force --ai cursor-agent

Pero solo después de respaldar cualquier personalización en:

.specify/memory/constitution.md
.specify/templates/

Ese respaldo importa porque la guía de actualización advierte explícitamente que, actualmente, el archivo de constitución se sobrescribe con la plantilla predeterminada durante la actualización.

Regla práctica para proyectos brownfield

Para un repositorio existente, trataría la inicialización de Spec Kit como un pequeño cambio de infraestructura:

  1. Primero haz un commit de tu rama actual.
  2. Agrega Spec Kit.
  3. Inspecciona el diff.
  4. Restaura tu constitución personalizada si es necesario.
  5. Haz un commit de la estructura inicial antes de comenzar la primera especificación.

Esto mantiene la configuración inicial de las herramientas separada del trabajo real de la funcionalidad.

Cómo generaría una constitución para un proyecto existente

Esta es una de las preguntas más importantes en proyectos brownfield, y la revisión de fuentes es útil porque nos dice tanto lo que existe como lo que no.

La guía oficial de inicio rápido claramente espera que definas la constitución desde el principio con /speckit.constitution. Al mismo tiempo, los issues de la comunidad muestran que todavía hay una gran demanda de mejores flujos de ingeniería inversa para bases de código existentes. Así que, hoy, el patrón más seguro no es “presionar un botón mágico”. Es:

  • usar el proyecto existente como evidencia
  • dejar que Cursor ayude a sintetizar el primer borrador
  • revisarlo como un documento de arquitectura, no como autocompletado

Esa recomendación es una inferencia mía a partir de las fuentes, no un contrato oficial de un comando de GitHub Spec Kit.

Parte de la evidencia, no de las aspiraciones

Para un proyecto brownfield, el primer borrador de la constitución debería basarse en lo que tu equipo ya exige o debate repetidamente:

  • README.md y documentos de arquitectura
  • .cursor/rules, AGENTS.md e instrucciones existentes para agentes
  • flujos de CI y verificaciones obligatorias
  • configuración de lint, verificación de tipos, pruebas y formato
  • manifiestos de despliegue, carpetas de infraestructura y convenciones de entorno
  • reglas de seguridad o cumplimiento que ya sean visibles en el código y los procesos
  • comentarios recurrentes en revisiones y normas del equipo del tipo “siempre lo hacemos así”

En otras palabras: no le pidas al agente que invente una empresa ideal. Pídele que extraiga las reglas duraderas que tu repositorio ya refleja.

Pídele a Cursor un borrador, pero delimita bien la tarea

Usaría un prompt como este en Cursor:

/speckit.constitution
Analyze this existing repository before drafting the constitution.
Use the current codebase, .cursor/rules, AGENTS.md, CI workflows, tests,
deployment files, and repo docs as evidence.

Create 6-10 durable principles only.
Separate project-wide invariants from feature-specific behavior.
Use MUST/SHOULD language.
For each principle, include:
- the rule
- why it exists in this project
- what kinds of future specs it should influence

Do not include temporary implementation details, current library preferences
unless they are a real team constraint, or aspirational best practices that are
not already supported by the repo.

Ese prompt importa porque un borrador débil de la constitución suele fallar de una de dos maneras:

  • se vuelve genérico e inútil
  • se convierte en un volcado de los detalles de implementación actuales

No quieres ninguna de las dos cosas. Una buena constitución brownfield debería seguir siendo útil para varias funcionalidades futuras.

Qué pertenece a la constitución

Para la mayoría de los proyectos existentes, limitaría la constitución a categorías como:

  • límites arquitectónicos que rara vez deberían vulnerarse
  • controles de calidad que se aplican a casi todos los cambios
  • reglas de seguridad y manejo de datos
  • restricciones de compatibilidad, migración o implementación gradual
  • reglas de documentación u observabilidad que influyen de manera significativa en la implementación

Ejemplos:

- Public API changes MUST be backward compatible for one release cycle.
- Database schema changes MUST be deploy-safe and rollback-aware.
- New external dependencies SHOULD be avoided unless there is a clear gap in the current stack.
- User-visible behavior changes MUST include automated tests or an explicit acceptance plan.

Qué no pertenece a la constitución

No pondría lo siguiente en la constitución, salvo que sea realmente innegociable:

  • soluciones temporales de implementación
  • decisiones puntuales de una funcionalidad
  • todas las preferencias de estilo de código
  • copias extensas de documentos de estándares o de la wiki

Si ya tienes reglas detalladas en .cursor/rules o en la wiki del equipo, usa la constitución como la capa de gobierno condensada, no como el lugar donde duplicar todos tus documentos.

Vista ASCII:

existing repo
  -> code patterns
  -> CI gates
  -> docs and runbooks
  -> agent rules
  -> recurring review norms
  -> draft constitution
  -> human review
  -> durable project principles

Cómo mantendría actualizada la constitución para futuras mejoras

Esta es la segunda mitad del problema, y las conversaciones de la comunidad sobre la evolución de las especificaciones son muy relevantes aquí.

El flujo de trabajo actual claramente permite crear especificaciones para nuevas funcionalidades. Lo que hoy está menos pulido es el paso de “cerrar el ciclo” después de que una funcionalidad cambia el proyecto de una manera que debería afectar el trabajo futuro. Varias respuestas de la comunidad hablan explícitamente de pedirle al agente que incorpore esas lecciones a la constitución o a una memoria más amplia del proyecto.

Así que mi recomendación es simple:

  • no actualices la constitución por cada funcionalidad
  • sí actualízala cuando una funcionalidad cambie un invariante de todo el proyecto

Usa una pregunta para decidir si hace falta un cambio

Después de fusionar una funcionalidad, haz una pregunta:

¿Aprendimos o formalizamos una regla que las futuras especificaciones deberían seguir por defecto?

Si la respuesta es no, deja la constitución como está.

Si la respuesta es sí, actualízala.

Motivos habituales:

  • introdujiste un nuevo límite arquitectónico
  • cambiaste las reglas de seguridad para despliegues o migraciones
  • agregaste un nuevo requisito de cumplimiento o seguridad
  • cambiaste el control predeterminado de pruebas o revisión
  • estandarizaste una nueva regla de coordinación entre repositorios

Revisa la constitución después de la fusión

Agregaría un breve paso de mantenimiento después de las funcionalidades importantes:

Review .specify/memory/constitution.md against the merged changes for
042-tenant-sso and the current codebase.

Only propose edits if there is a project-wide rule change that should affect
future specifications.

Do not copy feature details into the constitution.
For each proposed edit, explain:
- what changed
- why it should govern future work
- which future kinds of features it affects

Esto evita que la constitución caiga en dos extremos perjudiciales:

  • desactualizada e ignorada
  • editada en exceso y saturada

Revisa ante eventos, no solo según un calendario

Si tu equipo avanza rápido, priorizaría las revisiones de la constitución impulsadas por eventos:

  • después de cambios de arquitectura
  • después de incorporar nuevas capacidades de plataforma
  • después de cambios de seguridad o cumplimiento
  • después de cambios en las reglas de coordinación entre repositorios

También puedes hacer una revisión trimestral ligera, pero no confiaría únicamente en un calendario para la gobernanza. El mejor motivo es: algo cambió y la planificación de futuras funcionalidades debe tenerlo en cuenta.

Mantén una separación clara entre la constitución y las especificaciones de funcionalidades

La constitución es para reglas duraderas.

La especificación de la funcionalidad es para el cambio actual.

Esa separación es lo que mantiene a Spec Kit utilizable en sistemas brownfield. Si la constitución se convierte en un registro de cada mejora, deja de ser una constitución y empieza a convertirse en un historial de proyecto lleno de ruido.

Flujo de decisión ASCII:

feature merged
  -> did a project-wide invariant change?
     -> no: keep constitution as-is
     -> yes: update constitution, review, and commit separately

Mi regla práctica es: si un PM, tech lead o agente debería asumir la regla en la próxima funcionalidad no relacionada, pertenece a la constitución. Si no, pertenece a la especificación, el plan o las notas de implementación de la funcionalidad.

Cómo aplicaría ingeniería inversa a una funcionalidad existente para crear artefactos de Spec Kit

Este problema es distinto de generar una constitución para todo el repositorio.

Aquí el objetivo es más acotado:

  • tomar una funcionalidad existente
  • inferir cómo funciona hoy
  • generar los artefactos de Spec Kit que te gustaría tener ya disponibles
  • usar esos artefactos como base para futuras mejoras, refactorización u onboarding

La advertencia importante sigue siendo la misma: Spec Kit actualmente no incluye un comando oficial /reverse. La comunidad lo ha pedido explícitamente y también hay comentarios activos que solicitan una forma más clara de refinar las especificaciones existentes en su lugar. Por eso, la ruta recomendada hoy es usar deliberadamente el flujo normal de Spec Kit para documentar el estado actual.

Ese flujo de trabajo es una recomendación mía, no una capacidad oficial de un solo comando.

Delimita una funcionalidad, no un subsistema completo

Si diriges al agente hacia “el sistema de facturación” o “la plataforma de autenticación”, el resultado normalmente será amplio y poco preciso.

La ingeniería inversa funciona mucho mejor cuando eliges una funcionalidad con una interfaz de producto clara, como:

  • aplicación de cupones durante el checkout
  • configuración de SSO e inicio de sesión para un tenant
  • exportación de facturas a CSV
  • filtrado de eventos en un dashboard de telemetría

Esto les da a Cursor y a Spec Kit algo concreto que reconstruir.

El modelo mental más seguro

Trata el ejercicio como la creación de una rama de funcionalidad que establezca una base de documentación.

En otras palabras, no le digas a Spec Kit:

Create a new feature for telemetry dashboards

Dile:

Document the existing telemetry dashboard feature exactly as it works today,
including user-visible behavior, system boundaries, contracts, and constraints.
Do not invent enhancements.

Esa sola frase cambia por completo la calidad del resultado.

El flujo de trabajo en Cursor IDE que recomiendo

1. Primero reúne en Cursor la evidencia de la funcionalidad

Antes de ejecutar los comandos de Spec Kit, usa Cursor para identificar los límites de la funcionalidad:

  • rutas o páginas de la interfaz
  • puntos de entrada y menús
  • endpoints de la API
  • tablas de base de datos o entidades almacenadas
  • trabajos en segundo plano
  • feature flags
  • logs, analítica o eventos de auditoría
  • pruebas que ya describen el comportamiento
  • documentación, runbooks y capturas de pantalla, si están disponibles

Esto te da el conjunto de evidencias que el agente necesita para reconstruir la funcionalidad en lugar de inventarla.

2. Crea una rama de funcionalidad orientada a la documentación

Como /speckit.specify está optimizado para ramas de funcionalidad, aprovecharía ese diseño en vez de intentar cambiarlo.

Usa un nombre de rama que deje claro el propósito:

050-document-existing-telemetry-dashboard

o

050-baseline-tenant-sso-current-state

Esto deja claro a quienes revisan que la rama documenta el comportamiento actual, no que necesariamente vaya a cambiarlo todavía.

3. Usa /speckit.specify para registrar el comportamiento actual

En Cursor IDE, usaría un prompt como este:

/speckit.specify
Reverse-engineer the existing telemetry dashboard feature from this repository.

Describe the feature exactly as it works today.
Infer requirements, user journeys, system boundaries, and acceptance criteria
from the current code, tests, routes, API handlers, data access patterns,
background jobs, and existing docs.

Do not propose enhancements.
Do not redesign the feature.
Mark any uncertainty explicitly instead of guessing.

Esto te da la base de spec.md.

4. Usa /speckit.clarify para resolver las brechas evidentes

Aquí es donde conviertes un “probablemente” en un “lo sabemos”.

Ejemplo:

/speckit.clarify
Clarify gaps in the reverse-engineered spec for the telemetry dashboard.
Focus on access control, data freshness, empty states, filtering behavior,
failure modes, and any places where tests or code paths disagree.

Para el trabajo brownfield, este paso importa aún más que en el trabajo greenfield porque el comportamiento existente suele ser inconsistente entre el código, las pruebas y la interfaz.

5. Usa /speckit.plan para generar el conjunto de artefactos técnicos

Ahora pídele a Spec Kit que traduzca la funcionalidad documentada en artefactos de arquitectura, no en un rediseño:

/speckit.plan
Create an implementation plan that documents the current architecture of the
existing telemetry dashboard feature.

Infer the data model, component boundaries, integration points, API contracts,
background processing, test scenarios, and operational constraints from the
current implementation.

Prefer documenting the existing architecture over proposing a new one.
If the current implementation has inconsistencies, record them clearly.
Generate contracts only for externally observable APIs, events, or interfaces
that this feature currently depends on.

Según la documentación actual de Spec Kit, este es el paso que debería producir el conjunto principal de artefactos de apoyo alrededor de plan.md, como:

specs/050-document-existing-telemetry-dashboard/
  spec.md
  plan.md
  research.md
  data-model.md
  quickstart.md
  contracts/

Los archivos de apoyo exactos pueden variar según el plan y las plantillas, pero esta es la familia de artefactos que Spec Kit documenta alrededor de /speckit.plan.

6. Usa /speckit.tasks para crear el mapa de ejecución u onboarding

Luego genera tasks.md:

/speckit.tasks

Para ingeniería inversa, trato tasks.md de una de estas dos maneras:

  • como la hoja de ruta para validar la comprensión reconstruida
  • como el punto de partida para la siguiente mejora o refactorización

Esto lo hace útil tanto para ingenieros como para PMs. Convierte la documentación en algo ejecutable.

7. Usa /speckit.checklist para validar que no falte nada

Esta parte es fácil de omitir, pero vale la pena hacerla.

El README oficial describe /speckit.checklist como una forma de generar listas de verificación de calidad personalizadas. Para ingeniería inversa, pediría una lista como esta:

/speckit.checklist
Generate a reverse-engineering completeness checklist for the telemetry
dashboard feature.

Check whether the artifacts cover:
- user-visible behavior
- routes and entry points
- permissions and access control
- API contracts
- data model and persistence
- background jobs or async flows
- failure modes
- tests and validation scenarios
- known inconsistencies or undocumented assumptions

Esto te da un artefacto práctico de auditoría en lugar de solo un montón de archivos Markdown.

8. Ejecuta /speckit.analyze antes de confiar en el resultado

Por último:

/speckit.analyze

El README recomienda explícitamente hacerlo después de generar las tareas y antes de la implementación. Para la reconstrucción brownfield, es aún más útil porque ayuda a detectar contradicciones entre:

  • la especificación reconstruida
  • el plan inferido
  • las tareas generadas
  • la realidad de la base de código de la que partiste

El conjunto de artefactos al que apuntaría

Si la pasada de ingeniería inversa salió bien, la carpeta de la funcionalidad debería verse aproximadamente así:

specs/050-document-existing-telemetry-dashboard/
  spec.md
  plan.md
  research.md
  data-model.md
  quickstart.md
  contracts/
  tasks.md
  checklist artifact from /speckit.checklist

Eso basta para hacer tres cosas valiosas:

  • incorporar a un nuevo ingeniero a la funcionalidad
  • revisar la funcionalidad con un PM usando artefactos estables
  • comenzar una mejora posterior con mucho mejor contexto

Proyecto de ejemplo: un dashboard de telemetría brownfield

Si quieres una referencia real de estilo brownfield, el README de Spec Kit enlaza una guía de la comunidad basada en el sistema de soporte terrestre de código abierto Hermes de la NASA, donde se agrega un dashboard web ligero de telemetría a una base de código existente en Go.

Es un buen modelo mental para Cursor IDE, aunque tu stack sea distinto.

Imagina que ahora no estás construyendo el dashboard desde cero. Estás documentando la versión actual que ya está en producción para poder ampliarla de forma segura.

Usaría un prompt como este:

/speckit.specify
Reverse-engineer the existing web telemetry dashboard feature in this repo.

Document:
- which users can access it
- how they reach it
- which telemetry streams or events it shows
- how filtering, sorting, and refresh behavior work
- which backend endpoints, modules, and data sources it depends on
- what happens on empty, delayed, or failed data states
- what tests currently prove this behavior

Do not invent future capabilities.
Write the specification as the current-state source of truth for a later
enhancement project.

Luego seguiría con:

/speckit.plan
Create the technical plan and supporting artifacts for the current telemetry
dashboard implementation exactly as it exists today. Infer contracts, data
models, validation scenarios, and known technical constraints from the code.
Record inconsistencies rather than smoothing them over.

Eso me daría una base clara para una siguiente funcionalidad, como:

  • agregar filtros por tenant
  • agregar exportación a CSV
  • agregar umbrales de alerta
  • agregar visibilidad del dashboard basada en roles

Mi modelo de ramas recomendado para este trabajo

Como la evolución de las especificaciones todavía tiene dificultades en los flujos brownfield, normalmente dividiría esto en dos ramas:

050-document-existing-telemetry-dashboard
051-enhance-telemetry-dashboard

Primera rama:

  • reconstruir el estado actual mediante ingeniería inversa
  • generar y revisar los artefactos
  • fusionar la base de documentación

Segunda rama:

  • crear la especificación de la mejora real
  • reutilizar los nuevos artefactos de base
  • implementar con mucha menos ambigüedad

No es el flujo más rápido posible, pero es el más claro que he encontrado hasta ahora si te importan la documentación mantenible y el futuro trabajo asistido por IA.

Paso 2: Usa Cursor IDE como entorno de planificación

Una vez que Spec Kit está en el repositorio, Cursor IDE se convierte en el lugar más cómodo para ejecutar el flujo de trabajo con el contexto real de la base de código.

El stack práctico

Usa el repositorio de esta manera:

.cursor/rules/         -> persistent repo rules and scoped guardrails
.cursor/commands/      -> Spec Kit slash commands installed by Spec Kit
AGENTS.md              -> simple repo-level instructions for any agent surface
.specify/              -> scripts, templates, memory
specs/<feature-id>/    -> spec, plan, tasks, contracts, research

Esto te da una buena separación de responsabilidades:

  • Spec Kit se encarga de las fases del flujo de trabajo
  • las reglas de Cursor se encargan del comportamiento persistente en el repositorio
  • AGENTS.md se encarga de las instrucciones del equipo en lenguaje natural

Un enfoque útil para AGENTS.md

No necesitas un archivo de instrucciones enorme. Para la mayoría de los equipos, uno corto es mejor:

# Agent Workflow Notes

- Use GitHub Spec Kit for feature planning before implementation.
- Treat `specs/<feature-id>/spec.md`, `plan.md`, and `tasks.md` as the source of truth for active feature scope.
- Follow `.cursor/rules` for coding standards and review expectations.
- Do not edit unrelated files while implementing a Spec Kit task.
- Open questions and requirement conflicts should be written back into the active spec or plan, not left only in chat.

Eso basta para mantener alineados a ingenieros y PMs en un punto importante: la especificación debe sobrevivir a la sesión de chat.

Los primeros comandos que ejecutaría en Cursor

Para una funcionalidad brownfield real, seguiría este orden:

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.plan
/speckit.tasks

Después me detendría a revisar el plan generado antes de implementar.

Esa pausa es especialmente importante en repositorios existentes, donde el costo oculto casi nunca es “¿puede el modelo escribir código?”. Es “¿planificamos por accidente un cambio que afecta demasiadas áreas compartidas a la vez?”.

Paso 3: Usa Cursor Agent de la manera correcta

Cuando la gente dice “Cursor Agent”, a menudo se refiere a varias cosas distintas:

  • la experiencia del agente local dentro de Cursor IDE
  • la CLI cursor-agent
  • Background Agents conectados a GitHub

Para planificar la adopción, ayuda pensar en términos de planificación local frente a ejecución remota.

El mejor uso del Cursor Agent local

Usa el agente local cuando necesites:

  • explorar el repositorio
  • resolver ambigüedades
  • refinar el plan
  • hacer cambios de código que necesiten el contexto disponible en el IDE

Esta es la etapa donde más provecho obtienen los ingenieros y tech leads, porque la conversación puede mantenerse cerca de la base de código real.

Si prefieres la CLI o quieres automatizar parte del flujo, la documentación de la CLI de Cursor también admite la ejecución no interactiva con -p:

cursor-agent -p "Read specs/042-tenant-sso/plan.md and summarize the API-only tasks. Do not write code."

Esto es útil para verificaciones de planificación, resúmenes asistidos por CI o automatización ligera del repositorio. La misma documentación de la CLI también señala que Cursor lee AGENTS.md, CLAUDE.md y .cursor/rules, por lo que el agente puede seguir heredando las instrucciones de tu repositorio fuera del IDE.

El mejor uso de Cursor Background Agents

Usa Background Agents después de que la funcionalidad ya esté descompuesta en tareas con límites definidos.

Un buen ejemplo es:

@cursor Implement task 3 from specs/042-tenant-sso/tasks.md.
Only touch the API repo. Follow the acceptance criteria in plan.md.
Open a PR with a summary of what changed and any unresolved questions.

Este prompt es efectivo porque está delimitado por:

  • repositorio
  • tarea
  • especificación

Ese es el contrato adecuado para el trabajo asíncrono.

Qué no hacer

No le pidas a un solo agente en segundo plano que “implemente toda la funcionalidad en todos los repositorios”, a menos que hayas creado intencionalmente un entorno de ejecución compartido para ese propósito y entiendas el alcance de los posibles efectos.

La documentación es mucho más clara sobre el acceso a repositorios, la creación de PR y los repositorios dependientes/submódulos que sobre la orquestación libre entre varios repositorios independientes. Así que, para la mayoría de los equipos, la opción predeterminada más segura es:

  • un repositorio
  • un lote de tareas
  • un agente
  • un PR

Es más lento que la versión idealizada, pero más rápido que corregir la divergencia entre repositorios.

Cómo generaría varias especificaciones al mismo tiempo

Es fácil confundirse aquí, porque Spec Kit ya admite muy bien un tipo de paralelismo y otro solo de manera indirecta.

Según la guía oficial de SDD:

  • /speckit.tasks puede marcar como paralelas tareas independientes dentro de una funcionalidad
  • /speckit.specify sigue estando fundamentalmente orientado a una rama para una funcionalidad a la vez

Así que, si preguntas “¿puedo tener tres especificaciones de funcionalidades activas al mismo tiempo en el mismo repositorio?”, mi respuesta es:

  • sí, pero
  • no en el mismo árbol de trabajo
  • y no suponiendo que una rama puede representar de forma segura varias funcionalidades activas

El flujo de trabajo actual es mucho más fácil de entender si tratas una rama como un flujo de especificación.

El modelo seguro actual

Para varias especificaciones simultáneas en un repositorio, recomiendo:

one repo
  -> one launcher checkout on main
  -> one feature branch per spec
  -> one worktree per active spec branch
  -> one PR per spec

Esto se ajusta mejor al comportamiento actual centrado en ramas que intentar mantener varios directorios de especificaciones activos dentro de un solo checkout.

Por qué importa

Los issues de la comunidad son útiles aquí:

  • el Issue #370 muestra que todavía hay confusión real sobre cuándo los artefactos de planificación deberían vivir en main y cuándo en una rama de funcionalidad
  • el Issue #1191 muestra que los usuarios todavía quieren editar y refinar las especificaciones en su lugar con más facilidad, en vez de tener que crear siempre otra rama

Así que, hasta que Spec Kit desarrolle un modelo operativo más explícito para múltiples especificaciones, la regla más segura sigue siendo:

un flujo de especificación activo por rama

Un flujo práctico para tres especificaciones

Supongamos que quieres explorar tres funcionalidades en paralelo:

  • SSO para tenants
  • exportación de facturas a CSV
  • búsqueda en el log de auditoría

Usaría un checkout como punto de lanzamiento y lo mantendría en main.

Desde ahí:

main checkout
  -> /speckit.specify for feature A
  -> branch A created
  -> materialize worktree A

main checkout
  -> /speckit.specify for feature B
  -> branch B created
  -> materialize worktree B

main checkout
  -> /speckit.specify for feature C
  -> branch C created
  -> materialize worktree C

Vista ASCII:

repo-main/                     <- launcher checkout, stays on main
worktrees/
  042-tenant-sso/              <- spec branch + Cursor window A
  043-invoice-csv-export/      <- spec branch + Cursor window B
  044-audit-log-search/        <- spec branch + Cursor window C

La secuencia que usaría realmente

# launcher checkout stays on main
git switch main

# create first spec
/speckit.specify Add tenant SSO for enterprise accounts

# switch launcher back to main
git switch main

# create second spec
/speckit.specify Add invoice CSV export for finance admins

# switch launcher back to main
git switch main

# create third spec
/speckit.specify Add audit log search and filtering

En ese punto, Spec Kit habrá creado:

  • una rama por funcionalidad
  • un directorio specs/<branch-name>/ correspondiente por funcionalidad

Luego materializaría cada rama activa como un worktree.

Cuándo usar numeración de ramas con timestamp

Si varias personas o agentes van a crear especificaciones de forma independiente, la opción --branch-numbering timestamp del README se vuelve mucho más atractiva.

Usaría numeración con timestamp cuando:

  • varias personas puedan crear especificaciones al mismo tiempo
  • los agentes puedan crear especificaciones de forma asíncrona
  • las colisiones de números de rama sean más problemáticas que la legibilidad para las personas

Mantendría la numeración secuencial cuando:

  • una persona coordine la creación de especificaciones
  • los PMs e ingenieros revisen los IDs de especificación con frecuencia
  • te importe más que los IDs de funcionalidad sean legibles que la resistencia a colisiones

Qué no haría

Evitaría estos patrones:

  • crear varias especificaciones activas y luego hacer toda la planificación en un solo checkout sobre una rama que cambia constantemente
  • usar una rama genérica de “planificación” para funcionalidades no relacionadas
  • abrir PR que combinen dos o tres ramas de especificación solo porque las funcionalidades parecen cercanas

Esos atajos parecen más rápidos durante aproximadamente una hora y después salen caros.

Cómo usaría Git Worktree con Spec Kit

Git worktree es la protección que falta si quieres tener varias especificaciones activas en un repositorio sin cambiar de rama constantemente.

La documentación oficial de Git es clara: un repositorio puede admitir varios árboles de trabajo, por lo que puedes hacer checkout de más de una rama a la vez. Esto encaja de forma natural con el flujo actual de funcionalidades basado en ramas de Spec Kit.

La recomendación clave

Mantendría:

  • un checkout principal como punto de lanzamiento
  • un worktree por cada rama de especificación activa

Esto te da una relación clara:

one spec
  -> one branch
  -> one worktree
  -> one Cursor window
  -> one PR

Por qué no dejaría que /speckit.specify entre en conflicto con el estado del worktree

Ya existe un reporte de error de la comunidad que indica que el comportamiento actual de “crear una nueva rama” es frágil cuando se usa con git worktrees.

Así que el flujo práctico más seguro hoy es:

  1. Deja que Spec Kit cree la rama de funcionalidad en tu checkout de lanzamiento.
  2. Luego crea un worktree para esa rama.
  3. Haz las aclaraciones, la planificación, la definición de tareas y la implementación desde el worktree.

Esto es mucho menos frágil que intentar improvisar con la creación de ramas dentro de una estructura de worktrees que ya ha cambiado.

El patrón de worktree que recomiendo

Ejemplo:

# repo-main is your normal repository checkout
cd ~/repos/app
git switch main

# after /speckit.specify created branch 042-tenant-sso
git worktree add ../worktrees/042-tenant-sso 042-tenant-sso

# after /speckit.specify created branch 043-invoice-csv-export
git worktree add ../worktrees/043-invoice-csv-export 043-invoice-csv-export

# after /speckit.specify created branch 044-audit-log-search
git worktree add ../worktrees/044-audit-log-search 044-audit-log-search

Luego abre cada uno de forma independiente en Cursor:

cursor ../worktrees/042-tenant-sso
cursor ../worktrees/043-invoice-csv-export
cursor ../worktrees/044-audit-log-search

Dónde debe ejecutarse cada comando

Una vez que exista el worktree, ejecutaría el resto del flujo de Spec Kit dentro de ese worktree:

worktree for 042-tenant-sso
  -> /speckit.clarify
  -> /speckit.plan
  -> /speckit.tasks
  -> /speckit.analyze
  -> implementation / PR work

Esto importa porque la funcionalidad activa está vinculada a la rama en el flujo actual. Ejecutar los comandos dentro del worktree mantiene estable el contexto de la rama y hace mucho más difícil escribir accidentalmente el siguiente artefacto en el flujo de funcionalidad equivocado.

Usa SPECIFY_FEATURE solo como alternativa de emergencia

Si inferir la rama se vuelve complicado por scripts personalizados, una estructura no estándar o shells de coordinación, entonces:

export SPECIFY_FEATURE="042-tenant-sso"

Pero lo trataría como una alternativa de respaldo, no como la opción predeterminada.

La opción predeterminada más clara sigue siendo:

  • entrar al worktree correcto
  • dejar que el contexto de la rama identifique la funcionalidad

Un ejemplo completo: tres especificaciones concurrentes

Este es el patrón de extremo a extremo que realmente recomendaría para un repositorio:

# launcher checkout
cd ~/repos/app
git switch main

/speckit.specify Add tenant SSO for enterprise accounts
git worktree add ../worktrees/042-tenant-sso 042-tenant-sso

git switch main
/speckit.specify Add invoice CSV export for finance admins
git worktree add ../worktrees/043-invoice-csv-export 043-invoice-csv-export

git switch main
/speckit.specify Add audit log search and filtering
git worktree add ../worktrees/044-audit-log-search 044-audit-log-search

Luego:

../worktrees/042-tenant-sso
  -> finish clarify / plan / tasks / analyze

../worktrees/043-invoice-csv-export
  -> finish clarify / plan / tasks / analyze

../worktrees/044-audit-log-search
  -> finish clarify / plan / tasks / analyze

En ese punto, Cursor Background Agents o personas pueden encargarse de una rama a la vez sin interferir entre sí.

Mi regla práctica

Si el trabajo es dentro de una funcionalidad, usa el paralelismo a nivel de tareas de Spec Kit.

Si el trabajo es entre varias funcionalidades, usa ramas de Git y worktrees para aislar cada funcionalidad.

Esa distinción mantiene el flujo de trabajo bajo control.

El patrón polyrepo recomendado

Esta es la parte que la mayoría de los equipos realmente necesita.

Supongamos que una funcionalidad afecta a:

  • web-app
  • api-service
  • worker-service

Este es el modelo operativo que recomiendo.

Patrón A: Un único lugar para la especificación canónica

Elige un lugar donde vivan los artefactos de referencia de la funcionalidad.

Puede ser:

  • un repositorio de plataforma
  • un repositorio de arquitectura
  • el repositorio principal de la aplicación que usan los clientes
  • un repositorio dedicado a la coordinación

Luego almacena allí los artefactos canónicos:

specs/042-tenant-sso/
  spec.md
  plan.md
  tasks.md
  research.md
  contracts/

Todo lo demás debería hacer referencia a ese ID de funcionalidad.

Patrón B: Identidad de funcionalidad compartida entre repositorios

Usa el mismo ID de funcionalidad en todas partes:

042-tenant-sso

Úsalo en:

  • la carpeta de especificación
  • las ramas de los repositorios
  • los títulos de los PR
  • las etiquetas de los issues
  • las listas de verificación de implementación

Ejemplo:

specs/042-tenant-sso/
web-app:       feat/042-tenant-sso
api-service:   feat/042-tenant-sso
worker:        feat/042-tenant-sso

Parece algo menor, pero facilita mucho el traspaso entre PMs, el seguimiento del estado y las conversaciones sobre rollback.

Si ejecutas Spec Kit desde un directorio de coordinación no estándar o sin depender de la rama actual de git para inferir la funcionalidad activa, Spec Kit también documenta una alternativa manual:

export SPECIFY_FEATURE="042-tenant-sso"

Esto es especialmente útil cuando un repositorio de plataforma o un espacio de trabajo de orquestación coordina varios repositorios de implementación.

Patrón C: Complementos locales por repositorio, no especificaciones principales duplicadas

En un sistema polyrepo, las especificaciones duplicadas se desactualizan muy rápido.

Por eso mantendría:

  • un spec.md canónico
  • un plan.md canónico
  • notas locales por repositorio solo cuando sean necesarias

Por ejemplo:

web-app/docs/042-tenant-sso-notes.md
api-service/docs/042-tenant-sso-notes.md

Esas notas pueden registrar detalles de implementación, pero nunca deberían convertirse en fuentes de verdad que compitan entre sí para los requisitos.

Patrón D: Un agente y un PR por repositorio

Esta es la regla de coordinación segura más simple:

canonical spec
  -> split by repository
  -> one agent per repo
  -> one PR per repo
  -> merge in dependency order

Flujo ASCII:

feature request
  -> canonical spec + plan
  -> repo split
     -> web-app PR
     -> api-service PR
     -> worker-service PR
  -> integration check
  -> release / rollout

Patrón E: Usa numeración de ramas con timestamp solo si la creación distribuida es una necesidad real

El README de Spec Kit ahora documenta --branch-numbering timestamp como una opción útil para que los equipos distribuidos eviten conflictos de numeración.

Esto ayuda si varios equipos inicializan funcionalidades de forma independiente en repositorios separados. Pero si tu equipo tiene un único lugar para las especificaciones canónicas, seguiría prefiriendo IDs secuenciales simples porque son más fáciles de leer en las conversaciones de planificación.

Una configuración polyrepo práctica que realmente usaría

Si tuviera que implementar esto la próxima semana, lo haría así.

1. Crea o elige el lugar para las especificaciones

Ejemplo:

platform-coordination/
  specs/042-tenant-sso/

2. Agrega instrucciones ligeras en cada repositorio de implementación

Cada repositorio recibe:

  • .cursor/rules
  • AGENTS.md
  • opcionalmente, la estructura inicial de Spec Kit si el equipo también quiere comandos slash locales

3. Mantén explícito el contrato de implementación

Dentro de cada repositorio de implementación, el prompt del agente debería hacer referencia a:

  • el ID de funcionalidad
  • la ruta o URL de la especificación canónica
  • el subconjunto de tareas específico del repositorio
  • los límites de “no tocar”

Ejemplo:

Implement API-only tasks for 042-tenant-sso.
Source of truth is platform-coordination/specs/042-tenant-sso/plan.md.
Do not change the web-app or worker repos.
If an acceptance criterion is ambiguous, stop and write the question back to the spec.

4. Revisa la secuencia entre repositorios antes de fusionar

Aquí es donde PMs e ingenieros deberían alinearse explícitamente sobre:

  • qué PR debe fusionarse primero
  • qué contrato de API queda fijado
  • qué repositorio puede desplegarse de forma independiente
  • qué pasos de implementación gradual necesitan coordinación

Si eso no queda por escrito, incluso el mejor agente del mundo generará confusión organizacional.

Prácticas comunes que recomiendo

No todas estas son reglas oficiales. Son las prácticas que normalizaría para un equipo que usa este stack en serio.

  • Trata la inicialización de Spec Kit como infraestructura del repositorio, no como parte del diff de una funcionalidad.
  • Mantén la constitución breve y con criterios claros. Debería expresar lo que realmente no es negociable, no eslóganes genéricos de ingeniería.
  • Haz que spec.md, plan.md y tasks.md sean artefactos revisables. No entierres las decisiones de planificación solo en el chat.
  • Usa Cursor IDE para aclarar y descomponer el trabajo. Usa Background Agents para una ejecución acotada una vez que el alcance esté estable.
  • Prefiere un conjunto canónico de especificaciones por funcionalidad en entornos polyrepo. Duplica las especificaciones solo si quieres garantizar que diverjan.
  • Usa un ID de funcionalidad en todos los repositorios y PR.
  • Mantén acotada la responsabilidad de cada agente. Un repositorio, una parte de las tareas y un PR es una muy buena opción predeterminada.
  • Registra las preguntas abiertas en la especificación o el plan. Si la respuesta importa más adelante, el chat no es suficiente.
  • Respalda o restaura la constitución durante las actualizaciones. Esto no es opcional si la personalizaste.
  • Revisa .cursor/commands después de la inicialización. La documentación y el README se están alineando, pero una verificación rápida evita confusiones.

Preguntas comunes que harán los equipos

”¿Realmente puedo agregar Spec Kit a un repositorio que no está vacío?”

Sí. La documentación admite explícitamente specify init --here, y la guía de actualización indica explícitamente que la advertencia sobre un directorio que no está vacío es esperable en bases de código existentes.

”¿Sobrescribirá mi código fuente?”

La documentación dice que no. El riesgo de sobrescritura se aplica a la infraestructura administrada por Spec Kit, como archivos de comandos, plantillas, scripts y archivos de memoria.

”¿Necesito ejecutar specify cada vez que abro el proyecto?”

No. La guía de actualización indica explícitamente que specify init es para la configuración inicial y las actualizaciones, no para cada sesión de trabajo.

”¿Cursor tiene soporte oficial o es una solución alternativa?”

Según el README actual, Cursor es compatible de forma explícita y cursor-agent aparece en la referencia de la CLI. La revisión de fuentes sí reveló un pequeño desfase entre páginas de la documentación, así que de todos modos verificaría localmente los archivos generados después de la configuración.

”¿Cada repositorio de un entorno polyrepo debería tener su propia especificación completa?”

Por lo general, no. Mantendría una especificación canónica de la funcionalidad y usaría notas locales por repositorio solo donde los detalles de implementación realmente difieran.

”¿Qué pasa si la especificación cambia después de que comienza la implementación?”

Este es uno de los problemas más comunes de la comunidad. Mi recomendación es simple:

  • antes de empezar a programar, la especificación puede evolucionar libremente
  • una vez que el trabajo en los repositorios está en marcha, trata los cambios de especificación como eventos sujetos a control de cambios
  • actualiza primero la especificación canónica y luego las tareas de los repositorios afectados

Esto mantiene alineados a PMs, revisores y agentes con los mismos criterios de aceptación.

”¿De todos modos puedo coordinar varios repositorios desde un solo lugar?”

Sí, pero hazlo de forma deliberada. Las conversaciones de la comunidad muestran que hay personas experimentando con configuración compartida y un único repositorio de lanzamiento que lee otros repositorios como contexto. Eso puede funcionar. Pero lo reservaría para equipos maduros que ya tienen una capa sólida de convenciones compartidas. Para la mayoría de las organizaciones, un único lugar para la especificación canónica más una ejecución acotada a cada repositorio es más simple y seguro.

Mi modelo operativo recomendado para ingenieros y PMs

Si quieres una respuesta concreta y con criterio, aquí está:

  1. Agrega Spec Kit a un repositorio canónico de planificación o de plataforma.
  2. Usa Cursor IDE para generar y refinar la constitución, la especificación, las aclaraciones, el plan y las tareas.
  3. Revisa esos artefactos antes de que comience la implementación.
  4. Divide el trabajo por repositorio.
  5. Ejecuta un flujo de trabajo de Cursor Agent por repositorio, con límites explícitos.
  6. Mantén los PR pequeños y vinculados por el mismo ID de funcionalidad.
  7. Fusiona según el orden de las dependencias y actualiza la especificación canónica si cambiaron los criterios de aceptación.

Vista ASCII:

PM / feature request
  -> Cursor + Spec Kit planning
  -> canonical spec / plan / tasks
  -> repo-specific implementation prompts
  -> one PR per repo
  -> coordinated merge + rollout

Ese modelo es aburrido en el mejor sentido. Les da a los PMs algo que revisar, a los ingenieros una base estable sobre la cual construir y a los agentes de IA contratos de trabajo más acotados y seguros.

La brecha real a la que debes prestar atención

La brecha no es “¿pueden trabajar juntas estas herramientas?”. Pueden.

La brecha real es que la gobernanza polyrepo sigue siendo principalmente un problema de diseño del equipo:

  • dónde vive la especificación canónica
  • quién puede cambiarla después de que comienza el desarrollo
  • cómo circulan las instrucciones compartidas entre repositorios
  • cuándo se permite que los agentes asíncronos trabajen en más de un repositorio

Si respondes esas preguntas desde el principio, GitHub Spec Kit y Cursor encajan sorprendentemente bien. Si las ignoras, las herramientas solo te ayudarán a crear una confusión más ordenada.

Lista de fuentes

Fuentes oficiales

Fuentes de la comunidad que usé para entender las dificultades reales