Clase 06 · Módulo 02
Escribir la especificación para Claude Code
Escribir la especificación para Claude Code
Qué logras en esta clase
Reúnes el trabajo del módulo en un documento que Claude Code puede construir por etapas y que tú puedes comprobar.
- Saber qué secciones lleva una especificación y de dónde sale cada una
- Escribir requisitos que se pueden verificar
- Partir la construcción en etapas con criterio de «hecho»
- Mantener el documento al día mientras la app avanza
02
Por qué escribirla
Claude Code construye lo que le describes. Lo que no escribes, lo decide por ti, y no siempre como lo habrías decidido tú.
03
Qué es la especificación
Es un archivo de texto en formato Markdown, guardado en la carpeta de tu proyecto, que dice qué se va a construir y qué no.
- Tú la escribes y la mantienes; Claude la lee antes de cada etapa
- Es la única fuente: si código y documento no coinciden, uno está mal
- Te sirve también a ti, cuando vuelvas al proyecto tras un mes
04
Qué contiene y de dónde sale
| Sección | Ya la tienes de |
|---|---|
| Problema, usuario y propuesta | Clase 1 |
| Alcance de la primera versión y fuera de alcance | Clase 2 |
| Pantallas, navegación y flujos | Clase 3 |
| Entidades, relaciones y accesos | Clase 4 |
| Decisiones de tienda | Clase 5 |
| Etapas y criterios de «hecho» | Esta clase |
No partes de una hoja en blanco: esta clase ordena lo que ya decidiste.
05
Cinco rasgos de una buena especificación
- Comprobable: cada requisito se puede verificar mirando la app
- Con límites: dice explícitamente lo que no se hace
- Con motivos: explica el porqué de las decisiones que no son obvias
- Corta: se lee completa en diez minutos
- Al día: cambia cuando cambia una decisión
06
Requisito vago contra requisito comprobable
| Vago | Comprobable |
|---|---|
| «Que reservar sea fácil» | «Se reserva en tres pantallas desde Servicios» |
| «Que sea segura» | «Un cliente no puede leer reservas de otro» |
| «Manejar errores» | «Sin conexión, Confirmar muestra un mensaje y un botón para reintentar» |
La prueba: ¿podrías decir «sí» o «no» mirando el teléfono? Si la respuesta es «depende», reescríbelo.
07
«Fuera de alcance» es una sección
Claude tiende a completar lo que considera razonable. Si no dices que algo queda fuera, puede construirlo.
Esta lista sale de los cajones «después» y «fuera» de la clase 2. Copiarla aquí ahorra código que nadie pidió.
08
Stack y restricciones en pocas líneas
Incluye una sección breve con las decisiones técnicas que ya están tomadas:
- El stack del curso: Expo, TypeScript y Supabase
- Las plataformas de la primera versión
- El idioma de la interfaz
- Lo que no quieres que use o agregue sin preguntarte
09
Explica el porqué
Una decisión con su motivo se respeta mejor que una orden suelta, porque Claude puede aplicarla a casos que no previste.
| Solo la regla | Regla con motivo |
|---|---|
| «Ingreso solo con correo» | «Ingreso solo con correo: evita la exigencia 4.8 de Apple en esta versión» |
| «No borrar reservas» | «Las reservas cambian de estado: necesitamos el historial de cancelaciones» |
Una línea de motivo basta. No conviertas el documento en un ensayo.
10
No pidas la app completa
No le pidas la app entera de una vez. Pídele una etapa que puedas probar en tu teléfono antes de pasar a la siguiente.
11
Cómo partir en etapas
Cada etapa debe dejar algo que se pueda abrir y probar. Un orden que suele funcionar:
Si una etapa no se puede probar sola, es demasiado grande o depende de otra que va antes. Divídela o cámbiala de lugar.
12
Cada etapa lleva su criterio de «hecho»
Escribe, por etapa, de dos a cuatro comprobaciones que harás tú en el teléfono.
Sin criterio, «terminé» significa lo que Claude entienda. Con criterio, significa lo mismo para los dos.
13
Dónde vive y en qué se diferencia de CLAUDE.md
| Archivo | Qué dice | Cuándo se lee |
|---|---|---|
| Especificación | Qué se construye | Cuando la mencionas o la pides |
CLAUDE.md | Cómo se trabaja en el proyecto | Al inicio de cada sesión |
Guarda la especificación en el proyecto, por ejemplo en docs/especificacion.md. CLAUDE.md puede apuntar a ella con la sintaxis @ruta. Su configuración se ve en el módulo 3; la documentación recomienda mantenerlo bajo 200 líneas.
14
Escríbela conversando
- Reúne tus notas de las clases 1 a 5 en una conversación con Claude.
- Pídele que te entreviste sobre lo que falta, una pregunta a la vez.
- Pídele un borrador con las secciones de esta clase.
- Léelo completo y corrige lo que no dijiste.
- Guárdalo en tu proyecto.
El paso 4 no se delega. Un borrador que suena bien puede incluir decisiones que nunca tomaste.
15
Pídele que la ataque
Antes de construir, usa a Claude como revisor crítico del documento.
Cada «tendría que adivinar» es una decisión pendiente tuya. Resuélvela en el documento, no en la conversación: lo que queda solo en el chat se pierde.
16
Antes de construir: modo plan
En modo plan, Claude Code lee los archivos y propone un plan, pero no edita nada hasta que lo apruebas.
- Durante una sesión: presiona
Shift+Tabhasta que la barra de estado indiqueplan mode on - Al iniciar:
claude --permission-mode plan
Menciona el documento con @docs/especificacion.md para que su contenido entre en la conversación.
17
El ciclo de una etapa
Revisar el plan es barato: lees una lista. Si el plan menciona algo que está fuera de alcance, corrígelo ahí. Después de construido, sacarlo cuesta más.
18
Cuando la realidad contradice el documento
Va a pasar: una pantalla no convence al probarla o una regla cambia. El orden importa:
- Cambia primero la especificación.
- Anota la fecha y el motivo en una línea.
- Recién entonces pide el cambio en el código.
19
Cuánto detallar cada parte
| Detalla mucho | Detalla poco |
|---|---|
| Entidades y quién accede a qué | Colores y tamaños |
| Decisiones de tienda | Textos exactos de cada botón |
| Caminos de error del recorrido principal | Animaciones |
| Lo que queda fuera | Pantallas secundarias |
Lo de la izquierda es caro de corregir después. Lo de la derecha se ajusta mejor viéndolo en el teléfono.
20
Lo que una especificación no hace
| Límite | Qué haces tú |
|---|---|
| No garantiza código correcto | Pruebas cada etapa en el teléfono |
| Claude puede desviarse de ella | Revisas el plan y el resultado |
| Envejece si no se mantiene | La corriges antes que el código |
| Escribirla toma tiempo | Para una app personal de tres pantallas, una página basta |
21
Errores comunes
- Requisitos que no se pueden comprobar
- Omitir la sección de fuera de alcance
- Etapas sin criterio de «hecho»
- Dejar que el documento envejezca mientras el código cambia
22
Lo que te llevas
- La especificación reúne problema, alcance, pantallas, datos, reglas de tienda y etapas
- Un buen requisito se responde con sí o no mirando el teléfono
- Lo excluido se escribe, con la misma claridad que lo incluido
- Se construye por etapas: plan, revisión, construcción, prueba y versión guardada
- El documento se corrige antes que el código
23
Hazlo ahora
En 15 minutos:
- Crea el archivo con los seis títulos de sección.
- Pega en cada uno lo que hiciste en las clases 1 a 5.
- Escribe la lista de fuera de alcance.
- Define la primera etapa y tres comprobaciones de «hecho».
- Pídele a Claude que liste lo que tendría que adivinar, y resuélvelo.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026