Lo que aprenderás

Esta guía cubre la Harness engineering desde los principios fundamentales hasta la implementación práctica. Comprenderás qué es, por qué OpenAI apostó su mayor proyecto interno por ella, los patrones arquitectónicos específicos que la hacen funcionar y cómo aplicar estos principios a tus propios flujos de trabajo de AI agent — ya sea que utilices Codex, Claude Code, OpenCode o cualquier otro sistema de agentes.

Harness Engineering: La guía completa para el desarrollo de AI agents en 2026

Si 2025 fue el año en que los AI agents demostraron que podían escribir código, 2026 es el año en que aprendimos que el agente no es la parte difícil — el harness lo es.

El equipo de Codex de OpenAI publicó una publicación de blog histórica en February 2026 describiendo cómo construyeron una aplicación de producción que contenía aproximadamente 1,000,000 de líneas de código donde cero líneas fueron escritas por manos humanas. El secreto no fue un mejor modelo o un prompt más inteligente. Fue el sistema que construyeron alrededor del agente — el harness. Source

Esta guía desglosa cada principio, patrón y técnica práctica de ese experimento y del movimiento más amplio de Harness engineering que ha surgido a su alrededor.

Part 1: ¿Qué es la Harness engineering?

La definición

Harness engineering es la disciplina de diseñar todo el entorno — scaffolding, bucles de retroalimentación, documentación, restricciones arquitectónicas y artefactos legibles por máquina — que permite a los AI coding agents realizar un trabajo confiable y de alta calidad a escala con una intervención humana mínima.

El término "harness" proviene de los arreos de los caballos: riendas, silla, bocado — el conjunto completo de equipo para canalizar a un animal poderoso pero impredecible en la dirección correcta. Un caballo sin control es peligroso. Un caballo con arnés construyó civilizaciones. Lo mismo se aplica a los AI agents. Source

Por qué surgió ahora

El cambio de la prompt engineering a la Harness engineering refleja una maduración del panorama del desarrollo de AI:

Source

La idea clave que impulsó esta transición: los agentes se volvieron lo suficientemente capaces como para que el cuello de botella se desplazara de la calidad del modelo a la calidad del entorno. Un modelo de última generación que opera en un repositorio mal estructurado produce peores resultados que un modelo mediocre que opera en un entorno bien equipado con un harness.

Part 2: El experimento Codex de OpenAI

La escala

En un experimento interno de 5 meses, los ingenieros de OpenAI construyeron y lanzaron un producto beta que contenía aproximadamente 1,000,000 de líneas de código. El repositorio abarca la lógica de la aplicación, infraestructura, herramientas, documentación y utilidades internas para desarrolladores. No había código preexistente escrito por humanos para anclar el sistema. Source

El equipo

El proyecto comenzó con solo 3 ingenieros impulsando Codex. Durante el período de 5 meses, se abrieron y fusionaron aproximadamente 1,500 pull requests. A medida que el equipo creció a 7 ingenieros, el rendimiento aumentó — un resultado contraintuitivo que sugirió que el harness en sí era el principal multiplicador de productividad, no la habilidad individual.

OpenAI estima que construyeron el sistema en aproximadamente 1/10 del tiempo que hubiera tomado escribir el código a mano. Source

El scaffolding inicial

El proyecto comenzó con Codex CLI generando el scaffolding inicial utilizando GPT-5, guiado por un pequeño conjunto de plantillas existentes:

• Estructura del repositorio y convenciones de directorios
• Configuración de CI/CD
• Reglas de formateo de código y linting
• Configuración del gestor de paquetes
• Boilerplate del framework de la aplicación

A partir de esta semilla, todo lo demás creció a través del desarrollo impulsado por agentes.

El problema del viernes

Al principio del experimento, el equipo descubrió un problema crítico: pasaban cada viernes — el 20% de su tiempo de ingeniería — limpiando lo que llamaban "AI slop" (desperdicio de AI). Esto incluía patrones inconsistentes, lógica duplicada, variables mal nombradas y deriva arquitectónica.

Eso no escalaba. La solución fue codificar sus estándares en el propio harness para que los agentes produjeran resultados más limpios desde el principio, y construir sistemas de limpieza automatizados para la deriva residual.

Part 3: Los cinco principios básicos

Principio 1: Repository-First Knowledge

Desde la perspectiva del agente, cualquier cosa a la que no pueda acceder en contexto mientras se ejecuta, efectivamente no existe. El conocimiento que reside en Google Docs, hilos de chat, mensajes de Slack o en la cabeza de las personas es invisible para el sistema.

Esto significa que todo el conocimiento debe residir como artefactos versionados y locales del repositorio:

