Cómo hacer que GitHub Spec Kit genere resultados más concisos

Una queja frecuente sobre GitHub Spec Kit no tiene que ver con una función faltante, sino con lo contrario. Para un cambio pequeño, Spec Kit produce una pila de documentos extensos. Una corrección de dos líneas termina con una spec, un plan, un archivo de investigación, un modelo de datos, una carpeta de contratos, una guía de inicio rápido, una lista de tareas y una lista de verificación. El lector se ahoga en documentación antes de que empiece el trabajo.

Este artículo es una guía práctica para hacer que esos resultados sean más concisos. Complementa Extensiones de GitHub Spec Kit: agrega los modos Explore y Alternatives-Review, que explica cómo añadir las fases que le faltan a Spec Kit; aquí veremos cómo reducir lo que ya produce. Si aún no conoces el flujo principal, empieza con GitHub Spec Kit: cómo empezar.

TL;DR

• La verbosidad de Spec Kit viene de las instrucciones de los comandos, no solo de las plantillas; por eso, una plantilla más corta no basta para resolverla.
• Cuatro herramientas, de la intervención más ligera a la más duradera:
  1. Solo pídelo: limita el comando con un prompt inline para un caso puntual (sin modificar archivos).
  2. Plantilla concisa: una sobrescritura de plantilla local al proyecto que cambia qué secciones existen (se aplica en tiempo de ejecución, sin instalación).
  3. Simplifica el comando: edita el comando materializado para que los artefactos opcionales sigan siendo opcionales en la práctica (la opción predeterminada más duradera).
  4. Clasifica por impacto: decide qué tan conciso debe ser cada cambio con una clasificación Lean / Standard / Governed.
• El resultado más conciso es un archivo que nunca generas: clarify, analyze y checklist son opcionales, y los cambios triviales sin riesgo pueden omitir Spec Kit por completo; haz que specify/explore recomienden implementarlos directamente.
• Esto se resuelve con un preset o una sobrescritura local al proyecto, nunca con una extensión: las extensiones añaden comportamiento; los presets y las sobrescrituras lo modifican.
• Las reglas que realmente acortan los archivos: asigna un límite de extensión a cada archivo, omite las secciones vacías, enlaza en lugar de copiar, expresa cada dato una sola vez y genera un artefacto solo si influye en una decisión.
• Verifica la salida (ls + wc -w), no la configuración. Y no elimines lo que un cambio gobernado realmente necesita.

Qué aprenderás aquí

• Por qué la salida de Spec Kit es extensa por defecto y de dónde viene esa extensión
• Cuatro herramientas concretas para reducirla, desde un prompt puntual hasta un preset reutilizable
• Cómo decidir qué tan conciso ser para un cambio determinado (Direct / Lean / Standard / Governed)
• Cuándo omitir comandos por completo y cómo hacer que specify/explore recomienden implementar directamente los cambios pequeños y seguros
• Las reglas editoriales que acortan los archivos sin importar el mecanismo
• Cómo verificar el resultado y evitar eliminar algo que necesitabas

Audiencia: ingenieros y arquitectos que ya usan Spec Kit y consideran que sus artefactos son demasiado extensos para el trabajo cotidiano.

Fuentes y alcance de la versión

Volví a comprobar esto con GitHub Spec Kit v0.10.1 (publicado el 9 de junio de 2026) el 20 de julio de 2026, usando sus plantillas de comandos principales y las referencias de presets y extensiones.

Los artefactos de los comandos, la CLI specify, la jerarquía de resolución de personalizaciones y las estrategias de composición están respaldados por las fuentes de esa versión. Las cuatro herramientas, las reglas de concisión y el modelo Direct/Lean/Standard/Governed son mis recomendaciones editoriales. v0.10.1 es la versión que esta serie usa como referencia, pero existen versiones más recientes (v0.13.0 hasta julio de 2026). Si usas una versión posterior, vuelve a verificar el comportamiento de los comandos, en especial el conjunto de archivos que genera cada uno.

De dónde viene la extensión

