Phase 14 - Lesson 32

The Minimal Agent Workbench

Tipo: Construir Idiomas: Python (stdlib) Prerrequisitos: Fase 14 · 31 (Por Qué los Modelos Capaces Aún Fallan) Tiempo: ~45 minutos

Objetivos de Aprendizaje

  • Definir los tres archivos que forman la bancada de trabajo mínima viable.
  • Explicar por qué un enrutador raíz corto supera a un archivo AGENTS.md monolítico largo.
  • Construir un archivo de estado que el agente pueda leer en cada turno y escribir al final.
  • Construir un tablero de tareas que sobreviva a trabajos de sesiones múltiples sin historial de chat.

El Problema

La mayoría de los equipos intenta crear una bancada escribiendo un archivo AGENTS.md de 3000 líneas y dándolo por terminado. El modelo lo carga, ignora las partes que no puede resumir y sigue fallando en las mismas superficies de siempre.

Necesitas lo contrario. Un archivo raíz diminuto que dirija al agente a archivos más profundos solo cuando sea relevante. Estado duradero que el agente lea antes de actuar y escriba después. Un tablero de tareas que indique qué está en progreso, qué está bloqueado y qué es lo siguiente.

Tres archivos. Cada uno con una función. Cada uno lo suficientemente legible por máquina para evolucionar en un sistema real más adelante.

El Concepto

flowchart LR
  Agent[Loop del Agente] --> Router[AGENTS.md]
  Router --> State[agent_state.json]
  Router --> Board[task_board.json]
  State --> Agent
  Board --> Agent

AGENTS.md es un enrutador, no un manual

Un buen AGENTS.md es corto. Apunta al agente a:

  • El archivo de estado (dónde estás).
  • El tablero de tareas (qué queda).
  • Las reglas más profundas (bajo docs/agent-rules.md).
  • El comando de verificación (cómo saber si funciona).

Cualquier cosa más larga va a documentos más profundos, cargados solo cuando se necesitan. Los manuales largos se ignoran. Los enrutadores cortos se siguen.

agent_state.json es el sistema de registro

El estado contiene: el active task id, los archivos modificados (touched files), las suposiciones hechas, los bloqueos y la siguiente acción. El agente lo lee en cada turno. La siguiente sesión lo lee en lugar de reproducir el chat.

El estado vive en un archivo porque el historial de chat no es confiable. Las sesiones mueren. Las conversaciones se recortan. El archivo no.

task_board.json es la cola

El tablero de tareas contiene cada tarea con el estado todo | in_progress | done | blocked. Es la cola de la que extrae el agente cuando el estado está vacío, y la cola que lees cuando quieres saber si el agente va por buen camino.

Una tarea en el tablero tiene un id, una meta (goal), un propietario (builder, reviewer o human) y criterios de aceptación. El tablero es pequeño a propósito: cuando crece más allá de una pantalla, tienes un problema de planificación, no un problema de tablero.

Tres archivos es el piso, no el techo

Las lecciones posteriores agregan contratos de alcance, ejecutores de retroalimentación, compuertas de verificación, listas de verificación del revisor y paquetes de entrega. Los tres archivos aquí son lo que todos ellos asumen.

Constrúyelo

code/main.py escribe la bancada mínima en un repositorio vacío y demuestra un solo turno del agente que:

  1. Lee agent_state.json.
  2. Extrae la siguiente tarea de task_board.json si el estado está vacío.
  3. Modifica un solo archivo dentro del alcance.
  4. Escribe de vuelta el estado actualizado.

Ejecútalo:

python3 code/main.py

El script crea workdir/ junto a sí mismo, establece los tres archivos, ejecuta un turno y muestra el diff. Vuelve a ejecutarlo para ver cómo el segundo turno retoma donde quedó el primero.

Úsalo