• Código — el artefacto primario
• Documentación en Markdown — decisiones de arquitectura, convenciones, guías de incorporación
• Schemas — contratos de API, esquemas de bases de datos, definiciones de tipos
• Planes ejecutables — desgloses de tareas paso a paso que el agente puede seguir
• Configuración — reglas de linter, pipelines de CI, estándares de formateo

El equipo aprendió que necesitaban introducir cada vez más contexto en el repo con el tiempo. Cada vez que un agente cometía un error porque le faltaba contexto, la solución no era un mejor prompt — era agregar ese contexto al repositorio. Source

Implementación práctica:

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Principio 2: Golden Principles

Los Golden principles son reglas mecánicas y de opinión codificadas directamente en el repositorio que mantienen el código legible y consistente para futuras ejecuciones de agentes. No son pautas de aspiración — son restricciones aplicadas.

Ejemplos del experimento de OpenAI:

1. Preferir paquetes de utilidad compartidos sobre ayudantes hechos a mano — centraliza las invariantes para que cuando el comportamiento necesite cambiar, cambie en un solo lugar.
2. No sondear datos al estilo YOLO — validar los límites o confiar en SDKs con tipos para que los agentes no puedan construir accidentalmente sobre formas de datos adivinadas.
3. Un concepto, un archivo — cada archivo debe representar un solo concepto, facilitando que los agentes encuentren y modifiquen la ubicación correcta.
4. Explícito sobre implícito — evitar comportamientos mágicos que un agente necesitaría conocimiento tribal para entender.

Source

Estos principios no son solo documentación. Se aplican mediante:

• Reglas de linter — linters personalizados (generados por el propio Codex) que señalan violaciones.
• Pruebas estructurales — pruebas que validan el cumplimiento arquitectónico.
• CI gates — los pull requests que violan los Golden principles son rechazados automáticamente.

Principio 3: Arquitectura en capas con ejecución mecánica

Cada dominio de negocio en el proyecto de OpenAI se divide en un conjunto fijo de capas con direcciones de dependencia estrictamente validadas:

Types → Config → Repo → Service → Runtime → UI

Las dependencias fluyen en una sola dirección. Un componente de UI puede depender de Runtime y Service, pero un Service nunca puede importar desde UI. Un Repo puede depender de Config y Types, pero nunca de Service. Source

Estas restricciones se aplican mecánicamente:

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Las pruebas estructurales validan el cumplimiento y previenen violaciones del despliegue modular. Esto no es una sugerencia — es aplicado por CI. Cada pull request, ya sea creado por un humano o un agente, debe pasar estas pruebas.

Principio 4: Automated Garbage Collection

Incluso con Golden principles y aplicación estructural, el código generado por agentes deriva con el tiempo. El equipo de OpenAI solucionó esto implementando una Automated Garbage Collection — tareas en segundo plano recurrentes que:

1. Escanean desviaciones de los Golden principles en todo el código base.
2. Actualizan las calificaciones de calidad para cada módulo basadas en puntajes de cumplimiento.
3. Abren pull requests de refactorización dirigidos que corrigen categorías específicas de deriva.

Esto reemplazó la "limpieza del viernes" manual con un sistema que se ejecuta continuamente. El propio recolector de basura es impulsado por agentes Codex, creando un bucle de automantenimiento. Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Principio 5: Planes ejecutables

Antes de que los agentes escriban código, escriben planes. Estos planes no son notas informales — son documentos estructurados y ejecutables que especifican:

• Objetivo: Qué logra la tarea.
• Archivos a modificar: Lista explícita de archivos que el agente tocará.
• Dependencias: Otras tareas o módulos de los que depende este trabajo.
• Criterios de aceptación: Cómo verificar que el trabajo está completo.
• Restricciones: Reglas arquitectónicas que no deben ser violadas.

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

Los planes residen en el repositorio como archivos Markdown, están controlados por versiones y pueden ser revisados antes de la ejecución — dando a los humanos un punto de control entre la intención y la implementación.

Part 4: El bucle del agente Codex

Comprender cómo opera el bucle del agente Codex dentro de un harness es esencial para una Harness engineering efectiva.

La arquitectura del bucle

OpenAI publicó un desglose detallado del bucle del agente Codex en su publicación de blog complementaria "Unrolling the Codex agent loop." Source El bucle sigue este ciclo:

Read Context → Plan → Execute → Validate → Commit (or Retry)

En cada iteración:

1. Read Context: El agente lee los archivos relevantes, documentación, schemas y el plan de tareas del repositorio.
2. Plan: Basándose en el contexto, el agente determina qué cambios realizar.
3. Execute: El agente escribe o modifica el código.
4. Validate: El harness ejecuta pruebas, linters y verificaciones estructurales contra los cambios.
5. Commit or Retry: Si la validación pasa, el agente realiza el commit. Si falla, el agente lee la salida del error e intenta de nuevo.

