Los cinco subsistemas del harness

Una cocina con cinco zonas

La lección 02 compara un harness con una cocina profesional. Una cocina completa tiene cinco áreas, y si falta una, aún puedes cocinar, pero siempre incómodo. Estas son las cinco, con su equivalente.

Reglas (AGENTS.md) ----\
Progreso (PROGRESS.md) --> AGENTE --> Herramientas --> Entorno --> Resultados
                              ^                                       |
                              +------------ (test, lint, build) ------+

1. Instrucciones (la estantería de recetas)

Un archivo AGENTS.md (o CLAUDE.md) con: qué es el proyecto en una frase, el stack y sus versiones, los comandos para empezar, las restricciones innegociables y enlaces a documentación más detallada.

2. Herramientas (el estante de cuchillos)

Que el agente tenga acceso suficiente. No le quites la terminal «por seguridad» si luego no puede ni instalar un paquete. Pero tampoco abras todo: aplica el mínimo privilegio, es decir, solo lo necesario.

3. Entorno (los fogones)

Que el entorno se describa solo: dependencias bloqueadas en package.json o pyproject.toml, versiones del lenguaje fijadas (.nvmrc, .python-version) y contenedores para que todo sea reproducible.

4. Estado (la zona de preparación)

Las tareas largas necesitan seguimiento. Un simple PROGRESS.md con qué está hecho, qué está en curso y qué está bloqueado. Se actualiza antes de acabar cada sesión y se lee al empezar la siguiente.

5. Verificación (la ventana de control de calidad)

Es la zona con más retorno. Lista en AGENTS.md los comandos que comprueban el trabajo:

Comandos de verificación:
- Tests: pytest tests/ -x
- Tipos: mypy src/ --strict
- Estilo: ruff check src/
- Todo junto: make check

Principios de buen diseño

• El repositorio es la fuente de verdad. Lo que el agente no puede ver, no existe.
• Un mapa, no un manual. Un AGENTS.md de unas 100 líneas como página de índice; lo demás va en docs/ y se lee bajo demanda.
• Restringe, no microgestiones. Usa reglas ejecutables en vez de enumerar pasos uno a uno.
• Separa quien hace de quien revisa, porque los agentes tienden a elogiar su propio trabajo.

La historia de un equipo (cifras de la lección)

Un equipo con una app de TypeScript y React fue añadiendo piezas con el mismo modelo:

Cuatro iteraciones, mismo modelo, de un 20 % a casi el 100 %.

Mide con cuidado

La lección propone una ablación: con el mismo modelo, quitar un subsistema cada vez y ver cuál empeora más. Pero avisa de que la mayor caída muestra qué componente aporta más en esa tarea, no necesariamente el cuello de botella; y una caída nula puede significar que el componente sobra, está mal hecho o la tarea no lo usó. Para localizar el cuello de botella, apóyate también en el registro de fallos.