Convertir a Claude Code en el mejor socio de diseño

• Al usar Claude Code por primera vez, se lo abordó simplemente con un método de iterar entre instrucciones en prompts y correcciones, pero en tareas complejas surgieron problemas de dependencia del historial de conversación y límites de contexto
• Para resolverlo, antes de implementar una función se le hace redactar un documento de plan (plan document), que se convierte en la única fuente de verdad (SSOT) en una sesión nueva
• El documento de plan incluye una reformulación de requisitos, detalles de implementación, comandos para verificar la calidad del código y más, y sigue actualizándose durante la implementación como un documento vivo (living document)
• Esto resuelve el problema de pérdida de contexto y permite continuar el proyecto en sesiones nuevas usando solo un documento único
• Como resultado, la IA deja de ser una simple herramienta de ejecución y pasa a cumplir el rol de socio de diseño colaborativo que impulsa al desarrollador a pensar y documentar mejor el diseño

---

El problema: los límites de un enfoque basado solo en conversación

• Al trabajar de forma conversacional con Claude Code, sirve bien para tareas simples, pero a medida que las tareas complejas crecen aparecen varias limitaciones importantes
  • La conversación se vuelve la única fuente de verdad, por lo que un mensaje nuevo puede sobrescribir fácilmente instrucciones anteriores, y es difícil detectar con claridad cuándo ocurre eso
  • Debido al límite del tamaño de contexto de la IA, cuanto más larga se vuelve la conversación, más probable es que se pierda información anterior
  • Aunque Claude Code tiene una función de compresión de conversaciones, eso no elimina por completo esta limitación

Experimento con un enfoque centrado en documentos de plan

• Para resolver estos problemas, se probó un enfoque basado en documentos de plan
  • Al inicio, se le explica a Claude Code con el mayor detalle posible la función que se quiere implementar o el bug que se debe corregir
  • También se mencionan archivos fuente existentes o documentos de plan previos que puedan servir de referencia
  • Se evita dar instrucciones de implementación excesivamente específicas para fomentar el papel de la IA como generadora de propuestas de diseño
• Cuando el documento de plan resulta suficientemente satisfactorio, se borra el historial de conversación y se vuelve a empezar usando solo ese plan como contexto
  • El plan incluye un resumen de la función, el plan de implementación, código y pseudocódigo, y comandos de tipos/lint/tests

Proceso de diseño colaborativo

• Cuando no convence el diseño propuesto por la IA, se le da retroalimentación concreta para guiar una aproximación revisada
• En el proceso de discusión, a veces se descubre que la primera propuesta de la IA era más adecuada, y eso resulta más eficiente que programar basándose solo en un diseño propio
• Una conversación estructurada ofrece una experiencia parecida a discutir un plan con otro desarrollador
• La IA no suele presentar por sí sola un enfoque completamente distinto, pero si se le pregunta puede proponer alternativas diferentes

Enfoque de documento vivo (Living Document)

• El documento de plan no se escribe una sola vez y se da por terminado, sino que se sigue actualizando incluso durante la implementación de la función
  • Los cambios que aparecen durante la implementación, la verificación de tipos, el lint o las pruebas se reflejan en tiempo real
• Se forma el hábito de pedir una revisión del estado más reciente del plan cada vez que se hace un commit
• Como el plan se mantiene siempre actualizado, en una sesión nueva basta con adjuntarlo para continuar sin pérdida de contexto

Revisión de código y cambios en los hábitos de desarrollo

• Una vez iniciada la implementación, se revisan periódicamente los cambios y, si el resultado es satisfactorio, se tiende a confiar más en el trabajo de la IA
• Al revisar el código final, el documento de plan actualizado ayuda a entender la base de las decisiones técnicas
• La experiencia de planificar con cuidado y documentarlo de antemano permite crecer como mejor desarrollador
  • Como hay que explicárselo a la IA, uno termina organizando con mayor claridad su propio proceso de toma de decisiones

Del caos al sistema

• Este método hace que el documento de plan se convierta en la única fuente de verdad, resuelve la pérdida de contexto y fomenta el pensamiento arquitectónico
• El documento de plan incluye tanto la especificación como el registro de implementación, y deja constancia no solo del “qué”, sino también del “por qué” y el “cómo”
• El resultado final es un proceso de desarrollo planificado, bien documentado y confiable
• La IA se consolida no como un simple implementador, sino como un socio de diseño colaborativo

[jamsya]

Parece que en el flujo de trabajo de los desarrolladores está aumentando el peso de los roles de PM y arquitecto.

[GN⁺]

Opiniones de Hacker News

