Les Artefacts

Définition

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. Un bon artefact 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.

Pourquoi les artefacts sont indispensables

Sans artefacts, le contexte se perd à chaque changement de session. Les agents IA produisent du code générique sans AGENT-GUIDE, du code incohérent sans ARCHITECTURE, et du code incorrect sans SPEC. L’alignement entre intention et implémentation se dégrade silencieusement. Les artefacts sont la mémoire collective de l’équipe et le carburant de l’écosystème d’agents.

Intent Statement — Artefact de Premier Ordre (v1.5)

Définition. L’Intent Statement capture et archive l’intention humaine derrière chaque fonctionnalité, indépendamment de la spécification qui en découle. C’est un artefact de premier ordre : il précède et transcende la SPEC.

Pourquoi cet artefact existe. Dans six mois, quand une fonctionnalité est contestée ou doit être révisée, la question essentielle n’est pas “qu’est-ce que la SPEC dit ?” mais “qu’est-ce que l’équipe voulait accomplir et pourquoi ?”. La SPEC répond à la première question. L’Intent Statement archivé répond à la seconde. Sans cet archivage, l’intention se perd dans le bruit des itérations — c’est l’une des causes profondes de la dette intentionnelle.

Ancrage constitutionnel : Valeur 5 (Empirisme sans Concession), Article VII (mécanisme d’évolution du framework).

Comment. L’Intent Statement comprend cinq champs obligatoires :

## Intent Statement — [ID] — [Titre]

**Auteur humain :** [Prénom Nom] — [Date]

**POURQUOI MAINTENANT**
Qu'est-ce qui a changé dans le monde, dans le produit, ou dans la compréhension
de l'équipe pour que cette fonctionnalité soit nécessaire aujourd'hui ?

**POUR QUI**
Quel humain va voir sa vie changer, et comment ? Soyez précis sur la personne,
pas sur le persona.

**OBJECTIF**
Ce qu'on cherche à accomplir — formulé en termes d'impact, pas de fonctionnalité.

**CONTRAINTES**
Ce qu'on ne sacrifiera pas — valeurs, qualité, éthique, ressources.

**CRITERE DE DRIFT**
Comment saura-t-on, dans 3 mois, si l'implémentation a trahi l'intention initiale ?

Le cinquième champ — le CRITERE DE DRIFT — ancre la vérification de fin d’itération non plus uniquement sur une vérification technique (le code correspond-il à la SPEC ?) mais sur une vérification d’intention (l’implémentation reflète-t-elle ce que l’humain voulait vraiment ?).

La règle Human Authorship : le champ Auteur humain est obligatoire et rempli délibérément — jamais automatiquement. Cette friction minuscule est intentionnelle : elle marque le moment de l’appropriation.

Les Intent Statements sont archivés dans .aiad/intents/. La structure complète du répertoire AIAD est la suivante :

.aiad/
├── PRD.md
├── ARCHITECTURE.md
├── AGENT-GUIDE.md
├── intents/
│   ├── _index.md
│   ├── INTENT-001-[nom].md
│   └── archive/
├── specs/
│   ├── _index.md
│   └── SPEC-001-[nom].md
└── CHANGELOG-ARTEFACTS.md

Les indicateurs de succès : Intent Statements archivés pour 100 % des fonctionnalités majeures, taux d’alignement intention/livraison supérieur à 80 % (Atelier d’Intention), et auteur humain identifiable sur chaque Intent Statement à 100 %.

Anti-pattern. Demander à l’agent de “proposer un Intent Statement” pour gagner du temps. Si l’agent l’a rédigé, la session est invalidée.

PRD — Product Requirement Document

Définition. Le PRD clarifie pourquoi et quoi construire avant de se poser la question du comment. C’est le document de référence de la valeur attendue.

Pourquoi cet artefact existe. Sans PRD, les équipes construisent des fonctionnalités techniquement parfaites que personne n’a demandées, ou résolvent des problèmes mal compris.