El papel del harness es hacer que los pasos 1 y 4 sean lo más ricos en información posible. Cuanto más contexto lea el agente, mejor será su plan. Cuanto más específica sea la retroalimentación de la validación, más rápido convergerá en una solución funcional.

El App Server Harness

En su publicación "Unlocking the Codex harness: how we built the App Server," OpenAI describe la infraestructura concreta que impulsa el bucle del agente. Source El App Server proporciona:

• Entornos de ejecución en sandbox para cada tarea del agente.
• Acceso a herramientas preconfiguradas (sistema de archivos, terminal, navegador).
• Inyección automática de contexto desde artefactos del repositorio.
• Retroalimentación de validación en streaming para que los agentes puedan ver fallos de pruebas en tiempo real.

Part 5: Aplicando la Harness engineering a tu equipo

Primeros pasos: El harness mínimo viable

No necesitas replicar toda la infraestructura de OpenAI para beneficiarte de la Harness engineering. Comienza con estos elementos fundamentales:

Step 1: Crea un ARCHITECTURE.md

Documenta las reglas arquitectónicas de tu proyecto en un formato legible por máquina en la raíz de tu repositorio. Incluye:

• Límites de los módulos y dependencias permitidas.
• Convenciones de nomenclatura.
• Reglas de organización de archivos.
• Requisitos de pruebas.

Este único archivo mejora drásticamente la calidad de los resultados del agente porque los agentes lo leeren antes de realizar cambios.

Step 2: Agrega pruebas estructurales

Escribe pruebas que validen tus reglas arquitectónicas. Estas pruebas no verifican la lógica de negocio — verifican que el código esté organizado correctamente:

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Step 3: Configura la validación de CI

Asegúrate de que tu pipeline de CI ejecute pruebas estructurales, linters y verificaciones de tipos en cada pull request — incluyendo los creados por agentes. El agente debe ver la misma salida de validación que vería un desarrollador humano.

Step 4: Escribe planes de tareas antes de la ejecución del agente

Antes de pedirle a un agente que implemente una función, escribe un documento de plan estructurado que especifique los archivos a modificar, las restricciones a seguir y los criterios de aceptación. Almacena estos planes en tu repositorio.

Step 5: Configura la limpieza automatizada

Implementa un trabajo de CI semanal o nocturno que escanee tu código base en busca de desviaciones de tus estándares documentados y cree PRs de refactorización enfocados.

Elegir tu sistema de agentes

Los principios de Harness engineering se aplican independientemente del agente que utilices:

El harness reside en tu repositorio, no en tu agente. Esto significa que puedes cambiar de agente sin perder tu inversión en el harness.

Escalando de un agente a muchos

El experimento de OpenAI demostró que la Harness engineering permite la ejecución paralela de agentes. Debido a que el harness impone límites arquitectónicos, múltiples agentes pueden trabajar en diferentes partes del código base simultáneamente sin crear conflictos.

Requisitos clave para la ejecución paralela de agentes:

1. Propiedad clara de los módulos — cada agente trabaja dentro de un límite definido.
2. Interfaces con tipos entre módulos — los agentes pueden codificar contra interfaces sin conocer detalles de implementación.
3. Prevención de conflictos de fusión — las tareas se acotan para minimizar el solapamiento de archivos.
4. Validación centralizada — todos los agentes envían al mismo pipeline de CI.

Part 6: Errores comunes y antipatrones

Antipatrón 1: Tratar al agente como el harness

El agente no es el harness. El harness es el entorno en el que opera el agente. Pedirle a un modelo más inteligente que compense un repositorio mal estructurado es el enfoque equivocado. Corrige el entorno, no el prompt.

Antipatrón 2: Documentación en el lugar equivocado

Si tus decisiones arquitectónicas residen en Confluence, Notion o Google Docs, los agentes no pueden verlas. La solución es simple pero requiere disciplina: mueve toda la documentación relevante para el desarrollo al repositorio.

Antipatrón 3: Limpieza manual en lugar de aplicación automatizada

Si pasas una cantidad significativa de tiempo limpiando código generado por agentes, necesitas una mejor aplicación, no más sesiones de limpieza. Cada tarea de limpieza recurrente debería convertirse en una regla de linter, una prueba estructural o un trabajo de refactorización automatizado.

Antipatrón 4: Exceso de restricciones

Un harness que es demasiado rígido impide que los agentes encuentren soluciones creativas. El objetivo es restringir la arquitectura, no la implementación. Indica a los agentes qué módulos pueden modificar y qué dependencias están permitidas, pero deja que ellos decidan cómo implementar la lógica dentro de esos límites.

Antipatrón 5: Ignorar la retroalimentación del agente

