Configurer Claude Code
et Codex

La configuration n'est pas un ensemble de fichiers posés dans ~/.claude. C'est un pipeline de build. Les sources d'écriture vivent dans ~/.config/ai-agents/src/ et aucun client ne les lit. Un script de rendu en produit une release immuable, et ce sont les artefacts de cette release qui sont installés dans le home.

Cette indirection donne aux 2 agents une configuration cohérente par construction. Éditer ~/.claude/CLAUDE.md à la main marcherait, mais laisserait ~/.codex/AGENTS.md en arrière, et produirait 2 agents au jugement différent sur le même code.

Agrandir ↗

L'erreur la plus fréquente est de mettre dans un fichier d'instructions une règle qui doit être garantie. Le modèle la lira, la respectera souvent, et l'oubliera parfois. Si l'oubli coûte cher, c'est un hook, pas une phrase.

La 2e erreur est d'accumuler dans le fichier d'instructions. Il reste dans le contexte de chaque session, sur chaque projet. Chaque ligne se paie en contexte sur toute la durée d'usage de la machine. Une procédure longue réservée à une tâche précise appartient à une skill : seule sa description pèse tant que le corps n'est pas chargé.

Agrandir ↗

scripts/render.mjs lit src/, produit un répertoire sous releases/, et le nomme d'après le SHA-256 de son manifeste normalisé. 2 rendus du même contenu produisent le même identifiant ; un octet de différence produit un répertoire différent. Le pointeur current est un lien symbolique vers la release active.

Le champ sourceCommit n'est que la référence Git de base. Le manifeste lie séparément le contenu réel par sourceProvenance.contentDigest et chaque octet rendu par manifest.artifacts. Cette distinction compte, parce qu'un rendu produit depuis un arbre de travail modifié reste tracé, alors qu'un simple hash de commit mentirait.

{
  "schemaVersion": 1,
  "releaseId": "f4528d92…e657847",
  "sourceCommit": "27cb7932…866d0e6",
  "sourceProvenance": {
    "commitRole": "base-reference-not-content-proof",
    "contentBinding": "manifest.sources",
    "contentDigest": "f5e7ea7a…8c5a0067",
    "releaseBinding": "manifest.artifacts"
  },
  "requirements": { "node": ">=22" },
  "artifacts": {
    "claude/CLAUDE.md": { "hash": "8f9790e7…", "mode": 420, "type": "file" },
    "codex/AGENTS.md":  { "hash": "…", "mode": 420, "type": "file" }
  }
}

L'installation utilise un verrou exclusif, compare les préimages exactes des fichiers vivants, écrit atomiquement cible par cible, et journalise durablement. Une préimage périmée invalide l'approbation : si un fichier a changé entre la validation et l'écriture, la transaction s'arrête. Le rollback ne restaure qu'une cible qui correspond encore à sa postimage enregistrée.

# quelle release est active
readlink ~/.config/ai-agents/current

# dérive entre la copie Claude vivante et la projection
node ~/.config/ai-agents/scripts/check.mjs --home

# état des deux racines de skills
node ~/.config/ai-agents/scripts/inventory.mjs

Les 2 hôtes ne lisent pas les skills au même endroit. Claude Code lit ~/.claude/skills, Codex lit ~/.agents/skills puis ~/.codex/skills. La release fournit une projection par hôte, mais elles ne sont pas installées de la même façon.

Agrandir ↗

Chacun des 2 bugs de Claude Code a sa source : issue 38051 pour la racine en lien symbolique ignorée, issue 50052 pour la suppression du lien à l'auto-update. La copie réelle coûte une duplication sur disque et un risque de dérive ; c'est le prix d'une racine qui survit à une mise à jour.

Claude Code rend les instructions globales à plat. Le fichier rendu ne contient aucun import @ mutable, parce qu'un import cassé ferait disparaître silencieusement tout le bloc. Le pipeline rend donc un fichier unique, et la référence éditoriale longue reste un fichier séparé chargé seulement quand une tâche de rédaction longue le justifie.

