← Volver al listado de tecnologías ← Índice de Learn Harness Engineering

Capítulo 15 — Análisis de harnesses reales: Pi, Claude Code, Codex y DeepSeek

25 de agosto de 2026 Por: Artiko

harnessclaude-codecodexpideepseekanalisisarquitectura

Capítulo 15 — Análisis de harnesses reales

Este capítulo contrasta, uno por uno, la teoría de las lecciones anteriores con productos reales. En cada producto interesa una sola cosa: cómo está diseñado su harness, es decir, la capa de infraestructura de ingeniería que rodea al modelo.

Deliberadamente no hablamos de si el modelo razona mejor o peor, ni de si obtiene una puntuación alta en un benchmark concreto. Esas son cuestiones de la capa del modelo y de la capa del producto. Acá solo analizamos el harness: todo lo que queda fuera de los pesos del modelo.

flowchart TB
    subgraph F["Cuatro filosofías de harness"]
        P["Pi<br/>Núcleo minimalista<br/>+ extensiones programables<br/>«no decido nada por vos»"]
        CC["Claude Code<br/>Entorno de ejecución completo<br/>memoria por capas, permissions, hooks<br/>«funciona de entrada»"]
        CX["Codex<br/>Convenciones del repositorio<br/>worktree, AGENTS.md como índice<br/>«el repo es la especificación»"]
        DS["DeepSeek Harness<br/>Todo es un plugin<br/>hasta el ciclo del agente<br/>«el harness es un SO»"]
    end

Pi — núcleo minimalista y extensiones programables

Pi (paquete npm @earendil-works/pi-coding-agent) se define a sí mismo como minimal agent harness. Vale la pena detenerse en esas palabras: no afirma ser “el coding agent más potente”, sino que fija su identidad precisamente en el término harness.

Su filosofía: minimizar el núcleo y hacer programables las extensiones; llevar la ingeniería de contexto más allá del system prompt y permitir que el usuario —o el propio Pi— modifique el harness, en lugar de que Pi decida el harness por vos.

Divide el harness en cuatro capas personalizables:

Capa	Qué es
Extensions	Hooks de TypeScript conectados a los eventos del ciclo de vida; la superficie programable del runtime
Skills	Paquetes de capacidades cargados bajo demanda, con instrucciones y herramientas, mediante progressive disclosure
Prompt templates	Prompts reutilizables en Markdown que se despliegan al escribir `/nombre`
Themes	La apariencia de la TUI

Subsistema de instrucciones

AGENTS.md: orden de carga en tres niveles — ~/.pi/agent/AGENTS.md global → recorrido ascendente por directorios padre → ./AGENTS.md del directorio actual (también compatible con CLAUDE.md). Las instrucciones son archivos, no recordatorios en el chat.
SYSTEM.md: el system prompt por defecto puede reemplazarse o ampliarse por proyecto.

Pi subraya que su system prompt es minimalista. Detrás hay una decisión explícita: el núcleo no se llena con reglas extensas de “si… entonces…”, sino que deja puntos de extensión para que las reglas aparezcan como Skills y Extensions solo cuando hagan falta. Es la respuesta natural a la lección 4.

Estado y contexto: donde Pi llega más lejos

1. Compaction programable. Cuando se aproxima al límite del contexto, resume automáticamente los mensajes antiguos. Pero la estrategia de compaction es personalizable: una extensión puede implementar compaction por temas, resúmenes sensibles al código o incluso usar otro modelo para resumir. El mecanismo por defecto se activa por recuperación tras desbordamiento o por superación del umbral de conservación; el punto de corte mantiene aproximadamente los 20.000 tokens más recientes.

2. Contexto dinámico. Las extensions pueden inyectar mensajes antes de cada ronda de razonamiento, filtrar el historial, implementar RAG y construir memoria a largo plazo. Esto va más allá de “esperar a que el contexto se llene”: permite decidir qué entra y qué no antes de que el contexto llegue a la ventana.

