Cómo planificar una aplicación con Claude Code antes de empezar a programar

Apliqué este proceso a un caso concreto: una aplicación de pronósticos para el Mundial de fútbol de 2026, hecha para jugar con amigos. Tiene reglas de puntuación, perfiles públicos, un cuestionario y se conecta con datos externos sobre los partidos. Las decisiones que tomé allí sirven de ejemplo para cualquier herramienta interna, ya sea un CRM, un panel de control o una aplicación de apoyo a un evento.

Cuando empezamos a usar herramientas de programación asistida, existe la tentación natural de ir directamente a la consola y ver cómo aparecen cosas en la pantalla. Pero programar sin pensar primero qué se quiere construir suele generar trabajo que hay que rehacer: descubres a mitad del proceso que faltaba una regla, tienes que reescribir partes enteras y acabas dedicando más tiempo que si te hubieras detenido cinco minutos antes.

Si quieres ir más allá de preguntar cosas a un chatbot y empezar a construir herramientas propias para el negocio, conviene leer también cómo usar la IA en el negocio más allá del chatbot. Pero construir software interno con criterio, además de prototipos que nadie usa, exige este paso de planificación antes de tocar el código.

Define primero el funcionamiento real del negocio

Antes de pensar en pantallas o botones, escribe con tus palabras qué tiene que hacer la aplicación y qué reglas rigen cada acción. Si solo pides «una aplicación de gestión», el modelo rellenará los vacíos con suposiciones genéricas que no corresponden a tu trabajo.

En el proyecto de pronósticos, empecé por describir la lógica de puntuación: si el usuario acierta el resultado exacto de un partido, gana seis puntos; si acierta el signo del partido y los goles de uno de los equipos, gana cuatro; si solo acierta el signo, gana tres; si falla el signo, pero acierta los goles de un equipo, gana un punto. Sin esta descripción detallada, la herramienta habría inventado cualquier lógica.

Había otras condiciones importantes que describir:

• Plazos de bloqueo: los envíos se cierran tres horas antes del primer partido de cada jornada, sin excepciones;
• Mecánica del «Joker»: cada participante elige un partido por jornada en el que los puntos obtenidos cuentan el doble;
• Datos automáticos: los resultados y horarios, en hora de Lisboa, proceden de una búsqueda realizada por la propia herramienta, sin que yo tenga que introducir nada manualmente;
• Niveles de acceso: existe un área de administración para gestionar códigos de invitación y publicar avisos, y un área de miembros más limitada.

Si intentas resumir todo esto en una sola frase, Claude Code olvidará reglas o calculará puntos de forma incoherente. Una manera sencilla de organizar las ideas es abrir un documento de texto y escribir todo lo que tienes en mente, en portugués corriente, sin preocuparte por que esté bien redactado. Lo importante es no dejar fuera ninguna regla.

Deja que el asistente cuestione tu idea

Cuando tengas un borrador escrito, pásaselo a un modelo conversacional y pídele explícitamente que encuentre fallos y preguntas que aún no has respondido. En lugar de pedir código de inmediato, usa esta fase para concretar decisiones que quizá no habías considerado. Aquí se evitan muchas sorpresas a mitad del trabajo.

Hago estas preguntas antes de ejecutar. No es una lista cerrada de preguntas que se hacen de una vez: el asistente plantea bloques de cinco o seis preguntas, tú respondes y cada respuesta puede generar nuevas preguntas. Cuando preparé la aplicación de apoyo a una formación presencial, este proceso implicó varios cientos de preguntas a lo largo de unas horas.

Un ejemplo hipotético del tipo de preguntas que pueden surgir: si estuvieras planificando un CRM interno, el asistente podría preguntarte qué ocurre cuando un lead lleva más de una semana sin respuesta o quién tiene permiso para eliminar registros. Son precisamente estas decisiones las que, si quedan sin responder, aparecen más tarde como errores.

