Cómo usar Claude Code: separar planificación y ejecución

• Replantea de raíz la forma de usar herramientas de codificación con IA, proponiendo un flujo de trabajo que obliga a pasar por una etapa explícita de revisión del plan antes de escribir código
• El principio central es “no dejar que Claude escriba código antes de aprobar el plan”, con lo que se logra control estructural y un uso eficiente de tokens
• Todo el proceso avanza en una estructura cíclica de Research → Plan → Annotation → Todo List → Implementation → Feedback
• En cada etapa se colabora alrededor de documentos Markdown (research.md, plan.md), repitiendo comentarios y revisiones para mejorar el nivel de detalle
• Este enfoque pone el foco en separar y combinar la capacidad de ejecución de la IA con el criterio humano para obtener resultados estables y consistentes incluso en sistemas complejos

---

Resumen general del flujo de trabajo

• Tras usar Claude Code durante unos 9 meses como herramienta principal de desarrollo, se construyó un proceso sistemático que separa planificación y ejecución, en lugar del enfoque habitual de “ingresar prompt → generar código → repetir correcciones”
• Antes de que Claude escriba código, solo puede ejecutar a partir de un documento de planificación (plan.md) revisado y aprobado por el autor
• Este enfoque reduce pruebas y errores innecesarios, mantiene el control sobre las decisiones de arquitectura y maximiza la calidad en relación con el uso de tokens

Fase 1: Research

• Todo trabajo comienza con un análisis profundo de la base de código
  • Se le indica a Claude que lea y analice en profundidad una carpeta o funcionalidad específica
  • El resultado debe quedar registrado obligatoriamente en el archivo research.md
• Este documento funciona como una superficie de revisión para validar el nivel de comprensión de Claude y corregir malentendidos en esta etapa
• Como una investigación incorrecta lleva a planes e implementaciones incorrectos, esto bloquea por adelantado la fuente de fallas más costosa
• Por ejemplo, previene problemas como ignorar la capa de caché, no reflejar reglas del ORM o crear lógica duplicada

Fase 2: Planning

• Después de revisar la investigación, se le pide a Claude que redacte un plan de implementación detallado (plan.md)
  • Incluye fragmentos de código reales, rutas de archivos a modificar y trade-offs
  • En lugar del modo de planificación integrado, se usan archivos Markdown administrables directamente
• Si además se proporciona una implementación de referencia de código abierto, la calidad del plan de Claude mejora mucho
• Más importante que el documento del plan en sí es el ciclo de anotaciones que viene después

Ciclo de anotaciones

• El autor abre plan.md y agrega comentarios en línea directamente
  • Corrige supuestos equivocados, rechaza enfoques, añade conocimiento de dominio, etc.
  • Ejemplos: “esto debe ser PATCH”, “no hace falta caché”, “el campo visibility debe moverse al nivel de la lista”
• Luego se le indica a Claude: “actualiza el documento reflejando los comentarios, pero todavía no implementes nada”
• Este ciclo de comentar y actualizar se repite de 1 a 6 veces, y la instrucción “don’t implement yet” evita la ejecución prematura
• El documento Markdown funciona como un estado compartido que es más claro y estructurado que las instrucciones conversacionales
• A través de la iteración, un plan genérico evoluciona hasta convertirse en una especificación que encaja perfectamente con el sistema real

Creación de la lista de tareas

• Antes de implementar, se le pide a Claude que añada una lista detallada de tareas (todo list)
  • Incluye subtareas por etapa para seguir el avance
  • Como Claude marca los elementos completados, es fácil entender el estado incluso en sesiones largas

Fase 3: Implementation

• Una vez tomadas todas las decisiones, se le da la orden de ejecutar con un prompt estandarizado
  • “No te detengas hasta completar todas las tareas”, “prohibidos los comentarios innecesarios”, “prohibidos los tipos any/unknown”, “ejecutar type-check de forma continua”, etc.
