luismori.

AI Coding Workflows

Spec Kit Spec-Driven Development AI Coding

Usar GitHub Spec Kit para investigar alternativas antes de construir

Una guía práctica para ingenieros y PMs que quieren usar GitHub Spec Kit como flujo de investigación: comparar alternativas, aprobar una dirección y convertir la decisión en una especificación de implementación más sólida.

20 min de lectura Actualizado el 12 jun 2026

TL;DR

  • GitHub Spec Kit no solo es útil cuando ya sabes qué construir. También puede ayudarte a investigar qué opción vale la pena construir.
  • Trata el flujo inicial de Spec Kit como un embudo de decisión:
problem
  -> investigation brief
  -> alternatives
  -> decision matrix
  -> approved direction
  -> hardened spec
  -> implementation plan
  • Usa /speckit.specify para registrar el problema y los criterios de éxito, /speckit.clarify para identificar las incógnitas y /speckit.plan para comparar enfoques de implementación antes de escribir código de producción.
  • Pídele al asistente de IA alternativas explícitas, los trade-offs esperados, experimentos de validación y una respuesta a «¿qué demostraría que esto es incorrecto?».
  • No apruebes una alternativa solo porque suena elegante. Apruébala cuando la especificación explique:
    • por qué gana esta opción
    • qué opciones descarta
    • qué debe verificarse
    • qué riesgos quedan
    • qué restricciones de implementación ya no son negociables
  • El resultado más sólido no es solo una especificación más bonita. Es una especificación que incluye un registro de la decisión.

Qué aprenderás aquí

Al terminar este artículo, deberías poder:

  • usar GitHub Spec Kit como un flujo de investigación, no solo como un flujo de implementación
  • estructurar prompts que le pidan a un agente de IA investigar alternativas
  • reconocer los resultados esperados en cada etapa
  • aprobar una alternativa sin perder el contexto de las opciones descartadas
  • convertir la opción aprobada en una especificación de implementación más sólida
  • explicar el flujo tanto a ingenieros como a PMs

Este artículo está dirigido a equipos que ya conocen las dificultades de la entrega de software asistida por IA:

  • las ideas avanzan más rápido que el entendimiento compartido
  • los agentes producen código antes de que los requisitos sean estables
  • los PMs necesitan comparar opciones de producto sin leer un diff enorme
  • los ingenieros necesitan comparar opciones de arquitectura sin convertir cada idea en una rama

Revisión de fuentes

Volví a revisar este artículo el June 12, 2026 frente a los materiales públicos vigentes de GitHub Spec Kit y herramientas relacionadas basadas en especificaciones.

Estos puntos están respaldados por las fuentes:

  • Spec Kit es un toolkit de código abierto de GitHub para el desarrollo basado en especificaciones.
  • El flujo oficial gira en torno a especificaciones, planes, tareas e implementación.
  • Spec Kit inicializa plantillas locales al proyecto y archivos de comandos específicos para cada asistente.
  • GitHub presenta Spec Kit como una forma de hacer que las especificaciones sean lo bastante ejecutables para orientar la implementación asistida por IA.
  • Kiro y Tessl son puntos de comparación útiles porque también organizan el trabajo de software en torno a especificaciones, requisitos, diseño, tareas y validación.

Los puntos que reflejan mi criterio son mi propia síntesis:

  • usar Spec Kit como un embudo de investigación
  • agregar un paso explícito de aprobación de alternativas
  • tratar la alternativa aprobada como un registro de decisión que fortalece la especificación de implementación
  • usar experimentos ligeros antes de aprobar la implementación

El problema: los agentes de IA acortan la distancia equivocada

Los agentes de programación con IA son muy buenos para acortar la distancia entre:

prompt -> code

Eso es útil, pero no siempre es la distancia que tu equipo necesita acortar.

En el trabajo real de producto e ingeniería, la distancia más costosa suele ser:

unclear problem -> evaluated options -> defensible decision

