Phase 14: Agent Engineering

El trabajo de agente mínimo

El banco de trabajo más pequeño y útil es de tres archivos: un router de instrucciones raíz, un archivo de estado y un tablero de tareas. Todo lo demás está en capas arriba. Si un repo no puede llevar estos tres, ningún modelo lo guardará.

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 31 (Why Capable Models Still Fail)

Time: ~45 minutes

Objetivos de aprendizaje

  • Definir los tres archivos que forman el banco de trabajo mínimo viable.
  • Explica por qué un router de raíz corto supera a un monolitico largo AGENTS.md¿ Qué ?
  • Construye un archivo de estado que el agente pueda leer en cada turno y escribir al final.
  • Construir un tablero de tareas que sobreviva a la sesión de trabajo sin historial de chat.

El problema

La mayoría de los equipos se acercan a un escritorio escribiendo una línea de 3000 .AGENTS.mdEl modelo lo carga, ignora las partes que no puede resumir, y todavía falla en las mismas superficies en las que siempre falló.

Necesitas lo contrario. Un pequeño archivo raíz que envía al agente a archivos más profundos solo cuando sea relevante. Estado duradero el agente lee antes de actuar y escribe después. Una tabla de tareas que dice lo que está en vuelo, lo que está bloqueado y lo que está arriba después.

Tres archivos, cada uno con un trabajo, cada uno lo suficientemente legible para evolucionar a un sistema real más tarde.

El concepto

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

Agentes.md es un router, no un manual

Un buen .AGENTS.mdEs corto, señala al agente a:

  • El archivo del estado (donde estás).
  • El tablero de tareas (lo que queda).
  • Las reglas más profundas (endocs/agent-rules.md¿Qué es lo que se hace?
  • El comando de verificación (cómo saber que funciona).

Cualquier cosa más larga se enciende en documentos más profundos, cargados sólo cuando sea necesario.

agent_state.json es el sistema de registro

El estado lleva: la identificación de tarea activa, los archivos tocados, las suposiciones hechas, los bloqueadores 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 fiable las sesiones mueren las conversaciones se recortan el archivo no lo hace

task_board.json es la cola

El tablero de tareas lleva a cabo cada tarea con estado todo | in_progress | done | blockedEs la cola que el agente saca cuando el estado está vacío, y la cola que se lee cuando se quiere saber si el agente está en el camino correcto.

Una tarea en el tablero tiene una identificación, un objetivo, un propietario (builder¿ Qué ?reviewer, ohumanLa tabla es pequeña a propósito: cuando se hace más allá de una pantalla, se tiene un problema de planificación, no un problema de tabla.

Tres archivos es el piso, no el techo.

Las lecciones posteriores añaden contratos de alcance, corredores de retroalimentación, puertas de verificación, listas de verificación de revisores y paquetes de entrega.

Construye el mismo

code/main.pyescribe el banco de trabajo mínimo en un repo vacío y demuestra que un solo agente vuelve que:

  1. Leemosagent_state.json¿ Qué ?
  2. Retira la siguiente tarea de task_board.jsonsi el estado está vacío.
  3. Toca un solo archivo dentro del alcance.
  4. Escribe el estado actualizado.
  • ¿Qué quieres decir ?
python3 code/main.py

El guión creaworkdir/Junto a sí mismo, pone los tres archivos, ejecuta un giro, e imprime la diferencia.

Usalo

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

  • Claude Code: AGENTS.mdo CLAUDE.mdpara el router, .claude/state.json- Tiendas de estilo para el estado, ganchos para la junta.
  • Codex / Cursor:reglas del espacio de trabajo para el router, memoria de sesión para estado, tareas en cola en la barra lateral de chat para la placa.
  • Custom Python agent:Los mismos archivos que acabas de escribir.

Los nombres cambian, pero la forma no.

Modelos de producción en la naturaleza

El banco de trabajo mínimo sobrevive al contacto con monorepos reales cuando se colocan tres patrones en capas encima.

Nested AGENTS.md with nearest-wins precedence.Naves de OpenAI 88 AGENTS.mdLos archivos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de la base de datos de datos de datos de la base de datos de datos de datos de datos de la base de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos de datos deAGENTS.mdLos archivos de subdirectorio amplían el archivo raíz.AGENTS.override.mdEl método de superposición es específico para el código y se evita para el trabajo transversal.AGENTS.mdLos archivos dan un salto de calidad equivalente a la actualización de Haiku a Opus; los peores hacen que la salida sea peor que ningún archivo en absoluto.

Anti-patterns to refuse, even when they look like coverage.Las instrucciones contradictorias dejan caer silenciosamente el agente del modo interactivo al modo codicioso (ICLR 2026 AMBIG-SWE: 48,8% → 28% de tasa de resolución); número las prioridades en lugar de apilarlas. Reglas de estilo no verificables (" Siga la Guía de Estilo de Python de Google ") sin comando de ejecución permiten al agente inventar el cumplimiento; empareje cada regla de estilo con el comando de lint exacto. Liderar con estilo en lugar de comandos sepulta el camino de verificación; comandos primero, estilo último. Escribir para humanos en lugar de agentes desperdicia el presupuesto contextual; la concisión es una característica.

Cross-tool symlinks.Un único archivo raíz con enlaces simbólicos (ln -s AGENTS.md CLAUDE.md¿ Qué ?ln -s AGENTS.md .github/copilot-instructions.md¿ Qué ?ln -s AGENTS.md .cursorrules) mantiene a todos los agentes de codificación en la misma fuente de verdad.nx ai-setupautomatiza esto a través de Claude Code, Cursor, Copilot, Gemini, Codex y OpenCode desde una sola configuración.

Envío

outputs/skill-minimal-workbench.mdgenera el banco de trabajo de tres archivos para cualquier nuevo repo: un AGENTS.mdel router está conectado al proyecto, un agent_state.jsoncon las teclas correctas, y un task_board.jsonSe ha sembrado con el actual retraso.

Los ejercicios

  1. Añadir unlast_runtiempo de la marca de tiempoagent_state.json- Rechazar la ejecución si el archivo tiene más de 24 horas, a menos que el operador lo confirme.
  2. Añadir unprioritycampo a la tabla de tareas y cambiar el tirador para siempre elegir la mayor prioridad todo¿ Qué ?
  3. Migración task_board.jsona JSON Lines para que cada tarea sea una línea y las diferencias estén limpias en el control de versión.
  4. Escriba unlint_workbench.pyque falla si AGENTS.mdes más de 80 líneas o hace referencia a un archivo que no existe.
  5. Decida cuál de los tres archivos le haría más daño perderlo.

Términos clave

TermWhat people sayWhat it actually means
RouterAGENTS.mdShort root file that points the agent at deeper docs and files
State file"The notes"Machine-readable record of where the agent is, written every turn
Task board"The backlog"JSON queue of work with status, owner, acceptance
System of record"Source of truth"The file the workbench treats as authoritative when chat is gone

Leer más

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.