• Esta orden convierte la ejecución en una etapa mecánica que sigue el plan tal cual, porque el juicio creativo ya se resolvió antes
• Si se implementa de inmediato sin plan, se termina construyendo código sobre supuestos erróneos, así que la regla “don’t implement yet” es la salvaguarda clave

Feedback durante la implementación

• Durante la ejecución, el autor pasa a cumplir un rol de supervisión
  • El feedback se da de forma breve y clara: “falta esta función”, “muévelo a la app admin”, etc.
  • En cambios de frontend, se usan instrucciones cortas como “más ancho”, “gap de 2 px”, o incluso capturas de pantalla
• Se consulta con frecuencia el código existente para mantener una UI/UX consistente
• Si se avanza en la dirección equivocada, hacer git revert y reintentar con un alcance más pequeño resulta más efectivo que corregir gradualmente

Mantenerse al volante

• No se le da a Claude autonomía total; la decisión final siempre la toma una persona
• Solo se seleccionan algunas de sus propuestas o se modifican, eliminan o redefinen elecciones técnicas
  • Ejemplos: “en la primera usa Promise.all”, “ignora la cuarta y la quinta”
  • “elimina la función de descarga”, “no cambies la firma de la función”, “usa el método de una biblioteca específica”, etc.
• Claude se encarga de la ejecución mecánica, mientras que la persona se ocupa del criterio y de establecer prioridades

Sesiones largas únicas

• Desde la investigación hasta la implementación, todo se realiza de forma continua en una sola sesión larga
  • Durante la sesión, Claude acumula contexto de manera constante y, con auto-compaction, conserva suficiente contexto
  • plan.md se mantiene íntegro durante toda la sesión y puede consultarse en cualquier momento

Resumen clave

• “Lee en profundidad, escribe el plan, púlelo con anotaciones y luego ejecútalo de una sola vez.”
• Incluso sin prompts complejos ni instrucciones de sistema, se consigue alta calidad con una canalización disciplinada que separa Thinking de Typing
• Research evita cambios ignorantes, Plan evita cambios equivocados y Annotation inyecta el criterio humano
• La ejecución final se realiza como un procedimiento automatizado una vez que todas las decisiones están cerradas, completando una estructura de colaboración eficiente

[naka98]

Yo también sigo teniendo problemas parecidos. Cuando colaboras con IA solo sobre una base de chat, la descomposición del trabajo (WBS), el avance y el registro de decisiones tienden a volverse difusos.

[pcj9024]

Si simplemente metes el archivo del plan dentro del repositorio y guardas los cambios aplicados que se generan al ejecutar ese plan, el contexto se mantiene bastante bien.

[geekbini]

Este contenido no se limita solo a Claude; parece que también podría aplicarse de forma general a otros servicios de IA basados en CLI.

[GN⁺]

Opiniones de Hacker News

• El verdadero punto no es "planificar o no", sino hacer visibles las suposiciones antes de que el modelo las convierta en código
  Los LLM fallan menos por la sintaxis que por supuestos invisibles como la arquitectura o las restricciones. Por eso, un plan documentado crea una superficie donde esas premisas se pueden depurar.

  • En ese sentido, una arquitectura de subagentes ayuda mucho. Si uno se encarga de planificar, otro de implementar y otro de revisar, los roles quedan claros. Incluso puede hacerse en estilo blue team/red team. Al final, lo importante es ayudar al LLM a razonar correctamente con instrucciones más claras.
  • Si incluyes en las instrucciones todo el flujo del caso de uso, evitas que el modelo haga cosas fuera de lugar.
  • Pero el simple hecho de exponer esas suposiciones también puede cambiar el comportamiento del modelo. Es como cuando agregas un printf() y desaparece un Heisenbug.
  • ¿Que casi no hay errores de sintaxis? Mi experiencia dice otra cosa. Al intentar agregar un backend de S3 a un pequeño proyecto en Rust, Claude cayó en un bucle de alucinación de API y me quemó $20 en 30 minutos. Y era solo un problema simple de sintaxis.
  • ¿Seguro que este artículo no fue escrito con ChatGPT?