Si te saltas ese paso, el agente aún puede producir código. Incluso puede producir buen código. Pero el equipo no ha respondido las preguntas que tienen mayor impacto:

  • ¿Estamos resolviendo la versión correcta del problema?
  • ¿Qué alternativas descartamos?
  • ¿Qué restricciones importan más?
  • ¿Qué podría hacer que este enfoque falle?
  • ¿Qué debería ser cierto antes de comenzar la implementación?

Ahí es donde GitHub Spec Kit se vuelve más interesante que una simple estructura inicial para implementar. Te da un espacio recurrente para bajar el ritmo antes de escribir código, sin convertir la planificación en una ceremonia pesada.

El modelo mental simple

Spec Kit suele presentarse como un camino desde la idea hasta la implementación:

constitution
  -> spec
  -> clarify
  -> plan
  -> tasks
  -> implement

Para el trabajo de investigación, me gusta ampliar la parte intermedia:

constitution
  -> investigation spec
  -> clarification questions
  -> alternative plans
  -> decision approval
  -> final implementation spec
  -> tasks
  -> implementation

El cambio importante es este:

la primera especificación puede ser un documento breve de investigación.

No tiene que fingir que el equipo ya conoce la respuesta. De hecho, las especificaciones de investigación más sólidas dicen lo contrario:

Conocemos el resultado deseado. Todavía no conocemos la mejor forma de implementarlo.

Esa frase es saludable. Le indica al agente que investigue en vez de fingir certeza.

Cuándo usar Spec Kit para investigar

Usa este flujo cuando el costo de elegir mal sea mayor que el de hacer una ronda adicional de planificación.

Buenos casos de uso:

  • reemplazar una dependencia de un servicio central
  • elegir entre construir o comprar
  • rediseñar un modelo de datos
  • agregar una capa de autenticación o permisos
  • planificar la migración de una funcionalidad heredada
  • decidir entre varios frameworks de agentes
  • incorporar un nuevo componente de infraestructura
  • elegir un flujo de producto que cambie el comportamiento de los usuarios

Casos poco adecuados:

  • cambios mínimos en el texto de la interfaz
  • correcciones de bugs evidentes
  • adiciones CRUD de bajo riesgo
  • tareas para las que el equipo ya tiene un patrón estándar

Spec Kit es útil cuando la ambigüedad es real. Si la respuesta es obvia, no agregues ceremonias por razones estéticas.

El embudo de investigación

Este es el flujo que recomiendo.

+----------------------+
| 1. Frame the problem |
+----------+-----------+
           |
           v
+----------------------+
| 2. Generate options  |
+----------+-----------+
           |
           v
+----------------------+
| 3. Compare tradeoffs |
+----------+-----------+
           |
           v
+----------------------+
| 4. Validate quickly  |
+----------+-----------+
           |
           v
+----------------------+
| 5. Approve one path  |
+----------+-----------+
           |
           v
+----------------------+
| 6. Harden the spec   |
+----------+-----------+
           |
           v
+----------------------+
| 7. Plan and build    |
+----------------------+

La principal diferencia frente a una conversación normal con una IA es que cada etapa debería producir un artefacto que el equipo pueda revisar.

Paso 1: comienza con una especificación de investigación

En lugar de pedir:

Build a notification preference system.

Comienza con:

/speckit.specify

We need to design a notification preference system for a B2B SaaS app.

Goal:
- users can control which events notify them by email, in-app, or Slack
- workspace admins can set defaults for new members
- compliance events must remain non-optional

Investigation request:
- compare at least three implementation alternatives
- include schema impact, product flexibility, migration cost, and operational risk
- do not choose an implementation yet
- produce a spec that captures the problem, user outcomes, constraints,
  open questions, and evaluation criteria

Context:
- existing app uses Postgres
- events are already published to an internal queue
- product expects more notification channels next quarter
- team wants to avoid a hard-coded matrix of event types

