Guide Archon : isolement Git Worktree + workflow DAG pour maîtriser l’imprévisibilité du développement assisté par IA

Niveau débutant | ~20 minutes | Vous maîtriserez les concepts clés d’Archon (isolement Worktree, types de nœuds DAG, syntaxe YAML des workflows), la partie installation/configuration, ainsi que 3 mises en pratique typiques de workflows

---

Présentation du projet

Commençons par admettre une évidence : quand vous demandez à une IA de corriger un bug, elle peut aussi modifier des endroits que vous n’aviez pas prévu de toucher ; quand vous lui demandez d’ajouter une fonctionnalité, elle peut fonctionner aujourd’hui… puis dévier la prochaine fois, alors que vous répétez la même consigne ; quand vous lui demandez d’écrire une PR, le style de description change à chaque fois.

Ces problèmes ne viennent pas du fait que l’IA fasse exprès de perturber : c’est tout le processus qui manque de « structure ». L’IA reçoit une instruction vague, et la sortie dépend entièrement de l’humeur du modèle et du contexte au moment de la réponse.

Ce que fait Archon, c’est d’ajouter de la structure au développement avec l’IA. Il définit, en YAML, votre processus de développement : planification, validation, revue de code, création de PR—et précise pour chaque étape : ce qu’elle doit faire, de quoi elle dépend, et à quel moment elle est considérée comme terminée. Ensuite, il place l’IA dans ce cadre : elle peut s’exprimer librement, mais sans partir dans tous les sens.

Une autre capacité centrale d’Archon est le Git Worktree pour l’isolement : chaque workflow s’exécute sur une branche git et un répertoire de travail indépendants. Même si vous lancez 5 tâches en parallèle, elles ne s’écrasent pas entre elles. Quand c’est terminé, vous fusionnez dans la branche principale ; quand ça échoue, vous supprimez simplement le Worktree, proprement, sans laisser de traces.

---

Profil des lecteurs visés

• Développeurs utilisant Claude Code ou Codex
• Équipes qui ont besoin de standardiser les workflows de programmation assistée par IA
• Ceux qui veulent que l’IA produise quelque chose de répétable et vérifiable

Dépendances clés et environnement

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (nécessaire pour l’installation complète)

Arbre complet de la structure du projet

.archon/                     # Au niveau projet (généré par le setup wizard)
├── commands/                # Commandes personnalisées (fichiers Markdown)
├── workflows/               # Workflows personnalisés (YAML)
│   └── defaults/            # Modèles de workflows intégrés
└── config.yaml              # Configuration du projet (modèle assistant, etc.)

~/.archon/                   # Configuration globale côté utilisateur
├── workspaces/owner/repo/  # Environnements isolés, organisés par utilisateur/répertoire GitHub
│   ├── source/             # Clone du dépôt ou chemin local
│   ├── worktrees/          # Dossiers d’isolement Git Worktree
│   └── artifacts/          # Sorties du workflow (non intégrées à git)
└── config.yaml             # Configuration globale

---

Étapes pas à pas

Étape 1 : Installer Archon

Il y a deux façons d’installer. Choisissez celle qui correspond à votre situation.

Option 1 : Installation complète (recommandée, ~5 minutes)

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude

Ensuite, dites à Claude Code : "Set up Archon". Il lancera un guide interactif pour vous aider à configurer vos identifiants GitHub, choisir l’intégration de la plateforme, tester la connexion, puis copier enfin les fichiers de compétences d’Archon dans votre projet cible.

Option 2 : Installation rapide (~30 secondes, si vous avez déjà Claude Code)

# macOS / Linux
curl -fsSL https://archon.diy/install | bash

# Windows (PowerShell)
irm https://archon.diy/install.ps1 | iex

# ou via Homebrew
brew install coleam00/archon/archon

L’installation rapide installe uniquement le CLI : elle ne configure pas automatiquement les identifiants et les workflows dans le projet. Vous devrez effectuer l’initialisation manuellement.

Étape 2 : Lancer le Setup Wizard (utilisateurs en installation complète)

Si vous avez choisi l’installation complète, le setup wizard vous guidera dans les étapes suivantes :

1. Installation du CLI — installez le binaire archon dans le PATH
2. Authentification GitHub — gh auth login, pour que Archon ait les droits d’agir sur votre dépôt
3. Choix de plateforme — intégration à Telegram / Slack / Discord (optionnel)
4. Projet cible — sélectionnez le dossier de projet à enregistrer, le wizard copie les fichiers de compétences .archon/ dans votre projet

Une fois terminé, votre projet cible contient désormais ces éléments :

.archon/
├── commands/       # Fichiers de commandes appelables par l’IA
└── workflows/      # Définition des workflows

Étape 3 : Initialiser le projet cible

Si vous avez fait l’installation rapide, initialisez manuellement :

cd your-project
archon init
# ou dans Claude Code : "Use archon to set up"

