Buenas prácticas de Claude Code: planificación, transferencia de contexto y TDD

Claude Code premia una disciplina que la mayoría de herramientas para desarrolladores no exigen. Si lo has usado un tiempo, habrás notado que algunas sesiones dan justo lo que necesitas y otras se comen tokens sin llegar a nada. El propio equipo de Anthropic descubrió que los intentos sin guía aciertan en torno al 33% de las veces, y su creador abandona el 10-20% de las sesiones. 

La diferencia no está en los prompts que tecleas, sino en los patrones que pones alrededor de la herramienta.

Este artículo recoge cómo se aplican esos patrones en la práctica, a partir de flujos de trabajo en producción en empresas como Abnormal AI, incident.io y Trail of Bits. 

Si necesitas repasar la configuración y las funciones clave, nuestra guía de Claude Code 2.1 te cubre. Aquí damos por hecho que ya dominas lo básico y quieres sacarle más partido a la herramienta.

Para una visión más amplia de cómo razonan los agentes y dónde encajan los patrones de este tutorial, te recomiendo inscribirte en nuestro itinerario de aprendizaje AI Agent Fundamentals, que cubre todos los principios de base.

Por qué la disciplina de planificación lo cambia todo

Cada decisión que toma Claude sin guía puede tener alta precisión; suena bien para una elección aislada, pero al encadenarse en una funcionalidad con muchos puntos de decisión, la probabilidad de acertar en todo se desploma. Si asumes un 80% de acierto en 20 decisiones, obtienes 0,8^20, es decir, apenas un 1% de probabilidad de que la implementación sea totalmente correcta.

La planificación reduce esas 20 decisiones ambiguas a una especificación revisada donde cada una roza el 100% porque ya has tomado la decisión.

Planificar con el flujo de anotaciones iterativas

El flujo de planificación que mejor escala es un ciclo de anotaciones, como propone Boris Tane. Pide a Claude que redacte un plan.md, ábrelo en tu editor y añade notas en línea donde Claude se haya equivocado o haya dejado algo ambiguo: "usa drizzle:generate, no SQL sin procesar" o "esto debería ser PATCH, no PUT". 

Luego envías el plan anotado de vuelta con la frase de seguridad "address all notes, don't implement yet". Esa frase importa porque, sin ella, Claude se salta el plan y empieza a programar. Repite el ciclo hasta que no quede ambigüedad; entonces Claude implementará con muchos menos bandazos porque todas las decisiones ya están tomadas.

# plan.md — annotation cycle
 
## Step 3: Database migration
Create a new migration for the users table.
> NOTE: use drizzle:generate, not raw SQL
> NOTE: add created_at with default NOW()
 
## Step 4: API endpoint
Add PUT /users/:id endpoint.
> NOTE: this should be PATCH, not PUT. Partial updates only.
 
# After annotating, send back with:
# "address all notes, don't implement yet"

Usar el modo plan de Claude Code

Si los ciclos de anotación te parecen pesados, el modo plan integrado de Claude Code es una opción más ligera: 

1. Pulsa Mayús+Tab dos veces.
2. Itera el plan en conversación.
3. Cambia a aceptación automática con Mayús+Tab una vez. 

Los planes se guardan en ~/.claude/plans/, así que sobreviven a la compactación y a reinicios de sesión, lo que hace que el modo plan integrado sea un buen valor por defecto para la mayoría de tareas. Para funcionalidades muy grandes, escribir una especificación completa por adelantado también funciona: una persona dedicó dos horas a una spec de 12 pasos y se ahorró unas 6-10 horas de implementación. 

Llevar la planificación más lejos

Independientemente del enfoque, pegar buen código open source junto a la petición de plan mejora claramente el resultado, porque Claude rinde mejor con una referencia funcional que con descripciones abstractas.

La planificación también escala horizontalmente con git worktrees. En incident.io llevan 4-5 sesiones de Claude en paralelo en ramas separadas, cada una con su propio plan. Una persona se gastó 8 $ en crédito de Claude y obtuvo una implementación que mejoró el tiempo de generación de la API un 18%, ahorrando 30 segundos en una herramienta que usaba a diario todo el equipo. 