Cuando surja una cuestión técnica para la que no tengas respuesta, no adivines. Explica el objetivo de negocio y pide dos o tres alternativas con sus ventajas y desventajas. La decisión final sigue siendo tuya, pero se apoya en algo más que una intuición.

Reúne las respuestas en un archivo de especificaciones y divide el trabajo en fases

Todas las respuestas deben consolidarse en un único documento, a menudo llamado SPEC.md, que sirva de referencia permanente para las herramientas de desarrollo. Esto evita que los requisitos importantes se pierdan durante el trabajo y ayuda a controlar el consumo de tokens, porque reduce los intentos fallidos.

Dedico una parte significativa del trabajo a planificar. Eso me ayuda a reducir las idas y vueltas durante la construcción, aunque sigo necesitando probar y corregir errores antes de publicar.

El archivo de especificaciones debe contener, como mínimo:

1. Objetivo y alcance: qué resuelve la aplicación y quiénes son los usuarios;
2. Estructura de datos: qué información se guardará y quién puede leer o modificar cada parte;
3. Arquitectura técnica: qué tecnologías y servicios externos se utilizarán;
4. Plan por fases: división del trabajo en bloques que puedas probar por separado.

En la aplicación de pronósticos, el plan se dividió en varias fases: primero la autenticación con códigos de invitación, después la estructura de la base de datos y, solo entonces, la lógica de puntuación y la presentación de los partidos. Cada fase se probó antes de avanzar a la siguiente. Pedirlo todo a la vez suele hacer que el modelo pierda el hilo a mitad del proceso.

Aporta referencias visuales concretas

Si no indicas nada sobre el aspecto que quieres, la herramienta tiende a usar componentes visuales genéricos, como los que se ven en muchos proyectos hechos con IA. Para evitarlo, muestra referencias visuales concretas y pide que se analicen y traduzcan en reglas de estilo antes de empezar a construir.

En el proyecto de pronósticos, usé como referencia una aplicación conocida de resultados deportivos. En lugar de hacer capturas de pantalla al azar, pedí al asistente que inspeccionara esa página y documentara los parámetros de diseño en un archivo propio: paleta de colores, tipo de esquinas de las tarjetas, jerarquía entre información secundaria y principal, y comportamiento en móviles.

Ese trabajo se convirtió después en reglas de CSS que guiaron la construcción de los componentes desde el principio, sin tener que reescribir estilos a mitad del proceso. Conviene recordar que no deben copiarse elementos como los logotipos o las marcas registradas de organizaciones deportivas; el objetivo es inspirarse en la estructura visual, no reproducir la propiedad de terceros.

Separa el papel de constructor del de auditor

Tener dos modelos diferentes editando el mismo código simultáneamente suele generar conflictos y pérdida de trabajo. Una forma más estable de trabajar es separar claramente los papeles: un asistente ejecuta y programa, y el otro lee el código y señala problemas, sin autorización para modificarlo.

Uso Claude Code como constructor principal y abro una segunda instancia, con Codex, solo para auditar lo que ya existe. La instrucción al auditor tiene que ser explícita: no puede editar nada en el disco, solo leer los archivos de contexto del proyecto y devolver un informe con sugerencias o problemas encontrados. Después decido qué trasladar al constructor para que lo aplique.

Al trabajar con este flujo, pedí a Codex sugerencias de gamificación basadas en la estructura existente, como insignias de perfil para quienes acertaran varios resultados seguidos. También surgió un pequeño problema: un vídeo de YouTube no cargaba por una política de seguridad de contenido. Al pasar el mensaje de error exacto a Claude Code, identificó la causa y corrigió la configuración.

Protege las credenciales antes de publicar

Publicar una aplicación online sin revisar la seguridad es uno de los errores con consecuencias más graves. Existen sistemas automáticos que revisan constantemente los repositorios públicos buscando claves de API expuestas, y que un repositorio haya sido «público solo unos minutos» no elimina ese riesgo.

Antes de publicar, conviene confirmar:

