Que fait introspect ?
Transformez ce qui s'est passé dans vos threads de codage IA en modifications de la façon dont vos agents travaillent pour vous — afin que votre configuration progresse en capital plutôt que de réinitialiser à chaque session.
C'est agnostique vis-à-vis de l'agent. Cela lit vos threads de Claude Code, OpenAI Codex et Cursor, trouve les quelques éléments qui méritent d'être changés et — avec votre approbation — les réécrit dans la configuration de l'agent qui dirige effectivement les sessions futures. Claude Code intègre déjà /insights, qui lit vos 30 derniers jours et vous montre un rapport. C'est la partie lecture, réservée à Claude. Introspect est la partie écriture, pour tous les agents que vous utilisez. Comme l'a bien dit Youssef dans le fil d'où cela vient : corrigez le système une fois pour ne pas avoir à corriger le résultat mille fois.
L'idée centrale qui fait fonctionner cela : les modèles, pas les tactiques
Le piège de « qu'aurais-je pu faire mieux ? » est qu'il fait remonter des tactiques — un meilleur paramètre pour une commande, une approche plus astucieuse pour un bogue. Cela ne s'accumule pas. C'est oublié demain.
Ce qui s'accumule, c'est une habitude que vous répétez : la même correction que vous donnez dans trois threads différents, la même préférence que vous réexprimez chaque semaine, le même mauvais virage que prend l'agent à chaque fois qu'il touche votre configuration de test. La compétence est donc intrinsèquement orientée vers la récurrence :
Un changement candidat mérite sa place uniquement s'il apparaît plus d'une fois, n'est pas déjà écrit quelque part, et aurait plausiblement changé le résultat. Tout le reste est bruit — journalisez-le, n'agissez pas dessus.
C'est aussi la réponse honnête aux deux craintes que les gens ont soulevées dans ce fil :
- « Je crains d'accumuler des mauvaises décisions / que mon workflow devienne stupide. » → Rien n'est écrit sans que vous voyiez le diff exact et l'ayez approuvé. Chaque changement appliqué est journalisé et réversible. En cas de doute, proposez moins de choses.
- « Est-ce que cela se contente de mettre à jour la compétence tous les jours indéfiniment — est-ce que cela converge un jour ? » → Cela devrait converger. Si une règle existe déjà, vous la renforcez ou la fusionnez ; vous n'en ajoutez pas une seconde. Un jour calme produit un ensemble de modifications vide, et c'est un succès, pas un échec.
Le pipeline
Collecter → Extraire → Diff vs. configuration existante → Proposer un jeu de modifications → Approuver → Appliquer + Journaliser
(script) (vous) (vous, lire la config actuelle) (vous, avec preuves) (utilisateur) (vous, réversiblement)
1. Collecter — exécutez le script, ne réanalysez rien manuellement
scripts/collect_threads.py lit le magasin de threads de chaque agent (JSONL de Claude, fichiers rollout de Codex, SQLite de Cursor), filtre sur une fenêtre, masque les secrets, et émet UN résumé commun : par session, il marque l'agent concerné, les invites tapées par l'humain, les outils utilisés, là où les outils ont échoué, et des signaux légers de « friction » (invites qui ressemblent à des corrections, outils appelés plusieurs fois de suite).
python3 scripts/collect_threads.py --days 1 # aujourd'hui, chaque agent installé (auto)
python3 scripts/collect_threads.py --agent all --days 7 # dernière semaine, force les trois
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject # un projet
python3 scripts/collect_threads.py --selftest # vérification de tous les analyseurs
--agent par défaut à auto (détecte quels agents sont installés). Utilisez --format md lorsque vous lirez vous-même ; --format json pour le post-traitement. Le script ne décide jamais rien — il vous donne une matière première propre et normalisée pour que vous dépensiez votre jugement sur ce qui compte, et non sur l'analyse de trois formats de transcription différents.
2. Extraire — lisez le résumé et extrayez trois types d'éléments
Lisez le résumé comme si vous étiez le chef de cabinet de l'utilisateur passant en revue la journée sur tous ses outils. Les préférences de l'utilisateur passent en premier — cette compétence vise principalement à apprendre comment ils aiment travailler, pas à surveiller le comportement de base de l'agent. Séparez :
- Préférences durables (l'essentiel) — l'utilisateur corrige une valeur par défaut ou reformule comment il aime les choses (« non, utilise pnpm », « arrête d'ajouter des commentaires », « crée toujours une branche à partir de développement d'abord », « ne touche pas à l'arborescence de travail »). Une préférence qui apparaît à la fois dans vos threads Claude et Codex est un signal particulièrement fort — elle vous concerne, pas l'outil.
- Lacunes de configuration qui ont fait répéter le travail à l'agent — là où l'agent a redécouvert ou bloqué sur plusieurs sessions parce que quelque chose n'était pas écrit : réapprendre une commande de build, retrouver un fichier qui se trouve toujours au même endroit, manque d'un contexte de projet. La correction consiste à écrire l'élément manquant dans la configuration de l'utilisateur — PAS à ajouter une règle qui réprimande l'agent. Si une répétition est simplement un comportement générique de l'agent sans correctif propre à l'utilisateur (par exemple « lire un fichier avant de le modifier »), ce n'est pas une règle, c'est du bruit ; laissez-le de côté.
- Workflows réutilisables — une opération en plusieurs étapes que l'utilisateur a effectuée plus d'une fois et qui mérite de devenir une compétence ou une commande pour que ce soit une seule étape la prochaine fois.
Pour chaque candidat, notez la preuve : quel agent, quelles sessions, combien de fois, une courte citation. Pas de preuve de récurrence → c'est une tactique, pas un modèle → abandonnez-le.
3. Comparer avec la configuration existante — l'étape anti-gonflement / convergence
Avant de proposer quoi que ce soit, lisez ce qui existe déjà pour le ou les agents concernés, afin de renforcer le système au lieu de le gonfler. references/routing.md contient les emplacements et formats de lecture/écriture exacts pour chaque agent ; la version courte :
| Agent | Configuration existante à lire (et à écrire plus tard) |
|---|---|
| Claude | ~/.claude/CLAUDE.md (global), ./CLAUDE.md, mémoire par projet ~/.claude/projects/<dir>/memory/, ~/.claude/skills/, ~/.claude/commands/ |
| Codex | ~/.codex/AGENTS.md (global), <repo>/AGENTS.md (projet), compétences dans ~/.agents/skills/ |
| Cursor | .cursor/rules/*.mdc (projet), .cursorrules hérité, AGENTS.md |
Pour chaque candidat, demandez : Est-ce déjà couvert ? Si oui → abandonnez-le, ou proposez une petite modification qui affine la règle existante. N'ajoutez jamais une deuxième règle qui dit presque la même chose. Si deux candidats se chevauchent, fusionnez-les. Préférez la modification à l'ajout.
Conseil multi-agent : AGENTS.md est lu par Codex et Cursor, et de nombreuses personnes le lient symboliquement à CLAUDE.md. Si une préférence est véritablement universelle, préférez l'écrire là où chaque agent la verra (un seul AGENTS.md, ou un lien symbolique CLAUDE.md↔AGENTS.md) plutôt que de la dupliquer trois fois. Résolvez toujours les liens symboliques avant d'écrire pour savoir quel fichier vous éditez réellement.
4. Proposer un jeu de modifications — diffs concrets avec preuves, plafonnés
Présentez un jeu de modifications : une liste ordonnée et facile à parcourir où chaque élément a l'agent + le fichier cible, la modification exacte (un diff ou un avant/après clairement marqué), la preuve et une confiance. Utilisez le format dans references/changeset-format.md. Deux règles le maintiennent raisonnable :
- Plafonnez-le. Présentez au maximum ~5 modifications par exécution, la plus haute confiance en premier. Tout le reste va dans une section « backlog » — noté, pas appliqué. Un déluge de modifications, c'est ainsi que les workflows deviennent stupides.
- Classez par récurrence × impact. Une préférence énoncée trois fois qui fera gagner une correction à chaque session bat à chaque fois une astuce ponctuelle intelligente.
Sauvegardez toujours le jeu de modifications vers un rapport daté même si rien n'est appliqué, afin d'avoir un enregistrement pour référence ultérieure (cela répond à la question du fil : « est-ce que vous sauvegardez les sorties quelque part, ou juste lisez et passez ? »). Écrivez-le dans ~/.introspect/reports/YYYY-MM-DD.md.
5. Approuver — la barrière
Affichez le jeu de modifications et laissez l'utilisateur choisir ce qu'il souhaite appliquer : tout, une partie ou rien. Par défaut, proposez-et-approuvez — ne modifiez aucun fichier de configuration d'agent sans un oui explicite. Utilisez AskUserQuestion (sélection multiple) pour leur permettre de choisir des éléments lorsqu'il y en a plusieurs. Si l'utilisateur a explicitement demandé une exécution non supervisée/planifiée, voir « Exécutions non supervisées » ci-dessous.
6. Appliquer + journaliser — réversiblement
Pour chaque élément approuvé, écrivez sur la bonne surface (formats complets dans references/routing.md) :
- Claude — CLAUDE.md : ajoutez sous la bonne section
##ou modifiez la règle sur place ; conservez le style maison (court, impératif, explique pourquoi). - Claude — mémoire : créez/ajoutez un fichier nœud et ajoutez une ligne d'index au
MEMORY.md; respectez les conventionsfeedback_*/project_*/reference_*et les liens croisés[[wikilink]]. - Claude — compétence/commande : créez/modifiez
~/.claude/skills/<name>/SKILL.mdou~/.claude/commands/<name>.md. Si plusieurs sessions ont réécrit le même script d'aide, regroupez-le. - Codex — AGENTS.md : ajoutez à l'intérieur d'un bloc géré (
<!-- introspect:begin --> … <!-- end -->) afin que les ré-exécutions soient idempotentes ; restez compact (Codex tronque AGENTS.md à ~32 Ko). Privilégiez leAGENTS.mdà la racine du projet (l'application Desktop ne charge pas toujours le global de manière fiable). - Cursor — .cursor/rules/*.mdc : écrivez un fichier de règle avec l'en-tête YAML (
alwaysApply: truepour les préférences toujours actives, oudescription:+alwaysApply: false). N'essayez PAS d'écrire les « Mémoires » cloud de Cursor ; utilisez les fichiers de règle. N'écrivez pas le fichierstate.vscdben direct lorsque Cursor est en cours d'exécution.
Ensuite, ajoutez une ligne au registre ~/.introspect/ledger.jsonl — un objet JSON par changement appliqué : {date, agent, target_file, kind, summary, evidence, sessions, undo_hint}. Le registre vous permet (a) de montrer comment la configuration a progressé au fil du temps, et (b) d'annuler un changement plus tard. Avant de modifier un fichier existant, notez son état précédent dans undo_hint (ou conservez un .bak).
Modèle de sécurité (lisez ceci — c'est la raison pour laquelle ceci peut être exécuté quotidiennement sans risque)
- Proposez, n'imposez pas. Barrière d'approbation active par défaut. L'utilisateur voit chaque diff.
- Seuil de récurrence. Ne proposez pas à partir d'une seule occurrence. Habitudes, pas tactiques.
- Convergez, ne brassez pas. Renforcez/fusionnez les règles existantes au lieu d'ajouter des quasi-doublons. Une exécution qui ne change rien est parfaitement acceptable et attendue lors d'un jour calme.
- Plafonnez le rayon d'impact. Maximum ~5 changements par exécution ; le reste dans le backlog.
- Les règles concernent l'utilisateur, pas l'agent. Capturez comment l'utilisateur souhaite travailler. Ne créez pas de règles qui ne font que reformuler une compétence de base de l'agent (comme « lire avant de modifier ») — c'est du gonflement. Un signal « l'agent a bloqué / s'est répété » mérite un changement uniquement si le fait d'écrire un élément de la configuration de l'utilisateur empêcherait la répétition.
- Ne stockez jamais de secrets. Le collecteur masque les formes courantes de clés/jetons, mais restez vigilant : ne copiez jamais une clé API, un mot de passe, une valeur
.envou un jeton dans une règle ou un rapport. Si vous en voyez un, laissez-le de côté et (s'il semble actif) signalez-le à l'utilisateur. - Réversible. Tout ce qui a été appliqué se trouve dans le registre avec une indication pour annulation.
- Bonne surface, bonne portée. Préférences globales pour l'utilisateur → le fichier global pour cet agent. Faits spécifiques au projet → la configuration de ce projet. Ne mettez pas des détails de projet triviaux dans un fichier global.
Déclencheurs — trois façons d'exécuter
- À la demande. « révise mes threads », « exécute introspect », « qu'est-ce que je n'ai pas arrêté de répéter cette semaine dans Claude et Codex », « transforme les corrections d'aujourd'hui en règles ». Fenêtre par défaut : aujourd'hui.
- Quotidien / planifié (natif du harnais). Enregistrez l'exécution via le planificateur natif du harnais — la compétence
scheduleou l'outil de routineCronCreate— pas un cron système, launchd ou une boucle shell. La planification native exécute la routine à l'intérieur du harnais avec les mêmes outils et permissions, et l'utilisateur la gère avec/schedule. Une bonne valeur par défaut est une fois par jour en soirée sur la fenêtre du jour. - Tous les N-sessions / sur friction (optionnel). Certaines personnes (voir buildooor dans le fil source) préfèrent déclencher cela lorsque quelque chose a mal tourné ou environ toutes les ~10 sessions plutôt que sur une horloge. Câblez-le comme un hook
Stopqui compte les invocations et fait un rappel après N. Proposez-le ; n'installez jamais un hook sans approbation.
Exécutions non supervisées
Si invoqué par un calendrier/une routine sans humain présent, n'appliquez pas silencieusement de modifications à la configuration d'un agent. Au lieu de cela : exécutez le pipeline, écrivez le rapport daté avec le jeu de modifications proposé dans ~/.introspect/reports/, et affichez un bref résumé (via la notification de la routine) afin que l'utilisateur puisse approuver lors de sa prochaine session interactive. La seule catégorie sûre pour une auto-application non supervisée est un nouveau nœud de mémoire Claude qui ne duplique rien — et même dans ce cas, journalisez-le. Gardez la progression sous contrôle humain ; c'est le but.
Références
references/routing.md— sources de lecture par agent + surfaces d'écriture + formats disques exacts (CLAUDE.md, mémoire, AGENTS.md, .cursor/rules/*.mdc) et schémas de transcription utilisés par le collecteur.references/changeset-format.md— les modèles de jeu de modifications + rapport + registre.scripts/collect_threads.py— le collecteur multi-agent (exécutez--selftestpour le vérifier).
Répéter la boucle centrale, car c'est l'essence : collectez les threads de chaque agent → trouvez les modèles récurrents (pas les tactiques ponctuelles) → vérifiez qu'ils ne sont pas déjà écrits → proposez un petit jeu de modifications plafonné et étayé → appliquez uniquement ce qui est approuvé à la configuration du bon agent → journalisez-le réversiblement.