Cuando un agente falla repetidamente en ciertas tareas, el fallo suele indicar un vacío en el harness, no una limitación del agente. Realiza un seguimiento de los patrones de fallo y utilízalos para mejorar tu documentación, pruebas estructurales o restricciones arquitectónicas.

Part 7: El futuro de la Harness engineering

La perspectiva de Martin Fowler

Martin Fowler publicó un análisis sobre Harness engineering en su blog, señalando que representa un cambio fundamental en cómo operan los equipos de software. La disciplina toma prestadas décadas de mejores prácticas de ingeniería de software — integración continua, registros de decisiones de arquitectura, inyección de dependencias — pero las reutiliza para un mundo impulsado por agentes. Source

El framework HumanLayer

El equipo de HumanLayer publicó su análisis llamando a la Harness engineering un "skill issue" (problema de habilidad) — argumentando que la capacidad de diseñar harnesses efectivos se convertirá en el principal diferenciador entre los equipos de ingeniería de alto rendimiento y los que tienen dificultades. Source

Lo que esto significa para los desarrolladores

La Harness engineering no reemplaza la habilidad del desarrollador — la redirige. En lugar de escribir código, los ingenieros sénior diseñan los sistemas que permiten a los agentes escribir código bien. Las habilidades que importan pasan de la implementación a la arquitectura, de la codificación al diseño de sistemas, de escribir pruebas a diseñar frameworks de pruebas.

Para los equipos que construyen aplicaciones, plataformas como ZBuild ya están incorporando principios de Harness engineering en sus flujos de trabajo de creación de apps. En lugar de requerir que los desarrolladores diseñen sus propios harnesses desde cero, ZBuild proporciona patrones arquitectónicos preconfigurados, gestión de dependencias y sistemas de validación que guían a los AI agents hacia resultados de alta calidad — permitiendo que los desarrolladores se concentren en decisiones de producto en lugar de infraestructura.

Los tres horizontes

Mirando hacia el futuro, es probable que la Harness engineering evolucione a través de tres fases:

1. Corto plazo (2026): Los equipos adoptan documentación centrada en el repositorio, pruebas estructurales y Golden principles. El desarrollo asistido por agentes se convierte en la práctica estándar para proyectos con un buen harness.

2. Medio plazo (2027): La generación del propio harness se vuelve impulsada por agentes. Los agentes analizan los códigos base existentes y proponen configuraciones de harness — reglas de linter, pruebas estructurales, límites de dependencia — basados en los patrones que observan.

3. Largo plazo (2028+): Los harnesses se vuelven adaptativos. En lugar de reglas estáticas, evolucionan basándose en los resultados del código generado por agentes, endureciendo automáticamente las restricciones en áreas donde los agentes producen errores con frecuencia y relajándolas donde tienen éxito constante.

Part 8: Lista de verificación práctica

Usa esta lista para evaluar la madurez de la Harness engineering de tu equipo:

Fundación (Empieza aquí)

• ARCHITECTURE.md existe en la raíz del repositorio.
• El formateo de código está automatizado (Prettier, Black, gofmt).
• El linting se ejecuta en cada pull request.
• Se aplica la verificación de tipos (TypeScript strict, mypy, etc.).

Intermedio

• Las pruebas estructurales validan los límites de dependencia.
• Los Golden principles están documentados y son aplicables por máquina.
• Los planes de tareas se escriben antes de la ejecución del agente.
• Los PRs generados por agentes pasan por el mismo CI que los PRs humanos.

Avanzado

• La Automated Garbage Collection se ejecuta de forma programada.
• Múltiples agentes pueden trabajar en paralelo sin conflictos.
• Se rastrean los patrones de fallo de los agentes y se usan para mejorar el harness.
• El propio harness está controlado por versiones y se revisa como el código.

Experto

• Los agentes generan partes del harness (reglas de linter, pruebas estructurales).
• Se asignan automáticamente calificaciones de calidad a cada módulo.
• Las mejoras del harness están impulsadas por datos basados en las tasas de éxito de los agentes.
• El equipo entrega más código por ingeniero por semana que antes de adoptar agentes.

Conclusión

Harness engineering no es una moda pasajera. Es la evolución natural de la ingeniería de software en una era donde los AI agents son lo suficientemente capaces de escribir código de producción pero necesitan entornos estructurados para hacerlo bien. El experimento de 1,000,000 de líneas de OpenAI demostró el concepto a escala, y los principios que articularon — Repository-First Knowledge, Golden principles, arquitectura en capas, Automated Garbage Collection y planes ejecutables — son aplicables a equipos de cualquier tamaño.

Los equipos que dominen la Harness engineering en 2026 entregarán más rápido, mantendrán una mayor calidad de código y escalarán de manera más efectiva que aquellos que traten a los AI agents como un autocompletado glorificado. El agente es el caballo. El harness es lo que lo hace útil.

Sources

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote