luismori.

AI Coding Workflows

Spec Kit Spec-Driven Development AI Agents

La parte humana de GitHub Spec Kit: cómo hablar con los agentes entre comandos

Spec Kit puede generar los artefactos, pero las personas aún deben hacer explícitas las suposiciones, asumir las decisiones, propagar los cambios, establecer condiciones de parada y decidir qué evidencia es suficiente.

29 min de lectura

GitHub Spec Kit le da a un agente de programación con IA una secuencia disciplinada: especificar, aclarar, planificar, crear tareas, analizar, implementar y verificar la convergencia.

Pero la secuencia no elimina a la persona del diseño de software. Cambia su función.

El agente puede escribir un spec.md, un plan.md y un tasks.md convincentes. También puede llenar vacíos con valores predeterminados razonables, inferir vínculos entre requisitos y tareas, recomendar una arquitectura y marcar como completo el trabajo de implementación. Esos resultados pueden ser útiles sin estar aprobados, respaldados por evidencia o ser correctos.

La parte humana consiste en hacer visible el criterio que está oculto:

  • ¿Qué afirmaciones son evidencia, suposiciones o decisiones?
  • ¿Quién es responsable de cada decisión importante?
  • ¿Qué artefactos deben cambiar cuando cambia una respuesta?
  • ¿Qué condiciones deben cumplirse antes de ejecutar el siguiente comando?
  • ¿Qué evidencia es suficiente para aceptar la implementación?

Este no es un artículo sobre cómo crear otra skill, preset o extensión de Spec Kit. Es una guía práctica para la conversación alrededor de los comandos integrados: qué preguntar antes de avanzar, cuándo detenerse y cómo evitar que una aclaración deje otros tres artefactos desactualizados.

TL;DR

  • Trata cada resultado de un comando de Spec Kit como una propuesta para revisión, no como una aprobación.
  • Después de /speckit.specify, revisa las suposiciones y los valores predeterminados, no solo los marcadores de aclaración evidentes.
  • Ejecuta /speckit.clarify por categoría de alto impacto. Responder cinco preguntas no significa necesariamente que la funcionalidad esté lista.
  • Después de /speckit.plan, pregunta si la investigación o el diseño cambiaron alguna historia de usuario, caso límite, criterio de aceptación o suposición. Actualiza la especificación antes de generar tareas.
  • Antes de /speckit.tasks, declara explícitamente la política de pruebas. La plantilla principal de tareas actual indica que las pruebas son opcionales, a menos que la especificación o el usuario las soliciten.
  • /speckit.analyze es de solo lectura. «Analizar y resolver» es un ciclo: analizar, decidir, editar el artefacto correspondiente, regenerar los artefactos derivados y volver a analizar.
  • Una carpeta decisions/ puede ser una convención útil del equipo, pero el artefacto de planificación oficial es research.md, que registra decisiones, justificaciones y alternativas.
  • Durante la implementación, detente cuando la evidencia del código contradiga un artefacto aprobado. Clasifica la discrepancia antes de cambiar nada.
  • Una tarea marcada como completada es evidencia de avance, no de aceptación. Exige el mapeo de requisitos, la salida de los comandos, los resultados de las pruebas, las desviaciones y el riesgo restante.
  • A partir de GitHub Spec Kit v0.15.1, publicado el July 31, 2026, /speckit.converge es el comando posterior a la implementación para comparar el código con la especificación, el plan y las tareas, y agregar el trabajo pendiente.

Qué aprenderás aquí

  • Qué decisiones siguen dependiendo del criterio humano en cada fase de Spec Kit
  • Cómo mejorar los prompts que ya usas después de specify, plan, tasks, analyze e implement
  • Cómo priorizar la incertidumbre por impacto en lugar de hacer preguntas de aclaración al azar
  • Cómo distinguir la investigación del agente de la aprobación humana
  • Cuándo una aclaración debe obligar a cambiar la especificación, el plan, las tareas, los contratos, las pruebas o el código
  • Cómo usar subagentes para obtener evidencia sin delegar la responsabilidad de las decisiones
  • Una secuencia reutilizable de prompts para preparación, implementación y validación

