Spec de producto vs. spec de feature
Hay dos niveles de spec: el del producto (qué es, para quién) y el del feature (cómo funciona este endpoint/componente). Confundirlos hace que los specs sean o muy vagos para ejecutar, o demasiado detallados para decidir. Cada nivel tiene su scope.
Spec de producto responde "qué construimos"; spec de feature responde "cómo construimos este trozo".
Spec de producto
- Vive en
specs/concept.md. - Lo escribes una vez, se actualiza con cambios de dirección.
- Responde: qué hace, para quién, qué no hace, flujo mínimo, diferenciadores.
- Lo lee el agente al iniciar sesiones largas, para mantener alineación macro.
Spec de feature
- Vive en
specs/./ .md - Lo escribes por cada feature significativo (>50 líneas de código esperadas).
- Responde: contexto, comportamiento, edge cases, criterios de aceptación.
- Lo lee el agente cuando va a implementar ese feature específico.
La relación entre ambos
El spec de producto constrains los specs de feature. Un feature que contradice el producto debe gatillar una conversación: ¿cambió el producto? ¿el feature está mal scopeado?
Flujo sano:
- Spec de producto estable.
- Feature propuesto.
- ¿Encaja con producto? Sí → spec de feature + implementa. No → revisa producto o descarta feature.
El error común
Escribir specs de feature sin spec de producto. Cada feature hace sentido aislado, ninguno hace sentido conjunto. El producto final es una colección de piezas sin alma. Prevención: specs/concept.md siempre primero.
En tu `specs/`, ¿tienes `concept.md`? ¿Todos los feature specs encajan con él? Si hay contradicción, es señal de que uno de los dos está desactualizado.
- Producto = qué construimos. Feature = cómo construimos un trozo.
- Spec de producto es siempre primero.
- Feature que contradice producto gatilla revisión, no silencio.