Cómo construyo con IA: mi método con el caso de Revela

Revela es una cámara desechable compartida para eventos. Los invitados entran con un QR, sin descargar nada, hacen un número limitado de fotos y nadie las ve hasta que el anfitrión las revela. Detrás hay autenticación, base de datos, subida de fotos, pagos y analítica. Construirlo me ha obligado a resolver problemas que van bastante más allá de generar una interfaz con IA.

Tiene algo de nostalgia a propósito. Como una cámara desechable, cada invitado tiene un número limitado de fotos. Con pocas fotos, las haces con atención: piensas el encuadre, esperas el momento, y no sabes cómo habrán salido hasta que se revela el carrete.

El problema que plantea mi documento de visión es el de cualquier evento con mucha gente: las fotos quedan repartidas en los móviles de cada invitado, el anfitrión acaba pidiendo «mandadme las fotos» por WhatsApp, y ver cada foto al instante se carga la sorpresa que tenían las cámaras desechables.

Así funciona Revela en un minuto

Aquí aparece una pregunta interesante: ¿hasta dónde puede llegar con agentes de IA alguien que conoce de producto, pero no domina toda la implementación? Revela me está sirviendo para comprobarlo. No he dejado de necesitar criterio técnico, pero los agentes me han permitido participar directamente en decisiones e implementación que antes dependían necesariamente de otras personas.

Antes de entrar en herramientas y código, hay algo que conviene tener claro: construir software con IA es cada vez más accesible. Construir el producto adecuado sigue siendo otra historia. En Revela he comprobado que la parte difícil no es conseguir que la IA escriba código. Es conseguir que entienda qué estoy construyendo, que no improvise decisiones importantes y que pueda demostrar que lo que ha hecho funciona.

Un aviso antes de seguir: esto no es una metodología oficial ni pretendo enseñar ingeniería de software. Trabajo en producto y estoy explorando hasta dónde puedo llegar construyendo con IA. Comparto el proceso real, las herramientas que uso y las decisiones que tomo, y también los riesgos y lo que todavía no sé resolver. Tampoco presento Revela como un éxito comercial: sigo validando el negocio, centrado en B2B.

Vamos a ver el método en cinco pasos, con los prompts para que los copies. Después, lo que he aprendido construyendo Revela y la diferencia entre que algo funcione y que alguien lo necesite. La IA me permite construir más cosas; mi trabajo sigue siendo decidir qué merece la pena construir y asegurarme de que lo que construyo tiene sentido.

Índice

• Las herramientas, al servicio del método
• El método en cinco pasos
• Que funcione no es que alguien lo necesite
• Y un paso más: publicarlo
• Lo que he aprendido construyendo Revela
• Por dónde empezar a construir con IA
• AGENTS.md completo, para copiar

Las herramientas, al servicio del método

He usado las skills superpowers e impeccable, y MCP de Supabase, Vercel, Sentry y PostHog, entre otras cosas. También SDD, primero con especificaciones y después con los subagentes de superpowers, y TDD. No te quedes con la lista, que cambiará en pocos meses. Quédate con el problema que cada pieza evita.

Empiezo por superpowers, que es la que más conviene entender. Una skill es un conjunto de instrucciones que el agente carga para trabajar de una manera concreta. Según su documentación, superpowers convierte al agente en algo parecido a un método de trabajo: antes de escribir código te pregunta qué quieres de verdad, te enseña el diseño en trozos que se pueden leer y prepara un plan en tareas pequeñas, con test primero. Que se active sola depende de la instalación, la configuración y el agente que uses, así que no es una garantía universal.

El problema que evita es el más común al empezar: pedirle algo a la IA, recibir código enseguida y descubrir después que resolvía otra cosa. Si lo quieres ver en su fuente, está en github.com/obra/superpowers.

Y una advertencia que me parece importante: estas herramientas no hacen que el agente sea infalible. Le dan un proceso de trabajo. Sigue siendo responsabilidad nuestra revisar sus decisiones y comprobar los resultados.

