Les artefacts permanents et “à la demande” du projet

Un artefact de projet, c’est ce qui survit à une tâche : la doctrine chargée à chaque session, la règle, le glossaire, l’ADR. À distinguer des artefacts de tâche (traités au chapitre 5.1), ils se rangent en deux familles :

Six familles couvrent l’essentiel : doctrine, règle, sémantique métier, décision d’architecture, cartographie, documentation de référence.

Quel que soit le type, un artefact doit :

Par convention dans ce chapitre, chaque artefact est écrit en markdown versionné, avec un front-matter qui porte au minimum un champ description.

Doctrine (prescriptif)

La doctrine est le contrat permanent : CLAUDE.md / AGENT.md, chargé à chaque session. Elle pose les guardrails, pas une base de connaissance. Sa raison d’être recouvre celle du chapitre 4.2 : cesser de re-prompter, aligner humains et agents, rendre l’agent prévisible.

Exemple

// `CLAUDE.md` racine d'un backend e-commerce  

Go 1.22, monorepo, DDD avec bounded contexts dans domain/.  

Commandes : make test, make build, make lint.  

Règles non négociables : pas de panic en prod, erreurs wrappées avec `fmt.Errorf("...: %w", err)`.  

Voir domain/CLAUDE.md pour les patterns DDD, infrastructure/http/CLAUDE.md pour les endpoints.

Règle (prescriptif)

Là où la doctrine est toujours chargée, la règle est conditionnelle. .claude/rules, coding standard, pattern d’implémentation, CLAUDE.md dans des sous-répertoires : autant de conventions ciblées que l’agent ne lit que lorsqu’un fichier concerné entre dans le contexte.

Exemple

// `domain/order/CLAUDE.md`
---
when_to_use: éditer un agrégat dans domain/order/  
---

Un agrégat se met à jour via une méthode qui retourne un nouvel état, jamais par mutation directe.  

✓ o2 := o.Cancel(now)
✗ o.Status = Cancelled  

Référence : domain/order/order.go:Cancel

Modèle du domaine & Sémantique métier (descriptif)

UBIQUITOUS_LANGUAGE.md ou glossaire : le vocabulaire métier partagé qui fixe le sens des termes du domaine. Sans cette référence, l’agent devine, et il invente des règles plausibles mais fausses. Aligne humains et agents sur un même langage (vocabulaire DDD : bounded context, agrégat, value object).

Exemple

// `domain/order/UBIQUITOUS_LANGUAGE.md` 

- Order : commande passée par un Customer, agrégat racine.
- OrderLine : value object, immutable, prix figé à la création.
- Customer : référencé par ID, jamais embarqué dans l'Order.
- Synonymes à proscrire : panier → utiliser Cart (bounded context distinct).

Le plus important dans nos logiciels sont les concepts qui sont manipulés et exposés à l’utilisateur (Order, Stock, Location, Product, etc,).

Domain Concept

Tout modèle de domaine doit être exhaustif sur trois dimensions pour être complet et implémentable sans informations supplémentaires :

Model - Structure, behavior and interactions

Les concepts issus du Domain-Driven Design sont très efficaces pour décrire les concepts qui seront manipulés par notre logiciel en dehors de toute considération technologique. Ci-après un résumé de ces concepts avec lesquels nous pouvons structurer notre domaine (le métamodèle DDD).

Concepts pour décrire un modèle du domaine, le méta-modèle DDD

Ces Skills de design du domaine peuvent être utile pour construire ou extraire un modèle du domaine et ensuite alimenter le contexte du projet (⚠️ Disclaimer : nous sommes à l’origine de ces skills, tout feedback quel qu’il soit est donc le bienvenu et nous sera très précieux 🙂).

Design du système : quelle décomposition ?

Avec les agents IA, le développeur devient Designer, il doit décrire la structure et le découpage de sa solution. Il peut également demander des suggestions de software design à l’agent.

Demander à l’agent de proposer une décomposition : L’agent est très bon pour décomposer un problème si on le lui demande. Exemple de prompt : « Décompose ce problème en composants autonomes, propose leur interface (API), leurs responsabilités et interactions entre eux et les tâches nécessaires pour les implémenter. »

Un composant logiciel peut être décrit de manière minimale avec :

Une manière très efficace de bien séparer les responsabilités dans notre logiciel et de conserver notre domaine agnostique des considérations technologiques est de dériver le code applicatif (celui qui nous permet d’interagir avec le logiciel : UI, API, CLI, etc.) et le code d’infrastructure (DB, Messaging, autres systèmes invoqués à travers des SPI) depuis le domaine. Chaque concept doit être conçu et décrit de manière suffisante (éventuellement avec l’aide de l’agent lui-même) afin de laisser ensuite l’agent en faire son implémentation. Cette approche se marie très bien avec la description du comportement attendu avec les approches BDD/ATDD. Le style d’architecture “Hexagonale” et ses variantes nous semble donc le plus efficace dans la séparation correcte des responsabilités techniques d’un système logiciel type “backend pour une application de gestion” : code application, code du domaine et code d’infrastructure.

Décision d’architecture (descriptif)

L’ADR consigne une décision structurante, son contexte, ses alternatives écartées et ses conséquences. Une décision non tracée se re-débat à chaque session, un agent ou un humain la remet en cause faute d’en connaître le pourquoi. L’ADR fige le raisonnement, pas seulement le choix.

Exemple

// `adr/0007-event-sourcing-order.md`  

Date : 2026-03-15  
Status : accepté  
Contexte : besoin de tracer chaque modification d'une commande pour audit légal (RGPD, finance).  
Décision : le contexte Order est event-sourced, snapshot tous les 50 events.
Alternatives écartées : audit log relationnel (perte de causalité), CDC (trop d'infra).
Conséquences : reads via projections, complexité de migration accrue.

Cartographie (descriptif)

La carte du projet : où vivent les choses, comment les modules s’articulent, par où entrer. Elle évite que l’agent explore à l’aveugle ou se perde dans l’arborescence. On l’oriente, on ne déverse pas tout le code.

Exemple

// arborescence annotée dans `CLAUDE.md`

domain/         # logique métier pure, un dossier par bounded context
  order/        # commandes (event-sourced)
  cart/         # panier
  catalog/      # produits
infrastructure/
  http/         # endpoints REST — point d'entrée API
  db/           # repos Postgres
  eventstore/   # event store Order
cmd/            # binaires

# Ajouter un invariant métier → domain/<context>/
# Ajouter un endpoint      → infrastructure/http/

Documentation de référence (descriptif)

Un pointeur vers une base de connaissance externe que l’agent ne peut pas déduire du repo : libs critiques, API, schémas, formats. Sur une dépendance structurante, sans ancrage, l’agent prend des fausses hypothèses. La doc de référence le ramène à la réalité de l’outil, à l’endroit où la connaissance est maintenue.

Format de référence : llms.txt est un fichier texte standardisé qu’une lib publie à sa racine pour exposer une vue curée de sa doc, lisible par un agent.

Exemple

// `docs/pgx.md`

when_to_use: requêter Postgres dans infrastructure/db/

Lib : jackc/pgx v5.
llms.txt : https://pkg.go.dev/github.com/jackc/pgx/v5
Convention projet : toujours passer un context.Context explicite à pool.QueryRow.
Piège : pgx.ErrNoRows doit être wrappé en domain.ErrNotFound dans le repo, jamais propagé.

Ces six familles couvrent le contexte qui survit aux sessions. Le chapitre suivant traite l’autre moitié du métier : les artefacts de travail, ceux qui ne vivent que le temps d’un travail à mener.