• Durante las últimas dos semanas, cada noche me clavé muchísimo tratando de crear el “prompt perfecto” para completar un proyecto de una sola vez usando claude code. Al final armé una estructura donde un solo CLAUDE.md hace referencia a 8 archivos Markdown distintos con la arquitectura del proyecto, especificaciones del modelo, orden de build, capas de testing, escenarios, etc. Este proyecto es para gobernanza basada en modelos en Databricks Unity Catalog; tengo bastante experiencia en el tema, pero nunca sentí que las herramientas existentes fueran lo suficientemente flexibles. Al final terminé apoyándome en 3 subagentes reales para trabajar sobre los archivos de planeación: un experto en Databricks, un experto en Pydantic y un experto en prompts. Gracias a eso, la calidad de los archivos Markdown mejoró muchísimo en varios aspectos, desde problemas con versiones antiguas de Pydantic hasta malentendidos que yo tenía sobre Unity Catalog. Ayer por fin lo ejecuté de verdad y, salvo por algunas aprobaciones mías para usar herramientas, en 2 horas quedaron listas la mayoría de las herramientas y pruebas. Me sorprendió mucho porque se siente totalmente distinto a cómo trabajaba antes, y de verdad creo que hay futuro en documentar con cuidado lo técnico y alinear a todos hacia la misma dirección. Incluso siento que es más productivo que meterse directamente a picar código. Eso sí, cuando trabajo código entro más en estado de flujo, mientras que manejar varios documentos Markdown me dispersa más fácil. Tiempos realmente interesantes

  • Siento que está emergiendo con fuerza un patrón parecido a Test-Driven Development, donde primero te obliga a diseñar el sistema. Antes ibas dibujando el sistema poco a poco mientras escribías código, pero con este tipo de desarrollo basado en IA diseñas y mapeas el dominio por adelantado, y luego el código real se vuelve casi puro boilerplate para materializar el diseño. La IA es realmente buena para ese boilerplate

  • A mí me pasa exactamente lo mismo: soy más productivo, pero mi concentración se dispersa más. Se siente raro, pero por ahora funciona. A largo plazo habrá que encontrar una solución. El método que mejor me está funcionando es poner a varios agentes a trabajar en distintas tareas, cada uno en diferentes repositorios del proyecto, mientras yo sigo aprobando cosas. Se siente como ser project manager de un equipo enorme. Otra vez: tiempos interesantes

  • Es una forma de trabajar realmente fresca. Me da curiosidad cuál es el framework en el que corren los agentes en sus experimentos reales

  • Últimamente yo también estoy grabando por voz detalles del producto, recorridos de usuario y demás, y con eso arranco el proceso de documentación técnica. Un CLAUDE.md mínimo, workflows de Github para el desarrollo de software, aunque armar buenos workflows de CI sigue siendo difícil. Mi playbook es https://nocodo.com/playbook/

• No me convence mucho la idea de que “si planeas primero, el resultado mejora”. Desde siempre, para funciones grandes o proyectos, yo pensaba de antemano la estructura, el porqué y el cómo, ya fuera en mi cabeza, en papel, en Confluence o en un pizarrón. El 80% de la ingeniería de software consiste en pensar y definir el “qué, por qué y cómo”. Confirmas ideas y objetivos con stakeholders, haces investigación, etc. Solo el 20% final es codificar de verdad. Siempre ha sido así, y no sé si la IA sea realmente necesaria para una planeación o definición de objetivos bien hecha

  • Eso puede ser cierto en equipos grandes o entornos con una cultura ya establecida, pero muchísima parte del desarrollo se concentra en proyectos personales, equipos pequeños, side projects, POCs rápidas o herramientas de automatización de un solo uso. Ese tipo de trabajo no suele arrancar con documentación/especificaciones/pruebas desde el principio, sino mezclando código con pensamiento e implementación sobre la marcha. Hay lugares donde TDD encaja, pero en otros simplemente no hace falta. Pero desde que llegaron los agentes de coding con IA, se volvió mucho más importante definir claramente la idea y organizarla como especificación. Se volvió indispensable expresar en palabras todo lo que antes estaba solo en mi cabeza. El lenguaje de programación más hot ahora mismo es el inglés

  • Yo suelo mezclar desarrollo y diseño. Empiezo a programar y voy refinando y evolucionando a partir de ahí. En la mayoría de los casos, la solución general ya es bastante obvia y no siento que valga la pena invertir tiempo en una planeación profunda