SDD son las siglas de desarrollo guiado por especificaciones (en inglés, spec-driven development). La idea es escribir primero la especificación, que define el qué antes del cómo, y generar el código a partir de ella en varios pasos, en lugar de pedirlo todo de golpe en un solo prompt. Reduce el margen para que el agente complete por su cuenta decisiones que deberían estar definidas. Y, cuando quedan dudas, permite detectarlas y resolverlas antes de escribir código. Lo explican, por ejemplo, en la documentación de GitHub Spec Kit (github.com/github/spec-kit). Ten en cuenta que el término es joven y cada herramienta lo entiende un poco distinto. Con superpowers hay además un segundo uso: con el plan ya hecho, lanza un agente nuevo por cada tarea y revisa su trabajo antes de seguir. Es el comportamiento de ese flujo, según su documentación, no una propiedad de cualquier sistema con varios agentes.

El TDD, por su parte, consiste en escribir el test antes que el código. Te obliga a decir qué significa «funciona» antes de pedirlo, y así una tarea no se da por terminada solo porque la IA lo diga.

Un MCP es otra cosa: un protocolo que permite conectar al agente con herramientas y fuentes de datos externas, como tu base de datos o tu panel de errores. Según la conexión y los permisos, puede consultar información o ejecutar acciones sin que tengas que copiar los datos a mano. Puede darle acceso a contexto más actualizado, aunque sigue siendo necesario comprobar qué datos está consultando.

El método en cinco pasos

Paso 1. Escribe el producto antes de programarlo

En mi repositorio de Revela hay una carpeta docs con la visión, los requisitos del producto, la arquitectura, el modelo de datos, la API, la seguridad, el diseño, la monetización y la analítica. El índice incluye un glosario (carrete, evento, anfitrión, invitado, disparos, revelado) para que todos los documentos usen las mismas palabras.

Hay dos trucos que puedes copiar tal cual. Primero, el glosario: si la IA llama de tres formas distintas a lo mismo, el código acaba con tres nombres. Segundo, la etiqueta [HIPÓTESIS]: cuando algo no se puede verificar con fuentes públicas, se marca, en vez de darlo por cierto.

Este es el prompt para arrancar:

Quiero construir [describe tu idea en dos frases]. Antes de escribir código, ayúdame a redactar un documento de visión con: el problema, a quién afecta, qué hace hoy esa persona para resolverlo, la propuesta de valor y qué NO vamos a hacer en la primera versión.

Reglas:
- Hazme las preguntas que necesites antes de escribir. Máximo cinco.
- Si afirmas algo sobre el mercado o la competencia que no puedas verificar, márcalo como [HIPÓTESIS].
- Al final, propón un glosario con los términos del producto y úsalo siempre igual.

Paso 2. Trocea el trabajo en fases que se puedan terminar

El plan de Revela tiene 13 fases, de la 00 a la 12, desde la preparación del proyecto hasta el pulido final. Cada fase tiene objetivo, contexto, ficheros afectados, criterios de aceptación, pruebas y definición de terminado, y su propio prompt. También hay un mapa de dependencias: no empiezo la galería si el revelado no está hecho.

La regla de oro del plan:

Ejemplo real: la regla de oro del plan de fases

Antes de escribir código en cualquier fase, lee: coding-guidelines.md, y los docs específicos que la fase indique. No inventes esquema ni endpoints: están definidos. Si algo no está definido, pregunta o propón y márcalo, no improvises silenciosamente.

Y así es el prompt de una fase real, la 04, la captura del invitado, que el propio plan marca como la de mayor riesgo técnico:

Ejemplo real: fragmento del prompt de la fase 04

Objetivo
Web PWA donde el invitado se une por QR/enlace y dispara sin descargar app, con cola de subida offline y la foto oculta hasta el revelado.

Tareas (extracto)
- Ruta única /e/[code].
- RPC capture_photo con límite atómico e idempotencia por client_uuid.
- Cámara web con getUserMedia y alternativa cuando el navegador no lo soporte.
- Tras disparar: vista previa de un segundo; la foto NO queda visible.
- Cola de subida persistente que reintenta con espera creciente.

Criterios de aceptación (extracto)
- Abrir el QR lleva directo a la cámara, sin descarga ni cuenta.
- El límite de disparos se respeta de forma atómica; doble toque = 1 foto.
- La foto está oculta para todos hasta el revelado (verificar en servidor, no solo en la interfaz).
- Sin red: se encola y sube al reconectar, sin duplicados.