• Hay quienes dicen que Claude deja de leer superficialmente si usas palabras como “profundamente” o “en detalle”, pero sinceramente no me resulta intuitivo entender por qué

  • Eso se debe al mecanismo de atención. Los LLM fueron entrenados con todo internet, y los textos que incluyen frases como “mira los detalles del problema” suelen contener respuestas de nivel experto. Así que, cuando aparecen esas palabras, el modelo tiende a dar más peso a ese tipo de datos. Es la misma razón por la que funcionan prompts como “actúa como un profesor del MIT”.
  • Pero esa explicación suena a superstición. No hay evidencia validada estadísticamente y se siente como una forma de pensamiento mágico, casi como ofrecer sacrificios al dios del sol. Si de verdad funcionara, debería poder demostrarse como un problema de optimización, pero nadie publica datos.
  • De verdad estamos en una época extrañísima para el desarrollo de software. Nadie sabe por qué los LLM actúan así. Solo esperamos que los prompts muevan bien las probabilidades. Antes este era un campo determinista, y ahora estamos escribiendo órdenes en negritas dentro de archivos AGENTS.md como si un padre le hablara a su hijo.
  • Me sorprende que, viendo este tipo de cosas, la gente todavía lo tome en serio. Parece casi astrología para ingenieros.
  • Es más fácil entenderlo si piensas el espacio latente (latent space) del modelo como un terreno. El prompt es como dejar caer una pelota en cierto punto, y la elección de palabras determina hacia qué valle va a rodar. Expresiones como “en profundidad” hacen que esa pelota se quede mejor en la zona que buscas. Tal vez no sea una explicación perfecta, pero pensado así me ha funcionado bien en la práctica.

• Yo uso una estructura con tres tipos de documentos y dos skills
  Specs son los documentos estáticos de diseño del proyecto, Plans son los planes de ejecución generados por el LLM, y los archivos de Working memory sirven para seguir el estado del avance.
  Uso la planner skill de Gemini Pro para crear planes nuevos y la implementer skill de Codex para ejecutarlos.
  Así el contexto se mantiene ligero y enfocado, lo que mejora la eficiencia. Incluso con los planes de $20 de Codex/Gemini se puede avanzar con suficiente rapidez.

  • Yo hago algo parecido. Creo archivos spec a partir de papers y voy refinando el plan mientras interactúo con Claude. Manejo requisitos–pruebas–especificaciones como en un documento de ingeniería de sistemas estilo IEEE. Claude sigue bien los guardrails cuando se los das. En mi caso, Claude se adapta mejor a mi estilo que Codex.
  • Es un buen enfoque. Pero me pregunto si un monorepo es una mejor decisión en la era de la IA. En mi empresa tenemos varias apps de Next.js repartidas en distintos repos y estamos pensando si convendría unificarlas.

• La idea de dejar comentarios directamente en el documento de planificación me parece novedosa. Me pregunto si hay alguna forma de guardar esos comentarios por separado o de gestionarlos para revisarlos después.

• Hay varias cosas de este enfoque que no me convencen
  Primero, el enfoque de big bang, donde se genera todo el código de una sola vez, termina creando una masa enorme de código difícil de entender. Me parece mejor planificar y ejecutar por etapas.
  Segundo, me parece una lástima que, aunque se dé retroalimentación, no se actualice la base de conocimiento. Habría que registrar la causa de los errores para no repetirlos después.
  Por último, no se menciona nada sobre pruebas. Debería incorporarse al menos algo de desarrollo guiado por pruebas (TDD). Me interesa ver cómo el desarrollo asistido por IA se va a integrar con este tipo de metodologías.

  • Yo tuve una experiencia parecida. Divido PLAN.md por etapas y redacto con cuidado los prompts para que solo se ejecute cada etapa por separado. También incluyo las pruebas como parte del plan, aunque por ahora las agrego más hacia el final.