Una funcionalidad pequeña se convierte en muchos archivos porque /speckit.plan tiene instrucciones para generar varios artefactos por sí solo, y /speckit.specify añade una lista de verificación:

specs/001-add-rate-limit/
├── spec.md              # /speckit.specify
├── plan.md              # /speckit.plan
├── research.md          #   └ plan Phase 0
├── data-model.md        #   └ plan Phase 1
├── contracts/           #   └ plan Phase 1 (if external interface)
├── quickstart.md        #   └ plan Phase 1
├── tasks.md             # /speckit.tasks
└── checklists/
    └── requirements.md  # /speckit.specify

Son más de ocho archivos para un cambio que podría afectar a dos. Reducir esa cantidad es una tarea de personalización, no un comando nuevo; por eso corresponde a un preset o una sobrescritura local al proyecto, nunca a una extensión (las extensiones añaden comportamiento; los presets y las sobrescrituras lo modifican).

La idea clave: la verbosidad viene de las instrucciones de los comandos, no solo de las plantillas. Sustituir plan-template.md por una versión más corta no impedirá que /speckit.plan produzca esos archivos adicionales, porque sus propios pasos le indican al agente que los cree. Por eso, piensa en cuatro herramientas: las primeras tres reducen la salida y la cuarta decide qué tan conciso debe ser cada cambio:

One-off, no files touched     -> tell the agent inline how lean to be
Which sections exist          -> override the *-template.md   (runtime, instant)
How much + which files        -> trim the command itself      (durable default)
How lean per change           -> route Lean / Standard / Governed by impact

Herramienta 1: solo pídelo (para un caso puntual)

Para una sola funcionalidad no necesitas modificar ningún archivo. Limita el comando al ejecutarlo:

/speckit.plan Keep plan.md under 1,000 words. Skip research.md unless an open
unknown blocks design. Generate data-model.md and contracts/ only if this change
adds a schema or an external interface. Fold verification into a short section of
plan.md instead of a separate quickstart.md.

Esta es la forma más rápida de experimentar una salida más concisa antes de adoptarla. El costo es que debes repetir la instrucción cada vez y depender de que el agente la respete: está bien para una exploración puntual, pero es una base débil como estándar.

Herramienta 2: una plantilla más concisa (por repositorio, sin instalación)

Para que la estructura se mantenga en un repositorio, coloca una plantilla más corta en el directorio de sobrescrituras. Se lee en tiempo de ejecución, así que se aplica en la siguiente ejecución sin necesidad de instalar nada:

.specify/templates/overrides/templates/spec-template.md

# Feature: [name]

## Problem
[Who is blocked and why it matters. 3-4 sentences.]

## Scope
- In:
- Out:

## Requirements
- R1:

## Acceptance criteria
- [ ] AC1:

## Open questions
- [Only unresolved, decision-blocking items.]

Una plantilla controla qué secciones existen. No controla cuánto texto escribe el agente en cada una ni cuántos archivos adicionales crea; de eso se encarga la herramienta 3.

Herramienta 3: simplifica el comando (la solución duradera)

Tanto la cantidad de palabras como los archivos adicionales vienen del comando, por lo que esta es la herramienta que realmente se mantiene en el tiempo. Edita el comando materializado que lee tu agente (.claude/commands/plan.md, .cursor/commands/…) y haz que los artefactos opcionales sean opcionales en la práctica. Por ejemplo, la fase de diseño del comando de planificación viene más o menos así:

### Phase 1: Design & Contracts
1. Extract entities        -> data-model.md
2. Define interface contracts -> /contracts/
3. Create validation guide -> quickstart.md

Una versión más concisa conserva la fase, pero condiciona cada salida:

### Phase 1: Design (only what the change needs)
1. data-model.md — only if the change adds or alters entities
2. /contracts/   — only if it changes an external interface
3. quickstart.md — skip; fold a 3-line "How to verify" into plan.md

