Generación de hojas de ruta
Una hoja de ruta es un plan que la siguiente persona puede retomar y ejecutar sin depender de la conversación que lo generó. Indica qué intenta alcanzar el proyecto, en qué orden, cómo se sabrá que cada pieza está terminada y qué preguntas siguen abiertas. Vive en el repositorio, junto al código que describe, por lo que se revisa y versiona como todo lo demás.
Una hoja de ruta registra decisiones. No las toma. Cuando algo no se ha decidido, la hoja de ruta lo dice.
Primero, las reglas del repositorio
Antes de escribir nada, busca las convenciones propias del repositorio: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, un esquema de docs o wiki, y cualquier hoja de ruta existente. Ellas deciden dónde van las hojas de ruta, qué metadatos llevan, cómo se vinculan los issues y qué verificaciones ejecutar. Si entran en conflicto con este skill, prevalecen. Sigue el formato de una hoja de ruta existente en lugar de introducir una segunda.
Flujo de trabajo
1. Definir la solicitud
Determina cuál de estas opciones quiere el usuario, ya que cada una requiere un trabajo diferente:
- Nueva hoja de ruta: para un proyecto, una funcionalidad, una migración, un esfuerzo de pruebas, etc.
- Actualización: añadir o cambiar elementos, reordenar fases, registrar una decisión.
- Conciliación: alinear una hoja de ruta existente con lo que realmente se ha entregado.
- Revisión: leer una hoja de ruta e informar sobre carencias, sin reescribirla.
2. Recopilar evidencia antes de preguntar
Lee lo que el proyecto ya sabe: el código y las pruebas relevantes, issues abiertos y cerrados recientemente, PRs fusionados y abiertos, documentos existentes y el historial de commits del área. Anota qué existe hoy, qué está ya en progreso y qué se ha intentado antes.
Todo lo que puedas aprender de esta manera, no lo preguntes al usuario.
3. Preguntar sobre las decisiones críticas
Una hoja de ruta solo es tan buena como las decisiones que la respaldan, y la mayoría de esas decisiones pertenecen al usuario. Pregunta en rondas cortas en lugar de una lista larga, y explica por qué una pregunta es importante cuando la compensación no sea obvia. Buenos temas:
- Objetivo: ¿qué resultado hace que este esfuerzo valga la pena, y cómo se sabrá que se ha cumplido?
- Alcance: ¿qué está explícitamente fuera? ¿Qué no debe cambiar (APIs, formatos de datos, comportamiento)?
- Restricciones: plazos, lanzamientos, personas, presupuesto, plataformas.
- Prioridades: si solo se entrega la mitad, ¿qué mitad?
- Riesgo: ¿qué es lo menos entendido, y debería abordarse primero?
- Hecho: ¿qué pruebas, métricas o revisiones cuentan como evidencia?
Ofrece una recomendación cuando la evidencia la respalde. Siempre permite que el usuario responda "aún no decidido". Esa respuesta va en Decisiones abiertas, no en una suposición.
Para una actualización pequeña, pasa directamente a escribir. Para una nueva hoja de ruta, espera dos o tres rondas.
4. Elegir una estructura
- Un archivo (
ROADMAP.md, o un nombre que se ajuste al repositorio) para la mayoría de las hojas de ruta. - Un directorio (
roadmaps/<slug>/README.mdmás páginas de apoyo) solo cuando el plan necesite material complementario extenso, como notas de investigación, un borrador de diseño o matrices de pruebas, que enterrarían los elementos de trabajo. La página principal sigue siendo la propietaria de cada ID de elemento de trabajo.
5. Redactar
Usa la plantilla de abajo. Reglas que la mantienen útil con el tiempo:
- IDs estables. Asigna a cada elemento de trabajo un ID como
R-001. Nunca renumeres ni reutilices un ID. El trabajo abandonado permanece en el archivo, marcado comodropped, con la razón. - Las fases tienen criterios de salida. Cada fase indica qué es cierto cuando se completa. Ordena las fases primero por dependencia, luego por riesgo, luego por valor.
- Los criterios de aceptación son verificables. Escribe criterios que alguien pueda verificar: una prueba que pase, un comando que tenga éxito, un número medible. Evita palabras como "robusto", "mejorado" y "limpio".
- Las dependencias son explícitas. Enuméralas por ID. Señala cualquier cosa fuera del control del equipo, como otro repositorio, un proveedor o una decisión.
- Enlaza la evidencia mediante URL completa o ruta relativa al repositorio, para que los enlaces sobrevivan al ser copiados a otro lugar.
- Describe el plan, no la reunión. Tiempo presente, estado actual. El historial va en el registro de cambios.
6. Verificar
Antes de entregarlo:
- Cada elemento tiene un ID, un estado y al menos un criterio de aceptación.
- Cada dependencia apunta a un ID que existe.
- Ninguna fase depende de una fase posterior.
- Cada pregunta no decidida está bajo Decisiones abiertas, no oculta en un elemento.
- Los enlaces se resuelven y las rutas de archivo existen.
- Las comprobaciones de formato y documentación del repositorio pasan.
- El registro de cambios tiene una entrada para este cambio.
7. Informar
Dile al usuario qué creaste o cambiaste, las decisiones que registraste y las preguntas que siguen abiertas.
Conciliar una hoja de ruta con la realidad
Las hojas de ruta se desvían a medida que el trabajo se completa. Para conciliar una:
- Enumera los elementos que no están
doneodropped. - Para cada uno, busca PRs fusionados, issues cerrados y código que satisfaga sus criterios de aceptación.
- Marca un elemento como
donesolo cuando se cumplan todos los criterios. Enlaza la evidencia. - Si el trabajo se entregó de manera diferente al plan, actualiza el elemento para indicar lo que realmente sucedió, y señala la diferencia en el registro de cambios.
- Añade cualquier trabajo nuevo que descubras como nuevos elementos con nuevos IDs.
- Resume los cambios para el usuario. Pregunta antes de descartar algo.
Revisar una hoja de ruta
Cuando solo se te pida revisar, no reescribas. Informa, primero lo más importante:
- objetivos o fases sin forma de saber cuándo están terminados;
- elementos con criterios de aceptación vagos;
- dependencias faltantes o circulares;
- decisiones presentadas como resueltas que la evidencia no respalda;
- elementos que el código o el rastreador de issues muestran como ya hechos, o ya no relevantes;
- riesgos faltantes: las partes más difíciles o menos entendidas programadas tarde.
Plantilla
# Hoja de ruta de <Proyecto o funcionalidad>
**Objetivo:** <el resultado, en una o dos frases>
**Estado:** <borrador | activo | completado | reemplazado>
**Última actualización:** <AAAA-MM-DD>
## Contexto
Por qué este trabajo importa ahora, qué existe hoy y enlaces a la evidencia.
## Alcance
- **Dentro:** …
- **Fuera:** …
- **No debe cambiar:** …
## Leyenda de estados
| Estado | Significado |
| -------------- | --------------------------------------------------- |
| `planned` | Acordado, no iniciado |
| `in-progress` | Alguien está trabajando en ello |
| `blocked` | Esperando una dependencia o decisión (indicar cuál) |
| `done` | Todos los criterios de aceptación cumplidos, con evidencia |
| `dropped` | No se va a hacer (indicar por qué) |
## Fase 1: <nombre>
**Criterios de salida:** <qué es cierto cuando esta fase esté completa>
### R-001: <título corto>
- **Estado:** planned
- **Por qué:** <el problema que resuelve>
- **Criterios de aceptación:**
- [ ] <afirmación verificable>
- **Depende de:** <IDs, o "ninguna">
- **Evidencia:** <enlaces a issues, PRs o archivos>
## Fase 2: <nombre>
…
## Decisiones abiertas
| ID | Pregunta | Opciones | Bloquea | Responsable |
| ----- | -------- | -------- | -------- | ----------- |
| D-001 | … | … | R-004 | … |
## Riesgos
| Riesgo | Probabilidad | Impacto | Mitigación |
| ------ | ------------ | ------- | ---------- |
## Registro de cambios
- <AAAA-MM-DD>: <qué cambió y por qué>
Omite las secciones que no apliquen. Una hoja de ruta pequeña podría ser solo un objetivo, una fase y un registro de cambios.
No hagas
- Inventar una decisión porque la hoja de ruta parezca incompleta sin ella.
- Rellenar el plan con elementos genéricos ("añadir documentación", "mejorar pruebas") que no tengan un resultado específico.
- Renumerar elementos, o eliminar los descartados.
- Marcar trabajo como
donesolo por el título de un PR sin verificar los criterios. - Copiar todo el contenido de una hoja de ruta en issues, o viceversa. Enlaza en su lugar.