0. TL;DR
Este artículo surge de seis meses de uso profundo de Claude Code y de las lecciones aprendidas al gastar $40/mes en dos cuentas. Espero aportar algo valioso para todos.
Inicialmente lo usé como ChatBot, pero pronto me di cuenta de que algo iba mal: el contexto se volvía desordenado, las herramientas aumentaban pero la efectividad disminuía, y las reglas se ignoraban a pesar de ser más largas. Tras investigar Claude Code en sí, comprendí 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 vuelve y cómo controlarlo, cómo diseñar Skills y Hooks, el uso correcto de Subagents, el impacto arquitectónico de 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 provoca desequilibrio. Si CLAUDE.md es demasiado largo, contamina el contexto; demasiadas herramientas causan confusión; demasiados subagentes generan desviación de estado; saltarse la verificación impide encontrar dónde falló.
1. Cómo funciona internamente
El núcleo de Claude Code no es "responder", sino un bucle agéntico repetitivo:
1Recolectar 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 proporcionarle el contexto equivocado o no tener forma de juzgar si la salida es correcta o de revertirla.
Cinco capas en las que enfocarse:
Mirar estas capas facilita la resolución de problemas. ¿Resultados inestables? Revisa el orden de carga del contexto. ¿Automatización descontrolada? 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 / Herramientas / Skills / Hooks / Subagentes
Regla simple: usa Herramientas/MCP para nuevas acciones, 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 del contexto: la restricción más importante del sistema
Muchos tratan el contexto como un "problema de capacidad", pero el cuello de botella suele ser el ruido. La información útil queda enterrada en contenido irrelevante.
Composición real del costo del contexto
El contexto de 200K de Claude Code no está completamente disponible:
1Contexto Total 200K2├── 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 oculto 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 recomendadas del contexto
1Siempre residente → CLAUDE.md: Contrato del proyecto / comandos de compilación / prohibiciones2Basado en ruta → rules: Reglas específicas de idioma / 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 solo usas ocasionalmente.
Mejores prácticas para el contexto
- Mantén CLAUDE.md corto, directo y ejecutable. El propio Anthropic tiene ~2.5K tokens.
- Mueve documentos de referencia grandes de referencia a archivos de apoyo de 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 instrucciones compactas 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 fácilmente el contexto. 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 salida de pruebas en un solo mensaje de éxito.
Trampas de compresión
La compresión predeterminada podría eliminar decisiones arquitectónicas y restricciones.
Solución: Especifica instrucciones compactas en CLAUDE.md para priorizar decisiones arquitectónicas, 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 el progreso y los 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
Las Skills son conocimiento y flujos de trabajo bajo demanda.
Qué hace una buena Skill
- La descripción debe decir "cuándo usarme", no "qué hago".
- Tener pasos completos, entradas, salidas y condiciones de parada.
- Mantener el cuerpo principal para navegación y restricciones centrales; mover detalles a archivos de apoyo.
- Establecer disable-model-invocation: true para skills con efectos secundarios.
Revelación progresiva
Claude Code enfatiza la "revelación progresiva": primero proporciona índices y navegación, luego extrae detalles según sea necesario.
Tres tipos típicos de Skill
- Lista de verificación (Puerta de calidad): por ejemplo, release-check.
- Flujo de trabajo (Operaciones estandarizadas): por ejemplo, config-migration con reversión.
- Experto en dominio (Marco de decisión): por ejemplo, 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.
<payload-block>
Las herramientas de tareas pendientes se convirtieron en una "cadena" a medida que los modelos se volvían más fuertes. Las herramientas de búsqueda evolucionaron de RAG a Grep para una mejor flexibilidad y "revelació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.
Adecuado para Hooks
Bloquear archivos protegidos, autoformatear después de ediciones, inyectar contexto dinámico (rama 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 producen una salida masiva que no debería saturar el hilo principal.
Restricciones explícitas
Limita las herramientas, elige el modelo correcto (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 en torno a Prompt Caching. Las altas tasas de acierto ahorran dinero y aumentan los límites de velocidad.
Diseño del prompt para el caché
El orden importa para la coincidencia de prefijos: Prompts del sistema → Definiciones de herramientas → Historial del chat → Entrada del usuario.
No cambies de modelo a mitad de sesión
Cambiar de modelo rompe el caché. Usa Subagentes para las transferencias.
Implementación de la compactación
La compactación usa una bifurcación (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 el Prompt, la 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 secundarias), /insight (analizar sesión para actualizar CLAUDE.md).
11. Cómo escribir un buen CLAUDE.md
Es un contrato, no una base de conocimientos.
Incluye comandos de compilación/prueba, límites arquitectónicos, convenciones de código, barreras de seguridad e Instrucciones Compactas. Pide a Claude que actualice CLAUDE.md después de corregir sus errores.
12. Experiencias recientes
Lecciones de la construcción de Kaku (Rust + Lua): la transparencia del entorno es vital (usa un comando 'doctor'), y los Hooks son excelentes para proyectos multilingüe.
13. Antipatrones
14. Comprobación de estado
Usa npx skills add tw93/claude-health para verificar tu configuración.
15. Conclusión
<payload-block id="blk_21" type="upload"
El enfoque cambia de "cómo usar las funciones" a "cómo dejar que el agente se ejecute bajo restricciones". Si no puedes definir "terminado", la tarea no está lista para un agente.
