perhapsspy/codex-token-discipline

Token Discipline pour Codex

Objectif

Réduire le coût total racine+enfant sans affaiblir le succès de la tâche, les preuves requises ou le livrable demandé.

Maintenir les lectures, les sorties d'outils, les tentatives et les délégations sous contrôle. Préserver les preuves réutilisables et ne remonter que la partie non résolue.

Cadre de fonctionnement

N'utiliser que ce qui change le comportement :

1. Nommer la phase actuelle : explorer, planifier, implémenter, vérifier, publier ou transférer.
2. Définir la prochaine preuve nécessaire avant de lire largement.
3. Avant un appel d'outil potentiellement bruyant, définir la plus petite forme de retour utile et le budget de sortie.
4. Déléguer le travail annexe bruyant uniquement lorsqu'il peut retourner des résultats distillés avec preuves.
5. Aux limites de phase, sauvegarder un état de reprise compact et remettre les décisions de continuation de session au directeur propriétaire, le cas échéant.

Ignorer le rituel pour les petites modifications, les réponses directes et les commandes simples.

Contrat de pré-vol de sortie

Empêcher la sortie excessive avant qu'elle n'entre dans le contexte principal ; ne pas se fier à un résumé ultérieur.

• Pour toute commande imprévisible ou par lot, nommer d'abord la forme de retour requise : statut, nombre, chemins, champs sélectionnés ou première défaillance exploitable.
• Fixer un budget de retour fini sur l'appel d'outil. Pour les appels de type exec, utiliser par défaut un budget explicite inférieur ou égal à 2 000 tokens, sauf si une preuve nommée en nécessite davantage ; ne pas attendre un seul seuil de sortie importante.
• Filtrer, agréger ou sélectionner à la source. Pour les tests et les builds, retourner le statut de sortie, la première défaillance exploitable et la commande avant de demander plus de détails.
• Lorsque la sortie complète est utile pour une inspection ultérieure, l'écrire dans un artefact local à la tâche ou temporaire et retourner uniquement son chemin, sa taille, un résumé compact et la première défaillance exploitable. Inspecter des tranches bornées de l'artefact si nécessaire.
• Ne pas créer d'artefact pour une sortie jetable qui peut être réduite à la source.

Lectures en résumé d'abord

Commencer étroitement ; n'élargir que lorsque cela change la décision suivante.

• Rechercher avec rg ou des listes de fichiers avant d'ouvrir des fichiers.
• Préférer git diff --stat, git diff --name-only, git diff ciblé -- <chemin> et des plages sed -n ciblées avant les diffs complets.
• Pour les logs et les sorties de commandes, utiliser tail, head, jq, des compteurs, des filtres ou des recherches d'erreurs avant les transcriptions complètes.
• Traiter chaque résultat d'outil retourné comme un coût d'entrée futur. Préférer les compteurs, chemins, résumés ou preuves sélectionnées avant la sortie complète.
• Après un échec, élargir à partir de l'artefact sauvegardé ou relancer uniquement la portée défaillante la plus petite ; éviter les transcriptions complètes répétées dans le fil principal.

Si une lecture large est nécessaire, en expliquer la raison et la limiter à la portée la plus petite utile.

Travail de longue durée

Traiter les changements de phase comme des points de contrôle de contexte.

• Avant l'implémentation ou le changement de dépôt/tâche, préserver la conclusion, la décision suivante, l'étape suivante la plus proche et la plus petite limite utile.
• Dans les dépôts utilisant project-context, préférer BRIEF.md pour un état actuel compact et des logs pour les preuves.
• Lorsqu'un directeur coordonne un travail de longue durée, signaler le point de contrôle et laisser le directeur décider de continuer, de transférer ou de faire pivoter la session. Ne pas prescrire ou initier inconditionnellement une nouvelle session.
• Sans directeur, ne recommencer à neuf que lorsque la surface sauvegardée est suffisante pour continuer et que l'utilisateur ou le workflow propriétaire le demande.

Ne pas stocker de transcriptions, de matrices de validation ou d'inventaires de fichiers pour compenser une grande conversation.

Sous-agents

La délégation n'est pas intrinsèquement moins coûteuse. Utiliser l'agent nommé le plus étroit pour un travail délimité pouvant retourner des preuves ou une sortie compactes et indépendamment utiles.

Commencer avec un agent. Paralléliser uniquement les portées indépendantes et non chevauchantes. Ne pas dupliquer la même investigation, garder les agents en vie après l'intégration, ou répéter des validations encore valides.

Provoquer avec une portée, une limite d'écriture, une condition d'achèvement, une validation et une sortie compacte attendue. Les enfants ne doivent pas déléguer.

Boucles de navigateur et d'interface utilisateur

Avant une vérification visuelle ou de navigateur répétée, écrire les états à vérifier.

• Préférer une capture d'écran ou un passage de navigateur par état nommé.
• Si une vérification échoue, inspecter le plus petit propriétaire : erreur console, état DOM, données de routage ou composant ciblé.
• Garder les images, les captures d'écran en base64, le texte complet du corps et les vidages DOM hors du fil principal, sauf si cet artefact lui-même affecte la décision suivante.
• Arrêter une fois que les états nommés sont vérifiés ou qu'un blocage concret est isolé.

Surfaces de lecture permanente

Chaque ligne dans les instructions globales ou du dépôt a un coût récurrent.

• Placer les règles de comportement durables et les limites de sécurité dans des fichiers de type AGENTS.
• Placer les workflows reproductibles dans des compétences.
• Placer l'état actuel de la tâche dans les documents de tâche du dépôt.
• Placer les faits de domaine réutilisables actuels dans les documents de référence.
• Supprimer les profils obsolètes, les instructions en double et les explications historiques au lieu de documenter autour d'eux.

Lors de la modification d'un fichier lu en permanence, préférer une règle de routage courte à un texte de procédure.

Audit d'utilisation

Lorsqu'on vous demande où sont passés les tokens, résoudre scripts/summarize_codex_usage.py par rapport au répertoire d'installation de cette compétence, l'exécuter avec --help, puis auditer avec un --cwd-prefix explicite.

Le script regroupe les logs de déploiement Codex par fil racine et rapporte les totaux de tokens, le taux d'entrée en cache, la part de tokens des sessions enfants, le volume de sortie d'outils, les événements de sortie importante et les signaux de l'outil de sortie maximale sans les charges utiles brutes.

Traiter les totaux de tokens comme des signaux, pas comme une qualité. Éviter les recherches textuelles dans tout le répertoire personnel ; pointer le script vers $CODEX_HOME/sessions ou une autre racine de sessions explicite.

Vérification finale

• Le fil principal n'a-t-il reçu que les preuves nécessaires à la décision en cours ?
• Le travail d'outil bruyant avait-il une forme de retour et un budget avant exécution, avec les détails complets conservés dans un artefact uniquement si utile ?
• Les grandes lectures, les boucles de navigateur et les sous-agents ont-ils été délimités par des questions explicites ?
• L'état reprenable est-il dans la bonne surface, et le directeur propriétaire a-t-il retenu la décision de continuer/transférer/faire pivoter ?
• Les directives de lecture permanente sont-elles restées courtes et ont-elles redirigé les détails ailleurs ?