Fíjate en dos cosas. Los criterios hablan de cosas que se pueden comprobar, no de buenas intenciones. Y el plan pide dejar como pendiente de verificación manual lo que la IA no puede probar, como la cámara web en un iPhone real.

Para generar tu propio plan:

Con este documento de visión, propón un plan de desarrollo en fases pequeñas.

Para cada fase quiero: objetivo, qué documentos debes leer antes, qué ficheros se tocan, criterios de aceptación, qué pruebas se escriben y cuándo se considera terminada.

Ordénalas por dependencia y dime cuál es la más arriesgada. Separa lo que entra en la primera versión de lo que se deja para después.

Paso 3. Escribe el AGENTS.md

Si te llevas una sola cosa de este artículo, que sea esta. El AGENTS.md es un fichero en la raíz del repositorio con las normas para cualquier agente de IA que trabaje en el proyecto. Es un fichero versionado con reglas explícitas, y así no dependes de repetirlas en cada conversación con el agente. Por eso le doy tanta importancia. Un matiz técnico: cada herramienta debe soportar ese fichero o tener configurada su lectura; no todos los agentes lo cargan automáticamente. Por qué el contexto pesa más que el prompt lo cuento en La IA no va de hacer mejores prompts: va de trabajar con mejor contexto.

En Revela tengo un CLAUDE.md que solo contiene una línea que remite al AGENTS.md, así que hay una única fuente de verdad. El de Revela empieza diciendo que sirve para cualquier agente (Claude, Copilot, etc.), siempre que la herramienta esté configurada para leerlo. Estas son sus piezas y el problema que resuelve cada una:

• Principio de ejecución: incrementos pequeños y verificables, nunca una tarea entera de golpe. Evita recibir mil líneas que nadie ha revisado.
• Comprobación antes de cada commit: el mismo comando que corre la integración continua. Evita que algo pase en tu máquina y falle al subirlo.
• Convenciones: idioma, flujo de commits y dónde va la lógica que se puede probar. Evita decidir lo mismo cada vez.
• TDD con ciclo completo, reglas estrictas y una lista de comprobación. Evita que el agente dé una tarea por terminada sin pruebas, o que debilite un test para que pase. En mi configuración original lo exigía para todos los cambios. Después he matizado esa regla: no todos los cambios se verifican de la misma manera.
• Qué hacer si se rompe el ciclo. Evita seguir acumulando código encima de algo que nadie ha verificado.
• Cómo ejecutar las pruebas en el entorno de desarrollo. Evita perder tiempo con una suite que no arranca.

Dos matices. Primero, el tamaño de las tareas: pequeñas no significa dividir todo hasta el absurdo. Tienen que ser lo bastante pequeñas para revisar y verificar el resultado, pero conservar sentido funcional. Segundo, el TDD. Yo mantendría el ciclo completo para la lógica de negocio y los errores reproducibles. Para un ajuste visual pediría una revisión visual, y una exploración inicial no debería consolidarse sin una validación adecuada. No lo trataría como un test automático universal.

Con el plan y las reglas en su sitio, la gestión del día a día es siempre la misma: el agente lee el contexto antes de empezar, trabaja en tareas independientes, revisa cada incremento y ejecuta las comprobaciones antes de cada commit, sin acumular cambios sin verificar. No es una herramienta más: es lo que evita que el trabajo se desvíe mientras no miras.

Te dejo los fragmentos clave de una versión generalizada del mío, sin nada específico de Revela. El fichero completo, listo para copiar en la raíz de tu proyecto como AGENTS.md, está al final de este artículo. Rellena los corchetes y quita lo que no encaje:

Fragmentos clave del AGENTS.md generalizado

# AGENTS.md - [NOMBRE DEL PROYECTO]

(...)

## Principio de ejecución

Trabaja en incrementos pequeños y verificables. No ejecutes una tarea completa de principio a fin de una sola vez.

Cada incremento debe ser lo bastante pequeño para revisarlo y verificar su resultado, pero conservar sentido funcional. No lo dividas hasta que deje de significar algo.

Para los cambios que requieren TDD (ver más abajo) sigue el ciclo:

TEST → FAIL → IMPLEMENTACIÓN MÍNIMA → PASS → REFACTOR → VERIFY

Después de cada incremento, deja el proyecto en un estado funcional. Si una petición contiene varias funcionalidades, divídela en subtareas y procesa cada una antes de continuar con la siguiente.