Resultado esperado:

  • una carpeta de la funcionalidad para la rama actual
  • un archivo spec.md
  • historias de usuario o escenarios
  • requisitos funcionales
  • criterios de éxito
  • supuestos y preguntas abiertas
  • contexto suficiente para generar alternativas más adelante

Qué debes verificar:

  • ¿La especificación separa el problema del usuario de la solución de implementación que se supone?
  • ¿Los criterios de éxito son medibles?
  • ¿Las restricciones son explícitas?
  • ¿Las preguntas sin resolver están visibles en lugar de ocultas?

Si la primera especificación ya elige una solución, cuestiona esa elección.

Revise this spec so it remains implementation-neutral.
Keep the desired outcomes and constraints, but remove solution commitments.
Add an "Alternatives to investigate" section with placeholders only.

Paso 2: usa la clarificación para identificar los elementos de la decisión

Ejecuta el paso de clarificación antes de pedir opciones de arquitectura.

/speckit.clarify

Focus on questions that affect the choice between alternatives.
Group them by:
- product behavior
- data model
- migration
- security and compliance
- operational ownership
- future extension

Resultado esperado:

  • una lista de preguntas importantes sin responder
  • respuestas o supuestos sugeridos
  • texto actualizado en la especificación que haga visible la ambigüedad

Las buenas preguntas de clarificación suenan así:

  • ¿Los administradores del espacio de trabajo pueden imponer un canal o solo establecer valores predeterminados?
  • ¿Existe una obligación legal de entregar las notificaciones de cumplimiento o solo de intentar entregarlas?
  • ¿Necesitamos horarios de silencio por usuario?
  • ¿Las preferencias de notificación deben aplicarse de forma retroactiva a las notificaciones programadas?
  • ¿Cuántos tipos de eventos existen hoy y quién es responsable de agregar nuevos?

Las preguntas de clarificación poco útiles suenan así:

  • ¿La interfaz debería ser agradable?
  • ¿El sistema debería ser escalable?
  • ¿Deberíamos usar una base de datos?

Son demasiado genéricas. Las buenas preguntas pueden cambiar la decisión.

Paso 3: pide alternativas explícitamente

Ahora pídele al asistente que genere distintas opciones de implementación.

/speckit.plan

Before producing the final implementation plan, investigate three alternatives:

Alternative A:
- normalized relational model for users, channels, event types, and preferences

Alternative B:
- JSONB policy document per user or workspace

Alternative C:
- rules engine / policy evaluation layer with event metadata

For each alternative, produce:
- short architecture summary
- data model sketch
- example read path and write path
- migration strategy
- product flexibility
- operational complexity
- testing burden
- failure modes
- when this option is the wrong choice

End with a decision matrix and a recommendation, but do not create tasks yet.

Resultado esperado:

  • un archivo plan.md o un artefacto similar a un plan
  • bocetos de arquitectura
  • análisis de trade-offs
  • dirección recomendada
  • incógnitas técnicas
  • pasos de validación

La instrucción clave es «todavía no crees tareas».

Todavía estás decidiendo. Generar tareas demasiado pronto crea una falsa sensación de avance.

Paso 4: exige una matriz de decisión

Las comparaciones en formato libre son fáciles de leer y fáciles de olvidar. Una matriz de decisión obliga a presentar los trade-offs de una forma que los PMs y los ingenieros puedan discutir juntos.

Ejemplo de prompt:

Create a decision matrix with scores from 1 to 5.

Criteria:
- user experience flexibility
- admin control
- implementation simplicity
- migration safety
- reporting/queryability
- future channel support
- operational risk
- testability

Add one paragraph below the table explaining where the scoring is uncertain.

Resultado esperado:

Criteria                    | Relational | JSONB Policy | Rules Engine
----------------------------|------------|--------------|-------------
UX flexibility              | 4          | 3            | 5
Admin control               | 4          | 3            | 5
Implementation simplicity   | 4          | 5            | 2
Migration safety            | 4          | 3            | 2
Reporting/queryability      | 5          | 2            | 3
Future channel support      | 4          | 3            | 5
Operational risk            | 4          | 3            | 2
Testability                 | 4          | 3            | 3

