Artefacts de travail

Un artefact de travail, c’est ce qui ne survit pas à la tâche : la note de cadrage, le plan, l’état d’avancement, la user story. L’artefact de travail est à distinguer des artefacts de projet (chapitre 4.3) car il ne vit que le temps d’un travail à mener et s’efface une fois la tâche terminée.

Tous les workflows agentiques font transiter des artefacts entre leurs phases, souvent sous forme de fichiers Markdown. C’est la qualité de ces artefacts qui importe, pas le workflow choisi :

• pas d’artefact = tout reste dans la fenêtre de contexte, pas de continuité entre sessions, process non parallélisable ;
• trop d’artefacts = dispersion de l’attention de l’agent, risque de rater du contexte lors de l’exécution d’une tâche ;
• périmètre de l’artefact mal défini = l’agent l’ignore ou, à l’inverse, l’applique hors-scope.

Quatre grandes catégories artefacts couvrent le cycle d’une tâche : exploration, spécification, plan d’implémentation, état d’avancement. Chacun marque une transition et porte une question différente : qu’est-ce qu’on veut vraiment ?, que doit-on livrer ?, comment et où ?, où en est-on ? Chacun construit son workflow ; les modèles existants ne sont que des manières différentes d’enchaîner ces mêmes artefacts (chapitre 5.2).

Par convention dans ce chapitre, chaque artefact est court, versionné quand il dépasse la note de conversation, et porte un nom explicite (exploration.md, spec.md, plan.md, progress.md).

Exploration

L’exploration raffine le prompt initial et lève l’ambiguïté avant de figer l’intention. C’est le premier niveau de friction : un prompt brut est presque toujours sous-spécifié, et ce cadrage confronte la demande au réel avant de s’engager. Une ambiguïté non levée ici aura souvent des conséquences négatives en aval (shift-feedback-left).

• Contenu :
  • reformulation du besoin et questions ouvertes levées avec l’humain (Ask a question, grillme skill)
  • état des lieux du code et du domaine pertinents
  • options envisagées et leurs implications
  • hypothèses et zones d’incertitude restantes.
• Principe clé : maximiser la friction ici, à bas coût, pour l’éliminer plus loin où elle coûte cher (exécution, revue).
• Granularité : quelques échanges de clarification pour une tâche simple ; vraie phase de brainstorm pour une feature.
• Quand le mettre à jour : tant que des ambiguïtés subsistent ; on fige dès que la spec peut être écrite sans hypothèse implicite.
• Forme : court et jetable, actif le temps du cadrage ; peut rester une note de conversation ou un exploration.md si la phase est lourde.

Exemple

// `exploration.md` — commande `users export`

Besoin : dumper les users en CSV.
Questions ouvertes : tous les users ou un filtre (actif/inactif) ? Colonnes attendues ? Destination (stdout, fichier) ? Volume estimé (10k, 1M) ?
État du code : pas de commande CLI existante, `pkg/users` expose `ListAll()`.
Hypothèse : on streame pour ne pas charger 1M de lignes en mémoire.

Specification

La spec fige l’intention : le quoi et le pourquoi, jamais le comment. Sans cette ligne nette, l’agent dérive de deux manières — l’overreach (on en fait trop, hors périmètre) ou l’under-finish (on s’arrête trop tôt). La spec coupe court aux deux en posant un périmètre explicite et des critères d’acceptation qui servent dès le départ de boucle de feedback : un critère = un test. La spec est l’artefact intermédiaire entre l’intention et la production. L’artefact central est le modèle de domaine et les scénarios qui le mette en oeuvre, mais qui s’appuie sur des vrais valeurs concrètes et réelles au sein du scénario (afin d’obtenir ce précieux “exercice” de l’humain avec son domaine métier).

• Contenu :
  • objectif ou problème à résoudre (1-2 phrases)
  • critères d’acceptation explicites (formalisme EARS)
  • contraintes non négociables (NFR : sécurité, perf, fiabilité…)
  • format de sortie attendu
  • definition of done
  • périmètre explicite avec ce qui est dans le périmètre et hors périmètre.
