Workflow Codex centré sur le dépôt

Ce nouvel environnement ne fait plus d’un immense projet ChatGPT le centre du travail logiciel. La véritable frontière est le dépôt Git local et le contexte durable réside 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.

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

Ajouter un contrat lisible par les agents ne doit ni publier ni exiger un projet bootstrap privé. Examiner d’abord les sources déjà possédées par le dépôt :

cd /path/to/repository
git status --short --branch
find . -maxdepth 2 -type f \
  \( -name 'AGENTS.md' -o -iname 'arch.md' -o -iname 'architecture.md' \) \
  -print

Puis appliquer le plus petit changement révisable :

1. conserver la source d’architecture existante plutôt qu’en créer une seconde ;
2. créer AGENTS.md seulement sans contrat équivalent ;
3. faire pointer les ponts d’agents compatibles vers les mêmes 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.

Si le dépôt possède une commande bootstrap privée, la documentation publique décrit son comportement, pas le nom du dépôt auxiliaire ni son chemin absolu. Elle doit fonctionner en dry-run/create-only par défaut, signaler les architectures concurrentes, refuser les chemins dangereux et exiger une autorisation avant remplacement.

Le projet peut posséder AGENTS.md, un pont .agents/rules/project-guidance.md, les fichiers de base Git/éditeur, une seule architecture choisie et des réglages VS Code optionnels. Dans un dépôt mature, préserver le travail non commité et revoir chaque fichier : un bootstrap n’a pas autorité pour écraser le projet.

Contenu de AGENTS.md

Codex lit d’abord les règles personnelles, puis les fichiers AGENTS.md du projet le long du chemin ; le fichier le plus proche du répertoire de travail est prioritaire. 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 dans des worktrees Git distincts.
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                       # this environment also provides cx
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

Sous WSL, garder les dépôts dans le système de fichiers Linux, par exemple $HOME/Projects, puis lancer l’éditeur depuis le terminal WSL :

cd /path/to/repository
code .

VS Code doit afficher WSL: ... en bas à gauche. 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.

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. Si l’extension s’exécute par erreur côté Windows, activer ce réglage :

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

C’est un réglage VS Code, pas une clé de ~/.codex/config.toml. Recharger la fenêtre après modification.

Modèle de tâche compact

Il n’est pas nécessaire d’envoyer un énorme contexte. Quatre sections suffisent généralement :

Goal
Le résultat observable à produire.

Context
Dépôt, branche, fichiers concernés, faits vérifiés et reproduction.

Constraints
Ce qui ne doit pas changer ; autorisation du réseau, des dépendances, du commit,
du push ou du déploiement.

Done when
Tests, dry runs, contrôles de diff et comportement d’acceptation.

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 WSL, le même compte, puis comparer ~/.codex/config.toml et le fichier projet .codex/config.toml.

Un bootstrap propose une seconde architecture. Arrêter et retrouver la source existante, y compris imbriquée. Plusieurs candidats exigent un choix humain ; l’automatisation ne doit ni deviner ni créer une architecture concurrente.

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 Espaces Herdr pour Pi, Codex et Antigravity CLI pour gérer ces agents dans des terminaux persistants. Le journal de construction retrace l’évolution de l’environnement.

Mes lectures · Les notes ouvertes sont mémorisées dans ce navigateur.