Le vrai problème des agents IA : tu ne sais pas décrire ton propre travail

#Un agent installé, puis plus rien

Tu installes Claude Code. Tu configures ton environnement, tu ajoutes deux ou trois MCP, tu te dis que cette fois, tu vas vraiment déléguer ton travail. Trois jours plus tard, l'agent est toujours là, mais toi tu écris encore tout à la main.

Ce n'est pas un bug. Ce n'est pas un problème de modèle. Ce n'est même pas un problème d'infrastructure. C'est le problème le plus coûteux dans l'espace des agents IA aujourd'hui, et il est cognitif : tu n'arrives pas à décrire ton propre travail avec assez de résolution pour qu'un agent fasse quelque chose d'utile.

Cet article explique pourquoi ce problème arrive, pourquoi il est invisible, et quel pattern — SOUL.md — est en train d'émerger pour le résoudre.

#Pourquoi l'installation ne suffit pas

Un agent IA, techniquement, c'est trois choses : un modèle, des outils, et une boucle de décision. Une fois que tu as les trois, tu as 20 % d'un agent. Les 80 % restants, c'est le contexte : qui tu es, ce que tu fais, comment tu juges, ce que tu considères comme un bon résultat.

Sans ce contexte, l'agent fait ce que font tous les LLM sans guidance : il produit la moyenne. Des commits propres mais génériques. Des résumés qui ratent les nuances importantes. Des réponses clients polies mais sans voix. Ce n'est jamais mauvais. Ce n'est jamais à toi.

Le piège : un agent qui produit de la moyenne impressionne en démo (parce que la moyenne d'un LLM moderne est déjà bonne) mais échoue en production (parce que ton travail n'est pas moyen — sinon personne ne te paierait pour le faire).

#Le problème d'élicitation

En recherche utilisateur, on appelle ça un problème d'élicitation : comment faire exprimer à quelqu'un un savoir qu'il utilise tous les jours sans y penser ?

La réponse naïve — "dis à l'agent ce que tu veux" — ne marche pas, pour trois raisons.

Première raison : la malédiction de la connaissance. Plus tu es expert dans ton domaine, moins tu es capable d'expliquer ce que tu fais. Tes décisions sont devenues des réflexes. Demande à un développeur senior pourquoi il a refusé une PR : il dira "ça sentait pas bon". C'est vrai, c'est juste, et c'est inutilisable par un agent.

Deuxième raison : la page blanche. Quand tu ouvres un fichier CLAUDE.md vide et qu'on te demande "décris ton style", ton cerveau produit des généralités : "clair", "concis", "pragmatique". Des mots qui ne contraignent rien. Un agent peut être tout ça en produisant du contenu qui ne te ressemble pas.

Troisième raison : tu ne connais pas tes propres contradictions. Un bon contexte contient tes règles et tes exceptions. Tu préfères les phrases courtes, sauf quand tu expliques un concept subtil. Tu n'aimes pas les emojis, sauf en fin de message à un ami. Ces contradictions te définissent, mais tu ne les vois pas parce que tu les vis.

#SOUL.md : donner une identité persistante à l'agent

Le pattern qui émerge s'appelle SOUL.md. L'idée : au lieu d'un fichier de config qui décrit des règles techniques (comme CLAUDE.md), tu écris un document qui décrit qui tu es et que l'agent charge à chaque session comme contexte d'identité.

Un SOUL.md bien fait contient typiquement :

Section	Contenu	Exemple de granularité
Identité	Rôle, contexte professionnel, domaine	Dev junior React, apprend Go depuis 3 mois
Opinions	Positions tranchées avec raisonnement	Préfère les tests d'intégration aux unit tests car les mocks cachent les bugs de migration
Style	Voix, syntaxe, tics d'écriture	Phrases courtes, jamais d'emojis sauf en contexte ami, tutoiement systématique
Influences	Références nommées (auteurs, projets)	Suit DHH sur le Rails way, rejette l'architecture hexagonale pour les petits projets
Contradictions	Règles et exceptions explicites	Anti-abstractions sauf quand le même pattern apparaît 3 fois

Certaines implémentations séparent le fichier en trois :

SOUL.md : l'identité et les opinions
STYLE.md : la voix et les patterns d'écriture
SKILL.md : les modes opératoires concrets (comment tu écris un tweet, un commit, une PR)

Cette décomposition n'est pas obligatoire. Ce qui compte, c'est la granularité : un agent n'a pas besoin que tu sois "clair", il a besoin de savoir que tu préfères "expliquer avant d'utiliser un terme technique" et que tu utilises "en pratique" plutôt que "concrètement".

