Harness engineering

Harness engineering es la práctica de mejorar la calidad de las respuestas del modelo interviniendo sobre los elementos configurables que lo rodean: system prompt, capa de configuración, herramientas disponibles, ventana de contexto, bucle de ejecución y mecanismos de mantenimiento.

La práctica existe porque el modelo no es lo único que se diseña. Dos sesiones con el mismo modelo y la misma pregunta pueden producir resultados muy distintos en función de qué se cargó en el system prompt, qué herramientas estaban activas y qué quedaba en la ventana de contexto en ese momento. Cada uno de esos elementos es una decisión del usuario, no una constante del modelo.

El usuario lo nota cuando una instrucción dada al inicio deja de aplicarse, cuando el coste por turno aumenta sin causa aparente o cuando el agente ejecuta una herramienta fuera del alcance previsto. Esos síntomas no se corrigen reformulando la pregunta: se corrigen ajustando el harness.

Anatomía

System prompt. Primera capa que recibe el modelo y la única que el usuario no edita. Define el rol del agente, las convenciones de salida y las reglas operativas básicas. Anthropic lo actualiza con cada versión del CLI.

Capa de configuración. Los archivos CLAUDE.md jerárquicos (organización, global, proyecto, subdirectorio), settings.json, el output style activo y la auto memory del proyecto (MEMORY.md). Es la superficie que el usuario modifica con más frecuencia.

Tool surface. El conjunto de herramientas que el modelo puede llamar en un turno: built-in (Read, Edit, Write, Bash, Grep…), servidores MCP, slash commands, skills y subagentes. Cada herramienta presente añade tokens al system prompt efectivo.

Ventana de contexto. El historial visible en la invocación actual: mensajes, respuestas, resultados de herramientas y archivos leídos. Su tamaño máximo depende del modelo, pero en todos los casos es el recurso más limitado del sistema: lo que no esté en esta ventana, para el modelo no existe.

Bucle de ejecución. El ciclo del CLI que compone el contexto, llama al modelo, procesa la respuesta, ejecuta las herramientas solicitadas e inyecta sus resultados como nuevos mensajes hasta que la respuesta final no contiene llamadas pendientes.

Mecanismos de mantenimiento. Los componentes que controlan la evolución del harness entre turnos: la compactación automática cuando el contexto se aproxima al límite, los hooks que ejecutan acciones en eventos predefinidos (UserPromptSubmit, PostToolUse, SessionStart…) y la capa de permisos que determina qué herramientas se autorizan sin intervención del usuario.

Funcionamiento

Cada turno reconstruye el harness desde cero. El modelo no mantiene estado entre invocaciones: lo que el usuario percibe como continuidad es el resultado de reenviar el historial completo en cada llamada al backend.

El bucle empieza componiendo el contexto: el CLI concatena system prompt, CLAUDE.md aplicable, descripciones de herramientas activas, system reminders y el historial de la sesión. El resultado se envía al endpoint como un único bloque de tokens.

El modelo responde, y si su respuesta contiene tool calls, el CLI las ejecuta — secuencialmente o en paralelo si el modelo emitió varias en el mismo turno — y devuelve sus resultados al contexto como nuevos mensajes. El bucle vuelve a llamar al modelo y se repite hasta que la respuesta no contiene llamadas pendientes. Cada iteración reenvía todo el historial acumulado, por lo que el coste crece de forma cuadrática con el número de llamadas encadenadas.

Al cierre del turno se aplican los hooks (PostToolUse, Stop…) y los mecanismos de mantenimiento: la capa de permisos registra qué herramientas se autorizaron y, si el contexto se aproxima al límite del modelo, se dispara una compactación que sustituye el historial antiguo por una síntesis.

Construcción

Diseñar el harness consiste en controlar cinco mecanismos, ordenados por impacto sobre el comportamiento final.

Contexto base

CLAUDE.md actúa como cabecera permanente: todo lo que figure en él compite por tokens con el resto del contexto. Conviene separar las reglas en dos niveles: instrucciones operativas estables (convenciones de código, comandos del proyecto, restricciones de seguridad) directamente en CLAUDE.md, y guías extensas sobre dominios concretos (estilo de tests, esquema de una API, convenciones de UI) en archivos bajo .claude/conventions/, referenciados desde CLAUDE.md con la indicación de leerlos bajo demanda.

Encadenar los niveles de la jerarquía permite repartir el contenido por su alcance: preferencias personales en el CLAUDE.md global, convenciones del repositorio en el de proyecto y particularidades de un módulo concreto en el de subdirectorio.

Tool surface

Reducir la tool surface es el control más barato para bajar coste y errores. Tres mecanismos suman:

• settings.json restringe las herramientas autorizadas mediante el bloque permissions, con las listas allow, deny y ask; --allowedTools y --disallowedTools existen como equivalentes en la CLI, no como claves del JSON.
• Los servidores MCP se cargan de forma selectiva por proyecto; activar uno de gran superficie (acceso a base de datos, a Notion, a GitHub) en un proyecto que no lo necesita es una causa habitual de saturación.
• Los subagentes son el mecanismo principal de aislamiento: una llamada a Agent ejecuta el subagente en una ventana propia y devuelve solo su respuesta final al hilo principal. Las tareas con resultados voluminosos — exploraciones, búsquedas extensas, revisiones — se delegan a subagentes para que su contenido no se acumule en el contexto principal.