• que el archivo .gitignore excluye archivos con claves y variables de entorno;
• que existen reglas de permisos en la base de datos para que ningún participante vea o modifique datos ajenos fuera de lo permitido;
• que los campos introducidos por los usuarios se validan antes de guardarse;
• que hay límites de consumo definidos en las cuentas de servicios externos para evitar costos inesperados en caso de uso indebido.

Si una clave de acceso quedó expuesta, hacerla privada después no resuelve la exposición anterior. Revócala, crea una sustituta y comprueba dónde se estaba usando. Ocúpate de los accesos y los secretos durante la construcción, antes de poner la aplicación en internet.

Si estás estructurando procesos comerciales que dependen de datos fiables, conviene leer también cómo montar un embudo de leads que el equipo comercial pueda trabajar, porque la disciplina de organizar los datos antes de automatizar es similar.

Qué esperar de una primera versión

La planificación deja las decisiones principales por escrito: quién usa la aplicación, qué datos necesita y qué debe poder hacer. Cuando encuentres un error, vuelve a ese registro para entender si falló la ejecución o si faltaba aclarar una regla. Eso te da un punto de partida concreto para corregir.

No esperes que la primera versión de una herramienta interna sustituya de inmediato los procesos que ya existen en la empresa. Lo habitual es tener una base funcional, probarla con quienes la usarán a diario e ir ajustándola durante semanas, corrigiendo errores y añadiendo funciones a medida que surgen necesidades reales.

Aprender a estructurar bien estos documentos de planificación y proteger lo que construyes es una de las competencias más útiles en esta etapa. En Laboratório da IA y en mis formaciones, trabajo este proceso paso a paso, desde la idea inicial hasta la aplicación en producción.

Si estás preparando un proyecto interno, el siguiente paso práctico es sencillo: abre un documento en blanco, escribe todo lo que necesita hacer la aplicación sin preocuparte por la forma y, solo después, pásaselo a un asistente para que te haga preguntas antes de avanzar al código.

Cómo diseñar permisos por usuario y probar accesos denegados

Diseñar permisos empieza por enumerar quién usa la aplicación y qué necesita ver o modificar cada persona. Después de definir esos papeles, debes comprobar directamente si un usuario sin permiso queda bloqueado cuando intenta acceder a algo ajeno. No basta con asumir que la regla funciona porque la escribiste en la petición.

El primer paso es hacer una lista sencilla de los papeles existentes. En una aplicación hipotética para gestionar solicitudes de clientes, puedes tener tres: administrador, gestor de cuenta y cliente. El administrador ve todo, el gestor de cuenta solo ve a los clientes asignados y el cliente solo ve sus propias solicitudes. Escribir una frase por papel ya ayuda a la IA a construir las reglas correctas desde el principio.

Una vez definidos los papeles, tienes que decidir dónde se aplica ese permiso. No basta con ocultar un botón en la pantalla. Si la regla solo existe en la parte visual, alguien con conocimientos técnicos puede saltarse esa barrera y acceder a los datos mediante una petición directa al sistema. El permiso también tiene que verificarse donde se guardan y entregan los datos, no solo en lo que aparece en pantalla.

En el ejemplo hipotético de la aplicación de solicitudes, cuando el gestor de cuenta pide la lista de solicitudes, el sistema debe filtrar automáticamente por los clientes asignados a ese gestor, aunque intente pedir la solicitud de otro cliente mediante un enlace directo. Si el sistema devuelve esa solicitud solo porque se adivinó el enlace, el permiso falló, aunque la pantalla habitual ocultara esa opción.

Para probarlo en la práctica, crea cuentas de prueba para cada papel antes de dar por terminada la aplicación. Entra con la cuenta de cliente e intenta abrir la solicitud de otro cliente mediante su dirección directa, sin pasar por el menú habitual. Entra con la cuenta de gestor de cuenta e intenta ver clientes que no tenga asignados. Si consigues acceder a algo que no deberías, habrás encontrado un fallo antes de que lo descubra un usuario real por accidente o curiosidad.

