Por qué escribo la documentación antes que el código

Escribo la documentación antes que el código. No después, no a la vez. Antes.

Y no es disciplina ni buenas costumbres. Es que con una IA delante, la documentación ha dejado de ser el resumen de lo que hiciste y se ha convertido en la instrucción de lo que se va a hacer.

Ha cambiado el orden de las piezas, no solo el ritmo. Y creo que es el cambio más grande de trabajar así, más incluso que la velocidad.

¿Para qué documentar si la IA lee el código?

Esta es la objeción que me sueltan siempre, y tiene una respuesta corta.

La IA lee el código y sabe perfectamente qué hace. Lo que no sabe es por qué.

El código te dice que aquí se comprueba una cosa antes de guardar. No te dice que esa comprobación está ahí porque hace meses entraron datos malos y hubo que limpiarlos a mano durante una tarde. Sin ese porqué, cualquiera, humano o máquina, puede quitar esa línea en la siguiente refactorización y volver a meter el problema.

El código es el qué. La documentación es el por qué y el para quién. Y el por qué no está en ninguna parte salvo en tu cabeza, que es un sitio del que se borran cosas.

Hay una segunda razón, más práctica. Cuando le das contexto a un modelo, la calidad de lo que sale es proporcional a la calidad de lo que le has puesto delante. Si tu proyecto tiene escrito qué es, qué reglas sigue y qué no hay que tocar, la máquina acierta a la primera. Si no lo tiene, se inventa un criterio razonable que no es el tuyo, y tú te pasas la tarde corrigiendo decisiones que nunca habrías tomado.

El cambio de orden, en la práctica

Antes trabajaba así: pensar un poco, empezar a picar, ir viendo qué sale, y si el proyecto llegaba a algo, escribir un documento explicándolo. Que muchas veces no llegaba a escribirse.

Ahora trabajo así: escribo qué quiero, para quién, qué debe hacer y qué no debe hacer. Con eso delante, discuto el enfoque con la máquina antes de que se escriba una sola línea. Y solo cuando el documento aguanta, empezamos.

La diferencia no es de orden por gusto. Es que el documento hace de guion y evita el error caro, que no es escribir código malo. Es escribir código correcto para el problema equivocado.

Cuando te lanzas a construir directamente, te das cuenta del malentendido a las tres horas, cuando ya hay cosas hechas y te da pereza tirarlas. Cuando lo escribes antes, el malentendido aparece en el párrafo dos y corregirlo cuesta borrar una frase.

Esta separación entre pensar el plan y ejecutarlo la desarrollo entera en planificar antes de ejecutar con Claude Code, que es probablemente el hábito que más me ha cambiado la forma de trabajar.

Qué escribo exactamente antes de empezar

No son cuarenta páginas. Es media hoja y tarda quince minutos.

Qué es esto y para quién. Dos frases. Si no te salen dos frases claras, todavía no sabes qué estás construyendo, y eso es exactamente lo que querías descubrir antes de empezar.

Qué tiene que hacer. Cuatro o cinco puntos, en lenguaje normal, desde el punto de vista de quien lo usa. Nada técnico.

Qué NO tiene que hacer. Esta es la más valiosa y la que más gente se salta. Los límites explícitos evitan que el proyecto crezca solo. Y con una IA delante son oro puro, porque un modelo, si le dejas, te añade funciones que nadie ha pedido con un entusiasmo notable.

Las decisiones tomadas y por qué. Dónde viven los datos, qué se usa y qué se descartó. Con el motivo. Este apartado es el que te salva dentro de seis meses.

Lo que se rompe fácil. Los sitios delicados, lo que ya falló una vez, lo que hay que probar siempre antes de dar algo por bueno.

Con eso, cualquiera que llegue al proyecto, seas tú dentro de un año o un modelo dentro de un minuto, sabe dónde está.

Y una cosa que aprendí a base de escribir documentos que luego nadie leía: hay que actualizarlo en el momento en que se toma la decisión, no en una revisión posterior. La revisión posterior no llega nunca. Si cambias de criterio un martes, esas dos líneas se cambian ese martes o el documento empieza a mentir, que es peor que no tenerlo.

El archivo de instrucciones del proyecto

En Claude Code esto tiene un sitio concreto: un archivo de instrucciones que se lee antes de cada sesión. Es el manual del proyecto y es lo primero que creo.

Ahí van las reglas que no quiero repetir cada vez. Cómo se llaman las cosas, qué estilo se usa, qué está prohibido tocar, qué hay que hacer antes de dar algo por terminado. Cada regla que escribes ahí es una corrección que ya no vas a tener que hacer nunca más.

Cómo escribirlo bien, con lo que funciona y lo que sobra, lo tengo desarrollado en cómo escribir tu archivo de instrucciones. Y el aviso principal es este: menos es más. Un documento corto que se lee entero vale mucho más que uno enorme del que se ignora la mitad.

Lo importante conceptualmente: ese archivo no es documentación de acompañamiento. Es la instrucción principal. Cuando trabajas así, editar el documento es editar el comportamiento del proyecto, y eso es una sensación bastante distinta de la de escribir un README por obligación.

Y esto no va solo de programar

Uso el mismo orden para cosas que no tienen ni una línea de código.

Cuando monto un proceso nuevo, escribo primero qué tiene que pasar y en qué orden. Cuando preparo una serie de contenido, escribo primero de qué va y qué no va a tocar. Cuando organizo cualquier sistema, escribo primero las reglas.

Y es porque el beneficio real no está en el documento. Está en que escribir te obliga a decidir. Puedes tener una idea vaga en la cabeza durante semanas y sentir que la tienes clara. En cuanto la escribes en cinco frases, aparecen los tres huecos que llevabas semanas rodeando.

Por eso mucha gente que no programa acaba usando estas herramientas para exactamente esto. Lo cuento en Claude Code para no programadores: la mayor parte de lo que yo hago no es código, es documentación viva de cómo funcionan mis cosas.

Cuándo no lo hago

No lo hago cuando estoy explorando.

Si voy a probar si algo es posible, si estoy trasteando con una herramienta nueva o si el objetivo es aprender, escribir el documento antes es un lastre. Ahí toca hacer un cacharro rápido, ver qué pasa y tirarlo.

La documentación entra cuando el cacharro se convierte en algo que va a durar. Y esa transición hay que hacerla a propósito, porque si no, lo que pasa es que el experimento del martes acaba en producción sin que nadie lo haya decidido, y ese es el origen de la mitad de los problemas que arrastran los proyectos.

Ese momento tiene una señal clarísima: la primera vez que abres el proyecto y tardas más de un minuto en acordarte de cómo funcionaba. Ahí ya no es un experimento. Ahí toca escribir.

Si quieres montar tus proyectos y tus procesos de esta forma, con la documentación mandando y la IA ejecutando, es justo lo que enseño en Yo SA.

Ver Yo SA