Après initialisation, vérifiez :

archon workflow list
# devrait afficher 17 workflows intégrés

Étape 4 : Comprendre la structure des workflows YAML

Les workflows d’Archon sont un DAG (graphe orienté acyclique). Chaque nœud correspond à une étape d’exécution. Les dépendances entre nœuds sont déclarées via depends_on. Archon exécute ensuite selon l’ordre topologique : les nœuds sans dépendances peuvent tourner en parallèle.

Un workflow complet ressemble à ceci :

# .archon/workflows/my-feature.yaml
nodes:
  # Nœud 1 : planification (sans dépendances, exécution directe)
  - id: plan
    prompt: "Explorer le dépôt et définir un plan de réalisation"

  # Nœud 2 : implémentation (dépend du plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # nœud de boucle IA
      prompt: "Lire le plan, implémenter la prochaine tâche, exécuter la validation"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # À chaque boucle, un nouvel échange IA

  # Nœud 3 : exécution des tests (dépend d’implement, nœud bash, exécution purement déterministe)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Nœud 4 : revue de code (dépend du succès des tests)
  - id: review
    depends_on: [run-tests]
    prompt: "Passer en revue tous les changements et corriger tout problème par rapport au plan"

  # Nœud 5 : validation humaine (gate interactif)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Afficher le contenu des changements et répondre à tout retour"
      until: APPROVED
    interactive: true                        # Pause en attente d’une saisie humaine

  # Nœud 6 : création de PR
  - id: create-pr
    depends_on: [approve]
    prompt: "Pousser le code et créer un Pull Request"

Vue d’ensemble des types de nœuds :

Étape 5 : Mise en pratique — de GitHub Issue à PR

C’est l’un des workflows les plus utilisés : en entrée, un GitHub Issue ; en sortie, une PR.

Dites simplement dans Claude Code :

Use archon to fix issue #42

Archon fait automatiquement :

1. Créer une branche Worktree isolée ( archon/fix-42-xxx )
2. Exécuter le workflow archon-fix-github-issue : catégoriser le problème → investiguer → planifier → implémenter → valider → créer la PR
3. Si les tests échouent, entrer automatiquement dans la boucle self-fix
4. Opérer dans le Worktree sans impacter votre branche principale locale

Le processus que vous voyez, en gros :

→ Creating isolated worktree on branch archon/fix-42-abc...
→ Planning...
→ Investigating issue #42...
→ Implementing (task 1/3)...
→ Implementing (task 2/3)...
→ Tests failing - iterating...
→ Tests passing after 2 iterations
→ Code review complete - 0 issues
→ PR ready: https://github.com/you/project/pull/47

Étape 6 : Mise en pratique — d’une idée à une PR

Si vous n’avez pas d’Issue existante, vous n’avez qu’une idée :

Use archon to add dark mode to the settings page

Archon utilise le workflow archon-idea-to-pr :

→ Feature idea → plan → implement → validate → PR → 5 parallel reviews → self-fix

Pendant le processus, l’IA :

1. Explore d’abord le dépôt pour comprendre l’architecture actuelle
2. Établit un plan de réalisation (vous pouvez intervenir et le modifier en cours de route)
3. Implémente itérativement via les nœuds loop jusqu’à ce que toutes les tâches soient terminées
4. Lance la validation (bun run validate)
5. Fait tourner en parallèle 5 agents de revue de code (style, sécurité, performance, maintenabilité, documentation)
6. En fonction des retours, effectue un self-fix
7. Crée la PR et ajoute un résumé complet de la revue

Étape 7 : Écrire un workflow personnalisé

Les workflows intégrés sont un excellent point de départ : copiez-en un et modifiez-le.

cp .archon/workflows/defaults/archon-feature-development.yaml \
   .archon/workflows/my-feature.yaml

Ensuite, éditez le fichier YAML. Par exemple, si vous voulez supprimer l’étape de validation humaine, fusionnez simplement comme ceci :

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Analyser les besoins et définir un plan de réalisation"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Lire le plan, implémenter la prochaine tâche, marquer comme terminée"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

  - id: run-tests
    depends_on: [implement]
    bash: "bun test"

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Pousser le code, créer un Pull Request, en utilisant le modèle suivant : ..."

Substitutions de variables : les workflows peuvent utiliser ces variables intégrées :

- id: log-context
  bash: "echo $WORKFLOW_ID $ARTIFACTS_DIR $BASE_BRANCH"

• $1, $2, $3 — paramètres positionnels
• $ARGUMENTS — tous les paramètres
• $ARTIFACTS_DIR — répertoire de sortie du run du workflow en cours
• $WORKFLOW_ID — ID du run de workflow
• $BASE_BRANCH — nom de la branche principale
• $LOOP_USER_INPUT — feedback saisi par l’humain dans le gate d’approbation

Étape 8 : Web UI + intégration multi-plateformes

