DotMDCómo revisar una spec escrita por IA:una checklist antes de que el agente construya.
Un agente de IA escribe en un minuto una spec segura y ordenada. Ese es el peligro: se lee bien aunque esté equivocada. Esta checklist muestra qué buscar antes de decirle al agente que empiece a construir.
macOS 14 o posterior. Leer es gratis; editar y revisar se pagan una sola vez.
Respuesta rápida
Revisa una spec escrita por IA como revisas un pull request: comprueba que resuelve el problema correcto y después busca lo que falta. Repasa el alcance y lo que queda fuera, los casos límite, los datos y las migraciones, las pruebas y la marcha atrás, y deja un comentario en cada pasaje que quieras cambiar antes de que el agente escriba código.
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
Por qué las specs de IA necesitan otro tipo de revisión
Una persona que redacta una spec suele dejar huecos donde no está segura. Un modelo escribe texto fluido para todo, incluso para las partes que ha supuesto. Así faltan las señales habituales de una spec débil, el lenguaje vago y los huecos evidentes, y los problemas se esconden en frases seguras. Revisa buscando lo que habría preguntado un buen autor.
La checklist
-
Alcance: ¿resuelve lo que pediste?
Compara el primer párrafo con tu petición. Busca si resolvió otro problema y si incluye funciones que nadie pidió.
-
Fuera de alcance: ¿qué no hará?
Una spec sin lo que queda fuera no tiene bordes. Añade los extras que no quieres.
-
Suposiciones: ¿qué ha supuesto?
Busca «presumiblemente», «probablemente» y cualquier cosa dicha como un hecho sobre código o datos que quizá no haya leído. Pídele que cite los archivos.
-
Casos límite: ¿qué pasa cuando algo sale mal?
Entrada vacía, entrada muy grande, sin permiso, sin red, dos usuarios a la vez, la misma acción dos veces.
-
Datos: ¿qué se guarda, cambia o borra?
Campos, formatos, quién puede leerlos y qué pasa con los registros existentes.
-
Migraciones: ¿cómo se mueven los datos antiguos?
Un cambio de esquema necesita un orden de pasos, un plan para un fallo a medias y una forma de ejecutarlo dos veces sin riesgo.
-
Interfaces: ¿qué más se toca?
API, pantallas, tareas programadas, código de otros equipos. Todo lo que la spec cambia pero no lista es una sorpresa más adelante.
-
Seguridad y privacidad: ¿quién puede hacer qué?
Permisos nuevos, datos nuevos que salen del sistema, secretos en los registros.
-
Pruebas: ¿cómo sabrás que funciona?
Cada requisito debería corresponder a una comprobación. Si un requisito no se puede probar, reescríbelo.
-
Despliegue y marcha atrás: ¿cómo lo deshaces?
Un flag, una publicación gradual, un camino de vuelta. «Lo arreglaremos hacia delante» no es un plan.
-
Preguntas abiertas: ¿quién las decide?
Una spec honesta lista lo que no sabe. Si no hay ninguna, desconfía.
Un comentario que funciona
Un comentario vago produce una reescritura vaga. Un buen comentario de revisión señala un pasaje, dice qué está mal y qué quieres en su lugar:
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.Mantén los comentarios separados del texto de la spec para que el archivo quede limpio, y agrúpalos: lee toda la spec una vez y después comenta, para que el agente reescriba una vez y no diez.
El ciclo de revisión
-
Léela primero de principio a fin
Antes de comentar, asegúrate de haber entendido todo el plan.
-
Comenta los pasajes exactos
Un problema por comentario.
-
Deja que el agente revise
Corrige cada comentario y produce una versión nueva.
-
Comprueba qué cambió, no todo el documento
Lee las diferencias. Una corrección puede romper algo que estaba bien.
-
Aprueba solo cuando la checklist esté limpia
Entonces deja que construya, según los requisitos numerados.
La misma checklist sirve cuando un agente revisa la spec de otro. Pide al revisor que responda a cada punto con una cita de la spec.
Hacerlo en DotMD
Todo esto se puede hacer en la propia página. En DotMD seleccionas el pasaje y escribes un comentario sobre él; los comentarios se guardan en DotMD, no en el archivo. El agente los corrige y envía de nuevo el documento, y revisar los cambios muestra el texto antiguo en rojo y el nuevo en verde para que los aceptes uno a uno. La configuración se describe en revisar specs de IA. Leer es gratis; consulta los precios para las revisiones.
Errores habituales
- Revisar el estilo, no el fondo. Una spec pulcra puede seguir estando equivocada.
- Aprobar porque es larga. La longitud no es cobertura.
- Saltarse lo que queda fuera de alcance y la marcha atrás, las dos secciones que los modelos dejan más flojas.
- Arreglar el código en lugar de la spec. Si el plan está mal, corrígelo primero.
- Sin segunda mirada. Después de que el agente revise, comprueba el diff.
Preguntas sobre la revisión de specs escritas por IA
¿Cómo reviso una spec escrita por IA?
Comprueba que resuelve el problema correcto y después busca lo que falta: lo que queda fuera de alcance, los casos límite, los datos y las migraciones, las pruebas y la marcha atrás. Comenta cada pasaje y haz que el agente revise antes de que escriba código.
¿Qué debería incluir una checklist de revisión de specs?
Alcance, fuera de alcance, suposiciones, casos límite, datos, migraciones, interfaces, seguridad, pruebas, despliegue y marcha atrás, y preguntas abiertas.
¿Puede un agente de IA revisar la spec de otro agente?
Sí. Dale al revisor la checklist y pídele que responda a cada punto con una cita de la spec. Tú sigues decidiendo qué aceptar.
¿Por qué no leer directamente el código?
Para entonces las decisiones ya están tomadas y son caras de cambiar. Una suposición equivocada es más barata de corregir en la spec.