Cómo gestionar proyectos con Claude Code y documentación

Te dejo el vídeo arriba, pero aquí lo tienes escrito y con calma.

Me pedíais un ejemplo real. No otra explicación de cómo uso la IA, sino verme construir algo de cero en mi web, en directo. Así que grabé la creación de un recurso nuevo: una calculadora de calorías que quería montar como lead magnet.

Y ojo, porque el recurso es lo de menos. Lo importante es lo que hay detrás. Que no es magia, ni un prompt milagro. Es un sistema de documentación.

¿Por qué la mayoría falla usando IA para construir cosas?

Porque le piden a la IA que se lea el código para averiguar qué hace algo. Y desde el código, intuyendo, se cometen errores.

Es mucho mejor que lea el lenguaje humano. Cómo funciona un sistema explicado en palabras. Y solo después, si hace falta, que baje al código a ver cómo está hecho al dedillo.

Cuando lo haces al revés, pasa lo típico: le dices "crea esto" y te vuelve a programar desde cero una funcionalidad que ya tenías. ¿Por qué replica el código otra vez si ya existe? Porque no sabe que existe. Nadie se lo ha contado.

La documentación es justo eso: contárselo antes de que empiece.

Mi sistema: un cerebro digital lleno de documentación

Tengo un proyecto que llamo el planificador. Es una carpeta con muchas carpetas dentro, todas en Markdown, donde tengo documentado absolutamente todo sobre mis negocios y sobre cómo funciono.

Es mi cerebro digital. El sitio donde vive el "cómo se hacen las cosas aquí".

Y dentro tengo skills. Cada skill se encarga de una cosa: una gestiona el servidor web, otra un negocio concreto, otra lleva el tema de la pérdida de peso. Cada una accede solo a la parte de documentación que le toca, y ahí lee, escribe y hace lo que tiene que hacer.

No es que todas las skills lo vean todo. Cada una tiene su parcela. Así de simple.

El truco: código en un repo, documentación en otro

Esto es clave. El código de mi web está en un repo de Git. La documentación de cómo funciona esa web está en otro sitio, dentro del planificador.

Por un lado tienes el código. Por otro, la explicación en lenguaje humano de cómo funciona cada parte, con bastante profundidad.

Con las dos cosas juntas, la IA sabe cómo funciona todo a un nivel de detalle bestial. Y eso me evita muchos, muchos errores al programar. Acierta muchísimo más. Y cuando tengo que replicar algo, es facilísimo, porque ya ve cómo está preparado y no repite código.

Si quieres montar esa pieza del sistema, aquí te cuento cómo escribir tu CLAUDE.md para que la IA no se pierda, y por qué uso Claude Code más para documentos y notas que para picar código.

Cómo creé la calculadora, paso a paso

Lancé la skill de servidor web y le dije, más o menos, esto:

Quiero un recurso nuevo, una calculadora de metabolismo basal. La diferencia con las 30.000 que hay por internet es que no mete el NEAT, es decir, el movimiento del día a día. La mayoría de calculadoras te preguntan si tienes vida sedentaria y ya te suman unas calorías de más. Y cuando te lo tomas literal, tu cuerpo quema menos de lo que te dicen, sobreestimas el déficit y luego no cuadra nada.

Yo lo dejo en el metabolismo basal puro. Lo que tu cuerpo consume solo por estar vivo. Y a partir de ahí sumas todo lo que te muevas, los pasos y el ejercicio consciente, aparte.

Aviso: esto es lo que a mí me funciona, no soy médico, y si un experto en fitness me lee igual me echa a los lobos. Pregunta a un profesional. Yo cuento lo mío.

Le dije también que para entender bien el cálculo le preguntara a la skill de fitness, que ya tiene una fórmula funcionando dentro de un sistema de gamificación que uso. ¿Para qué va a reinventar la fórmula si ya la tengo hecha? La skill de fitness se la pasa y listo.

Y le añadí un par de reglas: el recurso va en la página de recursos, cualquiera puede calcular, pero para ver el resultado hace falta email. Un email gate, igual que en los tests. Esos correos se guardan con el interés de fitness para un funnel que crearé más adelante.

Le di al enter, y a partir de ahí trabajó solo.

¿Qué hizo la IA sola después de darle al enter?

Lo primero, entender el encargo. Cuando le digo "crea un recurso", ya sabe que eso vive dentro de la página de recursos, así que se va a la documentación de infraestructura, lee cómo se crea un recurso y sigue el patrón.

Lanzó la skill de fitness como agente para que le devolviera cómo funciona el cálculo. Con eso, servidor web se puso a construir. Aquí tienes más sobre cómo funcionan los subagentes de Claude Code cuando varios trabajan a la vez.

Escribió el código en el repo de la web, no en el de documentación. Creó los tests, la migración, el email gate idéntico al de los tests, y la persistencia: guarda el resultado y mete una entrada en el diario interno del usuario. Al volver a entrar, te muestra el último cálculo y te deja recalcular con los datos rellenos, porque depende de tu peso.

Cambió el slug del recurso a "calorías" en vez de "calculadora metabolismo", que se busca mejor, y creó las redirecciones para que las dos rutas apunten al recurso.

Se quedó vigilando el deploy con un monitor. Y mientras terminaba, se puso a documentar todo lo que había hecho en el repo de documentación. Sin que se lo pidiera. Ya es un patrón: sabe que siempre le pido la documentación, así que la crea sola.

Pasó los 1.645 tests, aplicó la migración sin romper nada, generó la portada con otra skill y la subió a Cloudflare R2. Calculadora desplegada y verificada en producción.

Yo, mientras tanto, me fui a beber agua.

¿Y esto por qué funciona tan bien?

Porque no hace falta volverse loco con prompts raros. Hace falta un buen sistema de documentación del que la IA tire, y unas skills que sepan leer cada una su parte y actuar.

Y aquí va lo importante: tienen que ser tus skills y tu documentación. No las que te bajas de internet. Las tuyas, de tus proyectos, de lo que tú quieres hacer.

Cada skill se especializa. Unas leen cierta documentación, otras se conectan a herramientas, APIs o MCPs, y cuando una necesita algo de otra, le pasa el contexto y ya está. Esto sirve igual para montar una web que para llevar el registro de lo que comes cada día.

Al final todo se reduce a lo mismo. Hay problemas reales que piden soluciones reales. Y cuando lo entiendes y lo aplicas bien, las cosas empiezan a funcionar.

Si quieres ver más de cómo trabajo con la terminal, esta es mi guía de Claude Code para no programadores.

Herramientas que salen en el vídeo

• Claude Code: la terminal desde la que lanzo las skills y trabajo con toda la documentación.
• Cloudflare R2: donde se sube la portada del recurso.

Aprender a montar todo esto (la documentación, las skills, los agentes, el sistema entero) es justo lo que enseño en Yo S.A.. No a crear una web, sino a todo lo que hay detrás para que luego crear una web sea así de simple.