Las puntuaciones exactas importan menos que la discusión que generan.

Una buena matriz debería hacer que alguien del equipo diga:

No estoy de acuerdo con esta puntuación.

Eso no es un fallo. Es señal de que el proceso funciona.

Paso 5: pide experimentos de validación

Antes de aprobar una alternativa, pregunta qué se puede probar rápidamente.

For the recommended alternative, propose validation experiments that can be
completed before implementation.

Include:
- one code spike
- one schema/query experiment
- one product review artifact
- one risk we cannot validate cheaply

Keep each experiment under half a day.

Resultado esperado:

  • una idea para un prototipo o script pequeño
  • un benchmark de consultas o una prueba de esquema
  • un wireframe o una revisión de escenarios de producto
  • un riesgo identificado que aún no se ha despejado

Ejemplo de plan de validación:

Experiment 1: Query shape
- Create sample tables for event_types, notification_channels, and preferences.
- Seed 50 event types, 5 channels, 10k users.
- Verify the read path can resolve preferences for one user and one event in one query.

Experiment 2: Admin default behavior
- Write three acceptance scenarios:
  1. new user inherits workspace defaults
  2. user override wins over default
  3. compliance event cannot be disabled

Experiment 3: Product review
- Review preference grouping with PM and design.
- Confirm whether users think in event categories or individual events.

Este paso evita que la investigación se convierta en teatro.

Paso 6: aprueba una alternativa

El momento de la aprobación debe ser explícito. No dejes que el plan final elija en silencio.

Usa un prompt como este:

We approve Alternative A: normalized relational model.

Update the spec and plan to record:
- why this option was approved
- which alternatives were rejected
- what trade-offs we accept
- which assumptions are now locked
- which risks require monitoring during implementation

Then rewrite the implementation spec so it is specific enough for task generation.

Resultado esperado:

  • una sección con la recomendación final
  • alternativas descartadas
  • trade-offs aceptados
  • restricciones de implementación
  • requisitos funcionales actualizados
  • requisitos no funcionales actualizados
  • criterios de aceptación más claros

La especificación aprobada ahora debería sonar distinta de la especificación de investigación.

Antes:

The system should support notification preferences across channels.

Después:

The system must store notification preferences in normalized relational tables:
event_types, notification_channels, workspace_notification_defaults, and
user_notification_preferences. User overrides must take precedence over
workspace defaults, except for compliance events marked as non-optional.

Esa diferencia importa. La primera versión le dice al agente qué quiere el producto. La segunda le dice qué decidió el equipo.

Paso 7: genera tareas solo después de la aprobación

Ahora el prompt para generar tareas tiene una base sólida.

/speckit.tasks

Generate implementation tasks from the approved relational-model spec.

Group tasks by:
- database migration
- domain model
- preference resolution service
- API endpoints
- admin defaults
- user settings UI
- compliance event enforcement
- tests
- migration and rollout

Mark tasks that can run in parallel.

Resultado esperado:

  • tareas ordenadas
  • una secuencia que tenga en cuenta las dependencias
  • tareas de prueba
  • tareas de migración
  • partes de la implementación que puedan revisarse

Las buenas tareas deben ser lo bastante pequeñas para que un ingeniero o agente de IA pueda completarlas sin reabrir todo el debate de producto.

Qué contiene una especificación final sólida

Después de la investigación, la especificación final debería incluir estas secciones:

  • Planteamiento del problema
  • Usuarios y partes interesadas
  • Criterios de éxito
  • Alcance y exclusiones
  • Enfoque aprobado
  • Alternativas descartadas
  • Resumen de la matriz de decisión
  • Supuestos
  • Requisitos funcionales
  • Requisitos no funcionales
  • Modelo de datos
  • Escenarios de aceptación
  • Plan de migración
  • Riesgos y mitigaciones
  • Lista de verificación de validación

Aquí tienes un esquema compacto que puedes pedirle a Spec Kit que genere:

Rewrite the spec using this structure:

1. Problem
2. Goals
3. Non-goals
4. Users and stakeholders
5. Approved approach
6. Rejected alternatives
7. Functional requirements
8. Non-functional requirements
9. Data model
10. Acceptance scenarios
11. Migration and rollout
12. Risks
13. Validation checklist

Keep the language precise enough for implementation.
Remove speculative options from the requirements, but keep them in
"Rejected alternatives" with short rationale.

Un conjunto de prompts reutilizables

Aquí tienes un conjunto práctico de prompts que puedes adaptar.

1. Documento breve de investigación

/speckit.specify

Create an investigation spec for [problem].

We know:
- [context]
- [constraints]
- [desired outcomes]

We do not yet know:
- [decision to make]

The spec must stay implementation-neutral.
Include success criteria, non-goals, open questions, and evaluation criteria.

2. Clarificar la decisión

/speckit.clarify

Ask only questions that could change the implementation choice.
Group them by product, technical, data, security, migration, and operations.
For each question, explain why the answer matters.

3. Generar alternativas

/speckit.plan

Investigate at least three implementation alternatives.
For each one, include:
- architecture
- data model
- integration points
- test strategy
- migration path
- risks
- when not to use it

End with a decision matrix and recommendation.
Do not generate implementation tasks.

4. Cuestionar la recomendación

Before we approve this recommendation, argue against it.

What assumptions would make it wrong?
What hidden costs are easy to underestimate?
What would a senior engineer object to?
What would a PM object to?
What should we validate before committing?

5. Aprobar la dirección

We approve [alternative].

Update the spec and plan:
- record the decision
- summarize rejected alternatives
- lock the implementation constraints
- preserve remaining risks
- rewrite acceptance criteria so they match the approved approach

6. Generar tareas de implementación

/speckit.tasks

Generate tasks from the approved spec only.
Do not reopen rejected alternatives unless a task depends on an unresolved risk.
Group tasks by dependency and mark parallelizable work.

Ejemplo: construir o comprar para feature flags

Imagina que un equipo está decidiendo si construir un sistema interno ligero de feature flags o adoptar una plataforma externa.

Prompt de investigación:

/speckit.specify

Create an investigation spec for feature flag management.

Context:
- B2B SaaS product
- 30 engineers
- weekly releases
- current flags are environment variables
- PMs want controlled beta rollouts
- compliance team wants audit history

Investigate:
- build a simple internal flag service
- adopt a managed feature flag platform
- use database-backed flags inside the existing admin app

Success criteria:
- reduce risky releases
- allow targeted rollout by workspace
- preserve audit history
- avoid blocking releases on engineering-only changes

Stay implementation-neutral until alternatives are compared.

Resumen esperado de la decisión final:

Approved approach:
Use a managed feature flag platform for rollout targeting, audit history,
and non-engineering control.

Rejected:
- Internal service: lower vendor cost, but high hidden operational and audit burden.
- DB-backed admin flags: fast to start, but likely to become an incomplete
  feature flag platform without experimentation, SDKs, or evaluation caching.

Accepted trade-off:
The team accepts vendor dependency in exchange for faster safe rollout,
auditing, and PM-operable controls.

Ese resumen es valioso incluso antes de que comience la implementación. Les da a los PMs una decisión clara y a los ingenieros un límite claro.

Comparación con otras herramientas basadas en especificaciones

GitHub Spec Kit forma parte de un cambio más amplio hacia el desarrollo basado en especificaciones.

Kiro, por ejemplo, también pone énfasis en especificaciones con requisitos, diseño y tareas. Tessl organiza el desarrollo de software en torno a especificaciones y a la entrega de software nativa de IA. Esas herramientas pueden ofrecer entornos de producto más integrados, según tu flujo de trabajo.

Spec Kit es especialmente interesante cuando buscas:

  • un toolkit de código abierto
  • artefactos locales en el repositorio
  • archivos de comandos específicos para cada asistente
  • un flujo que encaje con las ramas de Git y la revisión de PRs
  • especificaciones que vivan cerca del código

