Un proyecto de GitHub sobre codificación de IA ha recibido mucha atención recientemente. Su núcleo no es una base de código compleja, sino un archivo CLAUDE.md de aproximadamente 65 líneas. La razón por la que atrajo tantas estrellas no es la complejidad técnica. Es que captura los problemas con los que muchas personas se encuentran repetidamente cuando usan IA para escribir código.

Los antecedentes comienzan con las observaciones de Andrej Karpathy sobre la codificación de IA. Karpathy es un influyente educador e ingeniero en IA: doctor de Stanford, uno de los primeros contribuyentes de OpenAI y exlíder de IA de Tesla responsable del sistema de visión de Autopilot. Continuó compartiendo sus puntos de vista sobre modelos grandes, educación y herramientas de inteligencia artificial, por lo que sus comentarios sobre los cambios en los flujos de trabajo de programación tienden a llamar mucho la atención de los desarrolladores.

Una vez dijo que después de usar Claude Code durante algunas semanas, su estilo de programación cambió notablemente. Anteriormente, era aproximadamente un 80% de código escrito a mano y un 20% de asistencia de IA. Ahora está más cerca del 80% del código escrito por IA y del 20% editado por él mismo. Lo describió como “programación en inglés”, diciéndole a un LLM qué escribir en lenguaje natural.

Pero también señaló varios problemas recurrentes en la codificación de IA.

01 Suposiciones erróneas

El primer problema es que los modelos hacen suposiciones fácilmente en nombre del usuario y luego siguen escribiendo en ese camino. No siempre manejan su propia confusión y no siempre se detienen a hacer preguntas cuando el requisito es ambiguo.

Por ejemplo, si el usuario solo dice “agregar una función de exportación de usuario”, el modelo podría asumir que debe exportar todos los usuarios, generar JSON, escribir en un archivo local y omitir cualquier confirmación sobre permisos o campos. Sólo después de terminar el código el usuario descubre que la comprensión del modelo no coincide con el escenario real.

Un mejor enfoque es enumerar primero las incertidumbres: ¿debería exportar todos los usuarios o los resultados filtrados? ¿Debería activar una descarga del navegador o ejecutarse como trabajo en segundo plano? ¿Qué campos son necesarios? ¿Qué tamaño tiene el conjunto de datos? ¿Existen restricciones de permisos? Si estas preguntas no se aclaran, escribir más rápido sólo significa ir más lejos.

02 Sobrecomplejidad

El segundo problema es que los modelos a menudo convierten problemas simples en complejos. Una tarea que podría manejarse con una función podría recibir clases abstractas, patrones de estrategia, patrones de fábrica, capas de configuración y un montón de puntos de extensión que tal vez nunca sean necesarios.

Este tipo de código puede parecer diseñado, pero en la práctica aumenta el costo de mantenimiento. La IA es especialmente buena para generar rápidamente estructuras grandes, pero no siempre juzga si esas estructuras son necesarias. El resultado es que una tarea que se puede resolver en 100 líneas se infla en 1000 líneas.

La prueba es sencilla: ¿un ingeniero senior observaría el cambio y pensaría que está sobrediseñado? Si la respuesta es sí, elimine las capas adicionales y resuelva el problema actual con la menor cantidad de código necesario.

03 Daños colaterales

El tercer problema es que los modelos a veces modifican o eliminan código que no comprenden completamente. Mientras solucionan un pequeño error, pueden cambiar comentarios casualmente, reformatear el código cercano, limpiar importaciones que parecen no utilizadas o incluso tocar lógica no relacionada con la tarea actual. Estas “mejoras inmediatas” son riesgosas porque amplían el alcance del cambio y dificultan la revisión. Es posible que el usuario solo desee solucionar un fallo del validador causado por un correo electrónico vacío, pero el modelo también puede mejorar la validación del correo electrónico, agregar validación de nombre de usuario y reescribir cadenas de documentos. Al final, resulta difícil saber qué línea cambió el comportamiento.

Una regla más segura es: cambiar sólo lo que se debe cambiar y sólo solucionar los problemas causados ​​por su propio cambio. El código muerto existente, los problemas de formato o el bagaje histórico no deben tocarse a menos que la tarea lo solicite explícitamente. Como máximo, menciónalo.