• En realidad, este flujo de trabajo es la forma estándar de usar Claude Code que recomienda Anthropic. Pero el problema es que, si el plan no es perfecto, tienes que empezar otra vez desde cero.
  Por eso yo separo diseño → planificación → ejecución en varios lotes. Si divides los planes en unidades de menos de 1,500 líneas, es mucho más fácil manejar la complejidad.
  Mi app de 30 mil LOC tiene 100 mil líneas de planificación. Es imposible hacerlo todo de una sola vez.

  • Yo pasé por lo mismo. Por eso ahora divido el trabajo en planes más pequeños y gestiono los commits con ramas por funcionalidad. Gracias a la IA, de hecho mis hábitos de desarrollo mejoraron.
  • La verdad da un poco de pena que un flujo de trabajo presentado como “radicalmente distinto” sea simplemente usar el modo Plan básico.
  • Yo también creo que la ejecución incremental es la respuesta. Completar un proyecto gigantesco de una sola vez sigue siendo una fantasía.
  • No pasa nada si el plan no es perfecto. Basta con revertir solo las partes que modificó la IA e iterar otra vez desde la etapa anterior. La clave es reducir la complejidad con cambios pequeños.
  • 100 mil líneas de planificación son casi un millón de palabras. Solo leer eso tomaría 66 horas. En la práctica es imposible.

• En lugar de plan.md, yo trabajo más alrededor de scaffolds ejecutables y bucles de validación
  Construí con IA un sistema real de pagos llamado Kolibri Tickets. La clave no es que el modelo escriba código rápido, sino diseñar el bucle de validación.

  • mantener desde el principio un esqueleto ejecutable
  • agregar solo vertical slices delgadas cada vez
  • forzar artefactos verificables como pruebas, tipos y máquinas de estado
  • convertir el refactor en algo cotidiano
    De ese modo, no solo da una “ilusión de velocidad”, sino que realmente permite desplegar más rápido. El documento de plan es una forma de mantener estado compartido, y un harness verificable es otra.
  • Yo también, ahora que el código se ha abaratado, apunto a 100% de cobertura de pruebas. Estoy incorporando tipado estático en Python, pruebas con Playwright y hasta mutation testing. Ahora los agentes pueden correr durante una hora en bucle y entregar código que casi no necesita correcciones.

• Yo uso Claude Code para preparar clases
  Escribo apuntes de clase en Quarto y hago que Claude los convierta en diapositivas de Slidev. Después dejo comentarios en las diapositivas con cosas como “esto divídelo en dos” o “agrega una imagen aquí” para dar retroalimentación.
  Ese tipo de feedback basado en comentarios es muy potente. Ayuda mucho con la distancia de tokens y con mantener el contexto.

  • Quarto ya soporta varios formatos como PowerPoint, PDF y HTML, así que me da curiosidad por qué usar Slidev. ¿No bastaría con pedirle a Claude que regenere el documento de Quarto?
  • Me pregunto si dejas el feedback como comentarios inline. Por ejemplo, algo como # cambiar esta parte por X.
  • ¿Sabes si esa skill de Claude fue publicada como open source?

• Herramientas como Kiro de Amazon, Antigravity de Google, Spec Kit de GitHub y OpenSpec ya ofrecen algo parecido.

• El error más caro en la programación asistida por IA no es un fallo de sintaxis, sino una implementación que funciona en parte pero rompe el sistema completo
  Por eso yo agrego desde el principio un brief.md para dejar clara la definición del problema, las métricas objetivo y los criterios para detener una función. Así se reduce el costo de que los objetivos de negocio y la implementación técnica se desalineen.