#Le paradoxe : pour faire ton SOUL.md, tu as besoin d'un agent

Voilà le problème méta. Un SOUL.md devant une page blanche donne les mêmes généralités qu'un CLAUDE.md devant une page blanche. Tu écris "style direct", tu fermes le fichier, et l'agent continue de produire de la moyenne.

La solution qui émerge : laisser un agent t'interviewer pour rédiger ton SOUL.md. Pas un questionnaire générique, mais un dialogue long (30 à 60 minutes) où l'agent :

Te pose des questions ouvertes sur ton travail récent
Te confronte à des cas concrets ("qu'aurais-tu fait dans cette situation ?")
Te fait expliquer tes refus et tes désaccords (les contradictions apparaissent là)
Génère un brouillon de SOUL.md que tu corriges ligne par ligne

L'avantage : l'agent n'a pas la malédiction de la connaissance. Il peut te demander pourquoi tu as refusé la PR — et si ta réponse est "ça sentait pas bon", il peut enchaîner : "qu'est-ce qui sentait pas bon spécifiquement ?" Les questions de suivi font sortir le savoir implicite.

Tu peux amorcer le processus en donnant à l'agent tes artefacts récents : commits de la semaine, derniers messages Slack pros, PRs que tu as reviewées. Il va extraire des patterns que tu ne verrais pas toi-même.

#Mise en pratique : un premier SOUL.md en une session

Voici une recette minimale pour tenter l'exercice sans outil externe, juste avec Claude.

#Étape 1 — Collecter de la matière

Sors de la page blanche. Rassemble dans un dossier :

Tes 20 derniers commits avec leurs messages
2 ou 3 PRs complètes (description + review)
Un ou deux documents que tu as écrits récemment (RFC, postmortem, README)

Ce matériel factuel empêche l'agent de te poser des questions génériques.

#Étape 2 — Lancer l'entretien

Donne à Claude un prompt du style :

Je veux construire un fichier SOUL.md pour toi. Objectif : capturer
mon identité professionnelle avec assez de granularité pour que tu
puisses écrire dans mon style et juger comme je jugerais.

Voici mes artefacts récents : [colle les]

Interviewe-moi. Commence par des questions ouvertes, puis creuse
sur les cas concrets. Identifie mes contradictions. Ne propose un
brouillon qu'après au moins 15 échanges.

#Étape 3 — Laisser l'agent creuser

Résiste à la tentation de répondre vite. Les bonnes réponses sont longues, nuancées, et contiennent des exemples. Quand l'agent demande "qu'est-ce que tu n'aimes pas dans ce commit ?", ne réponds pas "le style". Réponds "le verbe 'update' qui ne dit rien ; j'aurais préféré 'replace mock with real DB' parce que ça nomme l'action".

#Étape 4 — Réviser le brouillon

L'agent produit un SOUL.md de 200 à 400 lignes. Tu le lis en entier. Tu biffes tout ce qui te ressemble à moitié. Tu précises ce qui est trop vague. Tu ajoutes les exceptions qu'il a manquées.

Un bon SOUL.md ne se termine pas en une session. Il se raffine sur plusieurs semaines, à mesure que tu remarques l'agent faire des erreurs que le fichier aurait dû prévenir.

#Étape 5 — Charger le fichier

Place le SOUL.md à un endroit que l'agent charge automatiquement. Pour Claude Code, tu peux le référencer depuis ton CLAUDE.md :

## Mon identité
Lis `SOUL.md` avant toute tâche créative (écriture, design, review)
pour comprendre mes préférences, mes opinions tranchées et ma voix.

#Le récapitulatif

Le vrai problème des agents IA n'est pas leur puissance, leur prix ou leur sécurité. C'est que la plupart des utilisateurs ne peuvent pas se décrire avec la résolution nécessaire pour qu'un agent soit utile. Les conséquences :

Un agent sans contexte identitaire produit la moyenne, pas ton travail
La page blanche empêche l'auto-description parce que les experts ne voient plus leurs propres règles
Le pattern SOUL.md propose un document d'identité persistant chargé à chaque session
Pour remplir un bon SOUL.md, il faut se faire interviewer par un agent, en partant de matériaux concrets

La leçon plus large : les prochaines années d'adoption des agents ne seront pas gagnées par les meilleurs modèles. Elles seront gagnées par les gens qui prennent le temps d'écrire leur contexte — leur identité, leurs opinions, leurs contradictions — avec assez de précision pour qu'un agent puisse vraiment les représenter.