3. Árbol de sesiones. Las sesiones se almacenan como árboles: /tree permite volver a cualquier nodo histórico y continuar desde ahí, y todas las ramas se guardan en un único archivo. Resuelve la ruptura del contexto entre sesiones no mediante resúmenes forzados, sino mediante reproducción de un historial estructurado.

Correspondencia con el marco del curso

Subsistema	Implementación de Pi	Evaluación
Instrucciones	Carga jerárquica de AGENTS.md + SYSTEM.md	Jerarquía clara, pero el usuario escribe las reglas
Herramientas	Skills bajo demanda + hooks de Extensions para todo el ciclo de vida	Muy potente; convierte el sistema de herramientas en superficie programable
Entorno	SYSTEM.md para autodescripción; el usuario declara el entorno en AGENTS.md	Mecanismo abierto, reproducibilidad depende del usuario
Estado	Árbol de sesiones + compaction personalizable + PROGRESS.md	Muy potente; continuidad y recuperabilidad son fundamentales
Retroalimentación	Comandos definidos por el usuario; session-summary / extract-patterns	Se provee el mecanismo; el usuario aporta el contenido

Diseños que vale la pena adoptar

Hacé conectable la estrategia de compaction. “Cómo se compacta el contexto” no debería ser un parámetro rígido, sino una interfaz de estrategia reemplazable.
Usá un árbol de sesiones en lugar de resúmenes forzados. Reproducir un historial estructurado suele ser un subsistema de estado más fiable.
Sé compatible con la prompt cache. Cargá skills bajo demanda: es ingeniería de contexto y también ingeniería de costes.
Permitile al agente modificar su propio harness. Si la superficie de extensión es suficientemente abierta, el agente puede semiautomatizar la optimización de su comportamiento.

Claude Code — el entorno de ejecución completo

Anthropic afirma explícitamente que la fiabilidad procede del harness, no del modelo, y clasifica a Claude Code directamente como un agentic harness. Es probablemente el harness con el análisis público más exhaustivo hasta la fecha.

En una frase: el núcleo de Claude Code es un ciclo while sencillo —invocar el modelo, ejecutar herramientas, observar los resultados, volver a invocar—. Pero la inmensa mayoría del código no está en ese ciclo, sino en el sistema que lo rodea: permissions, pipeline de compaction, mecanismos de extensión, orquestación de subagentes y almacenamiento de sesiones.

Subsistema de instrucciones: memoria por capas

flowchart TD
    O["Política de organización<br/>/etc/claude-code/CLAUDE.md"] --> U["Nivel de usuario<br/>~/.claude/CLAUDE.md"]
    U --> P["Nivel de proyecto<br/>./CLAUDE.md"]
    P --> L["Nivel local<br/>./CLAUDE.local.md (gitignored)"]
    L --> S["Subdirectorios<br/>carga bajo demanda al leer<br/>un archivo de ese directorio"]
    S --> A["Auto memory<br/>notas que escribe Claude<br/>máx. 200 líneas / 25 KB por sesión"]

Las instrucciones más específicas entran más tarde en el contexto. El valor está en no obligar al modelo a procesar un archivo enorme al comienzo de cada conversación, sino cargar la información cercana según su alcance. Es la respuesta de producto a la lección 4.

Subsistema de contexto: pipeline de compaction de cinco niveles

Claude Code no hace “resumir cuando se llena”, sino un embudo de varios niveles:

flowchart LR
    A["1. Poda sin pérdida<br/>eliminar resultados<br/>redundantes de herramientas"] --> B["2. Extracción<br/>estructurada"]
    B --> C["3. Resumen con pérdida<br/>vía LLM"]
    C --> D["Circuit breaker<br/>evita compaction excesiva"]