Para reutilizar la misma simplificación en varios repositorios, distribuye el comando simplificado y la plantilla como un preset; la materialización durante la instalación mantiene la consistencia entre repositorios, y specify preset resolve plan-template muestra qué capa tiene prioridad cuando se superponen varias. Si quieres un wrapper que reutilice los pasos exactos del comando principal en lugar de volver a enunciarlos, un preset puede envolver el comando incluido. Para ello, sustituye el marcador {CORE_TEMPLATE} por el cuerpo del comando principal dentro de un preámbulo que indica mantener el resultado al mínimo. Una advertencia: las fuentes oficiales de v0.10.1 no coinciden sobre si está implementada la composición más allá de replace, y la página de referencia la incluye como trabajo futuro. Confirma que wrap funcione con tu CLI antes de depender de él.

Herramienta 4: ajusta la salida al impacto (Lean / Standard / Governed)

Las primeras tres herramientas responden cómo producir menos. Esta responde cuándo. La concisión no debería aplicarse de forma global: cambiar un flag de configuración y realizar una migración de base de datos no requieren la misma documentación. Clasifica cada cambio según su impacto y aplica las herramientas anteriores solo donde correspondan:

idea or change
  └─ explore if uncertainty is high
        │
        ▼
   assess the impact
   ├── trivial / zero-risk  -> Direct:   skip the flow, implement + a one-line note
   ├── small / reversible   -> Lean:     trimmed spec + plan + tasks
   ├── normal feature       -> Standard: default spec + plan + tasks
   └── high-risk / shared   -> Governed: full artifacts + review + decision

Una clasificación inicial para adaptar, no para copiar al pie de la letra:

Los niveles reutilizan las herramientas anteriores en lugar de añadir mecanismos nuevos:

• Direct omite Spec Kit por completo; consulta ¿Necesitas todos los comandos? más abajo.
• Lean es donde las herramientas 1–3 dan resultado: un prompt inline que pida mantener el alcance reducido, una plantilla concisa o un comando simplificado.
• Standard ejecuta Spec Kit tal como viene; no elimines lo que realmente necesitas.
• Governed hace deliberadamente lo contrario de ser conciso: aquí los artefactos adicionales justifican su extensión.

Este es un modelo editorial, no una opción predeterminada de Spec Kit: no hay un clasificador incorporado. Tu equipo define los indicadores y quién aprueba un cambio Governed; el objetivo es que la elección sea explícita, no accidental.

¿Necesitas todos los comandos?

El resultado más conciso no es un archivo más corto, sino uno que nunca generas. Antes de recurrir a las herramientas anteriores, pregúntate si el cambio necesita toda la cadena de comandos. Dos características del flujo de v0.10.1 hacen que esto sea viable:

• Algunos comandos ya son opcionales. clarify, analyze y checklist están marcados como opcionales, y constitution se configura una sola vez. La cadena mínima es specify → plan → tasks → implement, así que omitir los comandos opcionales para un cambio pequeño no tiene costo.
• implement tiene requisitos previos. /speckit.implement requiere tasks.md y plan.md (la comprobación de requisitos previos se ejecuta con --require-tasks). Los artefactos de diseño que lee —data-model.md, contracts/, research.md, quickstart.md, constitution.md— se procesan solo «si existen», por lo que son realmente opcionales, pero no puedes pasar directamente de specify a implement mediante el comando principal.

Así que «menos comandos» tiene dos formas realistas:

Small but real change  -> keep specify → plan → tasks → implement; drop clarify/analyze/checklist
Trivial / zero-risk    -> leave Spec Kit entirely; implement directly and record why

Haz que specify (o explore) recomiende la ruta segura más corta

Puedes adelantar la decisión: haz que tu comando de entrada evalúe el cambio y recomiende cuánto proceso necesita, incluida la opción de «simplemente implementarlo». No hay un clasificador incorporado y el núcleo no tiene un comando explore (ese es la extensión del artículo complementario), así que este es un prompt de wrapper que puedes añadir a una sobrescritura de specify o a un comando explore:

Before writing a specification, classify this change:

- If it is trivial and zero-risk (no API/contract, schema/data, auth/secrets,
  or cross-team surface, and revertible in one commit), recommend implementing
  it directly. Do NOT generate spec/plan/tasks. Propose the edit and a one-line
  rationale for the commit or PR, and ask the user to confirm.
- If it is small but real, recommend the Lean path.
- If it touches a shared or risky surface, recommend Standard or Governed and
  name why.

Recommend; do not decide. Wait for the user to accept the path.

Para un punto intermedio —quieres un registro de auditoría, pero no toda la ceremonia—, un wrapper puede generar automáticamente spec.md, plan.md y tasks.md de una línea cada uno y luego pasar el control a implement. Eso satisface los requisitos previos de implement y mantiene cada artefacto en una sola oración.

Límites de seguridad para omitir el flujo

Omitir el flujo es una decisión, no la opción predeterminada. Hazlo de forma segura:

• Define «sin riesgo» de manera estricta. Sin cambios en API públicas ni contratos de eventos, sin migraciones de esquema o datos, sin afectar autenticación, secretos ni datos personales, sin superficies compartidas entre equipos y con posibilidad de revertirlo con un solo revert. Ante cualquier duda, escala al menos a Lean.
• Cero artefactos no significa cero responsabilidad. Registra la decisión. Un mensaje de commit o una descripción de PR claros —qué cambió y por qué no era necesaria una spec— son la evidencia mínima.
• Una persona confirma. El comando recomienda la ruta Direct; una persona la acepta. Esa confirmación cuesta menos que una spec y detecta los casos que «parecían triviales, pero no lo eran».

La idea central del artículo se aplica aquí en su forma más extrema: ajusta la cantidad de proceso al cambio que tienes delante. A veces eso implica una spec completa y gobernada. A veces basta con un buen mensaje de commit.

Las reglas que realmente acortan los archivos

Sin importar qué herramienta uses, las mismas reglas son las que hacen el trabajo:

Para conocer los IDs de requisitos y las prácticas de generación de tareas que mantienen la trazabilidad incluso en un tasks.md conciso, consulta Prompts de planificación del desarrollo de ingeniería con Spec Kit.

Verifica que funcionó

La prueba está en la salida, no en la configuración. Después de una ejecución, revisa el árbol de archivos y el número de palabras:

ls specs/<feature>/            # fewer files than before?
wc -w specs/<feature>/*.md     # each under its budget?

Cuándo no simplificar

Más conciso no siempre es mejor. Parte de la versión exacta del comando principal que ejecutas y elimina solo lo que entiendes; conserva los pasos de descubrimiento de funcionalidades, validación y cualquier hook del que dependa tu flujo de trabajo. Un cambio que afecta la seguridad, los contratos compartidos o las migraciones de datos es un cambio Governed: sus artefactos research.md, contracts/ y de revisión cumplen una función real, y eliminarlos equivale a cambiar un documento más corto por una decisión más riesgosa. El objetivo es tener menos palabras y menos archivos donde no aportan nada, no una fase de planificación que no funcione.

Fuentes

• Plantillas de comandos principales de Spec Kit v0.10.1: la instrucción del comando plan para generar research.md, data-model.md, contracts/ y quickstart.md; la lista de verificación de requisitos del comando specify; y la comprobación de requisitos previos del comando implement, que requiere tasks.md y plan.md (--require-tasks) y trata los artefactos de diseño como «si existen».
• Referencia de presets de Spec Kit: la jerarquía de resolución de personalizaciones, las sobrescrituras locales al proyecto (.specify/templates/overrides/), la estrategia de composición wrap / {CORE_TEMPLATE} y las plantillas resueltas en tiempo de ejecución frente a los comandos materializados durante la instalación.
• README de presets de Spec Kit v0.10.1: sobrescrituras de plantillas y comandos, jerarquía de prioridades y flujo de desarrollo local (specify preset add --dev, specify preset resolve).
• README de Spec Kit v0.10.1: el modelo de extensiones, presets y sobrescrituras locales al proyecto, y la distinción entre comandos principales y opcionales (clarify, analyze y checklist aparecen como opcionales).