El principal trade-off es que Spec Kit sigue siendo un toolkit, no un sistema completo de gestión de producto. Proporciona estructura, pero tu equipo sigue siendo responsable de la calidad de las preguntas, las decisiones y el proceso de aprobación.

Problemas comunes

Problema 1: la especificación elige demasiado pronto

Síntoma:

The spec says "use Redis Streams" before the team has compared queues.

Solución:

Revise this as an investigation spec.
Move Redis Streams into "Alternatives to investigate."
Keep requirements implementation-neutral until approval.

Problema 2: la matriz da una falsa precisión

Puntuar alternativas puede crear una ilusión de certeza.

Solución:

For every score in the decision matrix, add confidence:
- high
- medium
- low

Then list the three scores most likely to change after validation.

Problema 3: las alternativas descartadas desaparecen

Si la especificación final solo incluye la opción ganadora, los futuros lectores pierden el historial de la decisión.

Solución:

Add a "Rejected alternatives" section.
For each rejected option, include:
- why it was considered
- why it lost
- when we should reconsider it

Problema 4: las tareas reabren el debate

A veces, la generación de tareas vuelve a introducir opciones que el equipo ya descartó.

Solución:

Regenerate tasks using only the approved approach.
Rejected alternatives are context, not implementation options.

Una lista de verificación ligera para la aprobación

Antes de pasar de la investigación a las tareas, pregunta:

[ ] Is the user problem clear?
[ ] Are success criteria measurable?
[ ] Were at least two serious alternatives compared?
[ ] Are rejected alternatives recorded?
[ ] Is the approved approach explicit?
[ ] Are accepted trade-offs named?
[ ] Are implementation constraints clear?
[ ] Are remaining risks visible?
[ ] Is there a validation plan?
[ ] Would a new engineer understand why this path won?

Si no puedes marcar esas casillas, todavía no le pidas al agente que implemente.

La división entre producto e ingeniería

Este flujo funciona mejor cuando los PMs y los ingenieros revisan distintas partes de los mismos artefactos.

Los PMs deberían enfocarse en:

  • el planteamiento del problema
  • los escenarios de usuario
  • los criterios de éxito
  • lo que no se busca lograr
  • los criterios de aceptación
  • los trade-offs de producto

Los ingenieros deberían enfocarse en:

  • las decisiones de arquitectura
  • el riesgo de migración
  • el modelo de datos
  • el comportamiento operativo
  • las implicaciones de seguridad
  • la estrategia de pruebas

El artefacto compartido es la especificación. La decisión compartida es la alternativa aprobada.

Ese es el beneficio real: todos revisan la misma historia desde distintos ángulos antes de que exista el código.

Dónde Spec Kit sigue necesitando criterio humano

Spec Kit puede organizar la investigación, pero no puede garantizar que el equipo esté haciendo las preguntas correctas.

Sigues necesitando personas que decidan:

  • qué restricciones son reales
  • qué riesgos son inaceptables
  • cuándo un trade-off de producto justifica la complejidad de ingeniería
  • cuándo la recomendación parece demasiado conveniente
  • cuándo es necesario un prototipo
  • cuándo dejar de analizar y construir

La versión más saludable de este flujo no es «la IA decide». Es:

AI structures the decision.
Humans approve the decision.
AI helps execute the approved decision.

Conclusión

Es fácil subestimar GitHub Spec Kit si lo tratas como una simple capa de comandos para la implementación con IA.

Un mejor uso es más estratégico:

haz que el agente te ayude a pensar antes de pedirle que te ayude a programar.

Usa la primera especificación como un documento breve de investigación. Usa la clarificación para identificar los elementos de la decisión. Usa la planificación para comparar alternativas. Usa la aprobación para fijar una dirección. Luego, aborda las tareas y la implementación con mucha más confianza.

Esa pequeña pausa puede ahorrarte días de implementar impecablemente algo equivocado.

Lista de fuentes