wilmargarcia.md: Como Converti Toda Mi Experiencia en un Harness para Desarrollar con IA

Durante años pense que mi activo mas valioso como developer era el codigo que escribia. Estaba equivocado. Mi activo mas valioso es la forma en que decido que construir, como estructurarlo y cuando parar. Y todo eso vivia en mi cabeza: sin documentar, imposible de delegar y, lo peor, imposible de escalar.

Este post trata sobre como saque toda esa experiencia de mi cabeza y la puse en un solo archivo markdown: wilmargarcia.md. Pero no es solo la historia de un archivo. Es una guia de como construir el tuyo, porque estoy convencido de que en los proximos años este va a ser uno de los documentos mas importantes que un developer pueda tener.

Voy a mezclar las dos cosas a proposito: la reflexion de por que esto importa y el manual practico de como hacerlo. Al final quiero que te vayas con dos cosas: una idea nueva de cual es tu verdadero trabajo, y los pasos concretos para empezar hoy.

El Cambio de Oficio

Cuando empece a desarrollar con IA en serio, note algo incomodo. El modelo escribia codigo mas rapido de lo que yo podia revisarlo, pero producia decisiones que yo nunca habria tomado. Refactorizaba cosas que no pedi. Inventaba features. Elegia librerias que no uso. Hacia commits por su cuenta. Cada sesion empezaba de cero, como si nunca hubieramos trabajado juntos.

El problema no era el modelo. El problema era que yo no le habia dado contexto. Le estaba pidiendo que actuara como yo sin haberle dicho nunca quien soy ni como trabajo. Es como contratar al mejor developer del mundo, sentarlo frente a tu codigo, no decirle absolutamente nada de tu negocio ni de tus reglas, y molestarte porque no adivina.

Ahi entendi que mi oficio habia cambiado. Ya no me pagan principalmente por teclear codigo. Me pagan por el criterio: saber que se construye, en que orden, con que restricciones y bajo que estandar de calidad. El codigo es la salida. El criterio es el activo.

La pregunta entonces fue tan simple como incomoda: si el criterio es lo valioso, como lo hago portable? Como saco de mi cabeza algo que ni yo tenia escrito, y lo pongo en un formato que una maquina pueda leer y respetar cada vez que trabajemos juntos?

Que es Harness Development

La respuesta la encontre en un enfoque que cada vez suena mas entre quienes desarrollamos con IA: el Harness Development. Y la mejor forma de entenderlo no es pensando en software, sino en un caballo.

La palabra harness viene justo de ahi: es el arnes, las riendas y la montura con que se guia a un caballo. Asi que piensa en un caballo de carreras. Es puro poder: fuerza, velocidad, un motor vivo capaz de cosas que ningun humano hace por su cuenta. Pero un caballo sin riendas no gana carreras. Corre hacia donde quiere, se espanta, te tira, o se lanza de frente contra un muro. Toda esa potencia, sin direccion, es un peligro antes que una ventaja.

Las riendas no hacen al caballo mas lento. No le quitan fuerza. Solo le dan rumbo. Un buen jinete no gana por tener el caballo mas fuerte, sino por saber guiar la fuerza que el caballo ya tiene. Ese es el trato: el caballo pone el poder, tu pones la direccion.

Con la IA es identico. El modelo es el caballo: potente pero ciego. No conoce tu proyecto, tus convenciones, tu cliente ni tus limites. Sueltalo sin riendas y correra a toda velocidad hacia el lugar equivocado, con la mejor de las intenciones. El harness son las riendas: todo lo que construyes alrededor del modelo para que su potencia apunte a donde tu quieres, sin quitarle un gramo de fuerza:

• Las reglas que nunca debe romper (no hacer commits solo, no refactorizar fuera de scope, no inventar features).
• El contexto de quien eres y como trabajas.
• Los agentes especializados que ejecutan cada parte del flujo.
• Las herramientas que puede usar y las que tiene prohibidas.
• Los puntos de control donde tu, humano, decides antes de continuar.

Desarrollar con IA de forma seria no es escribir prompts mas inteligentes. Es construir el harness. Dejas de ser el caballo y pasas a ser el jinete: el arquitecto del sistema que escribe las lineas por ti, bajo tus reglas. El prompt es un tiron puntual de la rienda; el harness es la montura permanente dentro de la cual cada tiron tiene sentido.