• Principe clé : un critère d’acceptation = un test. La boucle de feedback est posée avant qu’une ligne ne soit écrite.
• Granularité : EARS pour une exigence ponctuelle ; PRD pour une feature complète ; Example Based pour illustrer les contraintes multiples.
• Quand le mettre à jour : à chaque fois que l’intention ou le périmètre change (≠ détails d’exécution).
• Forme : court et versionné, dénomination claire (spec.md ou nom de la tâche), description en front-matter.

Exemple

// `spec.md` — commande `users export`

Objectif : commande CLI `users export` qui écrit les users actifs en CSV sur stdout.

Critères d'acceptation :
- WHEN la commande est invoquée, THEN elle écrit l'en-tête `id,email,created_at` ;
- WHEN un user est inactif, THEN il est exclu ;
- WHEN le volume dépasse 100k lignes, THEN la mémoire ne dépasse pas 50 Mo (NFR).

Hors périmètre : filtres avancés, formats autres que CSV.

Plan d’implémentation

Le plan projette la spec sur le projet réel, à travers l’environnement disponible. Il décrit le comment et le où. C’est là qu’on découvre les contraintes, dépendances et impossibilités que la spec ne pouvait pas voir. Un bon plan rend l’exécution mécanique : chaque étape est petite, vérifiable, et s’appuie sur ce que l’environnement permet réellement.

• Contenu :
  • découpage du travail en étapes ordonnées
  • fichiers et modules impactés (file map) et leurs dépendances
  • ancrage dans l’environnement (commandes de build/test, runtime, services, libs disponibles)
  • mapping critères d’acceptation → changements concrets dans le code
  • décisions techniques et alternatives écartées (mini-ADR si besoin).
• Principe clé : un plan ne tient que s’il est vérifié contre le réel, pas contre une représentation que s’en fait l’agent.
• Granularité : quelques étapes pour une tâche ou plan multi-modules avec décisions d’architecture pour une feature.
• Quand le mettre à jour : quand la spec évolue, quand l’environnement change (refacto, nouvelle dépendance), ou quand l’exécution révèle que le plan ne tient pas face au réel.
• Forme : court et versionné (plan.md), file map + étapes cochables qui alimentent directement l’état d’avancement.

Exemple

// `plan.md` — commande `users export`

Étapes :
1. `cmd/cli/export.go` : ajouter la commande Cobra `users export`.
2. `pkg/users/repository.go` : ajouter `StreamActive(ctx) <-chan User`.
3. `cmd/cli/export.go` : encoder via `encoding/csv` en streaming sur `os.Stdout`.

Commandes : `go test ./pkg/users/...`, `go run ./cmd/cli users export | head`.
Décision : streaming par canal plutôt que slice (alternative écartée : charge mémoire).

État d’avancement

L’état d’avancement enregistre l’exécution du plan : ce qui est fait, en cours, bloqué, terminé. C’est la mémoire de travail de la tâche, et l’artefact le plus vivant des quatre. La continuité entre sessions ne vit pas dans la fenêtre de contexte, elle vit dans le repo. Ce fichier permet de reprendre une tâche après un /clear, de la paralléliser, et à un humain de reprendre la main.

• Contenu :
  • étapes du plan avec leur statut (à faire / en cours / fait / bloqué)
  • pour une étape bloquée, la raison et ce qui manque (contexte, décision)
  • décisions prises en cours de route et écarts par rapport au plan
  • pointeur vers l’étape suivante.
• Principe clé : on doit pouvoir repartir en lisant ce seul fichier.
• Granularité : une checklist légère pour une tâche ou un journal par étape avec décisions et écarts pour une feature longue.
• Quand le mettre à jour : à chaque transition d’étape (début, fin, blocage). Mis à jour en continu pendant l’exécution.
• Forme : court et versionné (progress.md ou TODO.md), étapes cochables alignées sur le plan et idéalement modifiable par l’agent lui-même.

Exemple

// `progress.md` — commande `users export`

- [x] Commande Cobra scaffold
- [x] `StreamActive` — tests passants
- [ ] CSV encoder — bloqué : `encoding/csv` ne flushe pas par défaut, à vérifier
- [ ] doc + changelog

Décision en cours de route : on ignore les users sans email plutôt que d'écrire une ligne vide.

Ces quatre artefacts cadrent le travail d’une tâche, de la demande floue à l’exécution tracée. Le chapitre suivant montre comment les workflows existants les enchaînent, et ce que chacun choisit de matérialiser ou non.