Dentro de los productos de agentes en producción, los mismos tres archivos aparecen bajo nombres diferentes:

  • Claude Code: AGENTS.md o CLAUDE.md para el enrutador, almacenamientos al estilo .claude/state.json para el estado, hooks para el tablero.
  • Codex / Cursor: reglas del espacio de trabajo (workspace rules) para el enrutador, memoria de sesión para el estado, tareas en cola en la barra lateral del chat para el tablero.
  • Custom Python agent: los mismos archivos que acabas de escribir.

Los nombres cambian. La forma no.

Patrones de producción en el mundo real

La bancada mínima sobrevive al contacto con monorepositorios reales cuando se superponen tres patrones sobre ella. Son independientes; elige los que tu repositorio realmente necesite.

Archivos AGENTS.md anidados con precedencia por cercanía. OpenAI distribuye 88 archivos AGENTS.md en su repositorio principal, uno por subcomponente. Codex, Cursor, Claude Code y Copilot avanzan desde el archivo de trabajo hacia la raíz del repositorio y concatenan cada AGENTS.md que encuentran en el camino. Los archivos de los subdirectorios extienden al archivo raíz. Codex agrega AGENTS.override.md para reemplazar en lugar de extender; el mecanismo de anulación (override) es específico de Codex y debe evitarse para el trabajo entre herramientas. La medición de Augment Code es la que importa: los mejores archivos AGENTS.md otorgan un salto de calidad equivalente a actualizar de Haiku a Opus; los peores empeoran el resultado en comparación con no tener ningún archivo.

Antipatrones a rechazar, incluso cuando parezcan dar cobertura. Las instrucciones en conflicto reducen silenciosamente al agente del modo interactivo al modo codicioso (greedy) (ICLR 2026 AMBIG-SWE: tasa de resolución de 48.8% → 28%); numera las prioridades en lugar de apilarlas en plano. Las reglas de estilo no verificables ("seguir la guía de estilo de Python de Google") sin un comando de aplicación permiten que el agente invente el cumplimiento; asocia cada regla de estilo con el comando exacto de lint. Empezar con el estilo en lugar de los comandos entierra la ruta de verificación; comandos primero, estilo al final. Escribir para humanos en lugar de agentes desperdicia el presupuesto de contexto; la concisión es una virtud.

Enlaces simbólicos entre herramientas. Un único archivo raíz con enlaces simbólicos (ln -s AGENTS.md CLAUDE.md, ln -s AGENTS.md .github/copilot-instructions.md, ln -s AGENTS.md .cursorrules) mantiene a todos los agentes de codificación bajo la misma fuente de verdad. El nx ai-setup de Nx automatiza esto en Claude Code, Cursor, Copilot, Gemini, Codex y OpenCode desde una única configuración.

Entrégalo

outputs/skill-minimal-workbench.md genera la bancada de tres archivos para cualquier repositorio nuevo: un enrutador AGENTS.md adaptado al proyecto, un agent_state.json con las claves correctas y un task_board.json sembrado con el backlog actual.

Ejercicios

  1. Agrega una marca de tiempo last_run a agent_state.json. Rehúsa la ejecución si el archivo tiene más de 24 horas, a menos que un operador confirme.
  2. Agrega un campo priority al tablero de tareas y cambia el extractor para que siempre elija el todo de mayor prioridad.
  3. Migra task_board.json para JSON Lines para que cada tarea sea una línea y los diffs sean limpios en el control de versiones.
  4. Escribe un lint_workbench.py que falle si AGENTS.md tiene más de 80 líneas o hace referencia a un archivo que no existe.
  5. Decide cuál de los tres archivos dolería más perder. Defiende tu postura.

Términos Clave

Término Lo que la gente dice Lo que realmente significa
Enrutador AGENTS.md Archivo raíz corto que apunta al agente a documentos y archivos más profundos
Archivo de estado "Las notas" Registro legible por máquina de dónde está el agente, escrito en cada turno
Tablero de tareas "El backlog" Cola de trabajo en JSON con estado, propietario y aceptación
Sistema de registro "Fuente de verdad" El archivo que la bancada trata como autoritativo cuando el chat desaparece

Lectura Adicional

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).