Esto se combina con almacenamiento de sesiones orientado a append: todo el historial se agrega a history.jsonl y /resume permite recuperarlo y crear ramas mediante fork. El handoff no depende de una buena memoria, sino de que la capa de almacenamiento sea append-only y reproducible.

Subsistema de herramientas: cuatro mecanismos de extensión

Mecanismo	Para qué	Responsabilidad
Skills	Conocimiento procedimental descrito por `SKILL.md`, cargado por palabras de activación	”Cómo hacerlo”
MCP	Protocolo JSON-RPC que conecta sistemas externos	”A qué conectarse”
Hooks	Scripts deterministas en eventos como `PreToolUse`, `PostToolUse`, `Stop`	”Cuándo imponerlo”
Subagentes	Delegar tareas complejas en agentes especializados	”Quién lo hace”

La decisión esencial es la separación de responsabilidades: CLAUDE.md gestiona “qué es”, las Skills “cómo hacerlo”, MCP “a qué conectarse” y los Hooks “cuándo imponerlo”. Si un equipo mezcla estas capas, aparece la fuga de contexto de la lección 4.

Retroalimentación: restricciones deterministas

Sistema de permissions: no es “preguntar todo”, sino modos y un clasificador; las operaciones de bajo riesgo se permiten, las de alto riesgo se consultan o rechazan. Así, definir los límites del agente (lección 7) se convierte en una imposición del runtime en vez de un pedido en el prompt.
Hooks: un hook PostToolUse puede ejecutar comprobaciones obligatorias tras usar una herramienta y escribir el resultado en el contexto; un hook Stop interviene cuando el agente declara que terminó. Así se separa quien trabaja de quien comprueba (lección 9), con verificación determinista en lugar de autoevaluación.
Subagentes: el historial de cada subagente se guarda en un archivo sidechain independiente y no amplía el contexto del agente padre. Al mismo tiempo que se divide la tarea, también se aísla la contaminación del contexto.

Diseños que vale la pena adoptar

Organizá las instrucciones por alcance en lugar de amontonarlas en un archivo.
Usá un embudo de compaction por niveles: primero sin pérdida, después con pérdida.
Usá hooks para comprobaciones deterministas.
Aislá el contexto de los subagentes: dividí el contexto al dividir la tarea.
Almacená las sesiones mediante append y reproducción.

Codex — el repositorio es la fuente de verdad

Codex es, de estos cuatro productos, el más ligado a los principios fundamentales del harness: el artículo Harness Engineering que dio nombre al campo resume precisamente la experiencia del equipo de OpenAI al desarrollar un producto con Codex.

Su filosofía: el repositorio es la fuente de verdad, AGENTS.md es solo una página de índice y el valor de la ingeniería reside en diseñar el entorno, expresar la intención y construir ciclos de retroalimentación.

AGENTS.md es una página de índice, no una enciclopedia

Esta es la decisión de diseño de Codex que más influyó en la teoría del harness:

Un único archivo de instrucciones gigante dificulta las comprobaciones mecánicas —cobertura, estado de actualización, propiedad y enlaces cruzados—, por lo que es inevitable que se aleje de la realidad. Dejamos de considerar AGENTS.md una enciclopedia y pasamos a tratarlo como una página de índice.

La recomendación concreta: mantener AGENTS.md en unas 100 líneas; al acercarse al límite, dividir en docs/. Es la fuente autorizada de “dá un mapa, no un manual”.

El principio complementario: imponer invariantes sin microgestionar la implementación. AGENTS.md solo contiene restricciones estrictas y comandos de verificación; el modelo decide cómo implementar los detalles.

Ingeniería de contexto: Write-Select-Compress-Isolate

Estrategia	Qué hace
Write (escribir afuera)	Persistir el contexto fuera de la ventana: conclusiones en documentos, estado en archivos
Select (seleccionar adentro)	Introducir solo los tokens necesarios; AGENTS.md indica el camino, los archivos se leen bajo demanda
Compress (comprimir)	Compaction automática y `/compact` manual, con `compact_prompt` personalizable
Isolate (aislar)	Los subagentes aíslan el contexto de distintas tareas; un subagente de frontend nunca ve el esquema de la base de datos