04 Transformando las quejas en CLAUDE.md

Después de que los comentarios de Karpathy se difundieran ampliamente, el desarrollador Forrest Cheung hizo algo inteligente: organizó estas quejas en reglas de comportamiento ejecutables y las puso en un archivo CLAUDE.md.

El proyecto no contiene código complicado. Su idea clave es convertir las partes más propensas a fallas de la codificación de IA en reglas de trabajo claras. Se pueden resumir en cuatro principios.

La primera es pensar antes de escribir. No asumas en silencio. No ocultes la confusión. Si un requisito tiene múltiples interpretaciones, enumérelas. Si hay un enfoque más sencillo, dígalo. Pregunte cuando sea necesaria una aclaración y responda cuando sea necesario.

El segundo es mantener las cosas simples. No agregue funciones que no fueron solicitadas. No abstraiga el código único. No agregue configuraciones innecesarias. No escriba grandes cantidades de código defensivo para escenarios extremadamente improbables. Si 50 líneas pueden resolverlo, no escribas 200.

El tercero es hacer cambios precisos. Cada línea modificada debe rastrearse directamente hasta la solicitud del usuario. No mejore el código cercano como misión secundaria. No refactorices algo que no esté roto. Haga coincidir el estilo del proyecto existente tanto como sea posible.

El cuarto es la ejecución impulsada por objetivos. No le des al modelo sólo una instrucción vaga. Dale un criterio de éxito verificable. Por ejemplo, “corregir el error” puede convertirse en “escribir una prueba que reproduzca el error y luego hacer que pase”; “agregar validación” puede convertirse en “escribir pruebas de entradas no válidas y hacerlas pasar”. Cuanto más claro sea el criterio de éxito, más fácil será para el modelo avanzar hacia su finalización.

05 Por qué despegó

Este proyecto se hizo popular no porque el contenido sea misterioso, sino porque se acerca al trabajo de desarrollo real.

Muchas personas que utilizan IA para codificar han visto escenas similares: el modelo malinterpreta con confianza el requisito, el código se vuelve más complejo a medida que avanza o toca lugares que no debería tocar. El valor de CLAUDE.md es que convierte esas experiencias en reglas de colaboración que se pueden colocar dentro de un proyecto.

El coste de entrada también es bajo: un archivo puede empezar a marcar la diferencia, sin una integración complicada. Combinado con la influencia de Karpathy y los ejemplos prácticos de comparación del proyecto, se extendió naturalmente a través de la base de usuarios de Claude Code y la comunidad de codificación de IA en general.

Más importante aún, estas reglas no son solo para el Código Claude. No importa qué herramienta de codificación de IA utilice, los problemas subyacentes son similares: el modelo necesita saber cuándo preguntar, cuándo simplificar, cuándo detenerse y cómo decidir que la tarea está completa.

06 Lo que los desarrolladores pueden llevarse

La lección para los desarrolladores comunes es simple: la codificación con IA no se trata de lanzar una oración a un modelo y esperar un milagro. El enfoque eficaz es darle límites al modelo.

Cuando el requisito no esté claro, pídale que exponga sus supuestos primero. Cuando la implementación comience a complicarse, pídale que vuelva a la solución viable más pequeña. Al cambiar el código, manténgalo enfocado en el objetivo de la tarea. Al finalizar el trabajo, utilice pruebas, comandos o puntos de control explícitos para verificar el resultado.

La IA ya es muy capaz de escribir código, pero aún necesita buenas limitaciones de colaboración. El hecho de que un breve CLAUDE.md pueda atraer tanta atención demuestra que los desarrolladores no sólo necesitan modelos más inteligentes. También necesitan formas de trabajo más fiables.

En resumen:

• Pensar antes de escribir para reducir suposiciones erróneas.
• Mantenga las cosas simples para evitar el diseño excesivo.
• Realizar cambios precisos para controlar el alcance del cambio.
• Trabajar hacia metas con criterios de éxito verificables.

Estas cuatro reglas no son complicadas, pero son prácticas. El requisito previo para que la codificación de IA realmente mejore la eficiencia es no hacer que el modelo escriba más. Está haciendo que escriba con mayor precisión, con menos código y bajo un mejor control.