Un criterio sencillo para decidir si un permiso está bien implementado es preguntar: si copio la dirección de esta página y se la envío a alguien sin ese permiso, ¿qué ocurre? La respuesta correcta es un mensaje de acceso denegado, no un contenido oculto únicamente porque no hay un enlace visible. Esta diferencia separa una aplicación segura de una que solo parece segura porque nadie intentó seguir el camino equivocado.

Cuando pidas a la IA que implemente estas reglas, explica el resultado esperado para cada caso de acceso denegado. En lugar de decir únicamente «solo el propietario puede ver la solicitud», pide que el intento de acceso de otro usuario produzca un mensaje claro y un registro de lo ocurrido, para poder confirmar después que se respetó la regla. Pedir a la IA una lista de los puntos donde se verifica el permiso ayuda a confirmar que no se quedó solo en la pantalla.

Conviene repetir esta prueba siempre que añadas una función nueva que afecte a datos sensibles, aunque el permiso ya funcionara. Un cambio en una parte de la aplicación puede abrir sin querer un camino nuevo que ignore la regla definida para otra parte. Este cuidado está directamente relacionado con la planificación y la revisión de seguridad que describo antes de publicar cualquier proyecto, incluido el trabajo que hago en Laboratório da IA y mis formaciones.

Cómo organizar una revisión de seguridad sin confiar en la opinión de la propia IA

Una revisión de seguridad solo sirve si produce una lista de comprobaciones concretas, realizadas una por una, y no una respuesta genérica de la IA diciendo que todo está bien. Necesitas probar credenciales, permisos y accesos como si fueras alguien externo que intenta entrar sin autorización.

El primer paso es separar la opinión de la comprobación. Si preguntas a la IA «¿es seguro?» y responde «sí, parece seguro», eso no te dice nada. Tienes que pedir una lista de puntos concretos: dónde se guardan las credenciales, si aparecen en el código o en archivos que podrían hacerse públicos, qué permisos tiene cada usuario en la base de datos y qué ocurre si alguien intenta acceder a un recurso al que no debería.

Imagina una aplicación interna para gestionar solicitudes de vacaciones. Antes de publicarla, entra con cuentas de empleados diferentes e intenta consultar las solicitudes de otra persona. Prueba también las rutas directamente y comprueba dónde están las credenciales. Una pantalla de administración oculta no demuestra que el acceso a los datos esté protegido.

Después de identificar esas preguntas, pide a la IA que compruebe cada una por separado y muestre el resultado, no una conclusión resumida. Por ejemplo, pídele que enumere todos los puntos del código donde se accede a datos de usuarios y confirme si cada uno valida la identidad de quien realiza la petición. Si la respuesta es vaga, insiste en ejemplos concretos del código, con el archivo y la línea correspondientes.

Un criterio sencillo para decidir si una comprobación está completa es que puedas repetir tú mismo la prueba sin la IA. Si dice que los permisos de la base de datos son correctos, entra en la plataforma que la aloja y confírmalo con tus propios ojos. Si dice que las credenciales no aparecen en el repositorio, busca en el historial de archivos enviados, no solo en el estado actual.

Otro punto que revisar es la separación entre información pública y privada. En una aplicación con área de administración, confirma que las pantallas privadas exigen autenticación antes de mostrar cualquier contenido y que esa comprobación ocurre en el servidor, no solo en la pantalla que ve el usuario. Alguien con conocimientos básicos puede saltarse una comprobación que solo exista en el lado visible.

También conviene probar qué ocurre cuando las cosas salen mal. ¿Qué devuelve la aplicación cuando alguien intenta acceder sin haber iniciado sesión? ¿Aparece un mensaje de error que revela detalles internos, como el tipo de base de datos o la estructura de las tablas? Los errores demasiado detallados pueden ayudar a encontrar fallos que de otro modo no se verían.

Después de esta lista de comprobaciones, haz una segunda revisión con alguien que no haya participado en la construcción, aunque sea de manera informal. Una persona externa suele probar caminos que quien construyó ni siquiera pensó en probar, precisamente porque desconoce las suposiciones hechas durante el desarrollo.