Un detalle de ingeniería que vale la pena copiar: build_environment_update_item solo emite los campos modificados —CWD, rama git y sistema de archivos— cuando cambia el entorno, en vez de pegar en cada ronda todo el contexto del sistema.

Herramientas y límites

1. Aislamiento mediante git worktree. Cada tarea se ejecuta en un worktree independiente, acompañado de un stack local de observabilidad. Es la implementación física de los límites de tarea de la lección 7: el límite no se establece con un pedido en las instrucciones, lo impone el aislamiento del entorno.

2. Subagentes en el núcleo. spawn_agent y wait_agent son herramientas del núcleo: el modelo crea explícitamente subagentes, les asigna historial y herramientas independientes, y espera sus resultados. Heredan las instrucciones del padre pero corren en su propio contexto. La configuración vive en .codex/agents/*.toml.

Correspondencia con el marco del curso

Subsistema	Implementación de Codex	Evaluación
Instrucciones	AGENTS.md como índice + división en `docs/` + invariantes impuestos	De manual; define “dá el mapa, no el manual”
Herramientas	Aislamiento por worktree + subagentes con `spawn_agent`	Límites sólidos impuestos por el entorno
Entorno	Worktrees independientes + stack de observabilidad	Su seña distintiva
Estado	Estrategia Write (el estado se escribe en archivos)	Depende de convenciones más que de memoria integrada
Retroalimentación	Comandos de verificación en la especificación + approval policies + plan mode	Convierte las rutas de feedback en la opción por defecto

La comparación con Claude Code es interesante: Claude Code aplica la suma —integra memoria, permissions y subagentes en el núcleo—; Codex aplica la resta —mantiene el núcleo contenido y deposita más responsabilidad en las convenciones del repositorio—. Por eso suele decirse que “la filosofía del harness de Codex vale más que su código”.

DeepSeek Harness — el harness como sistema operativo

DeepSeek Harness (comando dsh) se publicó en agosto de 2026 como Developer Preview. Su definición oficial es directa: Agent = Model + Environment + Tools + State.

Si al analizar los tres productos anteriores nos preguntábamos “cómo debería diseñarse un harness”, DeepSeek plantea algo más radical: ¿puede el harness independizarse de un modelo concreto y convertirse en un runtime autónomo?

Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself.

El núcleo (llamado Cordis) solo se ocupa de cargar y descargar plugins, gestionar sus dependencias y proporcionar el mecanismo de eventos. No posee ninguna capacidad específica del agente. No existe un núcleo privilegiado que haya que parchear: se amplía montando un plugin junto a los demás. Ni siquiera el ciclo del agente es sagrado.

Núcleo 1: capability seams

flowchart TD
    SD["Service Definition<br/>declara la interfaz"] --> SP["Service Provider<br/>la implementa"]
    SP --> CO["Consumer<br/>la usa, normalmente<br/>como herramienta del modelo"]
    SP2["Local FS"] -.provider de.-> FS["FS Service"]
    SP3["E2B FS"] -.provider de.-> FS
    SP4["Remote FS"] -.provider de.-> FS
    FS --> TOOL["file tools<br/>que ve el modelo"]

Esto resuelve una cuestión persistente: ¿debe el agente depender de una herramienta concreta o de una interfaz de capacidades? DeepSeek elige la segunda. Al cambiar un Provider, la herramienta que ve el modelo conserva su forma, pero el entorno cambia por completo.

Núcleo 2: pipeline de eventos

turn/start → claim input → assemble (system prompt / context / tools)
  → agent/pre-step → step/start → LLM request (agent/request) → llm/stream
  → assistant/message → tool/call
  → tools/pre-execute (permission / guard / policy / hook)
  → tools/execute → tools/post-execute → tool/result → step/end → next turn

La ventaja principal es que muchas funciones no requieren modificar el ciclo del agente en absoluto. ¿Querés una comprobación de seguridad antes de ejecutar una herramienta? Escuchá tools/pre-execute. ¿Querés agregar memoria? Inyectala en agent/pre-step. ¿Querés modificar la solicitud al modelo? Enganchate a agent/request.

Comparado con la lección 11, DeepSeek va más lejos: no “agrega logs”, convierte cada paso del ciclo en un punto de eventos, de modo que observabilidad, permissions, memoria y políticas se conectan como listeners en lugar de estar codificadas dentro del ciclo.

Núcleo 3: “Model-visible means logged”

DeepSeek incluye un Session Event Log append-only y establece una restricción de ingeniería muy fuerte:

Model-visible means logged. Todo lo que llega a una solicitud al modelo debe poder reconstruirse desde el log, y un invariante del runtime lo impone.

La observabilidad no es un log agregado a posteriori, sino una restricción fundamental: todo lo que entra en el contexto del modelo deja un log por defecto.

Correspondencia con el marco del curso

Subsistema	Implementación de DeepSeek Harness	Evaluación
Instrucciones	Basadas en plugins; reglas y skills se inyectan como plugins	Extremadamente flexible, sin convención integrada tipo CLAUDE.md
Herramientas	Service Definition → Provider → Consumer	Estandarización extrema del subsistema de herramientas
Entorno	Providers de sandbox/FS/Shell reemplazables (incluido E2B remoto)	El entorno es totalmente conectable
Estado	Session Event Log append-only + model-visible means logged	La observabilidad es restricción de primer orden
Retroalimentación	permission / guard / policy / hook en `tools/pre-execute`	Mecanismos de feedback basados en eventos

La diferencia fundamental con los otros tres: Pi, Claude Code y Codex optimizan el harness dentro de un agente concreto; DeepSeek define el harness como un sistema operativo independiente del modelo y trata al agente como una aplicación reemplazable que corre encima. El costo también es evidente: mayor libertad implica mayor costo de configuración.

Comparación final

Dimensión	Pi	Claude Code	Codex	DeepSeek Harness
Filosofía	Núcleo mínimo, todo extensible	Batteries included	Convención sobre configuración	Todo es un plugin
Instrucciones	AGENTS.md jerárquico + SYSTEM.md	CLAUDE.md en 4 alcances + auto memory	AGENTS.md como índice + docs/	Reglas inyectadas como plugins
Aislamiento	Extensions definen los límites	Subagentes sidechain + permissions	git worktree por tarea	Providers de sandbox reemplazables
Estado	Árbol de sesiones	history.jsonl append-only + compaction de 5 niveles	Estrategia Write a archivos	Session Event Log append-only
Observabilidad	Extension `telemetry`	Logs append-only + `/compact`, `/clear`	Stack local de logs, métricas y trazas	Invariante model-visible-means-logged
Costo de entrada	Alto (escribís tus extensions)	Bajo	Medio (convenciones del repo)	Alto (Developer Preview)

Qué llevarte de los cuatro, sin importar qué herramienta uses:

Organizá las instrucciones por alcance y cargalas bajo demanda (los cuatro lo hacen).
Aislá el contexto cuando dividas la tarea (los cuatro lo hacen, con mecanismos distintos).
Hacé que el almacenamiento de sesiones sea append-only y reproducible (Claude Code y DeepSeek).
Imponé la verificación desde el runtime, no desde el prompt (hooks, permissions, approval policies).
Tratá “cómo se comprime el contexto” como una estrategia reemplazable, no como una constante (Pi).

Lecturas adicionales

Anterior: Lección 14 — De los loops únicos a la ingeniería de grafos · Siguiente: Capítulo 16 — Biblioteca de plantillas