Tu objetivo no es maximizar la cantidad de código producido. Tu objetivo es mantener un estado verificable del producto.

## Cómo verificar cada tipo de cambio

Elige la verificación según el tipo de cambio.

- Lógica de negocio, errores reproducibles y cambios de comportamiento observable: TDD con el ciclo completo que sigue.
- Ajustes visuales: revisión visual (captura o vista previa en los tamaños que importen) y las comprobaciones automáticas que ya existan. No inventes un test automático solo por cumplir.
- Exploración inicial o prototipo: márcalo como exploración. No lo consolides en el proyecto sin una validación adecuada a su tipo: tests si es lógica, revisión visual si es interfaz.

(...)

## Evidencia

Nunca afirmes que algo funciona sin evidencia. Si no puedes verificar algo, dilo de forma explícita y déjalo marcado como pendiente de verificación manual.

(...)

Y el preámbulo común que abre todos mis prompts de fase, que es el mismo contrato en versión corta:

Ejemplo real: preámbulo común de los prompts de fase

- Lee coding-guidelines.md y los docs que la fase indique ANTES de escribir código.
- No inventes esquema de base de datos ni endpoints. Si algo falta, proponlo y márcalo, no improvises en silencio.
- TypeScript estricto. Claridad sobre ingenio. Comentarios mínimos (solo el porqué).
- Todo texto de interfaz en español de España, tuteo.
- Cada pantalla implementa estados: cargando, vacío, error, éxito.
- Seguridad: nunca service_role en el cliente; valida entradas; reglas de acceso siempre.
- Al final: ejecuta lint, typecheck y tests; no declares la fase terminada sin verlos verdes.

Nunca afirmes que algo funciona sin evidencia. Si no puedes verificar algo, dilo explícitamente y déjalo marcado como pendiente de verificación manual.

Es lo contrario de lo que apetece. Con IA lo fácil es pedir mucho de golpe y recibir un montón de código que nadie ha comprobado. Si prefieres que la IA te ayude a escribir el tuyo desde cero, usa este prompt:

Crea en la raíz del proyecto un fichero AGENTS.md con las reglas para cualquier agente de IA que trabaje aquí. Incluye:
1. Trabajar en incrementos pequeños; nunca una tarea completa de una vez.
2. Aplicar TDD a los cambios de lógica de negocio, comportamiento observable y errores reproducibles que lo requieran. Seguir el ciclo: test que falla, implementación mínima, test que pasa, refactor y verificación. Para cambios visuales, exigir revisión visual y las comprobaciones pertinentes.
3. Prohibido borrar o debilitar un test para que pase.
4. El comando que hay que ejecutar antes de cada commit.
5. Convenciones: idioma de los textos, estilo de commits, estructura de carpetas.

Después, dime qué reglas echas en falta para un proyecto como [tu proyecto].

Paso 4. Entiende qué te dice cada prueba

No necesitas dominar toda la implementación para construir con IA. Sí necesitas saber qué ha comprobado cada cosa. En Revela hay varias capas, y cada una dice algo distinto:

• Tests de la lógica con Vitest: comprueban una regla concreta de forma aislada.
• Pruebas de extremo a extremo con Playwright: comprueban un recorrido completo del usuario en el navegador.
• Scripts SQL en supabase/tests: comprueban reglas de la base de datos. Al menos el del aforo de disparos indica en su comentario que se ejecuta a mano contra una base de desarrollo.
• Integración continua: comprobación de estilo y de tipos, tests y una auditoría Lighthouse, que mide rendimiento y buenas prácticas de la web, no la seguridad.

Ninguna de ellas es una prueba de seguridad. Y una prueba de concurrencia, la que detecta fallos cuando dos operaciones coinciden, es otra cosa que tienes que pedir expresamente.

Un ejemplo con el límite de fotos. Es el caso concreto de uno de los scripts SQL, con lo que hace y hasta dónde llega:

Ejemplo real: qué comprueba un test del límite de fotos