À côté du fichier principal, ~/.claude/rules/ porte 5 règles thématiques également chargées en contexte.

Une skill est un répertoire contenant un SKILL.md avec un frontmatter YAML. Le champ description est l'information principale que le modèle voit avant de décider de charger la skill, avec son nom. Une description vague produit une skill qui ne se déclenche jamais, ou qui se déclenche tout le temps.

---
name: ma-skill
description: Ce que la skill fait. Use when <situations de déclenchement>. Do not use for <ce qui ressemble mais n'en relève pas>.
---

Le point décisif est d'écrire les 2 bornes, quand l'utiliser et ce qui lui ressemble sans en relever. Sans la borne négative, 2 skills voisines se disputent les mêmes prompts et le modèle en choisit une au hasard.

Le poste porte 95 skills globales, 35 agents et environ 48 commandes. À cette échelle, 2 mécanismes évitent la saturation : le champ skillOverrides de settings.json, qui porte 80 entrées coupant (off) ou restreignant (user-invocable-only) des skills, et le routeur BM25 décrit en partie III.

Un hook reçoit un JSON sur son entrée standard et décide. Sur PreToolUse, un code de sortie 2 bloque l'appel et renvoie le message au modèle pour qu'il corrige, sans faire échouer la session. L'effet de ce code dépend de l'événement : sur UserPromptSubmit il refuse le prompt, et sur PostToolUse l'outil a déjà tourné. Ce mode est préférable, parce qu'un hook qui casse une session finit désactivé, et ne vaut alors plus rien.

"PreToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "~/.config/ai-agents/releases/d16f4a6c…866bfc84/hooks/claude-adapter.sh",
        "timeout": 5
      }
    ]
  }
],
"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "env SKILL_ROUTER_HOST=claude SKILL_ROUTER_DATA_DIR=\"~/.local/state/ai-agents/skill-router/claude\" node \"~/.config/ai-agents/releases/d16f4a6c…866bfc84/hooks/skill-router/bm25-suggest.js\"",
        "timeout": 5
      }
    ]
  }
]

Les 3 mécanismes ne se recouvrent pas. deny refuse catégoriquement un motif de commande ou de chemin. ask interrompt pour demander confirmation. La sandbox est une isolation au niveau du système d'exploitation, appliquée à chaque commande shell prise séparément.

Agrandir ↗

La liste excludedCommands sort des commandes de l'isolation, elle mérite donc une lecture attentive. C'est nécessaire pour gh, docker ou les gestionnaires de paquets, mais chaque entrée est une brèche assumée. Elle doit rester justifiable ligne par ligne.

"permissions": {
  "defaultMode": "auto",
  "deny": [
    "Bash(git push --force *)",
    "Bash(git reset --hard *)",
    "Bash(gh repo delete *)",
    "Read(**/.env)",
    "Read(**/*.pem)",
    "Read(**/.ssh/**)"
  ],
  "ask": [
    "Bash(git push *)",
    "Bash(gh pr merge *)",
    "Bash(npm publish *)",
    "Bash(vercel *--prod*)"
  ]
},
"sandbox": {
  "enabled": true,
  "autoAllowBashIfSandboxed": true,
  "allowUnsandboxedCommands": false,
  "network":     { "allowedDomains": ["<44 domaines>"] },
  "filesystem":  { "allowWrite": ["<22 répertoires>"], "allowRead": ["<2 entrées>"] },
  "credentials": { "files": ["<5 chemins>"], "envVars": ["<13 variables>"] },
  "excludedCommands": ["gh *", "glab *", "docker *", "<92 autres entrées>"]
}

Un agent qui dispose de 95 skills garderait en contexte autant de descriptions, sans compter les corps. Il faut décider, avant chaque tour, lesquelles méritent d'être signalées.

BM25 a été retenu. Le compromis assumé est que le routeur compare des mots, pas des sens. En échange, il est débuggable, un score étant une somme lisible de contributions par terme.

BM25, ou Okapi BM25, est le classement par défaut de Lucene, Elasticsearch et SQLite FTS5. Pour chaque terme q de la requête présent dans le document D, il calcule une contribution, et le score total est la somme sur tous les termes de la requête.

score(q, D) = IDF(q) × ( f(q,D) × (k1 + 1) )
                       ÷ ( f(q,D) + k1 × (1 - b + b × |D|/avgdl) )

IDF(q) = log( 1 + (N - n + 0.5) / (n + 0.5) )

f(q,D)  fréquence du terme q dans le document D
|D|     longueur du document
avgdl   longueur moyenne des documents du corpus
N       nombre total de documents
n       nombre de documents contenant q

Constantes retenues : k1 = 1.2, b = 0.3

Agrandir ↗

`k1 = 1.2`, la saturation. C'est ce qui empêche la linéarité. Un document contenant 10 fois le mot sitemap n'est pas 10 fois plus pertinent qu'un document le contenant une fois. La fonction monte vite, puis plafonne.

`b = 0.3`, la normalisation par longueur. Sans elle, un document long gagne mécaniquement, parce qu'il contient plus de termes, donc plus de chances de correspondre. Le facteur |D|/avgdl pénalise les documents plus longs que la moyenne. b = 0 désactive la normalisation, b = 1 l'applique à fond.

La valeur 0.3 est basse, volontairement. Le corpus est fait de phrases de 5 à 15 mots, où la longueur ne porte presque pas d'information. Un b proche de 1 pénaliserait injustement une formulation détaillée face à un mot-clé isolé.

const K1 = 1.2;
const B = 0.3;

function computeIdf(docs) {
  const N = docs.length;
  const df = new Map();
  for (const doc of docs) {
    for (const t of new Set(doc.tokens)) df.set(t, (df.get(t) || 0) + 1);
  }
  const idf = {};
  for (const [t, n] of df) idf[t] = Math.log(1 + (N - n + 0.5) / (n + 0.5));
  return idf;
}

function scoreDoc(queryTokens, doc, idf, avgdl) {
  const tf = termFreq(doc.tokens);
  const dl = doc.tokens.length || 1;
  let score = 0;
  for (const q of queryTokens) {
    const f = tf.get(q);
    if (!f) continue;
    const num = f * (K1 + 1);
    const den = f + K1 * (1 - B + B * (dl / avgdl));
    score += (idf[q] || 0) * (num / den);
  }
  return score;
}

Un score brut ne dit pas s'il faut suggérer. C'est là que se joue la qualité du routeur, pas dans la formule.

Agrandir ↗

1. Maximum par cible, jamais la somme

   Le score d'une skill est celui de son meilleur scénario unique. Sommer donnerait mécaniquement l'avantage à une skill de 40 scénarios sur une skill de 10, indépendamment de la pertinence.

2. Seuil tau calibré par cible

   Chaque skill obtient son propre seuil, calculé à la construction de l'index. Une cible portant moins de 8 scénarios positifs ou moins de 2 négatifs est exclue de la calibration, parce qu'en dessous le seuil serait ajusté sur du bruit. Les positifs sont notés contre les autres positifs de leur cible, en s'excluant eux-mêmes, sinon le score est parfait par construction.

3. Le seuil se calibre sur les négatifs déclarés de la skill

   La calibration du seuil ne regarde que les scénarios de la skill : ses positifs, notés contre ses autres positifs, et ses négatifs déclarés. La comparaison entre skills voisines arrive après, à l'évaluation croisée.

4. Balayage de tous les seuils candidats

   Le seuil retenu est celui qui maximise F-beta sur l'ensemble des scores observés, en testant chaque point médian entre 2 scores consécutifs. La skill passe en statut ok si le F1 mesuré à ce seuil atteint 0,60, et reste en conflict sinon.

5. L'évaluation croisée décide de l'éligibilité

   Une skill calibrée en ok n'est pas encore suggérable. Le constructeur rejoue toutes les skills ensemble, garde celles dont le F1 croisé atteint 0,55, puis retire la moins bonne tant que le F1 global reste sous 0,70. Seules les skills qui survivent à cette passe portent eligible.

L'optimisation est asymétrique. Le F-beta utilisé pose beta = 2, ce qui fait peser le rappel 4 fois la précision. Une suggestion manquée est une skill qui ne sert pas. Une suggestion de trop est une ligne que le modèle ignore. La politique retenue accepte donc des faux positifs pour réduire les suggestions manquées.

# résumé de l'index, sans rien écrire
SKILL_ROUTER_HOST=claude node \
  ~/.config/ai-agents/current/hooks/skill-router/routing/build-index.js --dry-run

# reconstruire l'index
SKILL_ROUTER_HOST=claude node \
  ~/.config/ai-agents/current/hooks/skill-router/routing/build-index.js

# tester une suggestion de bout en bout
echo '{"prompt":"prépare un message pour l équipe"}' \
  | SKILL_ROUTER_HOST=claude node \
      ~/.config/ai-agents/current/hooks/skill-router/bm25-suggest.js

function scoreSkills(queryTokens, scenarios, index) {
  const bySkill = new Map();
  const negativeBySkill = new Map();
  for (const s of scenarios) {
    const raw = scoreDoc(queryTokens, s, index.idf, index.avgdl);
    if (s.polarity === 'neg') {
      if (raw > (negativeBySkill.get(s.skill) || 0)) negativeBySkill.set(s.skill, raw);
      continue;
    }
    if (s.polarity !== 'pos') continue;
    if (raw > (bySkill.get(s.skill) || 0)) bySkill.set(s.skill, raw);
  }
  // Un score par skill : son meilleur scénario, jamais la somme.
  return [...bySkill]
    .map(([skill, score]) => ({ skill, score, negativeScore: negativeBySkill.get(skill) || 0 }))
    .sort((a, b) => b.score - a.score);
}

function filterEligible(scored, thresholds, activeSkills) {
  return scored.flatMap((candidate) => {
    const threshold = thresholds[candidate.skill];
    const active = activeSkills[candidate.skill];
    if (!threshold || threshold.status !== 'ok' || threshold.eligible !== true || !Number.isFinite(threshold.tau)) return [];
    if (Number.isFinite(candidate.negativeScore) && candidate.negativeScore >= candidate.score) return [];
    if (candidate.score < threshold.tau || !active || !active.skillMd) return [];
    return [{ ...candidate, skillMd: active.skillMd }];
  });
}

Transmettre cette configuration telle quelle n'aurait pas de sens, parce qu'elle contient des chemins de projets, des serveurs MCP avec leurs clés, et 35 agents dont la plupart ne servent qu'à un usage précis. Le squelette reprend la structure et un routeur BM25 autonome, avec 2 skills d'exemple pour que la mécanique soit vérifiable dès l'installation.

agent-config-starter/
├── README.md                     les 4 couches, quand utiliser laquelle
├── install.sh                    simulation par défaut, --apply pour écrire
├── docs/bm25.md                  l'algorithme complet
├── claude/CLAUDE.md              instructions globales génériques
├── claude/settings.json          permissions + hooks
├── codex/AGENTS.md               miroir
├── codex/config.toml.example     commenté, sans secrets
├── hooks/anti-ai-markers.sh      hook PreToolUse, exit 2 = corrige-toi
├── hooks/skill-router/           routeur BM25 autonome, 4 fichiers
└── skills/<nom>/                 skills d'exemple avec corpus

Son script d'installation fonctionne en simulation par défaut et n'écrit qu'avec --apply. Il sauvegarde en .bak.<horodatage> avant tout écrasement, et ne fusionne jamais un settings.json existant. Il dépose un fichier .new à côté et laisse la fusion à la main. Fusionner automatiquement du JSON de configuration écrase un champ existant ou tranche mal un conflit, sans le dire.

Agrandir ↗

Ce comportement est cohérent avec la conception, où l'activation des hooks est une transaction séparée, distincte de l'installation des instructions et des skills. Elle demande une approbation explicite liée à un condensat. La conséquence pratique est qu'il faut rejouer cette transaction après toute modification de hook, et que rien ne le rappelle.

Les deux couvrent des objets différents et ne sont donc pas strictement redondants. La question à trancher est de savoir si le routage des agents et des commandes mérite encore un moteur séparé, ou si les 2 corpus peuvent fusionner dans le routeur host-aware.

Le routeur issu de la release ne porte pas ce défaut, car son garde-fou exige le nom précédé du sigil, /nom pour Claude et $nom pour Codex, ce qui distingue une invocation d'un mot de vocabulaire. C'est cette version qu'il faut reprendre si le routeur historique est conservé. Le squelette réutilisable a été corrigé dans ce sens, et un cas de test le couvre.

Ce rapport montre une configuration, telle qu'inspectée le 16 septembre 2026. Les contenus suivants, publiés sur le même site et rédigés en anglais, prennent chaque couche séparément et exposent le raisonnement, les mesures et les erreurs qui ont conduit à cette forme.

BM25 / Okapi BM25

Fonction de classement lexical qui note la pertinence d'un document pour une requête, à partir de la fréquence des termes, de leur rareté et de la longueur du document. Classement par défaut de Lucene, Elasticsearch et SQLite FTS5.

Hook

Script exécuté par le harness à un événement du cycle de vie d'une session. Reçoit un JSON sur son entrée standard. Une sortie 2 renvoie un message de correction au modèle sans faire échouer la session.

Projection

Arborescence de skills rendue par une release pour un hôte donné. Claude reçoit une copie réelle, Codex un lien symbolique.

Skill

Répertoire contenant un fichier SKILL.md avec un frontmatter. Chargée à la demande. Seule sa description est vue avant la décision de charger.

Conclusion

La valeur de cette configuration ne tient pas au nombre de skills ni à la finesse du routeur. Elle tient à une séparation nette entre ce qui est suggéré au modèle et ce qui lui est imposé, et à un pipeline qui rend les 2 hôtes cohérents tant que la release installée est contrôlée.

Les 3 écarts appellent chacun une disposition. L'épinglage des hooks sur une release antérieure au pointeur courant est sans effet aujourd'hui, mais il se périmera sans signal : il faut rejouer la transaction d'activation après chaque modification de hook. Le routeur historique reste sur le disque sans être câblé : soit il retrouve un câblage assumé, soit il est retiré. Son garde-fou anti-doublon doit être corrigé avant tout nouveau câblage, comme il l'a été dans le squelette.

Pour transmettre la méthode sans transmettre l'inventaire, la structure du squelette suffit : les 4 couches, un routeur vérifiable et 2 skills d'exemple, que le destinataire remplit au rythme de ses besoins réels. Le squelette lui-même n'est pas publié à ce jour.

Sources datées

• Claude Code, issue 38051 : racine de skills en lien symbolique ignorée · 16 septembre 2026 · Source documentaire
• Claude Code, issue 50052 : suppression du lien de skills à l'auto-update · 16 septembre 2026 · Source documentaire
• Documentation officielle des hooks Claude Code · 16 septembre 2026 · Source documentaire
• Okapi BM25, description de la fonction de classement · 16 septembre 2026 · Source documentaire
• Elasticsearch, similarité BM25 et rôle des paramètres k1 et b · 16 septembre 2026 · Source documentaire

La mention « consulté le » indique la date de lecture. Une source peut avoir été publiée plus tôt, puis modifiée.

Historique des mises à jour