Todo el mundo habla de los loops. Casi nadie habla de sobre qué se ejecuta el loop. 9 de cada 10 desarrolladores ejecutan Claude Code con el harness predeterminado: sin reglas, sin subagentes, sin hooks, sin memoria.
Luego se preguntan por qué su loop produce basura. La verdad es simple: un loop solo es tan bueno como el harness que lo sostiene. Esta es la hoja de ruta en 14 pasos para el harness, desde un agente hasta un sistema que se mejora a sí mismo.
Sigue mi Substack para recibir contenido exclusivo sobre IA:
La ingeniería de loops — construir un sistema que le da instrucciones a tu agente en un horario — acaparó toda la atención este mes. Pero Addy Osmani, quien escribió el artículo extenso sobre loops, tuvo cuidado de señalar lo que está debajo:
"La ingeniería de loops está un piso por encima del harness. El harness es el entorno en el que se ejecuta un solo agente. El loop es el harness, pero funciona con un temporizador, crea ayudantes y se alimenta a sí mismo."
La ingeniería del harness es diseñar ese entorno: el modelo, las herramientas, los permisos, el contexto, la memoria.
Es la capa poco glamorosa, y es la que decide si todo lo que está encima funciona. Un gran loop sobre un mal harness es una forma rápida de producir basura a escala.
14 pasos. 3 niveles. La base sobre la que se sostiene todo lo demás.
Parte 1 · Qué es el Harness
01. Un harness es el entorno en el que se ejecuta un agente.
Dejando de lado la jerga, un harness son cuatro cosas: el modelo que piensa, las herramientas a las que puede acceder, los permisos sobre esas herramientas y el contexto que lee al inicio de cada ejecución.
Esa es toda la superficie. Todo lo demás — subagentes, hooks, memoria — es una forma de moldear uno de esos cuatro elementos.
La razón por la que el harness importa más de lo que la gente cree: el agente es un bucle while True que elige una herramienta, la ejecuta, mira el resultado y decide el próximo movimiento.
El harness define qué herramientas existen, qué se le permite hacer al agente y qué sabe cuando comienza. Mismo modelo, diferente harness, agente completamente diferente.
02. Todo el harness vive en una carpeta. .claude/
Todo lo que da forma a tu agente se encuentra en un solo directorio en la raíz de tu proyecto. Aprende esta estructura y podrás leer el harness de cualquiera de un vistazo:
1.claude/2├─ CLAUDE.md # hechos permanentes — se lee en cada sesión3├─ settings.json # permisos, modelo, hooks4├─ .mcp.json # conexiones externas de herramientas5├─ rules/ # comportamientos por ruta6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # definiciones de subagentes (~30 líneas cada uno)9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # flujos de trabajo reutilizables12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # lo que sobrevive entre ejecuciones15 └─ STATE.md
Una regla que separa un harness limpio de un desastre: mantenlo lo suficientemente pequeño como para poder explicar por qué existe cada archivo. Si no puedes decir para qué sirve una regla, un hook o un subagente, elimínalo.
03. Harness vs. loop vs. sistema. Tres pisos, no los mezcles.
La mayoría de los problemas de "mi configuración de agente es un desastre" provienen de confundir los tres pisos. Mantenlos claros:
- El harness es el entorno de ejecución de un agente. Configuración estática: modelo, herramientas, permisos, contexto. Este artículo.
- El loop le da instrucciones al agente con un temporizador, crea ayudantes, se alimenta a sí mismo. Se ejecuta sobre el harness.
- El sistema que se mejora a sí mismo es un loop más memoria que se acumula: cada ejecución deja la siguiente más afinada.
La versión práctica: pon los hechos permanentes en el contexto, la aplicación de reglas en hooks, los procedimientos en skills y el aislamiento en subagentes.
Mezclar esto — aplicación de reglas en CLAUDE.md, procedimientos que inflan el contexto — es la causa raíz de agentes inconsistentes y costosos.
04. El harness predeterminado. Lo que obtienes de serie.
Instala Claude Code, abre una carpeta y ya tienes un harness, solo que vacío. El valor predeterminado te da un modelo capaz, las herramientas integradas (read, write, bash, search) y solicitudes de aprobación para todo lo riesgoso. Sin contexto del proyecto, sin subagentes personalizados, sin memoria.
Para una tarea única, el predeterminado está bien. Para cualquier cosa que hagas más de una vez, el predeterminado hace que el agente deduzca tu proyecto desde cero en cada sesión, pida permiso para operaciones seguras y olvide todo cuando cierres la terminal.
Los siguientes diez pasos tratan de cerrar esa brecha.
05. CLAUDE.md: hechos permanentes, mantenlo breve.
CLAUDE.md se lee al inicio de cada sesión. Es el conocimiento permanente del agente sobre tu proyecto: convenciones, arquitectura, el "no lo hacemos así por ese incidente".
El error más común: dejar que se convierta en un documento de procedimientos gigante que infla cada sesión.
La regla de los profesionales que lo usan a diario: mantén el archivo de memoria principal por debajo de ~500 tokens. Los hechos permanentes van aquí.
Los procedimientos de varios pasos van en skills (paso 8). Los comportamientos específicos de ruta van en archivos rules/ con alcance donde se aplican. Si una sección de CLAUDE.md se ha convertido en un procedimiento en lugar de un hecho, pertenece a otro lugar.
Lee tu CLAUDE.md en voz alta. Cada línea debería ser un
hecho
que el agente necesita en cada sesión ("usamos pnpm, no npm"). Si una línea es un
procedimiento
("para añadir una función, primero..."), muévelo a un skill.
Si es una regla para una carpeta, muévela a rules/.
06. settings.json: permisos y modelo, configurados una vez.
El harness predeterminado pregunta antes de cada acción riesgosa. Eso está bien cuando estás mirando, y mal cuando no. settings.json es donde pre-apruebas lo seguro, deniegas lo peligroso y eliges qué modelo se ejecuta.
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
La prueba para decidir qué auto-aprobar: si esto sale mal, ¿qué tan difícil es deshacerlo? Barato de deshacer → auto-aprobar.
Caro de deshacer (force-push, eliminar archivos, tocar secretos) → siempre denegar o preguntar. El punto intermedio está bien para auto-aprobar si lo registras.
07. Subagentes: contexto aislado para el trabajo sucio.
Un subagente es una sesión independiente de Claude lanzada desde la principal: su propia ventana de contexto, su propia lista de herramientas. El objetivo no es el paralelismo por sí mismo. Es mantener el ruido fuera del contexto principal.
Una tarea de investigación que lee 40 archivos, una revisión que necesita una perspectiva fresca, una ejecución de evaluación que produce un muro de registros: esas pertenecen a un subagente para no contaminar el hilo principal.
GIF
El subagente más valioso en cualquier harness es el que verifica el trabajo que hizo el agente principal. Un modelo revisando su propio resultado es demasiado indulgente consigo mismo.
Un revisor separado con una ventana de contexto nueva detecta lo que el escritor se convenció a sí mismo. Esta es la división escritor vs. verificador que hace que cada loop sobre el harness sea confiable.
08. Skills: procedimientos que el agente reutiliza.
Un Skill es un archivo SKILL.md que el agente ejecuta, ya sea cuando lo invocas con /skill-name o automáticamente cuando la tarea coincide con su descripción.
A diferencia de un subagente, se ejecuta en la misma ventana de contexto. Son solo instrucciones reutilizables que pasan a formar parte de la sesión.
El desencadenante para crear uno: notas que estás pegando las mismas instrucciones en cada nueva conversación. Eso es un skill esperando a nacer. Una lista de verificación de PR, un procedimiento de evaluación, un proceso de lanzamiento: se escriben una vez, se invocan para siempre.
Y como los skills son la unidad reutilizable, son lo que hace que el harness mejore con el tiempo: cada vez que el procedimiento falla de una forma nueva, añades la lección al skill, y la siguiente ejecución la hereda.
09. Hooks: reglas deterministas que el modelo no puede alucinar.
Hasta ahora todo depende de que el modelo entienda tus instrucciones. Los hooks no.
Un hook es un comando de shell que se dispara en un punto fijo del ciclo de vida del agente — antes de que se ejecute una herramienta, después de que cambie un archivo, cuando termina la sesión — y su código de salida puede bloquear la acción. Los hooks son aplicación de reglas; CLAUDE.md es sugerencia.
Dos hooks merecen su lugar en casi todos los harnesses:
- Una barrera PreToolUse que bloquea comandos peligrosos de forma determinista: rm -rf, leer .env, hacer push a main. El código de salida 2 detiene la llamada antes de que ocurra. El modelo no puede persuadirlo para que pase.
- Un formateador PostToolUse que ejecuta tu linter o formateador después de cada edición. El agente nunca envía código sin formato porque el harness lo formatea automáticamente.
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // exit 2 = bloquea la llamada antes de ejecutarse6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
Usa hooks para cualquier cosa que deba ocurrir o que nunca deba ocurrir: seguridad, formato, registro de auditoría.
No los uses para decisiones subjetivas; para eso está el modelo. Un buen harness tiene uno o dos hooks precisos, no veinte.
Parte 3 · Haz que se Acumule
10. Añade un loop. Ahora el harness funciona con un temporizador.
Un harness configurado todavía espera a que escribas. Un loop lo hace funcionar solo. La versión más simple es /loop en Claude Code: un prompt recurrente con una cadencia.
Combínalo con /goal y el loop continúa hasta que se cumple una condición objetiva, verificada por un evaluador independiente en lugar de que el agente se evalúe a sí mismo.
1> /loop 30m /goal Todos los tests pasan y el lint está limpio.2 Clasificar nuevos fallos, redactar correcciones en ramas claude/.34▲ Claude usa el harness que construiste:5 - rules/ para convenciones6 - subagente revisor para verificar cada corrección7 - hook PreToolUse bloquea los pushes a main8✓ Repitiendo. El evaluador independiente decide "listo".
Observa lo que acaba de pasar: el loop no añadió inteligencia. Reutilizó todo lo que había en el harness — las reglas, el subagente revisor, el hook de seguridad. Un buen harness hace que un loop sea trivial. Ese es el objetivo de construir primero los cimientos.
11. Añade flujos de trabajo dinámicos. El harness escribe su propia orquestación.
Para tareas demasiado complejas para un solo loop — masivamente paralelas, altamente estructuradas, adversariales — Claude puede escribir su propio harness en JavaScript sobre la marcha.
Eso es un flujo de trabajo dinámico: agent() para crear, parallel() para expandir, pipeline() para transmitir. Compone los subagentes que define tu harness en patrones como expandir-y-sintetizar o verificación adversarial.
La conexión con la ingeniería del harness: un flujo de trabajo dinámico es tan bueno como los subagentes y skills que puede invocar.
Si tu harness tiene un subagente revisor preciso y un skill de evaluación bien escrito, el flujo de trabajo tiene buenas piezas para orquestar. Si el harness está vacío, el flujo de trabajo no tiene con qué trabajar.
El flujo de trabajo es el director, tu harness es la orquesta.
12. Añade memoria. Lo que el agente olvida, el harness lo recuerda.
Este es el paso que convierte un harness configurado en un sistema que realmente mejora. El agente olvida todo entre ejecuciones. El harness no tiene por qué.
Un archivo de estado — un archivo markdown en agent-memory/, o un tablero de Linear — registra lo que se intentó, lo que funcionó, lo que falló, qué reglas sobrevivieron.
El patrón que hace que la memoria se acumule, extraído de cómo los agentes más potentes la usan:
- Escribe antes de irte. Cada ejecución termina actualizando el archivo de estado: lecciones aprendidas, hechos verificados, qué sigue.
- Lee al inicio. Cada ejecución comienza leyendo el archivo de estado y los skills relevantes, para retomar en lugar de reiniciar.
- Destila en skills. Cuando una lección es general ("los runners de Windows necesitan bash, no PowerShell"), pasa del archivo de estado a un skill, donde se aplica a todos los proyectos futuros.
1# Memoria del proyecto23## Hechos verificados # deja de adivinar estos4- prc está en dólares, no en centavos (verificado con SELECT MIN/MAX)5- orden del middleware de autenticación: rate_limit -> jwt -> rbac67## Lecciones aprendidas # destila las generales en skills8- Los runners CI de Windows fallan TLS 1.2 en PowerShell — usa bash9- Las migraciones en tablas de más de 1M filas deben hacerse en lotes de 10k1011## Última sesión # retoma, no reinicies122026-06-11 · 3 correcciones fusionadas, 2 escaladas. Siguiente: verificar la corrección de rate-limit.
13. Cierra el ciclo. Salida → lección → skill → mejor salida.
Aquí es donde los tres pisos se enlazan en algo que se mejora a sí mismo. Cada ejecución produce una salida. El subagente revisor (paso 7) la verifica.
El resultado — lo que pasó, lo que falló, lo que se aprendió — se escribe en la memoria (paso 12). Las lecciones generales se destilan en skills (paso 8).
La siguiente ejecución hereda skills más precisos y una memoria más rica.
Ese es todo el bucle de auto-mejora, y observa que está construido enteramente con partes del harness:
- Subagente evalúa el trabajo — verificación objetiva, contexto fresco.
- Memoria registra el veredicto — sobrevive entre ejecuciones.
- Skills lo ejecutan de nuevo — ahora con todo lo que aprendió la ejecución anterior.
- El loop lo ejecuta de nuevo — ahora con todo lo que aprendió la ejecución anterior.
El modelo nunca cambió. El harness a su alrededor se volvió más preciso. Eso es lo que significa realmente "auto-mejora": no un modelo que aprende, sino un harness que se acumula.
14. Distribuye el harness. Emplácalo. Compártelo. Reutilízalo.
Un harness que funciona en un proyecto es un activo.
Empaqueta los skills, subagentes y reglas en un plugin y todo tu equipo instala la misma configuración en un solo paso: las mismas convenciones, los mismos hooks de seguridad, el mismo revisor.
El harness deja de ser tu configuración personal y se convierte en infraestructura compartida.
El orden para construir, una última vez, porque el orden es la lección: logra que una ejecución manual sea confiable sobre un harness limpio.
Añade el contexto y los permisos. Añade un subagente revisor. Añade memoria. Luego, y solo entonces, envuélvelo en un loop. Un loop sobre un buen harness se acumula. Un loop sobre un mal harness solo sangra más rápido.
§ Los errores del harness que empeoran cualquier loop
- Ejecutar sobre el predeterminado. Sin contexto, sin reglas, sin memoria: el agente deduce tu proyecto desde cero cada sesión.
- Un CLAUDE.md inflado. Procedimientos metidos en el contexto permanente, inflando cada ejecución. Muévelos a skills.
- Aplicación de reglas en CLAUDE.md en lugar de hooks. El modelo puede ignorar una sugerencia. No puede ignorar un hook que sale con código 2.
- Un agente que escribe y evalúa su propio trabajo. Añade un subagente revisor con una ventana de contexto nueva.
- Sin memoria. Cada ejecución comienza desde cero. El archivo de estado es lo que permite retomar mañana.
- Envolver un loop alrededor de un mal harness. El loop solo produce basura más rápido. Construye los cimientos primero.
- Veinte hooks. Uno o dos precisos vencen a un montón que nadie entiende.
- Distribuir un harness sin escanearlo. Secretos filtrados y permisos demasiado amplios se propagan a todos los que lo instalan.
Conclusión:
El loop se lleva la gloria. El harness hace el trabajo.
La ingeniería de loops es la parte emocionante: el agente dándose instrucciones a sí mismo, ejecutándose mientras duermes. Pero un loop es solo un harness con un temporizador.
Todo lo que decide si la salida es buena o basura vive un piso más abajo, en el modelo que elegiste, las herramientas que permitiste, el contexto que escribiste, el revisor que añadiste, la memoria que conservaste.
Construye bien ese piso y todo lo que está encima se acumula: el loop reutiliza tus subagentes, el flujo de trabajo orquesta tus skills, la memoria hace que cada ejecución sea más precisa que la anterior.
La auto-mejora nunca fue una propiedad del modelo. Es una propiedad del harness que construyes a su alrededor.
Elige una cosa que no estés haciendo — probablemente un subagente revisor, un hook de seguridad o un archivo de estado — y añádela hoy. Mantén el harness lo suficientemente pequeño para poder explicarlo. Luego pon un loop encima y observa cómo los cimientos hacen el trabajo.