• Antes prompt engineering era motivo de burla, pero ahora sí lo estoy sintiendo de verdad. A veces paso 10 o 20 minutos dedicados a un prompt detallado y a la planeación inicial para poder aprovechar cloud code de forma sistemática. Igual que el OP, yo también guardo los planes en archivos y luego los ejecuto en un contexto nuevo. Lo que de verdad quiero es un buen CLI (ahorita uso charm y cc). Sería ideal poder usar modelos distintos para implementación, planeación y subagentes. Implementar con un modelo local y planear con un modelo en la nube, o irlos cambiando según haga falta para ahorrar dinero. Charm, de todo lo que he usado hasta ahora, está muy bien resuelto para ir y venir sin perder contexto. La función de subagentes en paralelo también es de lo mejor de claudecode. (Probé CCR, pero me decepcionó que no pasara del modelo por defecto)

  • Que prompt engineering se haya vuelto tema ahorita tiene mucho que ver con hot takes de Twitter o con la producción de contenido. Pero en la práctica, prompt engineering siempre ha sido importante. GIGO (“Garbage In, Garbage Out”) es una verdad universal en cualquier proyecto de machine learning. Por eso siempre les recomiendo a colegas y amigos: “tienes que usarlo tú mismo”. Lo que no funcionaba hace 6 meses puede que sí funcione ahora. Solo con práctica real puedes notar qué cambió y qué ya se puede hacer. Personalmente, creo que los casos reales de éxito, blogs, gists y ejemplos valen muchísimo más que el negativismo. No basta con hacer cálculos sencillos o detectar typos; tiene que poder mejorar y apoyar mi workflow para que de verdad me sirva. Prompt engineering es como cuando hace 10 o 15 años te obsesionabas con dominar Google y aprender constantemente los cambios nuevos y los patrones efectivos

  • Si quieres colaborar con IA, prompt engineering es de verdad la clave

  • Los proyectos en los que he usado IA han sido los mejor documentados y mejor testeados que he tenido. Como para sacarle rendimiento a un LLM necesitas contexto, la documentación mejora sí o sí; y como el costo de producir tests bajó, terminas teniendo más tests. En vez de que la calidad del código baje, como algunos predicen, creo que en realidad va a mejorar

  • Honestamente, el término “prompt engineering” es arquitectura diseñada a través de un medio nuevo. Antes se valoraba mucho la habilidad de “diseñar diagramas”; ahora esto es una nueva forma de hacer arquitectura

• Hace poco probé Claude Code un rato y pienso intentar el workflow que recomiendan. Se ve bastante bien. Pero el costo de CC es más alto de lo que esperaba. Solo en un refactor sencillo, con 5 minutos de trabajo y 15 de revisión, me gasté 4 dólares. Si lo hubiera hecho yo mismo, me habría tomado unos 15 o 20 minutos. Me da curiosidad cuánto se gastan normalmente por feature usando CC. Nadie habla de precios

  • Si te suscribes, te cobran una tarifa plana de $20 a $200 con límites diarios/semanales de uso de tokens. https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan

  • La dirección que quieren los inversionistas de IA es una estructura donde la IA reemplace partes del mercado laboral con márgenes del 15%. Va a llegar una época en la que el presupuesto para IA y para desarrolladores será 1:1. Por ejemplo, el trabajo de un senior developer con salario de 100 mil dólares será reemplazado por un presupuesto de IA de 100 mil dólares. El presupuesto de IA saldrá del costo de desarrollo, es probable que los salarios senior bajen, y los equipos de desarrollo podrían reducirse drásticamente. Ahorita estamos en la etapa de “captura de territorio” totalmente subsidiada por VC, pero por el ambiente que se ve en el Twitter de los VCs, parece que esa etapa ya está por terminar. Incluso atraer una y otra vez 500 millones de dólares para 9 meses de runway está llegando a su límite

  • Desde que migré parte de mi uso de Cursor a Claude Code, mis costos subieron bastante. En la empresa es fácil convencer al jefe porque lo usamos mucho, pero en side projects sí me la pienso. No quiero pagar 20 dólares cada vez que solo quiero bootstrapear una app por diversión

  • Puedes suscribirte eligiendo dos modelos: Sonnet (20 euros/mes) y Opus (100 euros/mes). Yo empecé con Sonnet y luego me pasé a Opus. Sonnet también sirve bastante bien. Dentro del límite de tokens, para mi caso de uso no se me ha quedado corto. Aunque no estoy seguro de cómo será más adelante

  • Dijiste “si lo hubiera hecho yo mismo me habría tomado 15 o 20 minutos”, pero me pregunto si esos 15 o 20 minutos no podrías usarlos en otra cosa

