- Un texto que presenta principios de ingeniería de contexto y flujos de trabajo prácticos para lograr buenos resultados con modelos de lenguaje actuales en codebases de producción a gran escala
- La clave es la Compacción Intencional Frecuente, que estructura y comprime el contexto durante todo el proceso de desarrollo para estabilizar la calidad del criterio del agente y su trayectoria de trabajo
- Mediante un proceso de 3 etapas —investigación → planificación → implementación— se crean entregables de investigación previa y documentos de plan, y la revisión humana se coloca en puntos de alto apalancamiento para reducir el slop y el retrabajo
- Demuestra su eficacia incluso en un entorno brownfield con casos reales en BAML, una base en Rust de 300 mil LOC, donde se lograron en poco tiempo tareas complejas como corrección de bugs y soporte para cancelación/WASM
- En conclusión, el AI coding no es un juguete sino una artesanía de ingeniería sofisticada, y la clave de la ventaja competitiva está en un cambio de proceso/cultura a nivel de equipo
Contexto: límites de la IA y problema en codebases complejos
- La mayoría de los desarrolladores ya sabe que las herramientas de AI coding no funcionan tan bien como se espera en codebases reales de producción
- Existen estudios que muestran que las herramientas de AI coding pueden reducir la productividad en codebases grandes y en tareas complejas
- Un estudio de Stanford encontró que una parte importante del código agregado por IA termina siendo trabajo repetitivo, al tener que corregir de nuevo código deficiente que antes había generado la propia IA
- Los agentes de AI coding son eficaces en proyectos nuevos o cambios pequeños, pero en codebases grandes incluso pueden reducir la productividad del desarrollador
- Por eso, en la práctica es común una postura cautelosa del tipo: “por ahora está difícil, cuando salgan modelos más inteligentes”
- Sin embargo, al aplicar ingeniería de contexto en una gran codebase real de Rust de 300,000 LOC, se vio que incluso con los modelos actuales se puede superar el nivel de mercado tanto en productividad como en calidad
- La clave es la compacción intencional frecuente, es decir, mantener el contexto que se le da a la IA en una forma estructurada y administrada durante todo el proceso de desarrollo
- Al final, el “AI coding” es un campo que requiere maestría técnica
Base conceptual: “Specs are the new code” e investigación sobre productividad
- Dos presentaciones en AI Engineer 2025 impulsaron un cambio de mentalidad
- En la charla Sean Grove's "Specs are the new code" se plantea “abandonar el prompt conversacional y conservar las especificaciones como código”
- La práctica de descartar los prompts y hacer commit solo del código resultante se compara con subir solo binarios sin el código fuente
- El estudio de Stanford sobre el impacto de la IA en la productividad de los desarrolladores sugiere que, aunque la IA aumente la producción a corto plazo, el efecto neto puede disminuir por caída de calidad y retrabajo
- El análisis de commits de 100 mil desarrolladores observó que las herramientas de IA aumentan el retrabajo y compensan así las ganancias de productividad
- También aporta la idea de que funcionan bien en greenfield, pero en brownfield y en trabajo de alta dificultad con frecuencia producen el efecto contrario
Principio: concepto de Frequent Intentional Compaction
- Se adopta una estrategia de compresión continua para mantener la ventana de contexto siempre entre 40–60%, minimizando exceso de contenido, omisiones e información incorrecta
- Lo que se comprime es el ruido: logs de búsqueda de archivos, trazas de flujo de código, historial de cambios, logs de tests/build, JSON grandes, etc.
- Los entregables de cada etapa se conservan como artefactos estructurados para garantizar la calidad del input del siguiente turno
- Por ejemplo: crear un documento de progreso que registre el resumen del avance, objetivo y enfoque, pasos completados y punto actual de fallo
Flujo de trabajo: Research → Plan → Implement
- En la etapa de Research se investigan archivos relacionados, flujos e hipótesis de causa, y se genera un documento resumido de investigación
- Si hace falta, se usan subagentes para explorar el alcance y resumirlo con contexto fresco
- En la etapa de Plan se redacta un plan de implementación que describe en detalle los archivos a modificar, la forma del cambio y el procedimiento de validación y pruebas
- El plan se usa como un punto de revisión de alto apalancamiento, incluso más que el code review
- En la etapa de Implement se ejecuta el plan por pasos, y tras validar cada paso se recompacta el estado en el documento del plan para acumularlo
- En tareas complejas se realiza una realineación del contexto en cada punto de reencuentro entre etapas
Antipatrones y sofisticación gradual
- El enfoque ingenuo deja ver problemas donde el contexto se contamina en un flujo tipo chat y termina en bucles de disculpas o desvíos
- Una forma apenas mejor es reiniciar la sesión y usar “prompts adicionales de instrucción”, pero el control de ruido de fondo sigue siendo insuficiente
- La compacción intencional es una mejor forma de reconstruir el contexto usando resúmenes de progreso (archivos) y mensajes de commit
- Se muestra un ejemplo de formato ideal de entregable comprimido y se fijan como objetivos la optimización de precisión/completitud/tamaño/trayectoria
Perspectiva técnica sobre la optimización del contexto
- Un LLM es una función sin estado, por lo que la calidad depende por completo del contexto de entrada
- El orden de los peores casos es información incorrecta > omisión > exceso de ruido
- Mientras más pequeño sea el contexto, mejor; por eso la clave es comprimir para obtener la máxima coherencia con el mínimo input
- También se mencionan perspectivas alternativas como estrategias simples de ejecución de agentes en bucle (por ejemplo, el proceso “Ralph”)
Rol de los subagentes: no roleplay humano, sino control de contexto
- Los subagentes realizan búsqueda/resumen/ordenamiento en contextos independientes para mantener limpia la ventana del agente principal
- La respuesta ideal vuelve en forma de un entregable comprimido y estructurado con objetivo/estado actual/ruta
- Con subagentes se localiza el costo de exploración y se eleva la capacidad de concentración del contexto de trabajo principal
Caso 1: corrección de bug en BAML aprobada al primer intento
- Se presenta el caso de una persona nueva en BAML, una base Rust de 300 mil LOC, que envió y logró aprobar un PR de corrección de bug en cuestión de horas
- Se iteró varias veces sobre el documento de investigación para elevar su calidad, y luego se logró una aprobación al primer intento con una implementación basada en el plan final
- Se cumplieron varios objetivos en términos de adecuación a brownfield, eliminación de slop y mantenimiento de alineación
Caso 2: soporte de cancelación/WASM en BAML con 35k LOC
- Se demostró un cambio grande en el que dos personas, en 7 horas, añadieron soporte para cancelación y compilación a WASM
- Según la estimación del equipo, era trabajo de 3–5 días por persona, que se redujo mediante el pipeline de research/plan/implement
- Algunos PR se fusionaron de inmediato y otros se dejaron abiertos al nivel de demo funcional, demostrando la posibilidad de resolver tareas de alta dificultad
Límites y aprendizajes desde el fracaso
- El intento de eliminar la dependencia de Hadoop en Parquet Java quedó como caso de fracaso por no profundizar lo suficiente en el árbol de dependencias
- Conclusión: no todos los problemas se resuelven con 7 horas de prompting, y hace falta la participación de un experto de dominio
- El apalancamiento de la revisión humana aumenta en el orden investigación > plan > código, y una sola línea errónea en la investigación puede amplificarse en miles de líneas incorrectas
Prioridad de documentación para alinear al equipo
- Se plantea que la esencia del code review está en mantener la alineación mental (mental alignment)
- Las cadenas de PR grandes provocan pérdida de entendimiento del producto y ansiedad en el equipo, por lo que specs/planes/investigación reducen el costo de alineación
- Para un ingeniero es más frecuente y más preciso leer un documento de plan de 200 líneas que 2 mil líneas de código
- Incluso al responder incidentes en áreas desconocidas, un prompt de investigación puede servir como guía rápida
Resumen general y estructura de costos
- Se afirma que se cumplieron todos los objetivos: compatibilidad con brownfield, resolución de problemas complejos, minimización de slop y mantenimiento de la alineación del equipo
- Desde el punto de vista del costo operativo, un equipo de 3 personas lo opera con un costo mensual de tokens de Opus de alrededor de $12k
- Aunque hay excepciones, se enfatiza que en términos generales ya es una metodología que funciona
Cambios futuros y productización
- Los agentes de coding se volverán una commodity, y el verdadero desafío será la transformación de la organización y del flujo de trabajo
- En un mundo donde la IA escriba el 99% del código, la reconfiguración total de la forma de colaborar será el punto de inflexión competitivo
- Para apoyar esto se lanzó en beta privada una herramienta “post-IDE” llamada CodeLayer
- Apunta a ser Superhuman for Claude Code y acelerar el desarrollo agéntico specs-first
3 comentarios
Final del anuncio...
Presentación de un servicio llamado CodeLayer como cierre...
Opinión de Hacker News
Fue una lectura interesante y tenía ideas novedosas. Pero creo que este tipo de afirmaciones tiene problemas. Sean predijo que la IA avanzará y que en el futuro los documentos de especificación serán el código real. Afirma que, dentro de 2 años, la frecuencia con la que la gente abrirá archivos Python en un IDE será similar a la frecuencia con la que hoy alguien abre un editor hexadecimal para ver ensamblador. Dice que al principio le incomodaba, pero que terminó aceptando enfocarse en las pruebas en lugar de leer una por una las líneas de código del PR, y tratar la especificación como la verdadera fuente. Sin embargo, por el problema de no determinismo de los LLM, por más que afines el prompt no siempre puedes esperar una implementación razonable. Un compilador es determinista y, aunque tenga errores, se puede reproducir y depurar; un LLM no
Incluso al trabajar con desarrolladores junior, la implementación es determinista hasta cierto punto. Pero con los modelos de IA, aunque les des instrucciones claras, salen implementaciones completamente distintas una y otra vez
Lo curioso es que, en realidad, el propio documento de especificación ya es no determinista. Si intentas escribir requirements en inglés para que nadie pueda malinterpretarlos, al final terminas creando un lenguaje de programación
Estoy de acuerdo con la preocupación de que "el prompt puede ser perfecto, pero ni siquiera así hay garantía de que el LLM lo convierta en una implementación razonable". De hecho, los prompts escritos en lenguaje natural suelen ser intrínsecamente ambiguos e incompletos. Por eso van bien cuando se busca un resultado creativo, pero si el lenguaje natural fuera adecuado para definir requisitos de software, la ingeniería de software ya habría resuelto esto hace décadas. Me entusiasmaron los LLM, pero creo que querer resolver todo con esto es forzado. En cuanto a especificación de requisitos, se siente parecido a los viejos sistemas formales y los intentos de verificación matemática, pero en el extremo opuesto. Incluso si esto termina siendo un fracaso parcial, lo veo como un experimento que puede dar nuevas ideas sobre el desarrollo de software. En algunos dominios generará valor real, y en otros podría desecharse por completo. Son tiempos interesantes
La verdad es que casi nadie escribe especificaciones o documentación técnica de forma clara y detallada. Y aun si existieran, no creo que eso se vuelva algo masivo en 2 años. ¿De verdad un redactor técnico que entienda a fondo la ingeniería de software quedaría satisfecho con solo darle buenos prompts a un agente de IA sin mirar el código? Yo no lo creo. Se parece mucho a la típica mentalidad de "los ingenieros tratando a las personas como si fueran máquinas"
La afirmación de que "gracias al compilador no hace falta abrir el editor hexadecimal para ver ensamblador en cada build" también tiene matices. Claro, las herramientas mejoraron, pero en investigación científica de HPC muchas veces se revisaba ensamblador directamente con herramientas como Intel VTune para comprobar si el compilador había vectorizado correctamente los loops importantes
He usado este patrón en dos codebases distintas. Una era un gran repositorio monolítico de apache airflow de 500 mil líneas, y la otra era un proyecto personal en flutter empezado desde cero. No sabía realmente nada de flutter ni de dart. Aun así, sentí que este método funcionaba. En el proyecto greenfield casi bastaba con correr
/create_plan, y podía aprovechar todo el soporte del agente. Lo importante es revisar con cuidado los documentos que genera la IA. Solo tienes que verificar por tu cuenta si cubren los edge cases que te preocupan o que se te podrían pasar, y si las decisiones técnicas son razonables. Por ejemplo, puedes detectar de inmediato una mala decisión como romper el patrón de sqlite y recomendar postgres. Normalmente puedes corregir el plan al momento mientras chateas con el agente. En la empresa tengo que usar github copilot, así que tuve que escribir los prompts de otra manera, pero sigo haciendo resumen deliberado entre etapas (compaction). Copilot no soporta subagentes como claude code, pero aun así he mantenido una productividad decente.También quiero compartir una experiencia personal. Justo antes de la era de la asistencia de programación con IA, estaba muy deprimido porque sentía que mi trabajo se estaba volviendo demasiado aburrido. Trabajar en codebases grandes siempre estaba lleno de tareas tediosas por la cantidad de repositorios, equipos y personalidades involucradas. Lo mejor de la programación con IA fue que maneja con fluidez ese tipo de pendientes menores. Yo encuentro mucha satisfacción en construir algo que funcione bien, pero una y otra vez esa alegría desaparecía por quedar atorado en esas tareas pequeñas. Ahora produzco buenos resultados de manera constante, y también me siento orgulloso de mí mismo
Hice un paquete que uso cuando trabajo en codebases grandes [GitHub.com/iambateman/speedrun]. Primero, con
/featureingreso la descripción de la funcionalidad, entonces empieza a analizar la codebase y hace preguntas. Cuando respondo, redacta un plan en formato markdown. En ese proceso se generan 8 a 10 archivos markdown, con lo que se va a hacer e incluso código de ejemplo. Luego viene una etapa de "code critic", donde intenta encontrar errores, aunque en realidad se equivoca como el 60% de las veces. Yo filtro los errores absurdos de ese feedback. Para este punto ya tengo una carpeta bien ordenada con los cambios que quiero y la descripción de la funcionalidad. Después solo le digo a Claude Code “continúa” y empieza a trabajar paso a paso. Este método me ayuda a evitar que se desvíe y me da confianza en el resultado. Uso este workflow varias veces al día para trabajos grandes, y para tareas relativamente concretas uso Claude code normal. Me parece un workflow bastante eficienteNo entiendo para nada por qué alguien querría pasar por un proceso tan complejo. Creo que programar de forma normal usando el LLM solo como apoyo es más productivo que esto
El gran problema de usar LLM en codebases grandes es que repiten los mismos errores. Me da curiosidad cómo haces para seguir rastreando en el contexto las decisiones de arquitectura para cada tarea
Se ve realmente genial. Hay una etapa intermedia de pseudo code, y me da curiosidad si definir de antemano el workflow o el proceso realmente ayudó. También he escuchado que es importante mantener cada archivo por debajo de 100 líneas, y me pregunto si tú sentiste algo parecido
Este artículo parece una cápsula del tiempo del momento en que me rendí por completo con la gestión del contexto en mi Claude code. Yo había creado especificaciones por carpeta para cada parte del código y guardaba logs por funcionalidad. Administraba varios subsistemas de un servidor API en Python, como cuentas, notificaciones y suscripciones. A medida que la situación se volvió más compleja, Claude ya no lograba entender bien la lógica de negocio y la gestión del contexto se volvió extremadamente difícil. Por ejemplo, para construir un sistema RBAC simple, tenía que darle hasta diagramas UML y ejemplos que explicaran la relación cuenta-perfil para que más o menos funcionara como esperaba
research_codebase.mdfue justamente esa. La gran preocupación era: "si nos encargan esta codebase y no conocemos su estructura, ¿cómo podemos hacer que el modelo trabaje sobre ella?" Hay dos problemas principales con el código escrito mayormente por IA. 1) Si no conoces el código, hace falta una etapa de research para captar rápido el flujo y la funcionalidad 2) Revisar PR enormes es muy doloroso, y el plan estructura qué cambió y por qué. Por cierto, Mitchell elogió muchísimo la función de compartir hilos de ampcode, y eso es una buena solución para el punto #2 [https://x.com/mitchellh/status/1963277478795026484]Hay un montón de declaraciones y afirmaciones sobre cómo usar IA, pero casi nadie publica el proceso concreto o los prompts. Hablar bonito es fácil; si realmente va a ser útil, tienen que quedar logs de prompts. Los commits generados por IA deberían incluir también qué prompts se aplicaron, para que igual que uno recorre el historial de commits, también pueda seguir el historial de prompts y entender cómo se escribió el código
El autor presume que investigó e implementó 35K líneas de código en 7 horas, pero en realidad quedaron 40 commits a lo largo de 7 días. Me pregunto si trabajó una hora por día. Y da risa que uno de los commits más recientes sea "ignorar algunas pruebas"
Había una frase que decía: "Unas semanas después, junto con @hellovai agregamos 35k LOC a BAML para introducir soporte de cancelación, compilación WASM y otras funciones nuevas. El equipo existente estimaba que cada función tomaría entre 3 y 5 días". Entonces, ¿eso significa que pensaban que un ingeniero senior iba a escribir entre 4 y 6 KLOC por día? (¿antes de genAI?)
El dato que falta aquí es que un ingeniero senior probablemente lo habría resuelto en solo 2KLOC
Y de hecho el propio autor admite en otro lado que este trabajo en realidad tomó una semana https://news.ycombinator.com/item?id=45351546
Estoy totalmente de acuerdo con la parte de "al principio fue incómodo, pero terminé renunciando a leer todo el código del PR y me enfoqué solo en revisar bien las pruebas. La especificación se volvió la verdadera fuente". Siento que nuestro rol se está moviendo de escribir directamente los detalles de implementación a definir y verificar el comportamiento. Hace poco necesitaba agregar carga recursiva a un operador Python de S3-to-SFTP, y había muchas flags de rutas complejas. Mi proceso fue el siguiente: 1) extraer el comportamiento existente como una especificación clara (es decir, hacer que pasaran las pruebas unitarias) 2) ampliar la especificación para la nueva funcionalidad 3) pasarle el problema y las pruebas al agente de código. Al final me di cuenta de que ni siquiera necesitaba entender el código viejo. Mi enfoque estaba solo en si el código nuevo cumplía correctamente con la especificación. En el futuro, nuestro valor estará en verificar la corrección, y el código real será un detalle que los agentes resolverán por su cuenta
Estoy de acuerdo con que "nuestro rol se mueve de escribir detalles de implementación a definir y verificar comportamiento". De hecho, hasta parece que siempre fue ese el trabajo principal. Gracias a los lenguajes de alto nivel, los compiladores y otras abstracciones, el tiempo que dedicamos a escribir detalles de implementación ha ido disminuyendo constantemente
Sobre "mi enfoque estaba en si el código nuevo funcionaba según la especificación", eso me hace pensar en la ley de Postel (Postel's Law). El comportamiento observado de un sistema ampliamente usado termina convirtiéndose de facto en la interfaz pública y la especificación del sistema, incluyendo todos sus defectos y errores de implementación. También hace falta probar si el lado cliente del código realmente sigue bien la especificación y, si hay desviaciones, detectarlas y manejarlas
Claude Plays Pokemon mostró lo mismo. La IA es mala para juzgar si algo realmente está funcionando bien. Más bien se queda dando vueltas en lo mismo. Pero si una persona va corrigiendo el rumbo de vez en cuando, puede ser una combinación muy poderosa
Si de verdad intentas definir todos los aspectos del comportamiento, al final es casi como escribir todo el código. Si hay una sola línea en el PR cuyo significado no entiendes al instante, probablemente no definiste suficientemente bien el comportamiento completo
Se decía que "en los próximos años los documentos de especificación se convertirán en el código real, y casi no habrá que abrir archivos Python". Para que eso se haga realidad, la generación de código con IA tendría que ser correcta al 99.9% y casi no tener alucinaciones. Confiamos en el compilador y no miramos el ensamblador porque tenemos la certeza de que el resultado siempre será el mismo y no tendrá errores (aunque rara vez haya bugs o problemas de optimización, casi siempre se corrigen de una vez). Por ahora, si el código generado por IA se comporta distinto de la especificación —es decir, del código original—, al final tiene que volver a corregirlo una persona
Me impresionó mucho el consejo de dividir la implementación y tratarla o revisarla por unidades de trabajo.
ARCHITECTURE.md, y en módulos grandes unDESIGN.mdCLAUDE-feature.mddonde organiza el plan de implementación y también información de apoyo (como los elementos accesibles en la codebase). Si veo que al archivo le faltan cosas o que la explicación es confusa, lo complemento con prompts adicionales. Entre prompts relativamente grandes hago/reset, le vuelvo a pedir que consulte el documento y sigo iterando mejoras. Cuando llega el momento de implementar, hago otro/reset, y en cada checkpoint del plan le hago/resetde nuevo mientras actualiza en el documento el progreso. En general funciona razonablemente bien, pero no sé si confiaría tanto en eso en el trabajo