Referencia Nivel · intro
Spec (Especificación)
Por qué te debe importar
Un [[spec]] no es documentación — la documentación describe lo que ya existe. El spec describe lo que debe existir. Es el contrato que el agente ejecuta, el artefacto que sobrevive a la conversación, y la razón por la que el código resultante es reproducible.
Idea central
Documento estructurado con contexto, comportamiento esperado, casos edge y criterios de aceptación, escrito antes del código.
Los cuatro bloques mínimos
- Contexto — qué parte del sistema toca, qué supuestos hace, por qué existe el feature.
- Comportamiento esperado — input → output, estados, transiciones, efectos secundarios.
- Casos edge — qué pasa si X falla, si Y está vacío, si Z es concurrente. Un spec sin edge cases es un prompt disfrazado.
- Criterios de aceptación — condiciones verificables para decir "hecho". Idealmente convertibles a tests.
Spec vs. documentación vs. prompt
- Prompt: "Haz X". Se ejecuta una vez, se desecha.
- Spec: describe lo que debe pasar, con verificabilidad. Vive en el repo.
- Documentación: describe lo que ya pasa. Se escribe después del código.
Un spec se lee antes de implementar; una doc se lee después.
Ejemplos en escalera
✓ Checkpoint
Toma el último feature que implementaste. Escribe su spec ahora, retroactivamente, en 15 líneas con los 4 bloques. Si al hacerlo descubres un edge case que no habías pensado, ese es el valor que el spec hubiera agregado antes.
Resumen — tres cosas que deberías recordar
- Spec = contexto + comportamiento + edge cases + criterios de aceptación.
- Se escribe antes del código; la documentación se escribe después.
- Un spec sin criterios verificables es un prompt con frontmatter.
Qué sigue