Este tipo de revisión está directamente relacionado con la planificación previa a la programación. Si las reglas de permisos y accesos quedaron bien definidas en el documento inicial, la revisión de seguridad tiene una base clara para confirmar si se respetaron. Si no se explicitaron, la revisión acaba descubriendo decisiones que deberían haberse tomado mucho antes.

Planifica qué hacer si algo falla antes de publicar

Antes de poner cualquier aplicación online, debes decidir qué ocurre cuando algo falla. Esto incluye guardar copias de los datos, saber cómo revertir una actualización y confirmar quién puede actuar si el sistema se detiene. Sin este plan, un problema pequeño puede convertirse en una crisis sin solución rápida.

Imagina, como ejemplo hipotético, una pequeña empresa que usa una aplicación interna para gestionar solicitudes de clientes, creada con apoyo de Claude Code. Antes de publicar, alguien tiene que responder preguntas sencillas: dónde se guardan los datos, con qué frecuencia se hacen copias de seguridad y quién tiene acceso para recuperarlas. Si esas respuestas no existen, la aplicación puede funcionar bien a diario y fallar justo cuando hace falta corregir un error grave.

El primer paso es definir la frecuencia de las copias de seguridad según el ritmo del negocio. Una aplicación que registra solicitudes varias veces por hora no puede depender de una copia semanal. En este ejemplo hipotético, tendría sentido preguntar al equipo cuántas horas de trabajo sería aceptable perder en el peor escenario y usar esa respuesta para decidir el intervalo entre copias.

Después de decidir la frecuencia, hay que confirmar dónde se guardan las copias y quién puede acceder a ellas. Guardarlo todo en el mismo lugar que la aplicación principal es un riesgo, porque un problema que afecte al sistema también puede afectar a la copia. Separar el almacenamiento de las copias del sistema en producción es una decisión que debe quedar escrita en el documento de planificación, junto a las demás reglas del proyecto.

La publicación también exige un plan de recuperación, además de las copias. Si una actualización introduce un error, el equipo necesita saber cómo volver a la versión anterior sin depender de prueba y error durante la crisis. Puede ser tan sencillo como guardar las versiones anteriores del código antes de cada actualización importante y probar previamente ese proceso de reversión, para no descubrir los problemas cuando ya es urgente.

Otro punto que decidir es quién se responsabiliza de actuar cuando algo falla fuera del horario de trabajo habitual. En una empresa pequeña puede ser una sola persona; en un equipo más grande, quizá haya que definir turnos o al menos un contacto de emergencia. Lo importante es que esta responsabilidad no quede implícita, porque en situaciones de estrés nadie quiere perder tiempo averiguando quién debe ocuparse del asunto.

También conviene probar el proceso de recuperación antes de que la aplicación esté en uso real, en lugar de confiar únicamente en que funcionará cuando haga falta. En el ejemplo hipotético de la aplicación de gestión de solicitudes, esto significaría simular una pérdida de datos en un entorno de pruebas y confirmar que la copia de seguridad puede restaurarse sin pérdidas inesperadas. Solo después de esa prueba el equipo puede confiar en el plan.

Estas decisiones deben registrarse en el mismo documento que las reglas de funcionamiento y los permisos de la aplicación, como mencioné antes. Separar la planificación de seguridad del resto del proyecto aumenta el riesgo de olvidarla una vez que la aplicación está publicada y funciona sin problemas visibles. Es precisamente en ese periodo de calma cuando los equipos tienden a prestar menos atención a las copias y la recuperación.

Por último, este cuidado no sustituye la revisión de seguridad que mencioné antes sobre credenciales, permisos en la base de datos y separación entre información pública y privada. Son capas diferentes del mismo trabajo: una protege frente a accesos indebidos y la otra frente a la pérdida o corrupción de información. Ambas deben existir antes de usar una aplicación en situaciones reales del negocio.