Un invitado tiene 2 disparos. El test:
1. Hace 2 fotos y comprueba que el contador llega a 2.
2. Intenta una tercera y comprueba que se rechaza.
3. Libera el hueco de la primera foto, que no llegó a subirse, y comprueba que se devuelve una sola vez.
4. Repite esa liberación y comprueba que el hueco no se devuelve otra vez.
5. Usa ese hueco para una foto más y comprueba que una cuarta se rechaza.
6. Marca otra foto como subida y comprueba que ya no se puede liberar su hueco.
7. Al final compara el contador del invitado con sus fotos pendientes o subidas.

Alcance: es un recorrido seguido, con un solo invitado y dos disparos. No prueba dos operaciones a la vez, ni un fallo real de subida (el estado de la foto se fija a mano), ni todos los estados posibles de una foto, como las ocultas por moderación. No se puede generalizar a todo el sistema.

Si no entiendes cómo se implementa algo así, no pasa nada. Pídele a la IA que te lo explique y que escriba el test que lo demuestre:

Explícame en lenguaje llano qué hace esta función de mi proyecto [pega el código] y qué pasaría si dos personas la llamaran a la vez con el último disparo disponible.

Luego escribe un test que lo compruebe: simula dos operaciones simultáneas intentando consumir el último disparo disponible, no te limites a ejecutar dos llamadas secuenciales. Asegúrate de que ambas operaciones llegan realmente a ejecutarse de forma concurrente en el punto crítico: no basta con lanzar dos llamadas sincrónicas o ejecutarlas una detrás de otra. Primero déjalo fallando contra una versión sin protección, y después comprueba si pasa con la versión actual.

No cambies el código de producción para que el test pase. Dime qué NO cubre el test.

Paso 5. Revisa los riesgos antes de lanzar

Los riesgos no salen solo en los tests: ninguna de las pruebas que acabas de ver sustituye a una revisión de seguridad, permisos, políticas de acceso, almacenamiento y pagos. Con pagos, permisos y datos personales, pide ayuda especializada antes de lanzar. Los tests tampoco descubren por sí solos qué casos límite debería contemplar el negocio: comprueban las condiciones que alguien ha definido previamente.

Para esa revisión, de la auditoría previa al lanzamiento que hay en mi repositorio me quedo con el método: cada afirmación se marca como verificada en el código, verificada en el entorno real o no verificada.

Un caso documentado en el repositorio: uno de los scripts de pruebas de la base de datos se titula «Fotos offline/tardías (auditoría 5 oct, B2)». Fija que un disparo hecho dentro de la ventana del evento y subido después del cierre se acepta (hasta pasadas 24 horas), y que sin la hora del disparo se rechaza. Es el tipo de condición que un requisito como «no dejar disparar fuera de la ventana» no contempla a primera vista. El test documenta esa regla, aunque no permite reconstruir quién detectó el caso ni cómo llegó a implementarse. Lo importante aquí es que una condición así puede pasar desapercibida si solo pensamos en el momento en que se dispara la foto.

Revisa este proyecto antes de lanzarlo. Para cada hallazgo indica:
- gravedad (bloqueante, importante, menor)
- evidencia: [VERIFICADO EN CÓDIGO] con fichero y línea, [VERIFICADO EN ENTORNO REAL] indicando cómo se ha comprobado, o [NO VERIFICADO] si es una hipótesis o no se ha podido comprobar
- cómo se arregla y cuánto trabajo supone

Revisa en especial: quién puede escribir en cada tabla, qué datos de dinero o de permisos puede cambiar el propio usuario, qué pasa con los ficheros cuando se ocultan o se borran, y cómo se borran los datos personales.

No me digas que algo funciona si no lo has comprobado. Y dime qué parte necesita revisión de una persona experta.

Ojo con esto. Un prompt de revisión no sustituye a una persona que sepa de seguridad. Si tu proyecto cobra o guarda datos personales, pide esa revisión y consulta los requisitos legales que te apliquen.

Que funcione no es que alguien lo necesite

Que una cámara funcione, que un pago se registre o que todos los tests pasen demuestra que el software hace lo que esperabas. No demuestra que alguien necesite Revela ni que esté dispuesto a pagar por ella. Eso se valida hablando con usuarios, y es justo donde estoy ahora. Construir era la primera mitad.

Y un paso más: publicarlo

Menos magia de la que parece: el código está en GitHub con integración continua, la web en Vercel y los datos, la autenticación y las fotos en Supabase. Los pagos van con Stripe (la función que recibe sus avisos verifica la firma y registra cada pago con un identificador único, para que un reenvío no se duplique) y la medición con PostHog y Sentry.