El modelo central: los comandos transforman artefactos; las personas controlan los puntos de decisión

La referencia oficial de Spec Kit describe un flujo de trabajo basado en agentes:

/speckit.constitution
  -> /speckit.specify
  -> /speckit.clarify
  -> /speckit.plan
  -> /speckit.checklist
  -> /speckit.tasks
  -> /speckit.analyze
  -> /speckit.implement
  -> /speckit.converge

En la referencia oficial, clarify, checklist y analyze son puntos de control de calidad opcionales para trabajos con ambigüedad significativa; el diagrama muestra un camino orientado a producción, no una secuencia obligatoria para cada cambio.

Ese es el recorrido de los comandos. El ciclo de control humano es diferente:

generate
  -> expose evidence, assumptions, and unknowns
  -> assign decision ownership
  -> approve or reject tradeoffs
  -> propagate changes through affected artifacts
  -> challenge the result
  -> approve one bounded next action
  -> execute
  -> inspect validation evidence

El segundo ciclo es lo que evita que una cadena de artefactos bien presentados se convierta en una cadena de errores heredados.

La distinción importa porque el comportamiento actual de Spec Kit incorpora deliberadamente el criterio del modelo:

  • specify puede usar valores predeterminados fundamentados y registrar suposiciones.
  • clarify hace hasta cinco preguntas por sesión, priorizadas por impacto e incertidumbre.
  • plan convierte las incógnitas técnicas en tareas de investigación y registra decisiones, justificaciones y alternativas.
  • tasks infiere el trabajo de implementación y solo incluye tareas de pruebas cuando se solicitan.
  • analyze estima la cobertura de requisitos por tareas mediante referencias explícitas, palabras clave y frases clave, y no edita archivos.
  • implement ejecuta tareas y actualiza las casillas de verificación.
  • converge compara la implementación con los artefactos y agrega el trabajo pendiente a tasks.md.

Estas son decisiones de automatización útiles. Ninguna de ellas determina si una concesión de producto es aceptable, si una decisión de arquitectura está autorizada o si un resultado de pruebas es suficiente para tu nivel de riesgo.

Las cinco responsabilidades humanas aparecen en cada etapa:

FaseCriterio ocultoControl humano
Constitución¿Qué reglas son realmente innegociables?Asumir la responsabilidad de los principios rectores y aprobarlos
Specify¿Qué valores predeterminados se convirtieron en requisitos?Exponer suposiciones e incógnitas
Clarify¿Qué respuesta representa la intención de producto o de política?Aprobar las respuestas con consecuencias importantes
Plan¿Qué evidencia y qué concesiones justifican el diseño?Asumir la responsabilidad de las decisiones de arquitectura y riesgo
Checklist y tareas¿Qué trabajo y qué pruebas son obligatorios?Propagar el alcance aprobado hasta convertirlo en trabajo ejecutable
Analyze¿Una relación inferida refleja la realidad?Verificar los hallazgos y dirigirlos a la fase correspondiente
Implement y converge¿El trabajo completado satisface la intención aceptada?Verificar la evidencia y aceptar o rechazar el riesgo residual

Ajusta el rigor al alcance del impacto

No todas las funcionalidades necesitan aprobadores designados, un registro de decisión y un registro de evidencia para cada elección. Eso reemplazaría el criterio oculto por una simulación de aprobación.

RiesgoControl humano apropiado
Bajo: herramienta interna reversible, prototipo, cambio aislado de textoDelegación respaldada por políticas, verificaciones automatizadas, revisión breve de suposiciones
Medio: comportamiento visible para el usuario, componente compartido, cambio recuperable de datosRevisión humana de suposiciones de alto impacto, concesiones del plan y evidencia de validación
Alto: autorización, dinero, datos personales, cumplimiento normativo, migración irreversible, plataforma compartidaResponsable designado, decisión registrada, condiciones de parada explícitas, evidencia independiente, revisión del despliegue y la reversión

El objetivo no es maximizar la formalidad. Es dedicar suficiente atención humana en función del costo de equivocarse.

