Aide-mémoire harnais d'agent : composants, fichiers, problèmes et liste de contrôle au lancement

Les cinq sous-systèmes du harnais

Ordre de construction à partir de zéro : retour d'information → instructions → état → environnement → outils.

Fichiers du harnais

Squelette d'AGENTS.md

# Projet : backend de paiement (FastAPI, PostgreSQL)

## Lancer
docker compose up -d && ./scripts/init.sh

## Vérifier
make check   # lint, types, unitaires, arch-check
make e2e     # scénarios de bout en bout

## Definition of Done
- make check et make e2e — code 0
- fonctionnalité passée à passing par le script scripts/verify.sh
- PROGRESS.md mis à jour

## MUST
- requêtes vers la base uniquement via les repositories
- secrets uniquement depuis les variables d'environnement

## Documents
- docs/payments.md — lorsque la tâche touche aux paiements et aux remboursements
- docs/migrations.md — lorsque le schéma de la base change

États d'une fonctionnalité

Niveaux de vérification

Le droit de dire « terminé » n'existe qu'après le niveau le plus élevé. Des tests unitaires verts ne valent pas achèvement.

Rendre les règles mécaniques

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "POURQUOI : les services n'accèdent pas directement à la base"
  echo "CORRECTION : utilisez un repository de app/repositories/"
  fail=1
fi
exit $fail

Problèmes courants et solutions

Rôles pour les tâches longues

Budget du travail autonome

• L'objectif tient en une phrase (par exemple : faire passer toutes les fonctionnalités en passing).
• WIP=1, une limite de temps et de tentatives par fonctionnalité.
• La métrique croît de façon monotone ; une régression entraîne un retour arrière immédiat.
• Migrations, infrastructure, argent : escalade vers un humain.
• Après plusieurs revues échouées, reprendre la fonctionnalité avec un contexte propre.

Liste de contrôle au lancement de l'agent

1. Un AGENTS.md existe : pile technique, démarrage, commande de vérification, DoD.
2. make check réussit sur un clone propre.
3. L'environnement est reproductible : fichiers de verrouillage, Docker ou devcontainer.
4. L'agent dispose des commandes nécessaires ; les commandes dangereuses sont interdites ou placées dans un bac à sable.
5. Il existe un test E2E au moins pour le scénario principal.
6. Il existe un PROGRESS.md et une règle imposant de le lire au début de la session.
7. Les fonctionnalités figurent dans une liste avec leur statut, une seule est active.
8. Le statut passing est attribué par un script.
9. Les messages de vérification contiennent POURQUOI et CORRECTION.
10. La tâche est formulée avec des critères d'acceptation et des limites de périmètre.
11. Ce qui exige une décision humaine est défini.
12. L'écart de vérification a été mesuré avant les modifications, pour servir de référence.

Métriques du harnais

En bref

Le harnais est une boucle, non un fichier : instructions, outils, environnement, état et retour d'information. Commencez par les vérifications, gardez AGENTS.md court, confiez le statut d'achèvement à un script et révisez le harnais régulièrement. Tout cela est assemblé dans son ensemble sur un projet de bout en bout dans le cours sur le harness engineering.