Workflow Codex centré sur le dépôt

Le centre du travail logiciel doit être le dépôt Git local, pas un projet ChatGPT dont la conversation ne cesse de s’allonger. Le dépôt est la véritable frontière du projet, et le contexte à conserver vit dans des fichiers versionnés. L’application Codex, la CLI et l’extension VS Code sont trois portes vers le même dépôt.

Rien de tout cela n’est propre à Codex. Quand un dépôt n’a pas de CLAUDE.md, Claude Code lit directement AGENTS.md, et Antigravity CLI traite aussi AGENTS.md comme des règles d’espace de travail. Les exemples ci-dessous utilisent Codex ; le contrat du dépôt, une conversation par résultat et des autorisations séparées valent tels quels pour ces agents.

Modèle central

L’historique du chat est une mémoire de travail temporaire, pas une source de vérité. Une décision utile à la prochaine tâche doit rejoindre AGENTS.md, la documentation d’architecture, un README, un test ou une issue.

Les projets ChatGPT restent utiles pour les fichiers téléversés, les sources Web et des discussions liées. Ils ne remplacent toutefois ni un répertoire local, ni l’état Git, ni des tests exécutables. Si le code y paraît indirect, lancer Codex depuis le dépôt.

Première adoption du dépôt

La première fois qu’un agent entre dans un dépôt, il lui faut un contrat. AGENTS.md est précisément cela : les règles du projet écrites pour l’agent, comment installer, comment tester, ce qu’il ne faut pas toucher et ce qui compte comme terminé. Avant de l’écrire, regarder quelles règles et quels documents d’architecture existent déjà, puis appliquer le plus petit changement révisable :

1. conserver la source d’architecture existante, c’est-à-dire le document d’architecture que le dépôt considère déjà comme faisant foi, plutôt qu’en créer une seconde ;
2. créer AGENTS.md seulement sans contrat équivalent ;
3. Codex, Claude Code et Antigravity CLI lisent tous directement AGENTS.md : un fichier de liaison est donc rarement utile ; n’en ajouter un, réduit à la ligne « les règles sont dans AGENTS.md », que pour un outil qui ne le lit pas, et ne jamais recopier les règles ;
4. ajouter .gitignore, .editorconfig ou réglages éditeur uniquement pour une lacune démontrée ;
5. examiner git diff avant commit, push ou déploiement.

Les fichiers utiles appartenant au projet peuvent comprendre :

• AGENTS.md : le contrat de référence du dépôt ;
• .gitignore, .editorconfig et .gitattributes ;
• un seul document d’architecture choisi comme référence ;
• des réglages VS Code propres au projet, facultatifs.

Dans un dépôt mature, préserver le travail non commité et revoir chaque fichier proposé.

Contenu de AGENTS.md

Selon les règles officielles de découverte des instructions, Codex lit d’abord les règles personnelles, puis les instructions du projet en suivant le chemin de la racine du projet au répertoire de travail courant ; les instructions les plus proches de ce répertoire remplacent les précédentes. Codex lit au plus 32 Kio d’instructions cumulées par défaut, et la documentation de Claude Code conseille moins de 200 lignes par CLAUDE.md. Le contrat doit rester bref et répondre à ces questions :

• Quel est le but du dépôt et où se trouve la vérité d’architecture ?
• Quelles commandes installent, testent, construisent et lintent le projet ?
• Quels dossiers, données et fichiers générés sont hors périmètre ?
• Que faut-il lire avant de modifier le code ?
• Quelles vérifications définissent l’achèvement ?
• Quels push, déploiements, migrations et actes destructifs exigent une autorisation ?

Ne pas mettre une demande ponctuelle, des journaux temporaires ou des dizaines de pages de contexte dans AGENTS.md. Les règles durables vont dans le contrat, les connaissances dans la documentation, les comportements dans les tests et l’objectif courant dans le chat.

Application Codex : console des tâches longues

L’application convient au raisonnement long, aux modifications multi-fichiers, aux revues indépendantes et au travail parallèle :

1. Ouvrir le dépôt local plutôt qu’un projet de chat géant.
2. Créer une conversation pour un résultat vérifiable.
3. Faire lire l’état Git, le AGENTS.md le plus proche et la source d’architecture.
4. Pour un changement complexe, établir d’abord une base factuelle.
5. Placer les agents parallèles qui écrivent du code dans des worktrees Git distincts, jamais dans le même checkout ; Coordination multi-agents explique ce qu’un worktree isole et n’isole pas.
6. À la fin, inscrire les décisions durables dans le dépôt.