/speckit.constitution: las personas son responsables de las reglas rectoras

La constitución se evalúa en las fases posteriores, por lo que un principio incorporado por accidente puede distorsionar todos los artefactos que siguen. Las personas deben decidir:

  • qué reglas son duraderas y se aplican a todo el proyecto
  • quién puede aprobarlas o modificarlas
  • qué reglas son obligatorias y cuáles son preferibles
  • si un hallazgo sobre una funcionalidad pertenece a sus artefactos o modifica una regla invariable de todo el proyecto

Usa:

Before updating the constitution:
- cite the project evidence for each proposed principle
- separate durable invariants from feature-specific decisions
- identify who can approve each MUST rule
- show which templates or active features the amendment may affect

Recommend changes, but do not treat them as approved until the named owner confirms.

Antes de cada comando: establece la superficie de control

Antes de hablar de prompts específicos para cada fase, deja claras cuatro cosas.

1. Confirma la funcionalidad activa

En v0.15.1, los scripts posteriores usan SPECIFY_FEATURE_DIRECTORY cuando está definido; de lo contrario, leen el directorio de la funcionalidad desde .specify/feature.json. Cambiar a otra rama de Git por sí solo no cambia la funcionalidad activa.

Eso significa que cambiar de rama no es una forma confiable de cambiar el contexto de los comandos.

Usa esta breve comprobación previa:

Before continuing, report:
- the active feature directory
- the artifacts this command will read
- the artifacts this command may write
- the current git branch as separate context

Stop if the active feature is not the feature we are discussing.

2. Identifica el origen de cada afirmación importante

Los agentes suelen convertir la información faltante en prosa fluida. Haz que la procedencia forme parte de la conversación:

Before editing any artifact, classify each material statement as:
- Confirmed repository evidence — cite path, symbol, test, or command output
- External evidence — cite the primary source and date
- Human decision — name the owner and decision date
- Assumption — state the impact if wrong
- Unknown — state what evidence or decision is needed

Do not convert absence of evidence into a confirmed requirement.

No necesitas esta etiqueta en cada oración. Úsala para afirmaciones que puedan cambiar el comportamiento, la arquitectura, la seguridad, las operaciones, el costo o la aceptación.

3. Designa responsables de las decisiones

Un agente puede recomendar un límite de autenticación. No puede aceptar el riesgo en nombre de la persona responsable de seguridad. Puede ordenar las opciones de producto. No puede decidir qué comportamiento de los clientes quiere el negocio.

Para las decisiones importantes, solicita:

- decision category: product, architecture, security, operations, or delivery
- accountable human owner
- options considered
- evidence for the recommendation
- consequence of delaying the decision
- artifacts affected

4. Establece una condición de parada antes de comenzar

«Continúa hasta terminar» es peligroso cuando no se ha definido qué significa «terminar».

Ejemplos de condiciones de parada útiles:

  • detente después de enumerar las incertidumbres; no edites nada
  • detente ante cualquier decisión no resuelta sobre seguridad o retención de datos
  • detente antes de generar tareas si la planificación cambia el comportamiento visible para el usuario
  • implementa solo las tareas T001-T006
  • detente si la evidencia en tiempo de ejecución contradice plan.md
  • no continúes mientras quede algún hallazgo crítico de analyze sin resolver

Después de /speckit.specify: encuentra la incertidumbre oculta

Una buena acción después de specify es seguir enumerando las incertidumbres y aclararlas según su impacto.

La mejora consiste en revisar tanto los vacíos explícitos como los valores predeterminados elegidos sin indicarlo. La ausencia de un marcador de aclaración no demuestra que una persona haya proporcionado el requisito.

Usa esto:

Do not edit yet.

Re-scan spec.md and list unresolved judgment by impact:
1. Blocker
2. High
3. Medium
4. Low

Group findings by:
- scope and non-goals
- actors and permissions
- data and lifecycle
- security, privacy, and compliance
- UX and edge cases
- reliability and operations
- success and validation

Include both explicit clarification markers and defaults recorded as assumptions.
For each item, name:
- why it matters
- the evidence needed
- the likely decision owner
- the artifacts it could affect