Comment. Le PRD contient le contexte et le problème (quel problème, pour qui, pourquoi maintenant), les Outcome Criteria (métriques mesurables de succès), les personas et use cases (profils utilisateurs et scénarios d’usage), le hors périmètre (ce que l’équipe ne fait pas volontairement), les trade-offs et décisions (décisions majeures et alternatives écartées), et les dépendances et risques (prérequis et risques identifiés).

Cinq bonnes pratiques sont non-négociables. Commencer par le problème, pas par la solution. Définir les critères de succès avant de construire (approche outcome-driven). Le rédiger avec l’équipe, pas pour l’équipe. Le maintenir vivant — il évolue avec la compréhension. Et intégrer des wireframes et flows quand pertinent.

Les indicateurs de succès : 100 % des membres comprennent le “pourquoi”, changements de scope inférieurs à 20 %, et Outcome Criteria atteints pour plus de 70 % des fonctionnalités.

Anti-pattern. Le PRD fleuve de cinquante pages que personne ne lit, ou le PRD vague type “Améliorer l’expérience utilisateur”. Les deux sont inutiles.

ARCHITECTURE — Standards Techniques

Définition. Le document ARCHITECTURE définit les standards techniques que les agents IA et les PE doivent respecter. C’est le référentiel de cohérence de l’équipe.

Pourquoi cet artefact existe. Sans document d’architecture, chaque fonctionnalité est implémentée différemment, les agents IA génèrent du code incohérent, et la dette technique s’accumule silencieusement.

Comment. Le document ARCHITECTURE contient les principes architecturaux (cinq principes non-négociables), la vue d’ensemble (architecture high-level avec justification), le stack technique (technologies, versions, justifications), la structure du projet (organisation des dossiers et modules), les conventions de code (nommage, formatage, imports), les patterns et bonnes pratiques (design patterns avec exemples), la sécurité (principes et pratiques obligatoires), la performance (budgets et stratégies), et les ADR (Architecture Decision Records).

Cinq bonnes pratiques guident la rédaction : rendre le document évolutif (l’architecture évolue avec le produit), justifier chaque choix (la rationale est explicite), rester pragmatique (YAGNI, pas d’over-engineering), le rendre visuel (diagrammes, pas que du texte), et le garder actionnable (les PE s’y réfèrent quotidiennement).

Les indicateurs de succès : décisions architecturales revisitées à moins de 10 % par an, code généré conforme aux standards à plus de 90 %, et temps d’onboarding technique inférieur à une semaine.

Anti-pattern. L’architecture “ivory tower” décidée sans connaître la réalité du terrain, ou le CV-driven development qui choisit des technos pour impressionner plutôt que pour résoudre.

AGENT-GUIDE — Contexte pour les Agents IA

Définition. L’AGENT-GUIDE fournit le contexte optimal aux agents IA pour qu’ils génèrent du code de qualité aligné avec les standards de l’équipe. C’est le document le plus opérationnel du framework.

Pourquoi cet artefact existe. Un agent sans contexte génère du code générique. Un agent avec un contexte riche génère du code professionnel adapté au projet. L’écart de qualité est considérable — et entièrement sous contrôle de l’équipe.

Comment. L’AGENT-GUIDE contient l’identité du projet (nom, description, domaine métier, mission), la documentation de référence (liens vers PRD, ARCHITECTURE, SPECs), le stack technique (résumé des technologies utilisées), les règles absolues (TOUJOURS et JAMAIS), les conventions de code (nommage, imports, structure composants), le vocabulaire métier (termes spécifiques au domaine), les patterns de développement (approches favorisées avec exemples), les anti-patterns (ce qu’il faut éviter avec exemples), et deux sections d’apprentissage spécifiques : Lessons Learned et Human Learnings.

Lessons Learned

La section Lessons Learned est un rituel obligatoire à chaque fin d’itération. Elle documente les erreurs récurrentes de l’agent pour éviter qu’elles se reproduisent d’une session à l’autre. La règle : à la fin de chaque itération, le PE vérifie s’il y a une erreur agent à documenter. Cinq minutes. Pas optionnel.

