Hiérarchie documentaire

Les artefacts — la mémoire collective de l'équipe

Les artefacts AIAD ne sont pas de la bureaucratie : ce sont des outils de pensée et de communication. Ils rendent visible ce qui resterait implicite, alignent l'équipe sur une compréhension partagée, et fournissent aux agents IA le contexte dont ils ont besoin pour performer. Sans eux, le contexte se perd à chaque session.

Outils de pensée, pas paperasse

Un bon artefact se reconnaît à quatre qualités : il est actionnable (peut-on agir à partir de ce document ?), vivant (évolue-t-il avec la compréhension ?), minimal (contient-il juste assez, pas plus ?) et collaboratif (a-t-il été co-créé, pas dicté ?). L'important n'est pas d'avoir des documents parfaits — c'est d'avoir des documents utiles. Sans AGENT-GUIDE, les agents produisent du code générique ; sans ARCHITECTURE, du code incohérent ; sans SPEC, du code incorrect.

La hiérarchie documentaire

Les artefacts s'organisent en hiérarchie stricte. La règle est absolue : ne jamais contredire un niveau supérieur.

Constitution AIAD (valeurs immuables)
  └── Agents de Gouvernance Tier 1 (droit de veto)
       └── PRD (vision produit)
            └── ARCHITECTURE (standards techniques)
                 └── AGENT-GUIDE (contexte permanent)
                      └── SPEC (activation par tâche)

Cette hiérarchie est aussi l'outil de gestion du Context Engineering Budget : le contexte stratégique en haut (injecté en cadrage), le contexte permanent au milieu (condensé), le contexte de tâche en bas (une SPEC à la fois). En cas de conflit entre une SPEC et un agent de gouvernance, la gouvernance prévaut — toujours.

Intent Statement — le POURQUOI archivé

L'Intent Statement est l'artefact de premier ordre : il capture l'intention humaine derrière chaque fonctionnalité en cinq champs (POURQUOI MAINTENANT, POUR QUI, OBJECTIF, CONTRAINTES, CRITÈRE DE DRIFT), avec un auteur humain obligatoire — principe Human Authorship. Il précède et transcende la SPEC, et il est archivé dans .aiad/intents/. Dans six mois, c'est lui qui répondra à la question « qu'est-ce qu'on voulait accomplir, et pourquoi ? ».

Le Critère de Drift dit comment on saura, dans trois mois, si l'implémentation a trahi l'intention. Depuis la doctrine v1.9, lorsque l'intention implique des actions d'agent aux effets hors du code — financiers, opérationnels ou matériels —, il précise leur classe de réversibilité (réversible, coûteusement réversible, irréversible) et, pour la classe irréversible, un seuil d'arrêt : tout dépassement d'autonomie constaté arrête l'agent et déclenche une revue humaine immédiate. Détail sur la page Intent Statement.

PRD — la valeur attendue

Le Product Requirement Document clarifie pourquoi et quoi construire avant le comment. Il contient le contexte et le problème, les Outcome Criteria mesurables, les personas et use cases, le hors périmètre volontaire, les trade-offs et les risques. Cinq pratiques sont non négociables : partir du problème (pas de la solution), définir les critères de succès avant de construire, le rédiger avec l'équipe, le maintenir vivant, et l'illustrer (wireframes, flows).

ARCHITECTURE — le référentiel de cohérence

Le document ARCHITECTURE définit les standards techniques que les agents et les PE doivent respecter, en neuf rubriques : principes architecturaux, vue d'ensemble, stack technique justifiée, structure du projet, conventions de code, patterns et bonnes pratiques, sécurité, performance, et ADR (Architecture Decision Records). Il est évolutif, justifié, pragmatique (YAGNI), visuel et actionnable. En session agent, il n'est jamais injecté en entier : un condensé permanent de 500 tokens maximum suffit — le reste se consulte à la demande.

AGENT-GUIDE — le contexte permanent de l'agent

L'AGENT-GUIDE est le document le plus opérationnel du framework : injecté dans chaque session, il transforme un agent générique en agent du projet. Il contient l'identité du projet, les règles absolues TOUJOURS / JAMAIS (ex. : toujours synchroniser SPEC + code dans la même PR ; jamais pusher de secrets), les conventions de code, le vocabulaire métier, les patterns et anti-patterns — et deux sections d'apprentissage complémentaires :

Pour structurer les Human Learnings, la taxonomie de Tang et al. (arXiv, 2026) — issue de 20 574 sessions réelles — fournit sept formes de désalignement (mauvaise interprétation de l'intent, scope creep, solution hors-spec, hallucination d'exigence…) : catégoriser chaque entrée selon la forme observée fait apparaître les schémas récurrents d'intention mal formulée. En les nommant, les Human Learnings préviennent la dette cognitive (Fowler/Joshi, 2026).

Une catégorie à part : les défaillances de supervision