• La forma en que uso la combinación de Visual Studio Code/ChatGPT5 preview es parecida a mi workflow {creo que lo estoy pagando por la suscripción de Github Copilot, aunque últimamente ya no estoy tan seguro}. Siento que los LLM no agentes tienden mucho a romper el código rápidamente. Cuando pasas a modo agente, la construcción de código cambia muchísimo. Yo no soy desarrollador de Python, pero ver al LLM armar montones de código nuevo sí me impresionó bastante. Después de completar algo, mi idea es correr un LLM pequeño en BitGrid y luego entender del todo el código más tarde. Voy repitiendo pequeñas etapas de exploración y haciendo solo algunos ajustes para mantener el diseño general como yo quiero. Esto me hizo confiar en el futuro donde los LLM serán compañeros de programación. Me da curiosidad si alguien más usa la combinación Visual Studio Code/ChatGPT5

• Me parece interesante que, al optimizar herramientas de IA, los desarrolladores estén redescubriendo el valor de la “buena comunicación” y de “alinear expectativas”. Tal vez ya va siendo hora de replantear la imagen del desarrollador 10x como alguien ermitaño o excéntrico

• He tenido una experiencia similar en Replit. Cuando la app crece, si los documentos de diseño no se vuelven la fuente de verdad para las tareas, todo se cae muy rápido. En OpenAI el chat se vuelve lento y deja de responder enseguida, así que ayuda tener documentos aparte e importarlos a un chat nuevo. También sentí que, a nivel humano, nosotros mismos deberíamos trabajar así. Si hacemos retrospectiva, documentamos y registramos la “memoria” en documentos de diseño, tanto nosotros como los LLM podemos trabajar con más libertad

• Yo también descubrí este workflow hace poco y me sorprendió muchísimo. Lo importante es darle a claude solo los requisitos mínimos y dejar que el modo plan corra con libertad. Si fuera un reporte de métricas de ventas, bastaría con algo como “Ultrathink relevant sales metrics” y te sugiere distintas métricas, además de ayudarte a priorizarlas. Para cada feature nueva creo un directorio aparte y le hago escribir el plan de esa feature en un archivo. Después le voy pidiendo por etapas el plan de implementación, los queries de datos necesarios, la implementación real, las pruebas, la documentación de usuario, y luego lo mando a QA. Antes, construir una sola función de predicción de ventas requería un equipo grande y bastante tiempo; ahora claude lo implementa en un contenedor Docker en medio día. Este cambio está transformando mi forma de ver el software. Antes, por NDA, IP y demás, las empresas jamás sacaban el source code al exterior. Pero ahora incluso un sistema ERP complejo que tomó 20 años puede ser reimplementado rápidamente por claude, con documentación y tests incluidos. En la práctica todavía no es perfecto, pero el avance es realmente veloz

• Para sacarle buenas features a Claude Code, la clave es escribir bien el plan primero. Últimamente uso GPT-5 High en Cursor para hacer el plan y luego se lo paso a Claude Code para implementarlo. Si además haces que documente por adelantado qué partes del codebase hay que tocar, puedes sacar resultados 15% a 20% mejores. Si el modelo de planeación documenta cómo funciona el sistema, la arquitectura, los patrones y además incorpora el diseño de la feature, el resultado sale mejor. Por último, revisar y corregir tú mismo la documentación y el plan ayuda muchísimo

  • En la empresa usamos Google Workspace, así que Gemini es muy fuerte para redacción de estilo “académico”, pero más débil que CC para escribir código. Entonces hago que Gemini detalle el plan con suficiente precisión, y luego se lo paso a CC para modificar e implementar dentro de mi codebase. Con este método vi resultados sorprendentes tanto para desarrollar features nuevas como para extender funciones existentes. En 8 semanas, un producto que construí yo mismo ya está corriendo en producción y hasta se está usando en demos con clientes. Estoy muy satisfecho con la experiencia y los resultados de CC. Como ya había comentado antes en HN, una buena parte sí la habría podido hacer nuestro equipo interno, pero el frontend ni siquiera nos atrevíamos a tocarlo. Algo que habría tomado más de un año, y mucho más trabajo de ingenieros y data scientists, se completó en apenas 2 meses. Agregar features ya no se siente como algo de tiempo, sino casi de “segundos”. Gracias a CC, me resulta interesante ver cómo mi experiencia termina compartiéndose con muchas otras personas

• Me pregunto si alguien ha encontrado una buena forma de integrar de manera elegante el diseño frontend en este proceso. La mayoría se queda en mencionar frameworks de frontend o en imágenes de Figma. Eso no me da la impresión de ser una solución de diseño integral