Ask which category I want to clarify first.

Esto produce un inventario de incertidumbres en lugar de una lista plana de preguntas.

Después, aclara una categoría a la vez:

/speckit.clarify Focus only on [category].

Ask one decision question at a time.
After each answer, report:
- the spec sections changed
- the assumption replaced
- affected user stories or edge cases
- whether the answer may change plan.md or tasks.md

At session end, list deferred and outstanding categories by impact.

El flujo oficial de clarify está limitado intencionalmente a cinco preguntas por sesión y puede ejecutarse varias veces. La decisión humana no es «¿terminó clarify?». Es «¿se pueden llevar las incógnitas restantes a la planificación sin correr riesgos inaceptables?».

Un punto de decisión útil para las recomendaciones

Antes de planificar, pregunta:

Recommend whether this spec is ready for technical planning.

Return:
- ready / ready with accepted assumptions / not ready
- unresolved blockers and high-impact unknowns
- assumptions we explicitly accept for planning
- product decisions still awaiting an owner
- user stories that are independently testable
- measurable success criteria that remain weak

This is an agent recommendation. Name the human owner who records the decision.
Do not run /speckit.plan.

Después de /speckit.plan: verifica si el diseño cambió el problema

Resumir el plan y preguntar si cambiaron las suposiciones, los casos límite o las historias de usuario es una de las pausas de mayor valor en el flujo de trabajo.

La planificación revela cosas. Una limitación de una API puede cambiar la UX. Una regla de retención de datos puede eliminar una historia de usuario. Una restricción de migración puede crear un nuevo estado de error. Si esos hallazgos solo quedan en research.md o plan.md, la cadena de artefactos ya ha perdido coherencia.

Usa un resumen breve:

After /speckit.plan, give a maximum 10-bullet summary covering:
- selected approach
- binding constraints
- important assumptions
- rejected alternatives
- data and interface changes
- test and validation strategy
- operational risks
- unresolved evidence gaps

Then answer:
Did planning change any assumption, edge case, acceptance criterion,
success criterion, or user story?

If yes, stop before tasks and propose the required spec reconciliation.

Luego ejecuta una revisión adversarial:

Review this plan as a skeptical architect who must operate and roll it back.

Find:
- the strongest counterargument to the selected approach
- irreversible or expensive choices
- unsupported research conclusions
- missing failure and recovery behavior
- security and permission boundary failures
- scale assumptions without evidence
- simpler rejected alternatives worth reconsidering

Do not edit.
Separate facts, inferences, and recommendations.

Este es un mejor uso de un agente que preguntar: «¿El plan es bueno?». La segunda pregunta invita a estar de acuerdo. La primera le da al modelo una tarea de refutación.

Dónde van las decisiones

El flujo principal de plan crea research.md con:

  • Decisión
  • Justificación
  • Alternativas consideradas

Si tu equipo ya usa specs/<feature>/decisions/, sigue usándolo para decisiones duraderas que puedan revisarse individualmente. Pero descríbelo con honestidad como una convención del equipo, no como un requisito integrado de Spec Kit.

Una instrucción práctica es:

For each material planning decision, record:
- context
- options considered
- decision
- accountable owner and approval date
- evidence
- consequences
- affected artifacts
- superseded decision, if any

Use research.md for normal planning decisions.
Use specs/<feature>/decisions/ only when this project convention exists
or the decision needs an independently reviewable record.

Los subagentes pueden recopilar evidencia y comparar opciones. La persona responsable sigue siendo quien aprueba la elección.

Después de /speckit.checklist: revisa la prueba de los requisitos

Spec Kit describe los checklists como «pruebas unitarias para los requisitos». La analogía es útil, pero un checklist generado también contiene decisiones de criterio: qué dimensiones importan, qué tan estricto es cada elemento y si una excepción es aceptable.

Pregunta:

Review this checklist before treating it as a gate.

Report:
- which risk or requirement each item protects
- important dimensions the checklist does not cover
- items that are subjective or not independently verifiable
- exceptions requested, with owner and rationale
- spec sections that must change for failed items