Archon n’est pas uniquement un CLI : il propose aussi un Web Dashboard complet. Démarrage rapide :

archon serve
# Télécharge le Web UI (la première fois), puis démarre sur http://localhost:4000

Le Web UI fournit :

• Page Chat — discussion temps réel avec l’IA, affichage du streaming et des appels d’outils
• Dashboard — surveiller l’état de tous les workflows en cours d’exécution (depuis toutes les plateformes : CLI, Slack, Telegram, etc.)
• Workflow Builder — éditeur visuel DAG avec création par glisser-déposer
• Workflow Execution — consulter étape par étape l’exécution de n’importe quel workflow

Intégrer une plateforme de chat (optionnel) :

Une fois l’intégration faite, vous pouvez déclencher un workflow directement depuis Slack ou Telegram, et les résultats seront envoyés en temps réel dans la même conversation.

---

Dépannage des problèmes fréquents

1. Claude Code ne trouve pas la commande Archon

C’est généralement dû au fait que le setup wizard n’a pas été exécuté après l’installation rapide :

# relancer le setup
cd your-project
claude
# dire "Set up Archon" ou "Use archon to set up"

# ou mettre à jour manuellement les fichiers de compétences
archon update

2. La création de Worktree échoue

La cause la plus fréquente est un manque d’espace disque ou un problème de permissions :

# vérifier l’espace disque
df -h

# vérifier la version git (nécessite 2.23+ pour supporter Worktree)
git --version

# nettoyer manuellement les anciens Worktree
archon isolation cleanup

3. La liste des workflows est vide

# vérifier que le dossier .archon/workflows/ existe
ls .archon/workflows/

# détecter manuellement les workflows en les lançant
archon workflow list --verbose

Si les workflows intégrés ne s’affichent pas non plus, vérifiez la version d’Archon :

archon --version

4. Boucle de dépendances des nœuds YAML

Si depends_on forme une boucle, Archon renvoie une erreur :

Error: Circular dependency detected in workflow

Solution : vérifiez le fichier YAML et assurez-vous qu’aucun nœud ne dépend du mauvais nœud (un nœud dont depends_on pointe vers lui-même ou vers un nœud en aval).

5. L’Approval Gate interactif ne répond pas dans le CLI

Le Approval Gate nécessite une intervention humaine. Dans le CLI, le workflow s’arrête et attend une saisie :

Workflow paused: awaiting approval
Type /workflow approve <run-id> [comment] to approve
Type /workflow reject <run-id> <reason> to reject

Si vous exécutez depuis le Web UI, les nœuds avec interactive: true affichent automatiquement des boutons d’approbation.

6. Changement PostgreSQL vs SQLite

Par défaut, Archon utilise SQLite (sans configuration). Les données sont dans ~/.archon/archon.db. Si vous souhaitez passer à PostgreSQL :

# démarrer PostgreSQL (Docker)
docker-compose --profile with-db up -d postgres

# définir la chaîne de connexion dans le fichier .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# redémarrer Archon
archon serve

---

Lectures complémentaires / pistes avancées

Détails des 17 workflows intégrés : Archon fournit une chaîne complète d’outils allant de l’assistance au quotidien (archon-assist) jusqu’à des revues complexes (archon-comprehensive-pr-review). Par exemple, archon-refactor-safely inclut des hooks de type-check, archon-architect réalise des scans de santé d’architecture, et archon-ralph-dag prend en charge l’itération d’un PRD.

Types de nœuds personnalisés : en plus des nœuds intégrés, vous pouvez écrire : command: pour appeler un fichier de commande personnalisé (Markdown), script: pour exécuter un script TypeScript/Python (avec prise en charge de deps: pour installer les dépendances et de timeout: pour contrôler le délai), et approval: pour définir un processus d’approbation humaine personnalisée.

Développement d’adaptateurs de plateforme : la couche d’adaptateurs d’Archon ( IPlatformAdapter ) permet d’intégrer n’importe quelle plateforme de messagerie. Consultez les implémentations sous packages/adapters/src/ pour Slack, Telegram et Discord : vous pourrez aussi intégrer des plateformes locales comme WeChat Entreprise ou Feishu.

Analyse approfondie de l’architecture d’Archon : au cœur, il y a l’exécuteur de DAG du package @archon/workflows (dag-executor.ts) + l’Orchestrator de @archon/core (routage des messages et gestion des sessions). Le YAML des workflows est parsé et validé via loader.ts, puis les nœuds sont assemblés en un graphe topologique via depends_on, avant d’être exécutés dans l’ordre topologique.

Standardisation des workflows en équipe : en commitant .archon/workflows/ dans Git, chaque membre de l’équipe récupère automatiquement la même définition de workflow après chaque clone. En combinant avec l’injection des conventions de codage dans .archon/config.yaml, tout le contenu généré par l’IA respectera les accords de l’équipe.