Une conversation doit couvrir environ une branche ou un résultat. En ouvrir une nouvelle si la direction change, fork pour comparer une autre voie et resume pour reprendre une ancienne tâche. Les contextes courts sont plus faciles à relire et à restaurer.

CLI Codex : entrée par défaut du dépôt

L’installateur officiel et la connexion de base sont :

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex login
codex login status

Lancer Codex depuis le dossier cible ; le dossier initial devient le projet :

cd /path/to/repository
codex
codex -C /path/to/repository
codex exec "Run the tests and explain the first failure; do not edit files"
codex review
codex resume
codex doctor
codex update

La référence officielle des commandes CLI présente ces commandes interactives utiles :

Commande	Usage
/status	Voir dossier, modèle, permissions et contexte
/permissions	Régler les approbations et le sandbox de la session
/model	Choisir le modèle et, lorsque disponible, son effort de raisonnement
/plan	Rendre une exécution complexe contrôlable
/review, /diff	Relire les changements et le diff Git
/mention	Ajouter explicitement un fichier au contexte
/new, /resume, /fork	Gérer le cycle de vie de la conversation
/compact	Compacter un contexte long et continuer
/mcp, /apps, /plugins	Examiner les capacités connectées

Conserver workspace-write et l’approbation à la demande comme frontière normale. Ne pas employer --dangerously-bypass-approvals-and-sandbox pour éviter une confirmation ; élever uniquement l’action précise qui nécessite réseau, autre dépôt ou publication.

Extension VS Code : travailler près du code

Après installation de l’extension Codex officielle, ouvrir son icône latérale ou exécuter Codex: Open Codex Sidebar depuis la palette et se connecter. La CLI et l’IDE partagent normalement l’authentification et les couches de configuration Codex. Sous WSL, garder le dépôt dans le répertoire personnel Linux et lancer code . depuis le terminal WSL ; voir le guide WSL officiel.

L’extension convient surtout pour :

• expliquer la sélection ou les fichiers ouverts ;
• effectuer un changement ciblé avec diff inline immédiat ;
• ajouter un fichier ou une sélection au thread ;
• planifier, relire et exécuter les tâches locales dans l’éditeur ;
• déléguer un travail long au cloud puis en relire localement le résultat.

Les entrées utiles comprennent nouveau chat, ajout de fichier/sélection et /plan, /review, /status, /model, /reasoning, /local, /worktree et /cloud.

Ouverture et autorisations

Rédiger chaque tâche confiée à un agent comme un paquet de tâche : objectif, contexte, contraintes et condition d’achèvement ; l’ingénierie du contexte en montre le format.

Une bonne ouverture est :

Établis d’abord une base factuelle : confirme la racine du dépôt et l’état Git,
puis lis le AGENTS.md le plus proche et la source d’architecture. Préserve les
changements sans rapport. Implémente directement et exécute les tests pertinents.
Rapporte les fichiers modifiés, les validations et les risques restants. Ne fais
ni commit, ni push, ni déploiement.

Pour un diagnostic, préciser « lecture seule, ne corrige rien ». Pour une revue, « ne te fie pas seulement aux tests ». Autoriser séparément commit, push, PR et déploiement, car chacun modifie un état externe distinct.

Dépannage

Codex ignore le contexte du projet. Vérifier le dossier de départ, puis placer les informations stables dans AGENTS.md ou l’architecture. Ne pas compenser une mauvaise frontière avec un prompt toujours plus long.

La conversation devient lente et confuse. Ouvrir un nouveau chat après un résultat ; utiliser /compact, /resume ou /fork. Un thread ne doit pas porter tout le cycle de vie d’un projet.

La CLI et l’extension se comportent différemment. Vérifier le même dossier, le même compte, puis comparer ~/.codex/config.toml et le fichier projet .codex/config.toml.

Le dépôt contient déjà des changements non commités. Ne jamais les nettoyer ou les écraser. Limiter la tâche, identifier les fichiers qui lui appartiennent et utiliser un worktree distinct pour le travail parallèle.

Voir Herdr : un terminal persistant pour plusieurs agents de programmation pour faire tourner plusieurs agents dans des terminaux persistants. Le journal de construction retrace l’évolution de l’environnement.

Mes lectures