Recommend pass, conditional pass, or fail.
A human owner records any exception and the gate decision.

Un checklist marcado como completado significa que sus preguntas se respondieron con base en el artefacto. No aprueba el comportamiento del producto ni demuestra que la implementación sea correcta.

Antes de /speckit.tasks: haz explícita la política de trabajo

No ejecutes tasks sin declarar la política de pruebas. El comando de tareas de v0.15.1 indica que las pruebas son opcionales y solo se generan cuando la especificación de la funcionalidad o el usuario las solicita explícitamente.

Por eso es importante esta comprobación previa:

Before generating tasks, restate:
- approved user-story scope and priority
- explicitly deferred scope
- required test policy
- migration work
- rollout and rollback work
- documentation and observability work
- accepted architecture decisions

Stop if any of these conflict with spec.md or plan.md.

Después:

/speckit.tasks

In tasks.md:
- reference the relevant user story, requirement, or success criterion
- give each user story an observable verifier
- include required test tasks
- include migration, rollout, rollback, documentation, and validation tasks
  where the approved plan requires them
- flag file paths and [P] markers that still require human confirmation
- do not introduce behavior absent from the approved spec

Spec Kit ya organiza las tareas por historia de usuario y marca el trabajo paralelo. La revisión humana debe cuestionar las dependencias semánticas que la estructura de archivos no puede demostrar:

  • ¿Realmente pueden ejecutarse estas tareas en paralelo sobre el mismo esquema o interfaz?
  • ¿Una tarea «fundacional» oculta comportamiento del producto?
  • ¿Realmente puede demostrarse la historia de usuario indicada después de su fase?
  • ¿La lista de tareas omitió trabajo operativo porque no corresponde a un archivo de código?

/speckit.analyze: primero analiza, después resuelve

La frase «ejecuta /speckit.analyze y resuelve con registros de decisión y evidencia» contiene dos operaciones, no una.

El comando oficial analyze es estrictamente de solo lectura. Informa inconsistencias, ambigüedades, conflictos con la constitución y brechas de cobertura. Puede sugerir correcciones, pero requiere aprobación explícita antes de hacer ediciones posteriores.

Usa:

/speckit.analyze

Keep the review read-only.
For each CRITICAL or HIGH finding, include:
- concrete evidence
- owning artifact and owning phase
- human decision required, if any
- downstream artifacts affected
- recommended rerun sequence

Treat semantic requirement-to-task coverage as a hypothesis, not proof.
Do not remediate until I approve finding IDs.

Después, resuelve solo los hallazgos aprobados:

Resolve only approved findings: [IDs].

Group edits by owning artifact.
For each material decision, record:
- context
- options
- decision
- owner and date
- evidence
- consequences
- artifacts requiring reconciliation

Update the owning source first.
Regenerate or reconcile downstream artifacts in order.
Then rerun /speckit.analyze.

La regla de modificar la fuente correspondiente evita que tasks.md redefina silenciosamente la intención del producto. Un defecto de requisitos vuelve a specify o clarify. Un defecto de diseño vuelve a plan. Un defecto de descomposición vuelve a tasks.

Cuando una aclaración llega tarde: crea una matriz de impacto

La pregunta «¿Cómo afecta esta aclaración reciente a la especificación, el plan y las tareas, y necesito ejecutar analyze?» debería ser un prompt estándar de control de cambios.

Amplíala un poco:

Given this clarification: [decision]

Show its impact on:
- spec.md
- research.md
- plan.md
- data-model.md
- contracts/
- quickstart.md
- tasks.md
- tests
- current implementation

For every "no change," explain why.
Identify invalidated assumptions and decisions.
Recommend which phases must rerun and whether /speckit.analyze must rerun.
Do not edit or implement until I approve the propagation plan.

Usa esta regla de decisión:

CambioRespuesta mínima
Solo redacción; comportamiento sin cambiosActualizar el artefacto correspondiente; no volver a ejecutar automáticamente
Cambió un criterio de aceptación o un caso límiteActualizar la especificación, ajustar tareas y pruebas, volver a ejecutar analyze
Cambió la arquitectura, el modelo de datos, la interfaz o una restricción operativaActualizar los artefactos del plan, regenerar tareas, volver a ejecutar analyze
Nueva capacidad visible para el usuarioReabrir el alcance o crear una especificación de seguimiento
Un hallazgo de implementación contradice la intención aprobadaDetenerse, clasificar, obtener una decisión y luego actualizar los artefactos

No vuelvas a ejecutar todo de forma mecánica. Vuelve a ejecutar las fases cuyas entradas cambiaron, además de analyze cuando la coherencia entre artefactos pueda haber cambiado.

Mini ejemplo: una decisión tardía sobre autorización

Supongamos que el plan generado asume que cualquier miembro del espacio de trabajo puede exportar eventos de auditoría. Durante la revisión de seguridad, la persona responsable decide que solo los administradores del espacio de trabajo pueden exportarlos.

Agent assumption:
  Any authenticated workspace member may export.

Human decision:
  Only workspace administrators may export.

Propagation:
  spec.md        -> actor, requirement, acceptance and denial scenarios
  plan.md        -> authorization boundary and enforcement point
  contracts/     -> forbidden response for non-admin callers
  tasks.md       -> policy enforcement and negative-test tasks
  tests          -> admin success and member denial evidence

Rerun:
  tasks, then analyze

El agente puede proponer ese mapa de impacto. La persona responsable de seguridad o producto autoriza el comportamiento. Luego, la validación debe demostrar tanto los casos permitidos como los denegados.

Cómo usar subagentes sin delegar el criterio

«Ejecutar más subagentes» solo mejora los resultados cuando cada subagente tiene una tarea independiente de búsqueda de evidencia. Enviar la misma solicitud vaga a tres agentes puede producir tres opiniones correlacionadas.

Para una corrección:

Investigate [failure] with independent subagents:
- one reproduces the failure and gathers runtime evidence
- one traces the affected requirement, plan decision, and task
- one evaluates fix alternatives and regression risk

Subagents gather evidence; they do not approve requirement or architecture changes.
Consolidate agreements and disagreements.
Stop for the accountable human decision.
Record any material decision and reconcile affected artifacts before implementation.

Una buena independencia proviene de preguntas diferentes:

  • ¿Qué ocurrió? Reproducción y logs
  • ¿Qué debería haber ocurrido? Especificación y criterios de aceptación
  • ¿Por qué lo permitió el diseño? Plan, contratos y límites
  • ¿Cuáles son las opciones de corrección? Alternativas y consecuencias

La persona resuelve los conflictos entre esas perspectivas.

Antes y durante /speckit.implement: delimita el trabajo

No le entregues a la implementación una carpeta de artefactos sin límites claros esperando que el alcance se mantenga estable.

Usa un punto de control de preparación para la implementación:

Before implementation, report:
- active feature directory
- approved task IDs or phase
- checklist status and any requested override
- unresolved analyze findings
- expected files and tests
- human-owned decisions still open
- explicit stop conditions

Wait for approval in the form:
"Approve implementation of [task range or phase]."

Para funcionalidades más grandes, esto coincide con la guía oficial de delimitar la implementación por fase o rango de tareas y validar cada etapa antes de continuar.

Durante la implementación, usa un protocolo de desviaciones:

If implementation evidence conflicts with spec.md, plan.md, or tasks.md:
1. Stop after preserving the current safe state.
2. Classify it as:
   - code defect
   - plan discovery
   - requirement change
   - new scope
3. Cite the evidence.
4. List affected artifacts and tests.
5. Propose alternatives without silently choosing one.
6. Wait for the decision owner.

Esto evita que el código se convierta en la fuente de verdad simplemente porque existe.

Después de la implementación: exige evidencia y luego converge

Una casilla de tarea marcada significa que el agente cree que el trabajo se realizó. No demuestra que se haya satisfecho el requisito.

Solicita un registro de evidencia:

For each completed task, report:
- task ID
- requirement or acceptance criterion addressed
- changed files
- validation commands executed
- exit status and relevant output
- manual validation performed
- checks not run and why
- deviations from approved artifacts
- remaining risk