Date	Contexte de l’erreur	Comportement observé	Correction appliquée	Statut
2026-02-01	Génération service auth	Import circulaire créé	Expliciter l’ordre d’import dans la SPEC	✅ Résolu

Human Learnings (v1.5)

La section Human Learnings est le pendant des Lessons Learned : elle documente non pas les défaillances de l’agent, mais les défaillances de l’intention humaine. Les Lessons Learned posent la question “qu’est-ce que l’agent a mal fait ?”. Les Human Learnings posent la question complémentaire : “qu’est-ce que l’humain a mal exprimé ?” Elle est maintenue par le PE et/ou le PM, et revue lors de l’Atelier d’Intention mensuel.

Ancrage constitutionnel : Valeur 5 (Empirisme sans Concession) — si on observe et révise les outputs de l’agent, on observe aussi les processus d’intention humaine.

Cinq bonnes pratiques guident la rédaction de l’AGENT-GUIDE : rester concret (exemples de code, pas juste principes abstraits), tenir les sections Notes d’Apprentissage à jour en continu, inclure le vocabulaire métier spécifique au domaine, maintenir l’équilibre (ne pas dépasser le Context Budget — un guide de cent règles est moins efficace qu’un guide de dix règles bien choisies), et le réviser mensuellement au minimum.

Les indicateurs de succès : first-time success rate du code généré supérieur à 70 %, conformité aux conventions supérieure à 90 %, et temps de correction post-génération inférieur à 20 % du temps total.

Anti-pattern. Le guide encyclopédique de cinquante pages jamais mis à jour, ou le guide vague type “Écrire du bon code”. L’AGENT-GUIDE doit être le document le plus lu par l’agent — et donc le plus ciblé.

SPECS — Spécifications Techniques

Définition. Une SPEC fait le pont entre l’intention métier (PRD) et l’implémentation concrète par les agents IA. C’est l’instruction de travail de l’agent pour une fonctionnalité donnée.

Pourquoi cet artefact existe. Une SPEC de qualité permet à un agent IA de générer 80 %+ du code correct du premier coup. Sans SPEC, le PE passe plus de temps à corriger qu’à orchestrer. La SPEC est l’investissement au meilleur ROI du framework.

Comment. Une SPEC contient le scope d’activation (injectée seule ou combinée avec d’autres SPECs — préciser), le contexte (référence Intent Statement parent, objectif, outcome attendu), le périmètre (in scope et out of scope explicites), les fichiers impactés (à créer ou à modifier), l’interface technique (API endpoints, types, schémas DB), le comportement détaillé (flow nominal et cas limites), les règles de validation (avec schémas), les règles métier (à appliquer), les tests attendus (scénarios à implémenter), les exemples d’usage (concrets, requête/réponse), la Definition of Done (critères de “Done”), et le Critère de Drift (règle concrète pour détecter si cette SPEC est devenue obsolète).

Le Spec Quality Score

Le Spec Quality Score est une checklist en cinq points que le PE valide avant de soumettre une SPEC à un agent :

Atomicité — une seule responsabilité fonctionnelle ?
Interfaces précises — types et signatures explicites, sans “retourner un objet” vague ?
Testabilité — cas de test inclus et liés aux Outcome Criteria du PRD ?
Non-ambiguïté — zéro adverbe vague — correctement, convenablement, rapidement ?
Scope défini — fichiers impactés exhaustifs et Critère de Drift renseigné ?

Une SPEC qui ne passe pas le Spec Quality Score ne doit pas être soumise à l’agent. Corriger prend dix minutes. Corriger le code généré sur une mauvaise SPEC prend des heures.

Critère 6 — Test de l’Étranger (v1.5, non-scorable)

Un sixième critère est ajouté à la checklist. Il ne bloque pas l’Execution Gate si la réponse est négative, mais il doit être posé, et la réponse doit être documentée dans la SPEC avant de continuer.

La question : “Si je montrais cette SPEC à quelqu’un qui ne connaît pas le projet, saurait-il pourquoi on la fait ?”

