ingeniería-de-arneses

Ingeniería de Arneses

La ingeniería de arneses diseña el sistema de control alrededor de un agente: qué puede editar, cómo recibe retroalimentación, dónde escribe el estado, cómo se recuperan los fallos y quién puede aprobar acciones irreversibles. El arnés es la diferencia entre una sesión de agente útil y un bucle autónomo que puede ejecutarse durante días sin corromper su objetivo.

Cuándo Activar

Active esta habilidad cuando:

• Construya bucles de investigación o experimentación autónomos
• Diseñe un entorno de agente con métricas bloqueadas y código o contenido editable
• Cree agentes que generen PR o agentes en segundo plano
• Evalúe si un agente puede ejecutarse de manera segura sin indicaciones frecuentes humanas
• Agregue novedad, ablación, poda, reversión o registro duradero a un flujo de trabajo de agente
• Evite que los agentes manipulen puntos de referencia, debiliten rúbricas o pierdan estado en la compactación

No active esta habilidad para trabajo adyacente propiedad de otras habilidades:

• Compuertas de calidad generales, suites de regresión o métricas de resultados sin superficies de control autónomas: evaluation.
• Esquemas de herramientas, formatos de respuesta y errores de recuperación para herramientas de arnés: tool-design.
• Ajuste modelo-tarea a nivel de proyecto, forma de tubería y planificación de costos: project-development.
• Infraestructura de sandbox remoto, grupo cálido y sesiones alojadas: hosted-agents.

Conceptos Centrales

Límite del Arnés

Separe el agente del entorno en el que opera. El agente propone acciones; el arnés define superficies permitidas, retroalimentación, persistencia y reglas de promoción.

Use cuatro clases de superficie:

Superficie	Ejemplos	Regla
Bloqueada	Métrica de evaluación, rúbrica, script de validación, política de fusión	El agente puede leer y proponer cambios, pero no puede autoevaluarse con reglas modificadas
Editable	Borrador de habilidad, archivo de experimento, indicación, configuración bajo prueba	El agente puede mutar durante el bucle
Solo anexar	Registro de resultados, hilo de investigación, ideas rechazadas	El agente puede anexar, no reescribir
Controlada por humano	Fusión, despliegue a producción, credenciales, operaciones destructivas	Requiere aprobación explícita humana

Bucles de Retroalimentación Apretados

La autonomía funciona cuando la retroalimentación es rápida, inequívoca y difícil de manipular. El autoresearch de Karpathy es el patrón mínimo: un archivo editable, un archivo de evaluación bloqueado, un presupuesto de tiempo fijo, una métrica escalar, reversión git y un registro de resultados duradero. La lección no es que cada arnés necesite una métrica; es que la retroalimentación ambigua crea autonomía ambigua.

Para el trabajo abierto de investigación a habilidad, reemplace la métrica escalar con rúbricas bloqueadas, verificaciones de estructura deterministas, trazabilidad de fuentes y umbrales de revisión humana.

Estado Duradero

Los agentes de larga duración deben externalizar el estado. Almacene planes, colas de fuentes, resultados, fallos y traspasos en archivos para que los agentes futuros puedan reanudar sin depender del historial del chat. El trabajo autónomo de nanoGPT de Prime Intellect mostró el valor de los blocs de notas duraderos y los registros estilo THREAD.md para la recuperación, monitoreo y auditoría.

Use registros de solo anexar para:

• Lo que se intentó
• Lo que mejoró o falló
• Por qué se mantuvo, descartó o enrutó a revisión un candidato
• Qué fuentes anteriores se verificaron
• Lo que el próximo agente debería hacer

Disciplina de Búsqueda

Los agentes tienden a explotar la superficie más cercana, apilar complejidad y no ejecutar suficiente poda. Agregue reglas de búsqueda explícitas:

1. Actualice las fuentes anteriores según un cronograma.
2. Exija verificaciones de novedad antes de gastar grandes presupuestos.
3. Preserve los intentos rechazados para evitar redescubrimiento.
4. Ejecute poda "deje uno fuera" cuando una pila tenga múltiples adiciones.
5. Recompense la simplificación cuando la calidad sea igual.
6. Use verificación separada antes de la promoción.

Registro de Mecanismos

