Codex y el repo como fuente de verdad

Un equipo que dejó de escribir código

Imagina una cocina donde el jefe ya no cocina: diseña la cocina. Decide dónde van los cuchillos, cómo se etiqueta cada recipiente y cómo se prueba cada plato antes de salir. Eso cuenta el artículo de OpenAI «Harness Engineering», que dio nombre a todo este campo: un equipo entregó en pocas semanas un producto de más de un millón de líneas, y las escribió Codex. El trabajo humano fue diseñar el entorno.

La filosofía cabe en una frase: el repositorio es la fuente de verdad, AGENTS.md es solo un índice y el valor está en el entorno, la intención y los ciclos de retroalimentación.

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

Un archivo de instrucciones enorme no se puede revisar mecánicamente (¿está actualizado?, ¿quién lo mantiene?, ¿los enlaces funcionan?) y acaba alejándose de la realidad. Por eso Codex lo trata como una página de índice: unas 100 líneas que apuntan a documentación estructurada en docs/. El agente lee esos documentos bajo demanda. Es dar un mapa, no un manual. Más detalle en AGENTS.md corto.

Segundo principio: imponer invariantes sin microgestionar. En AGENTS.md van las reglas que no se pueden romper y los comandos para comprobarlas; cómo implementar lo decide el modelo.

# AGENTS.md (esquema de ~100 líneas)
- Qué es este proyecto (3 líneas)
- Comandos: instalar, test, arrancar
- Invariantes: "nunca importar la capa UI desde servicios"
- Mapa: arquitectura -> docs/ARCHITECTURE.md, API -> docs/api.md

Contexto: escribir, seleccionar, comprimir, aislar

La comunidad resume la ingeniería de contexto de Codex en cuatro verbos:

• Write: guardar conclusiones y estado en archivos, no en la conversación.
• Select: meter en la ventana solo lo necesario; AGENTS.md indica el camino y el resto se lee si hace falta.
• Compress: compactación automática, /compact manual y un compact_prompt personalizable.
• Isolate: los subagentes tienen su propio contexto; uno de frontend nunca ve el esquema de la base de datos.

Un detalle fino del código (según un análisis comunitario): cuando cambia el entorno (carpeta, rama git), Codex envía solo los campos que cambiaron, no todo otra vez. Menos tokens repetidos.

Límites: worktrees y subagentes

Cada tarea corre en un git worktree independiente, con su propia pila de observabilidad (logs, métricas, trazas). El límite no es una petición en las instrucciones, lo impone el aislamiento físico. Para el subagente existen herramientas del núcleo (spawn_agent, wait_agent); heredan el AGENTS.md del padre y trabajan en contexto propio.

Verificación incluida de serie

Los comandos para comprobar que algo está bien viven en el repo. Tests, CI y documentación forman rutas de verificación ejecutables. Además hay políticas de aprobación y un modo plan: ante una operación arriesgada se presenta un plan y se pide visto bueno.