Y el corazon de ese harness, la pieza que lo hace mio y no de cualquiera, es un documento: wilmargarcia.md.

Recomendacion: deja de medir tu productividad con IA por que tan buenos son tus prompts. Un buen prompt te da un buen resultado una vez. Un buen harness te da buenos resultados siempre, incluso cuando estas cansado, con prisa o le pasas el proyecto a otra persona.

Spec-Driven Development: El Flujo que Rodea al Archivo

Antes de abrir el archivo, tengo que explicar el flujo que lo rodea, porque el contexto sin flujo no sirve de nada. Un documento perfecto que nadie consume es un documento muerto.

Adopte lo que se conoce como Spec-Driven Development (SDD): desarrollo guiado por especificaciones. La idea es simple pero lo cambia todo. En vez de saltar directo al codigo, primero se escribe un spec: un documento tecnico que define que se va a construir, por que, con que criterios de aceptacion y bajo que restricciones. El codigo es la consecuencia del spec, no al reves.

Suena a burocracia hasta que lo vives con IA. Con un humano, el spec compite con la intuicion del developer, que muchas veces acierta sin documentar nada. Con IA es distinto: el modelo no tiene tu intuicion, pero ejecuta un spec claro con una fidelidad que ningun humano cansado alcanza. El spec deja de ser papeleo y se convierte en el plano exacto que la maquina construye.

En mi harness el flujo tiene tres comandos:

/spec "descripcion"   → escribe el spec y lo crea como tarea en el kanban
/specs                → consulta el board y recomienda que implementar
/implement <task-id>  → ejecuta el spec con control humano en los puntos clave

Cada comando esta respaldado por un agente especializado, y esto es clave: no uso un solo agente que lo hace todo, uso varios que hacen bien una cosa.

Spec Writer recibe una descripcion de feature, lee el codigo real del proyecto para entender el contexto, hace preguntas aclaratorias y escribe el spec tecnico completo. No adivina: si algo no esta claro, pregunta antes de escribir una linea de spec.

Tech Lead consulta el kanban central, analiza prioridades y decide que vale la pena implementar ahora. Es el agente que responde a la pregunta "que sigue" sin que yo tenga que reconstruir el estado del proyecto en mi cabeza.

Implementer toma un task-id, obtiene el spec, hace un gap analysis contra el codigo que ya existe, implementa de forma acotada y reporta el resultado. Nunca cambia el estado de una tarea sin confirmarmelo primero.

El estado de todo vive en un kanban central. Los specs no son documentos muertos en una carpeta: son tareas vivas que se mueven por un board y se sincronizan con endpoints reales. Cualquier agente, en cualquier sesion, puede consultar en que punto quedo el trabajo.

Fijate en la flecha que regresa del kanban hacia mi: HITL (Human In The Loop). En los puntos que importan (declarar el scope antes de implementar, mover una tarea de estado) el sistema se detiene y me pregunta. La IA propone; yo decido. Ese es el limite que nunca negocio, y lo explico en detalle mas adelante porque es el error que veo cometer a mas gente.

Anatomia de wilmargarcia.md

Aca es donde todo converge. wilmargarcia.md es el archivo donde condense mi forma de trabajar para que cualquier agente del harness la herede como si fuera yo.

No es un README. No es documentacion del proyecto. Es mi documento: la destilacion de años de decisiones tecnicas en un formato que una maquina puede leer antes de escribir una sola linea. El proyecto tiene su propio contexto; este archivo tiene el mio, y viaja conmigo entre proyectos.

Lo divido en cuatro bloques. Estos son los mismos bloques que te recomiendo para el tuyo.

1. Quien soy y que hago

El contexto de la empresa, los servicios, el cliente ideal. Un agente que sabe que construyo ecommerce a la medida para el mercado colombiano toma decisiones distintas a uno que no lo sabe. La integracion con PSE, Wompi o WhatsApp no es un detalle tecnico: es el negocio. Cuando el modelo entiende el negocio, sus sugerencias dejan de ser genericas y empiezan a servir.

2. Como trabajo

Las convenciones de codigo, el stack por defecto, la estructura de archivos, el gestor de paquetes que uso. Cosas que yo doy por obvias pero que un modelo nunca adivinaria. Si tu proyecto usa pnpm y no npm, el modelo tiene que saberlo antes de sugerirte un comando, no despues de romperte el lockfile.

3. Que nunca debe pasar

Las reglas duras: no commits automaticos, no refactorizar fuera del scope, no añadir features que no pedi, no mover tareas sin mi confirmacion. Estas reglas son mas importantes que cualquier instruccion positiva, porque definen los limites del sistema. Es mas facil confiar en un agente que sabe lo que no debe hacer que en uno al que solo le dijiste lo que si.

4. Como fluye el trabajo

El sistema SDD completo: los comandos, los agentes, el kanban, los endpoints. El mapa de como una idea se convierte en codigo en produccion. Este bloque es el que conecta el archivo con el flujo del que hablamos arriba.

Todo eso en un solo archivo. Esa fue una decision deliberada, y vuelvo sobre ella mas abajo porque es una de las cosas que mas me han preguntado.

Como se ve por dentro

La teoria suena bien, pero lo que de verdad ayuda es ver el archivo. Este es un fragmento simplificado del mio, para que tengas algo concreto que copiar hoy:

# wilmargarcia.md

## Quien soy
Developer y fundador de WillDevp. Construyo ecommerce a la medida
para el mercado colombiano. Cliente ideal: negocios que venden por
redes y quieren su propia tienda, sin comisiones por venta.

## Stack por defecto
- Next.js 15 (App Router) + TypeScript
- Tailwind + shadcn/ui
- Convex (backend) + Clerk (auth)
- Gestor de paquetes: pnpm (nunca npm)
- Pagos: Wompi / PSE

## Reglas duras (nunca)
- No hagas commits por tu cuenta.
- No refactorices fuera del scope de la tarea.
- No agregues features que no pedi.
- No cambies dependencias sin avisar.
- No muevas tareas del kanban sin mi confirmacion.

## Como decido
- Primero el spec, despues el codigo.
- Si algo no esta claro, pregunta antes de asumir.
- Prefiero poco codigo legible sobre mucho codigo "inteligente".

## Puntos de control (HITL)
- Declara el scope antes de implementar.
- Confirma antes de cualquier accion destructiva.

Fijate que no hay nada sofisticado. Son frases cortas, en imperativo, que cualquiera podria leer en un minuto. Esa es la idea: el archivo no impresiona, funciona. Su valor no esta en la prosa, esta en que cada linea le ahorra al modelo una decision equivocada.

Guia: Como Construir Tu Propio .md

Hasta aca la reflexion. Ahora el manual. Si te convencio la idea, esto es lo que haria yo si empezara desde cero hoy. No necesitas mi stack ni mi negocio: necesitas el tuyo, escrito.

Paso 1: Empieza por las reglas duras, no por el contexto

La tentacion es empezar describiendote a ti mismo. No lo hagas. Empieza por lo que el modelo nunca debe hacer, porque esas son las lineas que mas dolor te ahorran. Abre el archivo y escribe cinco reglas que hoy te frustran de la IA. Las mias empezaron asi: no hagas commits solos, no refactorices fuera del scope, no inventes features, no muevas tareas sin confirmar, no cambies dependencias sin avisar.

Recomendacion: cada vez que la IA haga algo que te moleste, no solo lo corrijas en el chat. Vuelve al archivo y escribe la regla que lo habria evitado. Tu .md crece mejor por frustracion documentada que por planeacion perfecta.

Paso 2: Documenta tu stack por defecto

Escribe lo que usas sin pensar: framework, lenguaje, gestor de paquetes, librerias de estilo, patron de carpetas. Todo lo que para ti es automatico y para el modelo es una loteria. Se especifico. "Uso React" no basta; "Next.js 15 con App Router, TypeScript, Tailwind y componentes shadcn/ui, gestor pnpm" le quita al modelo diez decisiones equivocadas.

Paso 3: Describe tu flujo, no solo tus herramientas

Una lista de herramientas no dice como las usas. Describe el flujo: como pasa una idea de tu cabeza al codigo en produccion. En que orden. Que revisas antes de mergear. Donde paras a pensar. Aunque no tengas un sistema SDD como el mio, tienes un flujo, aunque este solo en tu cabeza. Escribirlo es la mitad del valor de todo este ejercicio.

Paso 4: Define roles, no un solo asistente

Si algo aprendi es que un agente que hace todo lo hace todo a medias. Divide el trabajo en roles con responsabilidades claras: uno que planea, uno que prioriza, uno que ejecuta. No necesitas construir agentes sofisticados desde el dia uno; puedes empezar simplemente diciendole al modelo "ahora actua como el que escribe el spec, no como el que programa". La separacion mental ya mejora los resultados.

Paso 5: Marca tus puntos de control humano

Decide explicitamente donde la IA debe detenerse y preguntarte. Antes de implementar, para declarar el scope. Antes de tocar algo destructivo. Antes de mover una tarea. Escribe esos puntos en el archivo. Un harness sin puntos de control es un caballo desbocado: veloz hasta el accidente.

Errores que Cometi (Para que Tu No los Cometas)

Quise escribirlo perfecto de una. Perdi semanas planeando la estructura ideal antes de escribir una linea util. El archivo mejora usandolo, no planeandolo. Escribe una version fea hoy y corrigela mañana.

Lo llene de instrucciones positivas y pocas prohibiciones. Al principio le decia al modelo todo lo que si debia hacer y casi nada de lo que no. El resultado fue un agente entusiasta que se salia del carril con las mejores intenciones. Las prohibiciones pesan mas que las instrucciones.

Confie sin puntos de control. Hubo una etapa donde deje que el sistema corriera solo para ir mas rapido. Fui mas rapido hacia los errores. El HITL no es falta de confianza en la IA; es respeto por las decisiones que solo un humano debe tomar.

Lo reparti en muchos archivos. Tuve una version del harness dividida en diez documentos "bien organizados". Nadie los mantenia porque ensamblarlos era un trabajo en si mismo. Volvi a un archivo que se lee de arriba a abajo y el harness revivio.

Que NO Poner en Tu .md

Escribir tu criterio no significa escribirlo todo. Hay cosas que no van en este archivo, y confundirlas es peligroso.

• Secretos y credenciales. Nada de tokens, llaves de API, contraseñas ni cadenas de conexion. El .md vive en git y se comparte; tratalo como codigo publico, no como una boveda.
• Datos de clientes. Nombres, contratos, informacion sensible de proyectos. El archivo describe como trabajas, no con quien.
• Detalles que cambian cada semana. La version exacta de cada dependencia o el estado de una tarea puntual viven en el proyecto o en el kanban, no en tu perfil. El .md es para lo estable: tu criterio, no tu backlog.
• Reglas que no piensas hacer cumplir. Una regla que escribes pero ignoras entrena al modelo a ignorar tus reglas. Mejor pocas reglas que respetas que muchas decorativas.

La prueba es simple: si te incomodaria que ese texto apareciera en un pull request publico, no va en el .md.

Por Que un .md y No una App

Me han preguntado por que no construi una herramienta, un dashboard, algo con interfaz. La respuesta es que el markdown es la interfaz correcta para este problema.

Un .md es texto plano. Vive en git, versiona con mi codigo, se revisa en un pull request, se lee en cualquier editor y no depende de ninguna plataforma. Si mañana cambio de modelo, de proveedor o de herramienta, wilmargarcia.md sigue funcionando, porque todo lo que consume markdown puede leerlo. Una app que construyeras para esto envejeceria; el texto plano no.

Invertir mi experiencia en un .md en lugar de en una app fue una apuesta por la durabilidad. Las apps se rompen. Los formatos cerrados mueren. Las plataformas cambian sus terminos. El texto plano es para siempre, y es lo unico que todos los modelos, presentes y futuros, saben leer.

Hay algo casi ironico en esto: pase años aprendiendo a construir sistemas complejos, y la pieza mas valiosa que he producido es un archivo de texto. Pero tiene todo el sentido. La complejidad nunca estuvo en el codigo. Estaba en el criterio. Y el criterio, cuando por fin lo escribes bien, cabe en un markdown.

Recomendacion: guarda tu .md en git y versionalo como versionas tu codigo. Cada cambio de regla es un commit. Con el tiempo, el historial de ese archivo se vuelve el mapa de como evoluciono tu forma de pensar como developer. No conozco documentacion mas valiosa que esa.

Objeciones que Me Han Hecho

Cada vez que cuento esto, aparecen las mismas preguntas. Las respondo de frente.

"Esto no es solo un CLAUDE.md o un system prompt con otro nombre?" Se parecen, pero no son lo mismo. Un system prompt o un archivo de configuracion pertenece a la herramienta: si cambias de herramienta, se queda. wilmargarcia.md es mio. Viaja entre proyectos, entre herramientas y entre modelos, porque es solo texto que yo controlo. La herramienta lo consume; no lo posee. El dia que aparezca un modelo mejor, mi criterio se muda con un copy-paste.

"No es mas rapido simplemente corregir a la IA en el chat?" La primera vez, si. La decima vez que corriges el mismo error, no. El chat corrige un caso; el .md corrige la clase entera de casos. Cada regla que escribes es un error que no vuelves a explicar nunca.

"Y si el modelo ignora lo que dice el archivo?" Pasa, y por eso existen los puntos de control. El .md inclina la balanza; el HITL atrapa lo que se escapa. No busco un sistema perfecto, busco uno que falle en los lugares donde yo estoy mirando.

"Esto no me encierra en una sola forma de trabajar?" Al reves. Como es texto en git, cambiar de opinion es un commit. Un criterio escrito es mas facil de cuestionar que uno que solo vive en tu cabeza, porque por fin lo puedes leer y discutir. Lo que no esta escrito no se puede mejorar.

Como Saber si Tu Harness Funciona

Un harness no se mide por lo bonito que se ve, sino por lo que deja de pasar. Estas son las señales de que el tuyo esta funcionando:

• Repites menos. Dejas de explicar las mismas cosas en cada sesion. Si notas que copias y pegas el mismo contexto una y otra vez, eso pertenece al .md.
• La IA se sale menos del carril. Las sorpresas desagradables (features inventadas, refactors no pedidos, commits sueltos) bajan de frecuencia hasta volverse raras.
• Revisas distinto. Dejas de vigilar cada linea buscando desastres y empiezas a revisar decisiones. Tu atencion se mueve de "que rompio" a "esto era lo correcto".
• Alguien mas puede tomar el mando. Si le pasas el proyecto a otra persona y el sistema sigue comportandose como tu quieres, tu criterio de verdad se volvio portable.

Si ninguna de estas cambia despues de un tiempo, tu .md probablemente esta lleno de buenas intenciones y pocas reglas ejecutables. Vuelve a el y hazlo mas concreto: menos adjetivos, mas limites.

Recomendacion: una vez al mes, revisa las correcciones que le hiciste a la IA en el chat. Cada correccion repetida es una regla que todavia no escribiste. Ese es el mejor combustible para que tu harness siga creciendo.

Que Gane

El resultado es un sistema donde mi experiencia dejo de estar atrapada en mi cabeza. Cuando abro una sesion nueva, el agente ya sabe quien soy, como trabajo y que no puede hacer. No repito el contexto. No corrijo los mismos errores. No vigilo cada linea esperando que se salga del carril.

Gane velocidad, pero eso es lo de menos. Lo que de verdad gane fue consistencia: cada tarea se ejecuta bajo el mismo criterio, el mio, sin importar la hora ni el cansancio. Y gane portabilidad: mi forma de trabajar ya no depende de que yo este presente y atento en cada decision.

El costo fue el tiempo de sentarme a escribir lo que nunca habia escrito: por que hago las cosas como las hago. Fue mas dificil que programar. Obligarte a articular tu criterio te muestra, sin piedad, cuanto de el era intuicion sin fundamento y cuanto era experiencia real. Ese ejercicio, incluso si nunca lo leyera una maquina, me hizo mejor developer.

El Siguiente Nivel: Un Equipo Entero en Markdown

Todo lo que conte hasta aca es sobre un solo developer: yo. Pero la idea no se detiene en una persona. Si mi criterio cabe en un .md, el de cada miembro de un equipo tambien. Y ahi es donde esto deja de ser un truco personal para convertirse en una forma de operar un equipo completo.

