Cómo uso Claude Code: meta repos, persistencia de planes y logs de iteración

Como ingeniero de software trabajando en múltiples proyectos — desde contribuciones de código abierto en Datalayer hasta dirigir Trepa, un gimnasio de escalada en Bogotá — he pasado el último año haciendo de Claude Code una parte integral de mi flujo de trabajo diario. Esto no es un tutorial ni una reseña de producto. Es un relato práctico de los patrones, soluciones alternativas y lecciones aprendidas a pulso al escribir código real con asistencia de IA.

¿Por qué la terminal en vez de VSCode?

Voy directo al grano: uso Claude Code exclusivamente desde la terminal. La extensión de Claude para VSCode existe, y la he probado múltiples veces, pero aún es demasiado inestable para mi trabajo diario. Se congela, el contexto se pierde a mitad de sesión, y problemas de interfaz que rompen mi flujo — siempre termino volviendo a la terminal.

La versión de terminal es mucho más sólida en comparación. Es rápida, predecible y encaja naturalmente en cómo ya trabajo — saltando entre paneles de tmux, ejecutando servidores de desarrollo y manejando git. Si estás indeciso, empieza con la terminal. No vas a extrañar la interfaz gráfica.

El Meta Repo: contexto compartido entre proyectos

Uno de los patrones más impactantes que he adoptado es el meta repo — un directorio a nivel de workspace que agrupa repositorios relacionados con contexto compartido. Gary Sheng escribió un excelente artículo sobre este enfoque, y yo llegué a una configuración muy similar.

Mantengo dos meta repos:

• Meta repo de Datalayer — Agrupa la extensión de VSCode, herramientas de Jupyter, paquetes del SDK y repos de documentación lado a lado.
• Meta repo de Trepa — Agrupa las herramientas de automatización del negocio, chatbots, flujos de scraping, sistemas de reseñas y repos de análisis de datos.

Cada meta repo tiene un CLAUDE.md de nivel superior que documenta las relaciones entre repos, convenciones compartidas y qué repos dependen de cuáles. Los repos individuales también tienen su propio CLAUDE.md con arquitectura y directrices específicas del proyecto.

Como dice Gary, la idea clave es contexto compartido sin acoplamiento. Claude puede razonar sobre cómo un cambio en un repo afecta a otro sin que esos repos necesiten fusionarse en un monorepo. El agente de IA entra a trabajar e inmediatamente entiende el panorama.

Guardando cada plan: el directorio claude-plans/

Cada funcionalidad no trivial que construyo con Claude empieza con un plan. Y cada plan se guarda.

Cada uno de mis proyectos tiene un directorio claude-plans/ en la raíz. Cuando le pido a Claude que planifique una funcionalidad — un nuevo componente de sidebar, un flujo de chatbot, una integración con una API — el plan va en un archivo markdown en ese directorio antes de escribir cualquier código.

Esto tiene varios beneficios:

• Continuidad: Cuando una sesión se queda sin contexto o necesito retomar el trabajo al día siguiente, el archivo del plan está ahí. Le digo a Claude "continúa desde este plan" y volvemos al camino.
• Responsabilidad: Puedo revisar lo que se planificó versus lo que realmente se implementó. La desviación ocurre, y tener el plan en disco la hace visible.
• Conocimiento del equipo: Incluso en proyectos individuales, el yo del futuro es una persona diferente. El directorio de planes se convierte en un registro de decisiones.

El log de iteraciones: depurando bugs difíciles

Esta es probablemente la parte más inusual de mi flujo de trabajo, y es la que me ha ahorrado más tiempo.

Cuando estoy resolviendo un bug difícil — algo que no se arregla en el primer o segundo intento — inmediatamente le digo a Claude que cree un archivo markdown para rastrear todos los intentos.

Esto era absolutamente esencial al trabajar con los modelos Claude 3.5 y 4.5. Sin este archivo, Claude frecuentemente volvía a enfoques que ya se habían intentado y fallado. Una vez tuve un bug que tomó 27 iteraciones para arreglar usando este enfoque.

Los modelos más nuevos Claude 4.6 (Opus y Sonnet) necesitan este patrón con mucha menos frecuencia. Aún así, mantengo el log de iteraciones para cualquier cosa que pase de 3 intentos fallidos, sin importar el modelo.

CLAUDE.md: la constitución del proyecto

Cada proyecto en el que trabajo tiene un archivo CLAUDE.md en la raíz. Es el archivo más importante para el desarrollo asistido por IA. Es lo primero que Claude lee al entrar a un proyecto, y moldea cada interacción.

Los míos típicamente incluyen:

• Stack tecnológico y versiones — React 19, no React 18. Tailwind v4, no v3. Estos detalles importan.
• Estructura del proyecto — Dónde viven las cosas, cuáles son las convenciones de nombres.
• Comandos — Cómo compilar, testear, hacer lint, desplegar. Claude nunca debería tener que adivinar.
• Convenciones clave — "Usamos TanStack Router, no React Router." "El modo oscuro usa el atributo data-theme."
• Lo que NO hacer — "No crear archivos de documentación a menos que se pida." "No hacer auto-commit."

La sección de anti-patrones es tan importante como la de patrones. Sin límites explícitos, Claude va a "mejorar" sutilmente cosas que no le pediste que tocara.

Mirando hacia adelante

El patrón del meta repo, la persistencia de planes y el registro de iteraciones son las tres prácticas que han tenido el mayor impacto en mi productividad. No son glamurosas. Son solo archivos markdown en los lugares correctos. Pero transforman un asistente de IA de un autocompletado inteligente a un verdadero colaborador.

Si estás usando Claude Code y aún no has adoptado estos patrones, empieza con el archivo CLAUDE.md. Todo lo demás viene de ahí.