Economía del contexto

Cada modelo aplica tarifas distintas para entrada y salida, y Anthropic aplica caché de prompt sobre el prefijo estable del contexto — system prompt, CLAUDE.md y descripciones de herramientas, que quedan fijados al inicio de la sesión y no se recargan hasta la siguiente. Si ese prefijo no cambia entre turnos, se factura al precio reducido de caché; cualquier cambio lo invalida. De ahí que el orden importe: lo estable va al principio.

La elección del modelo modifica la ecuación. El modelo de mayor capacidad resulta adecuado en fases de diseño y razonamiento denso; el modelo intermedio cubre la mayoría de las ediciones rutinarias a una fracción del coste; el modelo más ligero se aplica en tareas mecánicas de alto volumen — formateo, búsquedas con respuesta corta, validaciones — y en subagentes cuyo resultado sea pequeño y esté bien acotado.

Compactación

La compactación automática conserva la sesión pero reduce el nivel de detalle. Para trabajos largos, la regla operativa consiste en anticiparse:

• Cuando el contexto alcanza el 70-80 % del límite, ejecutar /compact <instrucciones> permite controlar qué se conserva.
• Cuando una sesión cambia de tarea — del diseño a la implementación, de un módulo a otro — conviene cerrar la sesión y abrir una nueva. Reconstruir contexto desde CLAUDE.md resulta habitualmente más barato que arrastrar el contenido irrelevante ya acumulado.
• En sesiones críticas, registrar las decisiones de diseño en un archivo del proyecto (un log de decisiones, una nota en .claude/) garantiza que sobrevivan a cualquier compactación.

Comportamiento estable vía hooks

Los recordatorios en prosa dentro de CLAUDE.md son frágiles: cuanto más se aleja un turno del inicio, menor es su efecto. Cuando una restricción debe cumplirse siempre — formatear antes de un commit, ejecutar tipado tras editar TypeScript, bloquear escrituras fuera de ciertos directorios — un hook resulta más fiable que un recordatorio, porque se ejecuta al margen del juicio del modelo. UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop y SessionStart son algunos de los puntos de extensión disponibles; los dos primeros concentran la mayoría de las restricciones que se imponen antes de que el modelo actúe.

Límites

El harness tiene puntos de fallo conocidos. Identificarlos evita atribuir al modelo problemas que corresponden al diseño del propio harness.

Saturación por tool results extensos. Un grep masivo, un package-lock.json o un dump JSON de varios miles de líneas pueden ocupar una parte sustancial de la ventana en un único turno. El efecto inmediato es desplazar las instrucciones tempranas hacia el fondo del historial, donde su peso se reduce. La mitigación consiste en delegar la lectura a un subagente que sintetice antes de devolver, o utilizar herramientas más específicas (head, wc -l, filtros) en lugar de volcados completos.

Pérdida silenciosa de contexto. Hay dos vías por las que información ya registrada deja de estar disponible sin aviso. La primera es la compactación: una decisión que existía solo en la conversación desaparece con la síntesis. La segunda son los ficheros de memoria persistente que operan como índice con presupuesto de tamaño: cuando una entrada nueva rebasa el cupo, las más antiguas se truncan sin notificación. En ambos casos la contramedida es persistir los acuerdos críticos en archivos del proyecto antes de alcanzar el umbral; el CLAUDE.md de la raíz, además, se reinyecta tras cada compactación.

Deriva entre turnos. Las instrucciones cercanas al inicio del contexto pierden influencia frente a tool results y mensajes recientes: una instrucción dada al principio de la sesión puede dejar de aplicarse turnos después sin ningún cambio explícito. Repetirla en cada turno no ayuda, porque ese contenido también se compacta; cuando la restricción es crítica, la opción robusta es un hook, según se detalla en Construcción.

Falsa persistencia. Como el prefijo queda fijado al inicio de la sesión, editar CLAUDE.md en disco no recarga su contenido en el contexto activo: el cambio solo se aplica a sesiones nuevas. El mismo principio rige para settings.json, las definiciones de skills y las descripciones de subagentes.

Tool surface excesivo. El síntoma habitual de una superficie de herramientas demasiado amplia son tool calls plausibles pero innecesarias: el modelo utiliza una herramienta porque está disponible, no porque corresponda. La contramedida — restringir permisos, cargar MCP de forma selectiva, retirar subagentes en desuso — se detalla en Construcción; conviene aplicarla de forma periódica, no como optimización accesoria.

Jerarquía de configuración mal repartida. Cuando la misma instrucción aparece en varios niveles (CLAUDE.md global, de proyecto, de subdirectorio) o cuando un subagente la repite, el modelo recibe señales contradictorias o redundantes que erosionan la prioridad pretendida. Cada nivel debe cubrir un alcance bien definido y no solapar autoridad sobre la misma regla.