Imagina que cada developer del equipo tiene su propio archivo: wilmargarcia.md, ana.md, carlos.md. No es documentacion de recursos humanos ni una evaluacion de desempeño. Es un perfil tecnico vivo que describe, para cada persona:

• Su nivel y especialidad: frontend senior, backend, devops, movil.
• Sus fortalezas: en que es rapido y confiable.
• Sus puntos ciegos: los errores que tiende a cometer, las cosas que suele olvidar.
• Sus convenciones personales: como nombra, como estructura, que patrones prefiere.
• Su foco de revision: que hay que mirar con lupa cuando esta persona toca el codigo.

Con eso, el harness deja de conocer a un solo developer y pasa a conocer al equipo entero.

Revision de PRs que conoce al autor

La pieza que mas valor genera es la revision automatizada de pull requests. Hoy la mayoria de reviewers con IA revisan todos los PRs igual, sin saber quien los escribio. Es como si un revisor humano leyera cada PR habiendo olvidado por completo con quien trabaja y que sabe hacer cada quien.

Cuando el reviewer lee el .md del autor antes de revisar, todo cambia. Si el perfil de Carlos dice que tiende a olvidar el manejo de errores en las llamadas a la API, el reviewer pone la lupa justo ahi. Si el de Ana dice que es fuerte en accesibilidad pero nueva en el backend, el reviewer confia en su markup y examina con mas cuidado sus queries. La revision deja de ser generica y se vuelve personal, calibrada a la persona real detras del commit.

No se trata de reemplazar la revision humana. Se trata de darle al equipo un primer revisor que nunca se cansa, que conoce a cada quien, y que deja a los humanos solo lo que de verdad necesita ojo humano. El senior deja de gastar su atencion en atrapar el mismo error de siempre y la invierte en las decisiones que si importan.

El harness compartido

Cuando cada dev tiene su .md y el equipo comparte unas reglas globales, pasa algo interesante: el conocimiento del equipo deja de vivir solo en las cabezas de los seniors. Un dev nuevo que entra no hereda el criterio del equipo en seis meses de osmosis; lo hereda el primer dia, porque esta escrito. El onboarding deja de ser "preguntale a fulano cuando puedas" y pasa a ser "leelo, ya esta en los archivos".

Y como todo es texto plano en git, el criterio del equipo evoluciona con pull requests, igual que el codigo. Cambiar como trabaja el equipo se vuelve una propuesta revisable y discutible, no un correo que nadie abre. El equipo entero, con sus fortalezas, sus manias y su forma de decidir, se vuelve versionable.

Recomendacion: si lideras un equipo, no impongas los .md desde arriba. Pide a cada dev que escriba el suyo, empezando por sus propios puntos ciegos. Un perfil que la persona escribe sobre si misma se usa; uno que le imponen, se ignora.

Cierre

Harness Development no es la moda de escribir mejores prompts. Es reconocer que, cuando la IA escribe el codigo, tu verdadero trabajo es construir el sistema que la guia. Y Spec-Driven Development es el flujo que le da forma a ese sistema: primero el criterio, despues el codigo.

wilmargarcia.md es mi respuesta personal a una pregunta que todo developer va a tener que responder pronto: cuando la maquina escribe el codigo, que aportas tu? Mi respuesta es el criterio. Y lo escribi en un archivo, para que no muera conmigo cada vez que cierro el editor.

Si eres developer, mi consejo final es este: empieza tu propio .md. No el de tu proyecto, el tuyo. Escribe como trabajas, que nunca debe pasar, como decides. Al principio se sentira raro documentar lo obvio. Pero lo obvio para ti es invisible para la maquina, y ese es exactamente el conocimiento que vale la pena capturar. No lo escribas perfecto. Escribelo hoy, feo, con cinco reglas. El resto lo va escribiendo el uso.

La IA no vino a reemplazar tu criterio. Vino a ejecutarlo a una escala que tu solo nunca alcanzarias, siempre y cuando primero te tomes el trabajo de escribirlo. Ese archivo eres tu, hecho portable. Empiezalo hoy.