Les agents IA maîtrisent le code mais ignorent l'essence des produits

Les limites des agents IA en matière de compréhension produit

Les agents d'intelligence artificielle spécialisés dans le codage sont capables de lire et d'analyser le code source des applications. Cependant, leur capacité à produire des résultats véritablement pertinents est souvent limitée par leur manque de compréhension du contexte de design du produit. Ce contexte inclut des éléments essentiels tels que le comportement du produit, les modèles d'interaction spécifiques qu'il adopte ou rejette, et les caractéristiques qui définissent son identité unique. Pour pallier ce manque, une compétence appelée Claude Code a été développée. Elle vise à enrichir les capacités des agents IA en leur fournissant un cadre de référence plus complet et pertinent.

Comprendre le produit au-delà du code

Pour qu'un agent IA puisse véritablement comprendre un produit, il doit intégrer sept types de connaissances distinctes. Ces connaissances vont bien au-delà de ce qui est généralement consigné dans un simple fichier README. Elles comprennent :

• Architecture : Cela inclut les services utilisés, les bases de données, les méthodes d'authentification, les flux de données, ainsi que les contraintes strictes qui régissent le système.

• Fonctionnalité : Il s'agit des flux de travail de bout en bout, du modèle d'entité de domaine, et des surfaces du produit.

• Conventions de la stack technique : Cela couvre des éléments tels que l'utilisation de yarn ou pnpm, la structure du monorepo, les vérifications pré-completion, et les règles d'importation.

• Voix de marque : Les axes de ton, le vocabulaire des appels à l'action (CTA), les modèles de texte et les anti-modèles font partie de cette catégorie.

• Identité visuelle : Inclut les polices, les poids, les familles de rayons, les teintes d'ombre, et les règles d'utilisation des couleurs.

• Principes d'interaction : Ce sont les positions UX spécifiques au produit que les agents génériques pourraient manquer.

• Positionnement : Cela décrit ce que le produit est, ce qu'il n'est pas, ses différenciateurs, et les concurrents dont il se distingue.

Ensemble, ces éléments forment le contexte de design, une frontière floue entre design et ingénierie que l'agent doit comprendre pour être efficace.

Les limites d'un README traditionnel

Un fichier README sert généralement de carte du système, mais il ne peut pas capturer le caractère unique du produit. Bien qu'il soit possible de décrire l'architecture ou de lister les entités dans un README, il est difficile d'y inclure des détails plus subtils comme les préférences de tokens, les exceptions spécifiques aux points de rupture, ou les règles strictes accumulées au fil du temps. Ces éléments sont cruciaux pour un agent IA qui doit comprendre le produit avant de pouvoir contribuer efficacement à son développement. Des systèmes de design matures, tels que Shopify Polaris ou le système de design d'Atlassian, offrent des exemples de documentation qui vont au-delà des simples spécifications techniques.

Développement de la compétence Claude Code

Pour combler ce fossé, le contexte de design a été transformé en une compétence Claude Code. Ce répertoire se charge automatiquement lorsque vous travaillez sur le produit et contient plusieurs fichiers clés :

<product>-context/
├── SKILL.md                      # routeur
├── design.md                     # UI / UX / marque / visuel / philosophie
├── pointers.md                   # index des documents référencés
├── quickref/
│   ├── component-map.md          # index Figma → code
│   ├── tokens.md                 # cheatsheet couleur / type / rayon / ombre
│   └── commands.md               # rituels de vérification pré-completion
└── references/
    ├── overview.md               # structure du monorepo, carte de l'application, packages partagés
    ├── functionality.md          # flux, entités, surfaces
    ├── system-analysis.md        # carte des services, authentification, flux de données, contraintes
    ├── typescript.md             # conventions de stack
    ├── python.md                 # conventions backend
    ├── figma-component-mapping.md
    └── frontend/
        ├── ui-package.md
        ├── styles-package.md
        └── styles.md

Le fichier SKILL.md agit comme un routeur, déterminant quel fichier doit être chargé pour une tâche donnée. Par exemple, pour écrire un texte UI, il renvoie à design.md section 2 sur la voix de marque. Pour un brainstorming de fonctionnalité, il oriente vers functionality.md et design.md. Ce routeur assure une utilisation disciplinée du contexte.

Processus de création

La création de cette compétence ne s'est pas faite en une seule fois. L'ordre de développement a été crucial.

Première étape : architecture et fonctionnalité

Ces deux aspects peuvent être principalement dérivés du code existant. Un sous-agent a été dirigé vers le code pour rédiger un aperçu de l'architecture, une carte des services, le modèle d'authentification, et les flux de données. Un autre sous-agent a été utilisé pour la fonctionnalité, se concentrant sur les flux de bout en bout, le modèle d'entité, et les surfaces. Chaque tâche a pris environ deux heures, suivies d'une légère édition.

Deuxième étape : conventions de la stack technique

Les fichiers typescript.md, python.md, et d'autres documents spécifiques au frontend ont été créés. Ceux-ci sont également principalement dérivables du code : quel gestionnaire de paquets est utilisé, quel linter est en place, et quelles sont les règles à ne jamais enfreindre. L'agent a rédigé un brouillon basé sur les configurations existantes, qui a ensuite été édité pour inclure des règles non visibles mais essentielles.

Troisième étape : design.md, le défi majeur

Cette partie ne peut pas être générée automatiquement par un agent. Bien que l'agent puisse lister les tokens, il ne peut pas comprendre des éléments comme le fait que le CTA principal doit être accentué. Le fichier design.md a été écrit en couches :

• Tokens : Inclut les couleurs, les poids typographiques, les espacements, les rayons, et les ombres.

• Modèles UX : Conventions d'état vide, avertissements-conseils, etc., qui existent dans le code mais ne sont pas évidentes sans étiquetage.

• Voix de marque : Axes de ton, vocabulaire des CTA, et anti-modèles. Chaque règle est ancrée dans une chaîne réelle du code.

• Esthétique : Englobe les principes de composition, la philosophie des couleurs, et les détails signature.

• Anti-modèles explicites : Descriptions de ce que le produit n'est pas, avec un auto-test de validation.

Les tokens sont lisibles par l'agent, mais la philosophie de composition doit être apprise.

Quatrième étape : le routeur

Le fichier SKILL.md est concis, avec moins de 150 lignes. Il utilise un frontmatter YAML avec des phrases déclencheuses pour guider l'agent vers les fichiers appropriés en fonction de la tâche à accomplir.