Para sistemas de investigación a habilidad, rastree los mecanismos aceptados por separado de la prosa. Un registro de mecanismo debe incluir un mechanism_id estable, owning_skill, status, escenario de activación, cambio de comportamiento, evidencia y modos de fallo. Las compuertas de novedad deben comparar contra este registro antes de usar superposición de corpus más amplia, porque la superposición de palabras clave atrapa frases obsoletas mientras que la comparación de mecanismos atrapa duplicación real.

Gobernanza

Los agentes autónomos pueden preparar PR, pero la gobernanza debe ser explícita. Pueden redactar cambios, ejecutar verificaciones y escribir resúmenes de PR. No deben fusionar, desplegar o enviar sin aprobación humana a menos que el usuario haya otorgado explícitamente ese permiso para la acción específica.

Temas Detallados

Bucle Estilo Autoresearch

Use este patrón al optimizar un artefacto contra un evaluador estable:

leer contexto bloqueado -> elegir hipótesis -> editar superficie permitida -> confirmar/punto de control
-> ejecutar evaluador -> registrar resultado -> mantener si es mejor -> descartar o revertir si es peor
-> repetir

Propiedades requeridas:

• El evaluador está fuera de la superficie editable.
• La cadencia de retroalimentación es lo suficientemente fija para comparar intentos.
• Los intentos fallidos dejan un rastro de auditoría.
• La reversión es barata.
• El agente tiene una política para fallos y tiempos de espera.

Bucle de Investigación a Habilidad

Use este patrón cuando las fuentes se conviertan en cambios de habilidad:

descubrir -> recuperar -> compuerta -> puntuar -> extraer mecanismo
-> mapear a habilidad existente o nueva -> redactar propuesta -> validar estructura
-> preparar PR -> revisión humana

El evaluador bloqueado es una combinación de rúbricas de fuente, rúbricas de cambio de habilidad, verificaciones de estructura y aprobación del revisor. El artefacto editable es el delta de habilidad propuesto.

Resistencia a la Manipulación de Métricas

Asuma que un agente optimizador aprenderá el arnés. Protéjase contra:

• Editar código de evaluación o rúbricas y luego usar la nueva versión para autoaprobación
• Agregar contenido verboso que complace a un juez pero daña la activación de la habilidad
• Citar fuentes no recuperadas
• Optimizar puntuaciones agregadas mientras se falla una dimensión crítica
• Evitar resultados fallidos en el registro

Mitigación: bloquee rúbricas por ejecución, reporte puntuaciones por dimensión, exija evidencia de recuperación de fuente, preserve intentos rechazados y enrute cambios de gobernanza a revisión humana.

Agentes de Monitoreo

Use agentes de monitoreo para ejecuciones largas, pero restrínjalos a informes de solo lectura a menos que se les indique explícitamente lo contrario. La salida de monitoreo debe reportar:

• Mejor candidato actual
• Trabajos o borradores activos
• Última actualización de fuente
• Bucles fallidos o estancados
• Desacuerdos entre registros y estado reclamado
• Próxima acción y bloqueador

Guía Práctica

Lista de Verificación de Diseño del Arnés

1. Defina el objetivo en una oración.
2. Identifique las superficies bloqueada, editable, solo anexar y controlada por humano.
3. Elija el mecanismo de retroalimentación: métrica escalar, rúbrica, pruebas deterministas, revisión humana o combinación.
4. Defina los estados de mantener, descartar, fallo, tiempo de espera y revisión.
5. Cree un registro de hilo duradero antes de que comience el bucle.
6. Agregue actualización de fuente, novedad del registro de mecanismos y reglas de poda para bucles de larga duración.
7. Defina qué puede hacer el agente sin preguntar y qué requiere aprobación.
8. Valide el arnés en un artefacto conocido bueno y uno conocido malo.

Estructura de Archivos

research-run/
  THREAD.md
  sources/
    queue.md
    evaluations/
  proposals/
  logs/
    results.tsv
    rejected.md
  drafts/

Use TSV o JSONL para registros legibles por máquina de solo anexar. Use Markdown para traspasos y resúmenes orientados al revisor.

Ejemplos

Ejemplo 1: Métrica bloqueada

Un agente optimiza train.py, pero prepare.py posee la carga de datos y la evaluación. El agente puede editar el modelo pero no puede cambiar la métrica. Los experimentos fallidos se registran y revierten.

Ejemplo 2: Rúbrica bloqueada

Un agente evalúa una nueva publicación de ingeniería de Anthropic u OpenAI, pero la rúbrica de curación de fuentes está bloqueada para la ejecución. Si la fuente pasa, el agente redacta una propuesta de habilidad. No puede bajar el umbral de la rúbrica para admitir la fuente.