Las claves de servidor van en variables de entorno del servidor, no en el cliente ni en el repositorio. Es una de las reglas que recogen los documentos de Revela. Aun así, revisa tú que ninguna clave acabe en el repositorio.

Los planes también cambian. En el repositorio, la app nativa para el anfitrión (con Expo) figura como congelada, y hoy Revela es una web. Algunos documentos, como el preámbulo de los prompts, siguen hablando de una app móvil. Cuando cambies de rumbo, pídele a la IA que actualice también los documentos, o la próxima vez seguirá un plan que ya no existe. Y cuando algo falle, este prompt te ahorra tiempo:

Me aparece este error: [pega el mensaje o el registro del servidor].

Explícame primero, sin tecnicismos, qué significa. Luego propón la corrección más pequeña posible, escribe el test que habría detectado el fallo y dime cómo compruebo que está arreglado.

Lo que he aprendido construyendo Revela

No es un caso de éxito: todavía estoy validando el negocio. Pero el camino me ha dejado varias lecciones que resumen buena parte de lo aprendido:

• Tener documentación no garantiza que esté actualizada. Cuando cambié de rumbo, parte de los documentos siguió hablando del plan antiguo. Si no los actualizas, la próxima vez la IA seguirá un plan que ya no existe.
• Un test en verde no garantiza que el sistema sea seguro. Los tests comprueban reglas concretas, y la seguridad pide su propia revisión. Por eso trato permisos, pagos y datos personales como algo aparte, no como una casilla más que el test ya cubre.
• Un agente puede implementar correctamente un requisito que estaba mal definido. «No dejar disparar fuera de la ventana del evento» no contemplaba las fotos hechas dentro y subidas después del cierre. El fallo no estaba en la ejecución, estaba en mi requisito.
• Dividir el trabajo no sirve si las tareas no tienen sentido funcional. Trocear hasta el absurdo genera cambios que se pueden ejecutar pero no se pueden revisar.
• Construir un producto funcional no demuestra que exista demanda. Por eso no doy Revela por validada: que funcione es la primera mitad; la segunda es hablar con usuarios, y ahí sigo.

Por dónde empezar a construir con IA

1. Elige un problema que conozcas de primera mano.
2. Escribe una página con la idea y deja que la IA te pregunte lo que falta (prompt 1).
3. Pide un plan por fases y empieza solo por la primera (prompt 2).
4. Fija las reglas del agente antes de la primera línea de código (prompt 3).
5. Revisa los riesgos antes de lanzar, y pide ayuda especializada si cobras o guardas datos personales (prompt 5). Después, prueba con pocas personas que conozcas antes de abrirlo al mundo.

La IA no sustituye el criterio. Quién es tu usuario, qué problema resuelves y cuándo algo está listo siguen siendo decisiones tuyas.

La diferencia ya no está solamente en quién sabe programar, sino también en quién sabe qué construir, cómo dirigir a los agentes y cómo comprobar que el resultado tiene sentido.

Construir Revela me está permitiendo aprenderlo en primera persona. Ahora toca comprobar si también tiene sentido para quienes podrían utilizarlo.

AGENTS.md completo, para copiar

Generalizado a partir del AGENTS.md de Revela, sin claves, datos privados ni dependencias del proyecto. Rellena los corchetes y quita lo que no encaje. Guárdalo en la raíz de tu proyecto con el nombre AGENTS.md.

# AGENTS.md - [NOMBRE DEL PROYECTO]

Instrucciones para cualquier agente de IA que trabaje en este repositorio. Léelas antes de tocar nada.

## Principio de ejecución

Trabaja en incrementos pequeños y verificables. No ejecutes una tarea completa de principio a fin de una sola vez.

Cada incremento debe ser lo bastante pequeño para revisarlo y verificar su resultado, pero conservar sentido funcional. No lo dividas hasta que deje de significar algo.

Para los cambios que requieren TDD (ver más abajo) sigue el ciclo:

TEST → FAIL → IMPLEMENTACIÓN MÍNIMA → PASS → REFACTOR → VERIFY

Después de cada incremento, deja el proyecto en un estado funcional. Si una petición contiene varias funcionalidades, divídela en subtareas y procesa cada una antes de continuar con la siguiente.

Tu objetivo no es maximizar la cantidad de código producido. Tu objetivo es mantener un estado verificable del producto.

## Comprobación antes de cada commit

Antes de proponer o hacer un commit, ejecuta la misma comprobación que corre la integración continua:

- Rápida (estilo y tipos): [tu comando]
- Completa (la rápida más los tests): [tu comando]

No des un commit por bueno si la comprobación rápida no pasa, aunque el fallo esté en un fichero que no tocaste.

## Convenciones del proyecto

- Idioma de textos, comentarios y mensajes de commit: [idioma].
- Flujo de ramas y commits: [por ejemplo, ramas por fase o commits directos a main].
- Separa la lógica de decisión en módulos puros, sin dependencias del entorno, para poder probarla con facilidad.

## Cómo verificar cada tipo de cambio

Elige la verificación según el tipo de cambio.

- Lógica de negocio, errores reproducibles y cambios de comportamiento observable: TDD con el ciclo completo que sigue.
- Ajustes visuales: revisión visual (captura o vista previa en los tamaños que importen) y las comprobaciones automáticas que ya existan. No inventes un test automático solo por cumplir.
- Exploración inicial o prototipo: márcalo como exploración. No lo consolides en el proyecto sin una validación adecuada a su tipo: tests si es lógica, revisión visual si es interfaz.

### Ciclo TDD (solo para los cambios que lo requieren)

1. RED. Antes de modificar código de producción, escribe o actualiza el test que representa el comportamiento esperado. Ejecútalo y comprueba que FALLA por la razón correcta. Si no falla cuando debería, no continúes.
2. GREEN. Implementa solo el código mínimo para que el test pase. No añadas funcionalidad que no cubra un test. Ejecuta los tests afectados.
3. REFACTOR. Con los tests en verde, mejora la implementación sin cambiar el comportamiento. Vuelve a ejecutar los tests.
4. VERIFY. Ejecuta la suite relevante completa y las demás validaciones del proyecto (estilo, tipos, build) cuando corresponda.

Reglas estrictas para los cambios que requieren TDD:

- No implementes primero y escribas los tests después.
- Nunca elimines, desactives ni debilites un test para conseguir que pase.
- Si un test debe cambiar porque el requisito ha cambiado, explica primero por qué y actualízalo de forma coherente con el nuevo requisito.
- No marques una tarea como terminada si hay tests fallando relacionados con ella.
- Los tests deben comprobar comportamiento observable, no detalles internos, salvo que formen parte del contrato.
- Prefiere tests deterministas, rápidos y aislados.

### Si rompes el ciclo TDD

Si en un cambio que requería TDD descubres que escribiste código de producción antes que el test: para, inspecciona lo que escribiste, decide qué comportamiento debería estar cubierto, escribe los tests (comprobando primero que fallan), reestructura si hace falta y solo después continúa. No compenses escribiendo tests al final sin pasar por RED.

## Comprobación antes de pasar a la siguiente tarea

Para todo cambio:

- [ ] Estilo, tipos y build pasan cuando corresponda.
- [ ] Se pensó qué casos no estaban contemplados en el requisito.
- [ ] No se eliminó ni debilitó ningún test.

Si el cambio requería TDD:

- [ ] Hay un test para el comportamiento implementado.
- [ ] Se comprobó que el test fallaba antes de implementar.
- [ ] El test pasa y la suite relevante pasa.

Si el cambio era visual:

- [ ] Se revisó el resultado visualmente.

Si algo de esto no se puede verificar, no continúes como si la tarea estuviera terminada. Dilo.

## Evidencia

Nunca afirmes que algo funciona sin evidencia. Si no puedes verificar algo, dilo de forma explícita y déjalo marcado como pendiente de verificación manual.

## Seguridad

- Las claves y secretos van en variables de entorno del servidor, nunca en el cliente ni en el repositorio.
- No imprimas ni registres valores secretos.
- Si una tarea toca permisos, pagos o datos personales, señálalo y pide revisión de una persona antes de darla por cerrada.

## Entorno de desarrollo

[Describe aquí lo que el agente debe saber de tu entorno: cómo ejecutar un solo fichero de test, limitaciones conocidas, qué suite es lenta, etc.]