Phase 14: Agent Engineering

Le bureau de travail de l'agent minimal

Le plus petit tableau de travail utile est composé de trois fichiers: un routeur d'instructions racine, un fichier d'état et un tableau de tâches. Tout le reste est en couches en haut. Si un repo ne peut pas transporter ces trois, aucun modèle ne le sauvegarde.

Type: Build

Languages: Python (stdlib)

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

Time: ~45 minutes

Objectifs d'apprentissage

  • Définir les trois fichiers qui constituent le tableau de travail minimum viable.
  • Expliquez pourquoi un routeur à racine courte bat un long monolithique AGENTS.md- Je suis désolé .
  • Construisez un dossier d'état que l'agent peut lire à chaque tour et écrire à la fin.
  • Construisez un tableau de tâches qui survit au travail en plusieurs sessions sans historique de chat.

Le problème

La plupart des équipes atteignent un bureau en écrivant une ligne de 3000AGENTS.mdLe modèle le charge, ignore les parties qu'il ne peut résumer, et échoue toujours sur les mêmes surfaces sur lesquelles il a toujours échoué.

Vous avez besoin de l'inverse. Un petit fichier racine qui enroule l'agent dans des fichiers plus profonds seulement lorsque cela est pertinent. L'état durable l'agent lit avant d'agir et écrit après. Un tableau de travail qui dit ce qui est en vol, ce qui est bloqué, et ce qui est en haut.

Trois fichiers, chacun avec un travail, assez lisible pour évoluer en un système réel plus tard.

Le concept

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

AGENTS.md est un routeur, pas un manuel

Une bonne .AGENTS.mdIl indique l'agent à:

  • Le dossier de l'État (où vous êtes).
  • Le tableau de tâches (ce qui reste).
  • Les règles plus approfondies (en)docs/agent-rules.md)
  • La commande de vérification (comment savoir si elle fonctionne).

Tout ce qui est plus long est dans des documents plus profonds, chargé seulement quand il est nécessaire, les manuels longs sont ignorés, les routeurs courts sont suivis.

agent_state.json est le système de dossiers

L'agent le lit à chaque tour, la session suivante le lit au lieu de reproduire le chat.

L'État vit dans un dossier parce que l'historique de chat est peu fiable, les sessions meurent, les conversations sont coupées, le dossier ne le fait pas.

task_board.json est la file d'attente

Le comité de tâches effectue chaque tâche avec statut todo | in_progress | done | blockedC'est la queue que l'agent tire quand l'état est vide, et la que vous lisez quand vous voulez savoir si l'agent est sur la bonne voie.

Une tâche sur le tableau a un identifiant, un objectif, un propriétaire (builder- Je suis là .reviewerou humanLa carte est délibérément petite: lorsqu'elle dépasse un écran, vous avez un problème de planification, pas un problème de carte.

Trois dossiers est le sol, pas le plafond

Les leçons ultérieures ajoutent des contrats de portée, des coureurs de rétroaction, des portes de vérification, des listes de contrôle des réviseurs et des paquets de remise.

Faites-le

code/main.pyécrit le tableau de bord minimal dans un repo vide et démontre qu'un seul agent tourne:

  1. Il est en train de lire .agent_state.json- Je suis désolé .
  2. Il tire la prochaine tâche de task_board.jsonSi l'état est vide.
  3. Touche un seul fichier à l'intérieur du champ de vision.
  4. Il écrit à l'état actualisé.
  • Je vais le faire.
python3 code/main.py

Le scénario créeworkdir/Il met les trois fichiers à côté de lui, fait un tour et imprime le diff.

Utilisez-le

Dans les produits des agents de production, les mêmes trois fichiers apparaissent sous des noms différents:

  • Claude Code: AGENTS.mdou CLAUDE.mdpour le routeur, .claude/state.json- des magasins de style pour l'État, des crochets pour le conseil.
  • Codex / Cursor:règles de l'espace de travail pour le routeur, mémoire de session pour l'état, tâches en file d'attente dans la barre latérale de chat pour le tableau.
  • Custom Python agent:Les mêmes dossiers que vous venez d'écrire.

Les noms changent, mais pas la forme.

Modèles de production dans la nature

Le tableau de travail minimum survit au contact avec des monorepos réels lorsque trois modèles sont couchés dessus.

Nested AGENTS.md with nearest-wins precedence.Les navires OpenAI 88 AGENTS.mdLes fichiers de référencement sont tous en cours de marche depuis le fichier de travail vers la racine du référencement et se concatenent chaque fois.AGENTS.mdLes fichiers de sous-répertoire étendent le fichier racine.AGENTS.override.mdLe mécanisme d'annulation est spécifique au codex et l'éviter pour les travaux croisés.AGENTS.mdLes fichiers donnent un saut de qualité équivalent à la mise à niveau de Haiku à Opus; les pires font que la sortie est pire que aucun fichier.

Anti-patterns to refuse, even when they look like coverage.Les instructions contradictoires font passer le médicament du mode interactif au mode avide (ICLR 2026 AMBIG-SWE: taux de résolution de 48,8% → 28%); numérotation des priorités au lieu de les empiler. Règles de style non vérifiables (" suivez le guide de style de Python de Google ") sans commande d'exécution permettent à l'agent d'inventer la conformité; associer chaque règle de style avec la commande de lint exacte. Le leadership avec style au lieu de commandes enterre le chemin de vérification; commandes d'abord, style dernier. Écrire pour les humains au lieu d'agents gaspille le budget contextuel; la concision est une caractéristique.

Cross-tool symlinks.Un seul fichier racine avec des liens symboliques (ln -s AGENTS.md CLAUDE.md- Je suis là .ln -s AGENTS.md .github/copilot-instructions.md- Je suis là .ln -s AGENTS.md .cursorrulesIl garde tous les agents de codage sur la même source de vérité.nx ai-setupautomatique à travers Claude Code, Cursor, Copilot, Gemini, Codex et OpenCode à partir d'une seule configuration.

La faire partir

outputs/skill-minimal-workbench.mdgénère le tableau de travail de trois fichiers pour tout nouveau repo: un AGENTS.mdLe routeur est adapté au projet, unagent_state.jsonavec les bonnes clés, et un task_board.jsonLes résultats de l'enquête ont été obtenus en raison de la situation actuelle.

Exercices

  1. Ajouter un last_runTemps de la date de l' ouvertureagent_state.json- Refuser d'exécuter si le fichier est supérieur à 24 heures, à moins que l'opérateur ne le confirme.
  2. Ajouter un prioritychamp à la table de tâches et changer le tirage pour toujours choisir la priorité la plus élevée todo- Je suis désolé .
  3. Migrés task_board.jsonà JSON Lines afin que chaque tâche soit une ligne et les différences sont propres dans le contrôle de version.
  4. Écrivez unelint_workbench.pyqui échoue si AGENTS.mdest supérieur à 80 lignes ou renvoie à un fichier qui n'existe pas.
  5. Décidez lequel des trois dossiers fera le plus de mal à perdre.

Les termes clés

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

Pour en savoir plus

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.