Ejemplo 3: Auto-PR sin auto-fusión

Un agente prepara una rama y el cuerpo del PR después de pasar las verificaciones de fuente, habilidad y estructura. El PR indica los riesgos no resueltos y espera la aprobación humana para fusionar.

Guías

1. Bloquee los evaluadores antes de iniciar el bucle.
2. Mantenga las superficies editables lo suficientemente estrechas para diferencias confiables.
3. Escriba registros duraderos antes de que la compactación del contexto pueda borrar el estado.
4. Reporte puntuaciones por dimensión en lugar de solo puntuaciones agregadas.
5. Exija recuperación de fuente antes de la cita.
6. Agregue compuertas de novedad para búsqueda amplia y compuertas de poda para pilas complejas.
7. Prefiera la simplificación cuando la calidad sea igual.
8. Separe la preparación del PR de la autoridad de fusión.
9. Revalide los cambios del arnés con evaluadores antiguos y nuevos.
10. Trate los bucles autónomos detenidos como fallos del arnés, no como peculiaridades de personalidad del agente.

Problemas Comunes

1. Evaluador mutable: Si el agente puede editar la métrica, puede optimizar el punto de referencia en lugar de la tarea. Mantenga las rúbricas y el código de evaluación bloqueados durante la ejecución.
2. Memoria solo de chat: Las ejecuciones largas fallan después de la compactación cuando los planes viven solo en el historial de la conversación. Escriba registros de hilo y archivos de resultados desde el principio.
3. Sin registro de descarte: Sin registros de intentos rechazados, los agentes repiten ideas fallidas. Preserve los fallos con suficiente detalle para evitar redescubrimiento.
4. Acumulación de complejidad: Los agentes apilan cambios y rara vez los eliminan. Exija rondas de poda y recompense la simplificación de igual calidad.
5. Afirmaciones prematuras de novedad: Los agentes etiquetan recombinaciones como novedosas. Compare contra las habilidades existentes del repositorio, la cola de fuentes y los registros rechazados antes de reclamar novedad.
6. Informe erróneo del monitor: Los agentes de monitoreo pueden resumir estado obsoleto o inconsistente. Exija que citen los archivos o registros detrás de las afirmaciones.
7. Ambigüedad en la aprobación humana: "Preparar un PR" no es "fusionar un PR." Haga explícitos los límites de aprobación en el arnés.
8. Deriva volátil de fuentes: Las afirmaciones rápidas de laboratorio envejecen rápidamente. Ponga evidencia fechada en las referencias y programe la revalidación.

Integración

Esta habilidad se conecta con:

• evaluation - Las rúbricas y las compuertas de calidad proporcionan la superficie de retroalimentación bloqueada
• advanced-evaluation - La comparación por pares y la mitigación de sesgos mejoran la revisión de propuestas
• filesystem-context - Los registros duraderos, blocs de notas y archivos de hilo preservan el estado
• multi-agent-patterns - Los agentes investigador, verificador, monitor y escritor necesitan contextos aislados
• tool-design - Las herramientas del arnés deben exponer contratos claros y errores de recuperación
• project-development - Las tuberías basadas en archivos y el análisis de ajuste modelo-tarea mantienen los bucles simples
• hosted-agents - La ejecución en segundo plano necesita sandbox, instantánea y límites de aprobación

Referencias

Referencias internas:

• researcher/README.md - Leer al implementar el sistema operativo nativo del repositorio de investigación a habilidad
• researcher/rubrics/harness-change.md - Leer al evaluar cambios en un arnés de agente
• researcher/runbooks/autonomous-research-loop.md - Leer al ejecutar un bucle de fuente a habilidad

Recursos externos:

• Karpathy autoresearch - Bucle de experimentación autónomo restringido con evaluación bloqueada
• Prime Intellect autonomous nanoGPT speedrun - Blocs de notas duraderos, traspasos, monitoreo y modos de fallo de autonomía
• AlphaEvolve y FunSearch - Candidatos generados por LLM emparejados con evaluadores sistemáticos
• HELM y LM Evaluation Harness - Infraestructura de evaluación transparente y reproducible

---

Metadatos de la Habilidad

Creada: 2026-05-14 Última Actualización: 2026-05-15 Autor: Agent Skills for Context Engineering Contributors Versión: 1.1.0