Répondre en deux phrases maximum. Si ce n’est pas possible, le contexte humain est insuffisant. La réponse s’intègre dans la SPEC :

## Contexte pour un lecteur extérieur
[Deux phrases. Rédigées par un humain. Avant l'Execution Gate.]

Ancrage constitutionnel : Valeur 1 (Primauté de l’Intention Humaine), Article VIII (transparence). Ce critère traduit le principe Feynman : on ne comprend vraiment quelque chose que quand on peut l’expliquer simplement.

Si vous ne pouvez pas remplir ce champ, revenez à l’Intent Statement avant de continuer.

Le champ Scope d’Activation indique si cette SPEC doit être injectée seule (par défaut) ou en combinaison avec d’autres SPECs (cas des fonctionnalités transverses). Mélanger le contexte permanent de l’AGENT-GUIDE avec des SPECs multiples non reliées sature le budget de contexte de l’agent. Le champ Critère de Drift est une règle concrète pour détecter si cette SPEC est devenue obsolète. Exemple : “Cette SPEC est en drift si le fichier auth/validator.ts est modifié sans mise à jour de la section Interface Technique.”

Les indicateurs de succès : code généré correct du premier coup supérieur à 80 %, ratio temps de rédaction SPEC versus correction code supérieur à 1:3, et moins de deux questions de clarification par SPEC.

Anti-pattern. La SPEC tentaculaire avec vingt fonctionnalités, ou la SPEC vague type “Améliorer la performance”. Les deux sont inutilisables.

Les Definitions of Done

Definition of Output Done (DoOD)

La Definition of Output Done (DoOD) établit le standard de qualité uniforme pour qu’un incrément soit considéré comme “Done” et livrable. Sans DoOD partagée, “Done” signifie quelque chose de différent pour chaque membre de l’équipe.

Les critères s’organisent en six catégories :

Techniques : conventions respectées, linting OK, types complets, tests passants
Sécurité : scan passé, pas de secrets, validation inputs
Performance : budgets respectés, queries optimisées
Fonctionnels : SPEC respectée, acceptance criteria validés
Déploiement : build réussit, déployé en staging, smoke tests OK
Review : code review faite, QA validé

Le principe est non-négociable : une fonctionnalité n’est “Done” que si TOUS les critères sont satisfaits. “Done à 90 %” n’est pas Done.

Definition of Outcome Done (DoOuD)

La Definition of Outcome Done (DoOuD) mesure si la valeur attendue a été réalisée pour les stakeholders. L’output est le moyen. L’outcome est le but. Une fonctionnalité livrée mais non adoptée n’est pas un succès.

Les métriques se distribuent en trois catégories :

User Outcomes : NPS, CSAT, adoption, time to value, retention
Business Outcomes : MRR, conversions, efficacité opérationnelle
Learning Outcomes : hypothèses validées ou invalidées, insights découverts

Le process de mesure suit cinq étapes : définir les outcomes avant de construire, mesurer à des jalons définis (une semaine, un mois, trois mois), comparer attendu versus réalisé, décider (continuer, itérer ou sunset), et documenter les learnings.

Anti-patterns des artefacts

“On n’a pas le temps de rédiger des SPECs.” Résultat : le PE passe 80 % de son temps à corriger le code généré au lieu de 20 %. Une heure de SPEC bien rédigée économise plusieurs heures de correction. Ce n’est pas une contrainte — c’est un investissement à rendement élevé.

“Notre AGENT-GUIDE fait cent pages.” Conséquence directe d’un Context Budget dépassé : l’agent ignore la plupart des règles. Un guide concis et priorisé est plus efficace qu’une encyclopédie. L’AGENT-GUIDE pour le contexte permanent, la SPEC pour le contexte de tâche. Ne jamais mélanger les deux.

“La SPEC est validée, on ne la touche plus.” Le code évolue, la SPEC reste figée. C’est le spec drift. En cinq itérations, la SPEC est obsolète et l’agent travaille sur une base erronée. Toute modification du comportement d’une fonctionnalité impose une mise à jour immédiate de la SPEC dans la même session. Sans exception.