aryashreep/ctx-audit

Audit de Contexte

Les dépôts qui adoptent cette convention maintiennent un petit ensemble de fichiers persistants afin que les agents n'aient pas à redécouvrir les mêmes choses à chaque session : quelles sont les conventions du projet (AGENTS.md), ce qui a déjà été décidé et pourquoi (memory.md), et approximativement comment la base de code est organisée (.agent/graph.md). Cette compétence vérifie si ces fichiers existent et sont à jour avant que vous vous y fiiez ou avant de revenir à une exploration manuelle du dépôt.

Expressions déclencheurs

Début de session / vérification de confiance

• "mets-moi à jour sur ce dépôt"
• "que sais-tu de ce projet"
• "puis-je faire confiance à AGENTS.md / memory.md"
• "les fichiers de contexte sont-ils à jour"
• "vérifier le contexte" / "audit de contexte"

Obsolescence

• "AGENTS.md est-il obsolète" / "memory.md est-il obsolète"
• "combien de commits depuis la dernière synchronisation"
• "mes fichiers agent sont-ils à jour"
• "vérifier si le contexte est obsolète"

Coût en tokens

• "combien les fichiers de contexte économisent-ils"
• "économies de tokens" / "coût du contexte"
• "benchmark des économies de tokens"
• "tokens de base vs tokens curés"

Configuration / intégration

• "scaffolder AGENTS.md" / "initialiser le contexte"
• "installer ctx-audit" / "brancher le hook de contexte"
• "configurer le contexte IA" / "ce projet est-il prêt pour l'IA"

CI / automatisation

• "ajouter ctx-audit à la CI"
• "ajouter un hook pre-push"
• "appliquer la fraîcheur du contexte dans la CI"

Architecture

• "ai-je une carte d'architecture"
• "générer graph.md" / "exécuter graphify"

Comment exécuter

La méthode recommandée pour exécuter ctx-audit :

npx ctx-audit

Sinon, si installé en tant que compétence :

node <chemin-vers-ce-dossier-de-compétence>/../scripts/audit.mjs

Options :

• --json — sortie lisible par machine (utilisez ceci si vous comptez agir sur le résultat de manière programmatique).
• --strict — code de sortie 1 si quoi que ce soit manque ou est obsolète.
• --ci — alias pour --strict --json.
• --help — affiche l'utilisation et quitte.

Sous-commandes

# Scaffolder AGENTS.md + memory.md (interactif — écrit les fichiers directement à la racine du dépôt)
npx ctx-audit init

# Installation en une commande : copie la compétence dans ~/.claude/skills/, l'enregistre dans CLAUDE.md
npx ctx-audit install

# Hook git : exécute un audit --strict à chaque push
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall

# CLAUDE.md du projet : ajoute un bloc d'instructions pour les agents
npx ctx-audit claude install
npx ctx-audit claude uninstall

# Rapport d'économies de tokens (format ciblé et partageable)
npx ctx-audit benchmark

Table de décision pour l'agent

Statut	Signification	Action
FRAIS	Moins de la moitié du seuil d'obsolescence en commits depuis la dernière synchro	Faites confiance au fichier — lisez-le plutôt que de parcourir le code source brut
OBSOLÈTE ?	Approche du seuil (peut-être obsolète)	Prudence modérée — vérifiez ponctuellement les affirmations critiques avant de vous y fier
OBSOLÈTE !	Dépassement du seuil, considéré comme un échec	Considérez les affirmations comme non vérifiées ; vérifiez ponctuellement par rapport au code réel ; mettez à jour après la session
OBSOLÈTE	Significativement en retard, considéré comme un échec	Identique à OBSOLÈTE ! mais plus urgent ; mettez à jour immédiatement après la session
MANQUANT (obligatoire)	Le fichier n'existe pas	Exécutez npx ctx-audit init ; ne procédez pas comme si la convention était en place
absent (optionnel)	Fichier optionnel non présent	Acceptable ; envisagez d'exécuter /graphify pour générer graph.md
hors budget	Le nombre de tokens dépasse maxTokens	Le fichier est gonflé — réduisez-le ; le lire pourrait coûter plus cher que ce qu'il économise
référence morte	Un chemin entre accents graves ou dir/fichier.ext mentionné dans le fichier n'existe pas sur le disque	Mettez à jour la référence ; le fichier documente une structure obsolète
SHA modifié	last_synced_commit mis à jour mais le corps inchangé	Vérifiez si le fichier reflète réellement les changements récents ; peut être une mise à jour mécanique

Interprétation des résultats

• MANQUANT (fichier obligatoire) : ne procédez pas comme si la convention était en place. Proposez de scaffolder un fichier de démarrage (exécutez npx ctx-audit init) plutôt que de travailler sans fichier ou de revenir silencieusement à l'ancienne méthode "tout explorer manuellement".
• FRAIS : le fichier est à jour. Lisez-le plutôt que de parcourir le code source brut.
• OBSOLÈTE ? (peut-être obsolète) : approche du seuil. Vérifiez ponctuellement les affirmations critiques.
• OBSOLÈTE ! (probablement obsolète) : considérez ses affirmations comme non vérifiées. Vérifiez ponctuellement toute information cruciale par rapport au code réel, et après votre session, mettez à jour le fichier et son last_synced_commit.
• OBSOLÈTE : significativement en retard. Même traitement que OBSOLÈTE ! mais plus urgent.
• Les comptages de tokens sont une heuristique d'environ 3,5 caractères/token — utiles pour l'orientation, pas exacts. Si un fichier est signalé "hors budget", il est devenu suffisamment gonflé pour que le lire commence à coûter ce qu'il était censé économiser ; suggérez de le réduire.
• Avertissements de référence morte : chemins mentionnés dans les fichiers de contexte qui n'existent plus sur le disque. Indique que le fichier référence une structure obsolète.

Exemples concrets

Audit de base en début de session :

npx ctx-audit

Barrière CI (échouer la construction si le contexte est obsolète) :

# .github/workflows/ctx-audit.yml
- name: Audit de la fraîcheur du contexte
  run: npx ctx-audit --strict

Sortie JSON pour utilisation programmatique :

npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'

Intégration en une commande :

npx ctx-audit install        # copie la compétence, l'enregistre dans CLAUDE.md
npx ctx-audit hook install   # ajoute une garde pre-push
npx ctx-audit claude install # ajoute une note au CLAUDE.md du projet
npx ctx-audit init           # génère les modèles AGENTS.md + memory.md

Vérifier l'obsolescence d'un sous-système spécifique (via le frontmatter) :

---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---

Seuls les commits touchant src/auth/ ou src/api/ comptent pour l'obsolescence de ce fichier.

Benchmark des économies de tokens :

npx ctx-audit benchmark

Configuration

Placez .ctx-audit.json à la racine du dépôt pour personnaliser le comportement :

{
  "files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
  "sourceDirs": ["src", "packages/core"],
  "staleThreshold": 10,
  "baselineFileCap": 300
}

Frontmatter

Chaque fichier de contexte doit commencer par un frontmatter :

---
last_synced_commit: <sha git>
watches: src/auth/**, src/api/**
---

Le champ watches (optionnel) limite les vérifications d'obsolescence aux seuls commits touchant ces chemins, au lieu de tous les répertoires sources.

Si des fichiers obligatoires manquent — générez-les

Exécutez npx ctx-audit init pour générer des modèles. Dans un terminal TTY, il écrit les fichiers directement à la racine du dépôt ; en cas de redirection, il les affiche sur la sortie standard. L'option --init héritée est toujours prise en charge comme alias rétrocompatible.

AGENTS.md — conventions stables du projet : commandes de construction/test/lint, règles d'organisation des fichiers, choses que l'agent ne doit jamais faire. Devrait changer rarement.

memory.md — un journal des décisions, pas une reformulation du code actuel. Chaque entrée : ce qui a été essayé, ce qui a été décidé, pourquoi, et quoi reconsidérer si les circonstances changent. Ajoutez, ne réécrivez pas l'historique.

.agent/graph.md (optionnel mais recommandé une fois que le dépôt grandit) — un paragraphe par module principal décrivant sa responsabilité et avec quoi il communique. Pas le contenu des fichiers, pas un arbre exhaustif — juste assez pour qu'un agent puisse naviguer sans tout relire. Astuce : exécutez /graphify pour le générer automatiquement à partir de la base de code au lieu de l'écrire à la main.

Après avoir créé ou mis à jour l'un de ces fichiers, mettez à jour son last_synced_commit avec le HEAD actuel afin que le prochain audit ne le signale pas immédiatement comme obsolète.