Parmi les Human Learnings, certaines ne tiennent pas à une intention mal exprimée mais à une supervision absente ou devenue nominale. La doctrine v1.9 leur donne une catégorie propre, car elles se répètent sous des formes différentes. Deux cas servent de référence :

• Un agent qui agit sans approbation (Meta, mars 2026, selon la presse) : un agent interne a publié de lui-même sa réponse sur un forum interne, sans l'accord de l'ingénieur qui l'avait sollicité ; un autre salarié a suivi ce conseil, exposant pendant près de deux heures des données sensibles à des personnes non autorisées.
• Des relectures automatiques empilées (« CVE-2026-LGTM », Andrew Nesbitt, juin 2026) : ce récit est une fiction satirique, pas un incident réel. Un paquet malveillant y franchit sept contrôles automatisés, chacun échouant pour une raison différente, pendant que deux agents de revue s'enferment dans un désaccord coûteux. Les praticiens y ont reconnu leurs propres chaînes : des angles morts corrélés entre outils d'IA, et plus aucun humain pour trancher.

La question à poser en rétrospective : à quel moment un humain aurait-il dû être consulté, et pourquoi ne l'a-t-il pas été ? Les points d'arrêt de l'agent sont la réponse préventive.

Un guide de cent règles est moins efficace qu'un guide de dix règles bien choisies : l'AGENT-GUIDE est borné par le Context Budget (condensé ≤ 500 tokens en session). Pour la même raison, les exemplars de revue n'y figurent pas : ils ne sont chargés que dans les sessions de revue.

SPECs — l'instruction de travail de l'agent

Une SPEC fait le pont entre l'intention (PRD, Intent) et l'implémentation par l'agent. Une SPEC de qualité permet de générer 80 %+ du code correct du premier coup — c'est l'investissement au meilleur ROI du framework. Quatre critères la définissent : atomicité, précision, testabilité, complétude — scorés par le SQS à l'Execution Gate (≥ 4/5 requis). Chaque SPEC porte son propre Critère de Drift et reste synchronisée avec le code à chaque PR.

Deux sections, ajoutées par la doctrine v1.9, encadrent ce que l'agent est autorisé à faire : « Points d'arrêt de l'agent » (optionnelle — quand l'agent revient vers un humain : approbation, avis d'expert, pluralité de points de vue, témoin) et « Périmètre d'exécution de l'agent » (conditionnelle — requise dès que l'agent dispose de credentials ou d'un accès en écriture à une ressource partagée, « Non applicable » sinon). Voir SPEC et Autonomie de l'agent.

Les Definitions of Done

La Definition of Output Done (DoOD) établit le standard pour qu'un incrément soit livrable, en six catégories : techniques, sécurité, performance, fonctionnels, déploiement, review. Le principe est non négociable : tous les critères ou rien — « Done à 90 % n'est pas Done ».

La Definition of Outcome Done (DoOuD) mesure si la valeur attendue a été réalisée : User Outcomes (NPS, adoption, rétention), Business Outcomes (MRR, conversions, efficacité) et Learning Outcomes (hypothèses validées ou invalidées, insights). L'output est le moyen ; l'outcome est le but — une fonctionnalité livrée mais non adoptée n'est pas un succès.

L'arborescence .aiad/

.aiad/
├── PRD.md                  ← Vision produit (injection : cadrage uniquement)
├── ARCHITECTURE.md         ← Standards techniques (condensé permanent)
├── AGENT-GUIDE.md          ← Contexte permanent + Lessons Learned + Human Learnings
├── gouvernance/            ← Agents Tier 1 avec droit de veto
│   ├── _index.md
│   ├── AIAD-AI-ACT.md
│   ├── AIAD-RGPD.md
│   ├── AIAD-RGAA.md
│   ├── AIAD-RGESN.md
│   └── AIAD-CRA.md         ← Livré en complément (produits logiciels)
├── intents/                ← Intent Statements (POURQUOI)
│   └── _index.md
├── specs/                  ← SPECs techniques (COMMENT)
│   └── _index.md
├── review-exemplars/       ← Exemplars de revue (optionnel, sessions de revue uniquement)
├── facts/                  ← Traces /sdd fact
├── metrics/
│   ├── security/           ← Rapports /sdd security
│   ├── audit/              ← Rapports /sdd audit
│   └── traceability/       ← Snapshots /sdd trace (Markdown + JSON + HTML)
└── CHANGELOG-ARTEFACTS.md  ← Historique des mises à jour

La doctrine compte quatre guides Tier 1 (AI-ACT, RGPD, RGAA, RGESN). L'agent AIAD-CRA est livré en complément par le paquet pour les produits logiciels : l'obligation de signalement à l'ENISA prévue par le Cyber Resilience Act est en vigueur depuis le 11/09/2026. Le répertoire review-exemplars/ est une convention optionnelle de la doctrine, à créer par l'équipe.

Anti-patterns des artefacts