0. TL;DR
Este artículo surge de seis meses de uso intensivo de Claude Code y lecciones aprendidas al gastar $40 al mes en dos cuentas. Espero aportar información valiosa para todos.
Inicialmente lo usé como ChatBot, pero pronto me di cuenta de que algo andaba mal: el contexto se volvía confuso, las herramientas aumentaban pero la efectividad disminuía, y las reglas se ignoraban a pesar de ser más largas. Después de investigar a fondo Claude Code, entendí que no era un problema de Prompt, sino de diseño del sistema.
Quiero hablar de: cómo funciona Claude Code internamente, por qué el contexto se ensucia y cómo gestionarlo, cómo diseñar Skills y Hooks, el uso correcto de Subagentes, el impacto arquitectónico del Prompt Caching y cómo escribir un CLAUDE.md realmente útil.
La forma más directa de entenderlo es dividir Claude Code en seis capas:
Reforzar solo una capa genera desequilibrio. Si CLAUDE.md es demasiado largo, contamina el contexto; demasiadas herramientas causan confusión; demasiados subagentes derivan en desviación de estado; saltarse la verificación imposibilita encontrar dónde falló.
1. Cómo funciona internamente
El núcleo de Claude Code no es "responder", sino un bucle agéntico repetitivo:
1Recopilar Contexto → Tomar Acción → Verificar Resultado → [Finalizar o Repetir]2 ↑ ↓3 CLAUDE.md Hooks / Permisos / Sandbox4 Skills Herramientas / MCP5 Memoria
Me di cuenta de que los cuellos de botella rara vez se deben a que el modelo no sea lo suficientemente inteligente, sino a que se le entrega el contexto equivocado o no hay forma de evaluar si la salida es correcta ni de revertirla.
Cinco capas en las que enfocarse:
Al observar estas capas, solucionar problemas es más fácil. ¿Resultados inestables? Revisa el orden de carga del contexto. ¿Automatización fuera de control? Revisa la capa de control. ¿Calidad decreciente en sesiones largas? Los productos intermedios contaminaron el contexto; es mejor iniciar una nueva sesión que ajustar los prompts.
2. Límites conceptuales: MCP / Plugin / Tools / Skills / Hooks / Subagentes
Regla simple: usa Tools/MCP para acciones nuevas, Skills para flujos de trabajo, Subagentes para entornos aislados, Hooks para restricciones/auditoría obligatorias y Plugins para distribución entre proyectos.
3. Ingeniería de Contexto: La Restricción del Sistema Más Importante
Muchos tratan el contexto como un "problema de capacidad", pero el cuello de botella suele ser el ruido. La información útil queda enterrada bajo contenido irrelevante.
Composición Real del Costo del Contexto
El contexto de 200K de Claude Code no está completamente disponible:
1200K de Contexto Total2├── Sobrecarga Fija (~15-20K)3│ ├── Instrucciones del sistema: ~2K4│ ├── Descriptores de Skills: ~1-5K5│ ├── Definiciones de herramientas del servidor MCP: ~10-20K ← El mayor asesino oculto6│ └── Estado LSP: ~2-5K7│8├── Semifijo (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memoria: ~1-2K11│12└── Dinámico Disponible (~160-180K)13 ├── Historial del chat14 ├── Contenido de archivos15 └── Resultados de herramientas
Un servidor MCP típico (como GitHub) contiene 20-30 definiciones de herramientas, cada una de ~200 tokens, totalizando 4,000-6,000 tokens. Conectar 5 servidores consume 25,000 tokens (12.5%). Esto es crítico al leer grandes cantidades de código.
Capas de Contexto Recomendadas
1Siempre Residente → CLAUDE.md: Contrato del proyecto / comandos de compilación / prohibiciones2Basado en Ruta → rules: Reglas de lenguaje / directorio / tipo de archivo3Bajo Demanda → Skills: Flujos de trabajo / conocimiento del dominio4Aislado → Subagentes: Exploración a gran escala / investigación paralela5Fuera del Contexto → Hooks: Scripts deterministas / auditoría / bloqueo
No cargues cosas que usas solo de vez en cuando.
Mejores Prácticas de Contexto
- Mantén CLAUDE.md corto, contundente y ejecutable. El de Anthropic tiene ~2.5K tokens.
- Mueve documentos de referencia extensos a los archivos de soporte de los Skills.
- Usa .claude/rules/ para reglas de ruta/idioma.
- Usa /context para monitorear el consumo.
- Usa /clear para cambiar de tarea y /compact para nuevas fases.
- Escribe Compact Instructions en CLAUDE.md para controlar lo que se conserva.
Ruido en la Salida de Herramientas: Otro Asesino Oculto
La salida dinámica de herramientas (como cargo test o git log) puede llenar el contexto fácilmente. Claude no necesita verlo todo.
RTK (Rust Token Killer) es un buen enfoque: filtra la salida de comandos antes de que llegue a Claude. Por ejemplo, puede condensar miles de líneas de resultados de pruebas en un solo mensaje de éxito.
Trampas de Compresión
La compresión predeterminada puede eliminar decisiones de arquitectura y restricciones.
Solución: Especifica Compact Instructions en CLAUDE.md para priorizar decisiones de arquitectura, archivos modificados, estado de verificación y tareas pendientes.
Otra solución proactiva: haz que Claude escriba un HANDOFF.md antes de iniciar una nueva sesión para explicar avances y callejones sin salida.
Valor de Ingeniería del Modo Plan
El Modo Plan separa la exploración de la ejecución.
Para refactorizaciones complejas, esto es mejor que lanzarse a codificar. Consejo avanzado: usa un Claude para escribir el plan y otro como "Ingeniero Senior" para revisarlo.
4. Diseño de Skills: Flujos de Trabajo Cargados Bajo Demanda
Los Skills son flujos de trabajo y conocimiento bajo demanda.
Qué hace que un Skill sea bueno
- La descripción debe decir "cuándo usarme", no "qué hago".
- Debe tener pasos completos, entradas, salidas y condiciones de parada.
- Mantén el cuerpo principal para la navegación y restricciones centrales; mueve los detalles a archivos de soporte.
- Establece
disable-model-invocation: truepara Skills con efectos secundarios.
Divulgación Progresiva
Claude Code enfatiza la "divulgación progresiva": primero proporciona índices y navegación, luego extrae detalles según sea necesario.
Tres Tipos Típicos de Skills
- Lista de Verificación (Puerta de Calidad): ej., release-check.
- Flujo de Trabajo (Operaciones Estandarizadas): ej., config-migration con reversión.
- Experto en Dominio (Marco de Decisión): ej., runtime-diagnosis.
Mantén los descriptores cortos para ahorrar espacio en el contexto.
5. Diseño de Herramientas: Ayudar a Claude a Elegir Correctamente
Las herramientas para agentes deben centrarse en la facilidad de uso correcto, no en la completitud de funciones.
Herramientas Buenas vs. Malas
Principios de diseño: usa prefijos (github_pr_*), soporta formatos concisos, proporciona mensajes de error útiles y evita exponer demasiadas herramientas fragmentadas.
Evolución de las Herramientas Internas
La evolución de la herramienta "AskUserQuestion" muestra que una herramienta dedicada es más estable que el formato markdown o los parámetros de salida.
Las herramientas de tareas pendientes se convirtieron en una "atadura" a medida que los modelos se volvieron más potentes. Las herramientas de búsqueda evolucionaron de RAG a Grep para ofrecer mejor flexibilidad y "divulgación progresiva".
6. Hooks: Lógica Obligatoria Antes/Después de las Operaciones
Los Hooks recuperan el control determinista sobre procesos como formateo, protección de archivos y notificaciones.
Adecuados para Hooks
Bloquear archivos protegidos, autoformatear después de ediciones, inyectar contexto dinámico (rama de Git) y notificaciones.
Detección Temprana de Errores
7. Subagentes: Instancias Independientes de Claude
Los Subagentes proporcionan aislamiento. Tareas como escanear repositorios o ejecutar pruebas generan resultados masivos que no deberían saturar el hilo principal.
Restricciones Explícitas
Limita las herramientas, elige el modelo adecuado (Haiku para exploración, Opus para revisión) y establece maxTurns.
8. Prompt Caching: El Núcleo de la Arquitectura de Claude Code
Claude Code está construido alrededor de Prompt Caching. Las altas tasas de acierto ahorran dinero y aumentan los límites de velocidad.
Disposición del Prompt para Caching
El orden importa para la coincidencia de prefijos: System Prompt → Tool Definitions → Chat History → User Input.
No Cambies de Modelo a Mitad de Sesión
Cambiar de modelo rompe el caché. Usa Subagentes para las transferencias.
Implementación de Compactación
La compactación usa un fork para resumir el historial a 1/10 del costo gracias a los aciertos de caché.
9. Bucles de Verificación: Sin Verificador, No Hay Agente de Ingeniería
"Claude dice que está listo" es inútil sin verificación. Define la verificación explícitamente en Prompt, Skill y CLAUDE.md.
10. Comandos de Alta Frecuencia
Comandos como /context, /clear, /compact y /memory ayudan a gestionar el contexto activamente.
Gobernanza y Paralelismo
Comandos ocultos útiles: /simplify (revisión de código), /rewind (puntos de control), /btw (preguntas laterales), /insight (analizar la sesión para actualizaciones de CLAUDE.md).
11. Cómo Escribir un Buen CLAUDE.md
Es un contrato, no una base de conocimiento.
Incluye comandos de compilación/prueba, límites de arquitectura, convenciones de código, barreras de seguridad y Compact Instructions. Pídele a Claude que actualice CLAUDE.md después de corregir sus errores.
12. Experiencias Recientes
Lecciones al construir Kaku (Rust + Lua): la transparencia del entorno es vital (usa un comando 'doctor'), y los Hooks son excelentes para proyectos multilingües.
13. Anti-patrones
14. Verificación de Salud
Usa npx skills add tw93/claude-health para verificar tu configuración.
15. Conclusión
El enfoque cambia de "cómo usar las funciones" a "cómo hacer que el agente funcione bajo restricciones". Si no puedes definir "terminado", la tarea no está lista para un agente.