Do not use the [X] checkbox as acceptance evidence.

Luego usa /speckit.converge. En v0.15.1, este comando inspecciona rutas de código y conceptos derivados de la especificación, el plan y las tareas de la funcionalidad. Informa que no encontró brechas o agrega tareas trazables para trabajo faltante, parcial, contradictorio o no solicitado que requiera acción. Esto sigue siendo una evaluación generada por un agente, no una prueba formal de corrección. El ciclo es:

/speckit.implement
  -> inspect evidence
  -> /speckit.converge
     -> converged: human review and release checks
     -> tasks appended: inspect, approve, implement, and converge again

La convergencia tampoco es una autorización de lanzamiento. La revisión de seguridad, la preparación operativa, la aceptación de las partes interesadas y la aceptación del riesgo siguen siendo puntos de decisión humanos o del equipo.

Un resumen de preguntas y respuestas antes de la siguiente acción

Tu solicitud de resumir la especificación, el plan y las tareas como preguntas y respuestas es útil porque permite comprobar si el conjunto de artefactos cuenta una historia coherente.

Usa:

Recap the current spec, plan, and tasks as Q&A:

- What problem and outcome are approved?
- Who are the actors and decision owners?
- What is explicitly out of scope?
- Which assumptions remain?
- Which clarifications changed the original request?
- What architecture and alternatives were approved?
- What is the MVP and task order?
- How will each user story be validated?
- What risks or decisions remain?
- What is the next gate?

Cite the owning artifact section for each answer.
Flag contradictions instead of choosing one silently.

Las referencias son importantes. Sin ellas, el resumen puede convertirse en otra síntesis plausible desconectada de los archivos.

Un paquete compacto de prompts para la intervención humana

Si quieres la versión utilizable más breve, ten estos prompts a mano.

Después de specify

List remaining uncertainties by impact and category.
Include assumptions and inferred defaults, not only explicit markers.
Name the evidence, owner, and affected artifacts for each.
Do not edit yet.

Durante clarify

Focus on [category]. Ask one decision at a time.
After each answer, show changed assumptions, stories, edge cases,
acceptance criteria, and downstream impact.

Después de plan

Summarize the plan in 10 bullets maximum.
Did planning change any assumption, edge case, acceptance criterion,
success criterion, or user story?
If yes, stop before tasks and propose spec reconciliation.

Antes de tasks

Restate approved scope, deferred scope, test policy, migration,
rollout, rollback, documentation, observability, and accepted decisions.
Stop on conflicts before generating tasks.

Analizar y resolver

Run /speckit.analyze read-only.
For high-severity findings, cite evidence, owning artifact, decision owner,
affected artifacts, and rerun sequence.
Wait for approval of finding IDs before remediation.

Antes de la implementación

Report active feature, approved task range, checklist status,
open analyze findings, expected files/tests, and stop conditions.
Wait for explicit approval of the task range.

Después de la implementación

Map completed tasks to requirements and validation evidence.
List commands, exit status, unrun checks, deviations, and remaining risk.
Then run /speckit.converge and review any appended tasks before continuing.

El contrapunto: la revisión humana también puede fallar

La revisión humana es costosa y falible. Una persona puede malinterpretar un resumen generado, convertirse en un cuello de botella que bloquea la entrega o aprobar puntos de control sin leerlos.

La respuesta no es exigir una reunión para cada decisión del agente. Autoriza de antemano las decisiones de bajo riesgo mediante la constitución, las plantillas, las reglas de arquitectura, la política de pruebas y los umbrales explícitos. Escala solo cuando el trabajo cruce esos límites.

Algunos motivos útiles para escalar son:

  • el repositorio y los artefactos proporcionan evidencia contradictoria
  • una decisión cambia el comportamiento visible para el usuario o el alcance aceptado
  • está involucrado un límite relacionado con seguridad, privacidad, dinero, cumplimiento normativo o datos irreversibles
  • el agente propone una excepción a una regla rectora
  • la evidencia de implementación invalida una suposición aprobada
  • falta validación para un requisito de alto impacto