Algunos desarrolladores van más allá: ejecutan worktrees en competencia que implementan enfoques distintos al mismo problema y comparan resultados.

Mejores prácticas de arquitectura en CLAUDE.md

Tu archivo CLAUDE.md tiene un presupuesto que probablemente no conoces. El análisis de HumanLayer sobre el funcionamiento interno de Claude Code detectó que el sistema inyecta un recordatorio por encima de tus instrucciones: "This context may or may not be relevant to your tasks." 

Entender el sistema de instrucciones por capas de Claude Code

Claude filtra activamente qué sigue, en lugar de tratarlo todo como un mandato persistente. Además, los modelos con razonamiento puntero siguen en torno a 150-200 instrucciones antes de que caiga la conformidad, y el prompt de sistema de Claude Code ocupa unas 50. Eso te deja aproximadamente 100-150 huecos para tus reglas. HumanLayer mantiene su archivo por debajo de 60 líneas.

Puedes observar este presupuesto en acción. Añade una línea a tu CLAUDE.md diciendo "always address me as Mr. Tinkleberry" y verás lo rápido que Claude deja de usarla, normalmente en unos miles de tokens. Cuando desaparece el nombre, tus instrucciones pierden prioridad por el mecanismo de atención, y todo lo demás en tu CLAUDE.md también pierde influencia.

Usar revelación progresiva para referencias de instrucciones

La forma de trabajar dentro de este presupuesto es la revelación progresiva. Tu CLAUDE.md raíz se mantiene corto y centrado en reglas que aplican en todo el proyecto. Para lo específico del dominio, referencia un archivo aparte sin incrustarlo: "Cuando trabajes con el sistema de pagos, lee primero docs/payment-architecture.md." 

Claude solo lee el archivo referenciado cuando entra en esa parte del código, liberando tu presupuesto de instrucciones para reglas prioritarias. Una empresa que consume miles de millones de tokens al mes estructura así el CLAUDE.md de su monorepo, con cada equipo con un presupuesto de tokens para su sección:

# Monorepo CLAUDE.md — progressive disclosure
 
## Python
- Always use type hints for function signatures
- Test with: pytest -x --tb=short
 
## <Internal CLI Tool>
- <usage example>
- Always validate input before processing
- Never use raw SQL, prefer the ORM
For <complex usage> or <error> see path/to/<tool>_docs.md

Los CLAUDE.md de subdirectorios amplían esto aún más. Pon un CLAUDE.md en src/persistence/ con instrucciones específicas de base de datos y otro en src/api/ con convenciones de endpoints. 

Claude carga automáticamente los CLAUDE.md desde el directorio de trabajo hacia arriba hasta la raíz del proyecto, así que los archivos de subdirectorio solo se activan cuando Claude trabaja en esa zona. Mantienes el archivo raíz general y das a Claude instrucciones precisas justo donde hacen falta.

Un error habitual: no hagas @-file de documentación dentro de CLAUDE.md. Eso incrusta el archivo entero en cada ejecución y se come tu presupuesto de instrucciones antes de empezar la conversación.

Gestión de contexto en Claude Code

Claude Code te da 200K tokens de contexto, pero la ventana utilizable es menor de lo que parece. 

Una sesión limpia de monorepo consume unos 20K tokens cargando el prompt de sistema, definiciones de herramientas y CLAUDE.md antes de que escribas nada. Cada servidor MCP añade esquemas de herramientas que ocupan contexto de forma permanente, así que el límite práctico es de unas 5-8 instancias antes de empezar a desplazar trabajo real.

Lo peor es lo pronto que cae la calidad. Múltiples profesionales han llegado de forma independiente al mismo umbral: no dejes que el contexto supere el 60% de capacidad. 

La salida de Claude empieza a degradarse entre el 20-40% de la ventana, mucho antes de tocar el límite, porque el mecanismo de atención resta peso a instrucciones tempranas según se llena el contexto. 

La auto-compactación salta en torno al 83,5% y es con pérdida: una persona perdió 3 horas de refactorización cuando borró decisiones de migración a mitad de sesión, reteniendo solo el 20-30% de los detalles.

Usar el patrón Document & Clear

La mejor defensa es el patrón Document & Clear. Cuando el contexto pese: 

1. Vuelca tu plan y progreso actual en un archivo markdown

2. Ejecuta /clear para reiniciar la sesión

3. Empieza de cero con Claude leyendo ese archivo

Así tienes la ventana completa de 200K solo con lo que decidas conservar, mejor que /compact porque controlas exactamente qué sobrevive. 

Un comando personalizado /catchup suaviza la transición: tras limpiar, lee todos los archivos cambiados en la rama git actual para que Claude retome el hilo sin el histórico de conversación.

<!-- .claude/commands/catchup.md -->
Rebuild context after a /clear. Read all files modified on the
current branch compared to main. For each file, understand the
changes made. Then summarize what's been implemented so far and
what work remains.
 
Changed files on this branch:
$ git diff --name-only main

Transferir contexto con skills personalizadas de Claude Code

Uso una /transfer-context skill que va un paso más allá. Cuando una sesión empieza a degradarse, el comando vuelca un archivo de traspaso estructurado con el trabajo completado, decisiones abiertas, trampas a evitar y rutas de archivos relevantes. La siguiente sesión lee ese archivo y retoma donde lo dejó la anterior, con solo la información que importa y sin la paja de la conversación.

Otras buenas prácticas para ahorrar contexto

También puedes ahorrar contexto cargando herramientas de forma perezosa. Un proyecto recuperó unos 15.000 tokens por sesión usando hooks UserPromptSubmit para inyectar definiciones de skills solo cuando el prompt del usuario activaba palabras clave relevantes, en lugar de precargar todo al inicio.

La regla más simple detrás de todo esto: una tarea por conversación. Empezar de cero cuesta 20K tokens, nada comparado con la pérdida de calidad de una sesión contaminada.

Hooks de Claude Code como barandillas deterministas

Incluso un CLAUDE.md bien estructurado se sigue solo un 70% de las veces. Para preferencias de estilo, vale. Para reglas de seguridad como "no hagas push a main" o "no borres datos de producción", no. Los hooks cierran ese hueco al 100% ejecutando scripts de shell en puntos concretos del flujo de Claude.

Hay dos tipos clave. Los hooks de bloqueo al enviar se ejecutan como eventos PreToolUse y paran la acción en seco: el código de salida 2 bloquea y obliga a Claude a probar otra cosa. Los hooks de pista dan feedback no bloqueante, como ejecutar un linter tras cada edición y devolver la salida sin interrumpir el flujo.

La configuración pública más completa hace lo siguiente:

• Bloquea comandos rm -rf (sugiere trash en su lugar), 

• Impide pushes directos a main, 

• Registra todas las mutaciones con marca de tiempo, y 

• Ejecuta una compuerta anti-racionalización. 

Esa compuerta usa Haiku para revisar respuestas de Claude y cazar excusas tipo "problemas preexistentes" o "fuera de alcance". Cuando detecta una victoria prematura, rechaza la respuesta con feedback concreto y obliga a Claude a seguir trabajando. Una versión más ligera ejecuta automáticamente Prettier y comprobaciones de TypeScript tras cada edición de archivo:

{
  "hooks": {
	"PostToolUse": [
  	{
    	"matcher": "Edit|Write",
    	"hooks": [
      	{
        	"type": "command",
        	"command": "prettier --write \"$CLAUDE_FILE_PATHS\""
      	}
    	]
  	}
	]
  }
}

Una trampa a evitar: nunca bloquees las herramientas Edit o Write a mitad de un plan. Bloquear en escritura rompe el razonamiento multi-paso porque Claude pierde el hilo. Deja que termine de escribir y valida después con hooks PostToolUse o comprobaciones pre-commit. Nuestro tutorial de hooks de Claude Code cubre más patrones si quieres construir sobre ellos.

Desarrollo guiado por pruebas como estrategia óptima de programación agentic

Sin tests, la única forma que tiene Claude de verificar su trabajo es su propio juicio, que se degrada a medida que se llena el contexto. Los tests crean un oráculo externo que sigue siendo fiable por muy larga que sea la sesión. 

Cada ciclo de rojo a verde da a Claude feedback inequívoco, y puede iterar por toda la batería sin intervención humana, lo que convierte el desarrollo guiado por pruebas (TDD) en el patrón más sólido para trabajar con herramientas de programación agentic.

El flujo que recomienda Anthropic sigue una secuencia concreta:

1. Write tests first
   > "Write tests for the auth module using pytest.
  	TDD approach, no mock implementations."
 
2. Confirm tests fail
   > "Run the tests. They should all fail."
 
3. Commit the failing tests as a checkpoint
 
4. Implement until green
   > "Write the implementation. Do not modify the tests.
  	Keep going until all tests pass."

La última instrucción es más importante de lo que parece. A veces Claude cambia los tests para hacerlos pasar en lugar de arreglar la implementación. Hacer commit de los tests antes te da una red de seguridad: si Claude los toca, el diff muestra qué cambió y puedes revertir.

Para frontend, funciona bien una variante visual del bucle: si le das a Claude un diseño mock y un servidor MCP de Puppeteer, hace una captura tras implementar, la compara con el mock y vuelve a iterar. Este bucle de verificación mejora la calidad entre 2 y 3 veces cuando Claude puede comprobar su salida contra un objetivo visual.

Economía de costes y selección de modelo en Claude Code

Los datos oficiales de Anthropic sitúan el coste medio de Claude Code en 6 $ por desarrollador y día con precios de API, con el 90% por debajo de 12 $/día. Al mes, son unos 100-200 $ por desarrollador con Sonnet 4.6.

La suscripción Max cambia las cuentas por completo. Una persona registró 8 meses de uso con unos 10.000 millones de tokens y calculó que su coste equivalente por API superaría los 15.000 $, mientras que su suscripción Max real fue de unos 800 $: un 93% de ahorro. 

Más del 90% de sus tokens fueron lecturas de caché, por eso el cobro por uso de la API penaliza mucho más que una suscripción plana. El punto de equilibrio del plan Max está en torno a 100-200 $/mes en uso equivalente de API, un umbral que cualquiera que lo use a diario supera rápido.

La selección de modelo es otra optimización. El modo "opusplan" de Claude Code enruta Opus 4.6 para planificar y cambia automáticamente a Sonnet 4.6 para generar código, logrando el razonamiento de Opus donde más importa y usando las tarifas 5 veces más baratas de Sonnet para los tokens de implementación. 

Sonnet 4.6 fue preferido frente a Opus 4.5 por el 59% de usuarios de Claude Code en pruebas internas de Anthropic y suele producir código más limpio con menos sobreingeniería. Para flujos con muchos subagentes, CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929" ejecuta los subagentes en Sonnet manteniendo Opus para el orquestador.

Asegúrate de evitar las tres grandes fuentes de despilfarro de tokens: 

• No limpiar el contexto entre tareas 

• Lecturas de archivos redundantes por una mala estructura de CLAUDE.md

• Prompts vagos que llevan a Claude a bucles de prueba y error

Corregir solo estas tres suele reducir el uso de tokens a la mitad.

Resolución de problemas en Claude Code

Antes de cerrar, veamos problemas habituales al trabajar con Claude Code y cómo atajarlos.

Pérdida de contexto

El fallo más doloroso es la pérdida de contexto. El patrón Document & Clear del apartado de gestión de contexto existe justo por esto: nunca dejes que una sesión larga sea tu único registro de decisiones. Haz commit a menudo, vuelca el progreso a archivos y trata cada sesión como desechable.

Alucinaciones con tecnologías de nicho

Claude también genera código convincente para tecnologías que no domina. Si trabajas en un lenguaje o framework que no puedes verificar tú mismo, cada salida requiere revisión extra. Como dijo un desarrollador: "Me he metido en un buen lío usando LLMs con tecnologías que no conozco. Pero con algo que sí controlo, los LLMs han multiplicado mi velocidad."

Sobreingeniería

La sobreingeniería es frecuente. Claude tiende a escribir capas extra, helpers no solicitados y refactorizaciones prematuras si no le dices lo contrario. Añadir "usa el enfoque más simple posible" a tu CLAUDE.md ayuda, y organizar la base de código por dominios de problema en lugar de por capas técnicas reduce la carga cognitiva para Claude y para los humanos.

Pérdida de datos críticos

El fallo más dramático registrado: mientras se creaba una app de fonética, Claude borró todos los archivos de audio de fonemas para los que el desarrollador tenía permiso y los sustituyó por sonidos generados por IA. Renombró archivos y "se convenció de que había etiquetado mal, pese a no poder distinguir los fonemas relevantes". 

La lección: haz commit o copia de seguridad de archivos irremplazables antes de dar a Claude acceso a ellos.

Sesiones improductivas

El propio consejo de Anthropic para sesiones que se tuercen es honestamente directo: guarda el estado antes de dejar trabajar a Claude, deja que ejecute, y después acepta el resultado o empieza de cero en lugar de pelearte con correcciones. 

Cuánto confiar a Claude los commits depende de tu cobertura de tests y tu tolerancia al riesgo. Algunas personas hacen commit con comandos slash decenas de veces al día, con la revisión de PR como compuerta. En bases de código en producción con clientes, revisar cada diff compensa la fricción.

Ponte manos a la obra con Claude Code

Para más detalles, el Claude Code Overview de Anthropic es la referencia canónica sobre la que se apoya gran parte del contenido de la comunidad. Si quieres profundizar en lo de aquí y practicar varias funciones de Claude Code, estos tutoriales merecen la pena:

• Claude Code 2.1 Guide — descubre las novedades de la versión 2.1, cómo configurar Claude Code y realiza una serie de experimentos guiados
• Claude Code Hooks Tutorial — profundiza en la automatización con hooks y aprende a usarlos para testing, formateo y notificaciones
• Using Claude Code With Ollama Local Models — ejecuta GLM 4.7 Flash en local con Claude Code y Ollama para evitar lock-in y transferencias a la nube
• How to Build Claude Code Plugins — aprende a instalar extensiones, elegir entre skills y MCPs, y crear un plugin de logging de sesiones
• Claude Code Docker — ejecuta Claude Code en Docker para entornos aislados y domina prácticas seguras de programación para agentes de IA
• Claude Code Router — conecta con múltiples proveedores de modelos y usa el LLM adecuado para cada tarea

Varios proyectos open source también empaquetan las prácticas de este artículo en configuraciones listas para usar:

• obra/superpowers — un framework de skills componible que incluye TDD forzado, lluvia de ideas socrática, planificación granular y revisión automática de código entre tareas. Ahora es un plugin oficial en el marketplace de Anthropic.

• github/spec-kit — el toolkit oficial de GitHub para Spec-Driven Development. Estructura el trabajo como Constitución → Especificar → Plan → Tareas, haciendo que la spec sea la única fuente de verdad para cualquier agente de código.

• bmad-code-org/BMAD-METHOD — un framework ágil completo con más de 12 personas de agente (Arquitecto, QA, Scrum Master) y 34+ flujos que cubren todo el ciclo de desarrollo.

• wshobson/commands — 57 comandos slash listos para producción que puedes colocar en .claude/commands/, incluidos 15 flujos multiagente.

• awesome-claude-code — el directorio de referencia del ecosistema de skills, hooks, comandos, agentes y plugins. Empieza aquí si quieres explorar.

Conclusión

Todos los patrones de este artículo convergen en la misma idea: constriñe a Claude de forma agresiva antes de ejecutar y dale una forma de verificar su salida. La planificación elimina ambigüedad. CLAUDE.md y los hooks ponen límites. Los tests verifican. La higiene de contexto mantiene todo funcionando entre sesiones.

Si vas a empezar por un solo cambio, que sea Document & Clear. El coste de la pudrición del contexto entre sesiones supera con creces los 20K tokens necesarios para empezar de cero. Después:

• Añade un hook pre-commit que bloquee commits si fallan los tests

• Empieza toda tarea multiarchivo con un plan antes de tocar código

• Mantén tu CLAUDE.md por debajo de 100 instrucciones y usa archivos por subdirectorio para reglas específicas de dominio

Hemos añadido recientemente un nuevo itinerario de habilidades sobre AI Engineering with LangChain. Su contenido es IA-nativo, así que podrás aprender con tu propio agente tutor. Te recomiendo echarle un vistazo para convertirte en un auténtico pro diseñando flujos de trabajo de IA.