El criterio humano aporta valor cuando resuelve una decisión que la política no puede resolver. Agrega demora cuando simplemente repite una decisión que la política ya tomó.

Lo que recomiendo mantener bajo responsabilidad humana

Para este flujo de trabajo, recomiendo asignar una persona responsable identificada a estas responsabilidades cuando el riesgo lo justifique:

  • aprobar el comportamiento visible para el usuario y los objetivos excluidos
  • aceptar las concesiones relacionadas con privacidad, seguridad, cumplimiento normativo o retención de datos
  • autorizar decisiones irreversibles de arquitectura o migración
  • decidir qué suposiciones se pueden mantener sin correr riesgos inaceptables
  • aceptar checklists incompletos o hallazgos sin resolver
  • aprobar cambios en los requisitos descubiertos durante la implementación
  • decidir si la evidencia de validación es suficiente
  • aceptar el riesgo residual y autorizar el lanzamiento

El agente puede preparar excepcionalmente bien cada decisión. Puede reunir evidencia, comparar opciones, exponer contradicciones y registrar el resultado. Preparar una decisión no equivale a ser responsable de ella.

Modos de fallo que esta conversación evita

«Clarify terminó, así que ya no hay ambigüedad»

Hizo hasta cinco preguntas. Otras categorías pueden seguir sin resolverse. Revisa qué quedó cubierto y decide si ejecutar otra ronda enfocada.

«Analyze indicó 100% de cobertura»

El comando infiere la cobertura de tareas a partir de identificadores de requisitos, palabras clave y frases clave. Es una comprobación útil de consistencia, no una prueba formal de que la implementación satisface el requisito.

«Todas las tareas están marcadas»

Eso demuestra que se actualizó el estado de las tareas. No demuestra el comportamiento esperado, la propiedad de seguridad, el objetivo de rendimiento ni el resultado operativo.

«El agente investigó y seleccionó la arquitectura»

research.md debe mostrar la decisión, la justificación y las alternativas. Una persona sigue siendo quien aprueba las decisiones con costos, riesgos o consecuencias organizacionales importantes.

«Corregimos el código, así que el plan puede seguir desactualizado»

Solo si el código estaba equivocado y el plan aprobado sigue siendo correcto. Si la implementación reveló un cambio válido de diseño o de requisitos, actualiza el artefacto correspondiente y todos los artefactos derivados.

«Más subagentes significan más confianza»

Solo cuando investigan de forma independiente, citan evidencia y exponen sus desacuerdos. Más coincidencias sin sustento no constituyen evidencia más sólida.

Conclusión

La parte humana de GitHub Spec Kit no consiste en escribir todo el Markdown tú mismo. Consiste en controlar cómo la incertidumbre se convierte en compromisos.

En cada fase:

  1. expón lo que el agente infirió
  2. separa la evidencia de las suposiciones
  3. asigna a personas las decisiones importantes
  4. propaga los cambios aprobados a todos los artefactos afectados
  5. establece una siguiente acción delimitada y una condición de parada
  6. exige evidencia antes de aceptar

Spec Kit le da a la conversación una estructura duradera. La persona se asegura de que esa estructura contenga decisiones que el equipo realmente entiende y acepta.

El mejor prompt no es el más largo. Es el que hace imposible pasar por alto la siguiente decisión, su responsable, la evidencia requerida y el punto de parada.

Lecturas relacionadas

Fuentes

Fuentes principales de Spec Kit revisadas para v0.15.1, publicada el July 31, 2026:

Guías complementarias de gobernanza:

El comportamiento de los comandos descrito arriba está respaldado por las fuentes. Los patrones de prompts, los puntos de decisión, la matriz de impacto en los artefactos y la recomendación de tratar cada resultado como una propuesta son mi síntesis editorial.

El comportamiento de los comandos de Spec Kit cambia con el tiempo. Verifica estos prompts con las plantillas instaladas en tu proyecto en lugar de asumir que el comportamiento de v0.15.1 se aplica a todas las versiones futuras.