Guía para principiantes de Archon: aislamiento con Git Worktree + flujo de trabajo DAG, para domar la incertidumbre de la programación con IA

Nivel principiante | ~20 minutos | Aprenderás los conceptos fundamentales de Archon (aislamiento con Worktree, tipos de nodos en DAG, sintaxis de flujo de trabajo en YAML), la instalación y configuración, y 3 prácticas típicas de flujos de trabajo

---

Introducción al proyecto

Empecemos reconociendo una verdad: le pides a la IA que arregle un bug y quizá, de paso, toque cosas que ni siquiera querías modificar; le pides que añada una funcionalidad y, cuando luego repites el mismo caso, primero ejecuta y luego se desvía hablando; le pides que escriba un PR y cada vez describe con un estilo distinto.

Estos problemas no es que la IA esté “buscando” hacerte la vida imposible, sino que, en todo el proceso, no existe una “estructura”. La IA recibe una orden vaga y la salida depende totalmente del estado mental del modelo y del contexto de turno.

Lo que hace Archon es añadirle estructura a la programación con IA. Define el flujo de desarrollo con YAML—planificación, validación, revisión de código, creación de PR—y deja claro qué pasa en cada paso, de qué depende cada cosa y cuándo se considera completado. Después, mete a la IA dentro de ese marco para que pueda expresarse con libertad, pero sin salir corriendo a cualquier lado.

Otra capacidad clave es su aislamiento con Git Worktree: cada flujo de trabajo corre en una rama y un directorio de trabajo independientes de git; aunque tengas 5 tareas en paralelo, no se pisan entre sí. Cuando terminan, se fusionan de vuelta a la rama principal; si fallan, simplemente se elimina el Worktree y listo, limpio y sin residuos.

---

Perfil de lectores objetivo

• Desarrolladores que usan Claude Code o Codex
• Equipos que necesitan estandarizar flujos de trabajo de programación con IA
• Personas que quieren que la IA produzca resultados repetibles y revisables

Dependencias y entorno principales

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (se requiere una instalación completa)

Estructura completa del proyecto

.archon/                     # A nivel de proyecto (generado por el setup wizard)
├── commands/                # Comandos personalizados (archivos Markdown)
├── workflows/               # Flujos de trabajo personalizados (YAML)
│   └── defaults/            # Plantillas de flujos de trabajo integradas
└── config.yaml              # Configuración del proyecto (p. ej., modelo del assistant)

~/.archon/                   # Configuración global a nivel de usuario
├── workspaces/owner/repo/  # Entornos aislados organizados por usuario/repo de GitHub
│   ├── source/             # Clon del repositorio o ruta local
│   ├── worktrees/          # Directorio de aislamiento con Git Worktree
│   └── artifacts/          # Artefactos de los flujos de trabajo (no se incluyen en git)
└── config.yaml             # Configuración global

---

Paso a paso

Paso 1: Instalar Archon

Hay dos formas de instalarlo; elige la que mejor se ajuste a tu caso.

Opción 1: Instalación completa (recomendada, ~5 minutos)

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

Luego, dile a Claude Code: "Set up Archon". Lanzará un asistente de guía interactivo para configurar tus credenciales de GitHub, elegir integraciones de plataforma, probar la conexión y, al final, copiar los archivos de habilidades de Archon dentro de tu proyecto objetivo.

Opción 2: Instalación rápida (~30 segundos, si ya tienes Claude Code)

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

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

# O usando Homebrew
brew install coleam00/archon/archon

La instalación rápida solo instala la CLI; no configura automáticamente credenciales ni flujos de trabajo dentro del proyecto, así que tendrás que hacer la inicialización manualmente.

Paso 2: Ejecutar Setup Wizard (para usuarios con instalación completa)

Si usaste la instalación completa, el setup wizard te guiará para completar estos pasos:

1. Instalación de la CLI — instalar el binario archon en el PATH
2. Autenticación de GitHub — gh auth login, para que Archon tenga permisos de operar tu repositorio
3. Selección de plataforma — si deseas integrar Telegram / Slack / Discord (opcional)
4. Proyecto objetivo — elige el directorio del proyecto a registrar; el wizard copiará los archivos de habilidades .archon/ dentro de ese proyecto

Al terminar, tu proyecto objetivo tendrá estas cosas:

.archon/
├── commands/       # Archivos de comandos que la IA puede invocar
└── workflows/      # Definiciones de los flujos de trabajo

Paso 3: Inicializar el proyecto objetivo

Si hiciste la instalación rápida, debes inicializarlo manualmente:

cd your-project
archon init
# o di en Claude Code: "Use archon to set up"

Después, verifica:

archon workflow list
# Deberían aparecer 17 flujos de trabajo integrados

Paso 4: Entender la estructura de flujos de trabajo en YAML

Los flujos de trabajo de Archon son un DAG (grafo dirigido acíclico): cada nodo es un paso de ejecución. Las dependencias entre nodos se declaran con depends_on; Archon ejecuta según el orden topológico, y los nodos sin dependencias pueden correr en paralelo.

Un flujo completo se ve así:

# .archon/workflows/my-feature.yaml
nodes:
  # Nodo 1: Planificación (sin dependencias; se ejecuta directamente)
  - id: plan
    prompt: "Explora el repositorio de código y define un plan de implementación"

  # Nodo 2: Implementación (depende de plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # Nodo de bucle de IA
      prompt: "Lee el plan, implementa la siguiente tarea y ejecuta la validación"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # En cada iteración se usa una sesión nueva de IA

  # Nodo 3: Ejecutar tests (depende de implement; nodo bash; ejecución determinista)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Nodo 4: Revisión de código (depende de que pasen los tests)
  - id: review
    depends_on: [run-tests]
    prompt: "Revisa todos los cambios y, de acuerdo con el plan, corrige cualquier problema"

  # Nodo 5: Aprobación manual (gate interactivo)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Muestra el contenido de los cambios y responde cualquier comentario"
      until: APPROVED
    interactive: true                        # Pausa para esperar entrada humana

  # Nodo 6: Crear PR
  - id: create-pr
    depends_on: [approve]
    prompt: "Envía el código y crea un Pull Request"

Resumen de tipos de nodo:

Paso 5: Práctica — De un Issue de GitHub a un PR

Este es uno de los flujos de trabajo más utilizados: introduces un GitHub Issue y obtienes un PR.

Di directamente en Claude Code:

Use archon to fix issue #42

Archon hará automáticamente:

1. Crear una rama de Worktree aislada (archon/fix-42-xxx)
2. Ejecutar el flujo archon-fix-github-issue: clasificar el problema → investigar → planificar → implementar → validar → crear PR
3. Si fallan los tests, entrar automáticamente en el bucle self-fix
4. Al finalizar, operar sobre el Worktree sin afectar tu rama principal local

El proceso que ves, a grandes rasgos, es:

→ 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

Paso 6: Práctica — De una idea a un PR

Si no tienes un Issue listo, solo tienes una idea:

Use archon to add dark mode to the settings page

Archon usa el flujo de trabajo archon-idea-to-pr:

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

Durante el proceso, la IA hará:

1. Explorar primero el repositorio para entender la arquitectura actual
2. Definir un plan de implementación (puedes intervenir y cambiarlo a mitad de camino)
3. Usar nodos loop para implementar repetidamente hasta que se completen todas las tareas
4. Ejecutar la validación (bun run validate)
5. Ejecutar en paralelo 5 agentes de revisión de código (estilo, seguridad, rendimiento, mantenibilidad, documentación)
6. Aplicar self-fix según los comentarios de la revisión
7. Crear el PR y adjuntar un resumen completo de la revisión

Paso 7: Escribir flujos de trabajo personalizados

Los flujos integrados son un gran punto de partida; copia uno y ajústalo:

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

Luego edita el archivo YAML. Por ejemplo, si quieres eliminar la etapa de aprobación manual, solo combina:

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Analiza los requisitos y define el plan de implementación"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Lee el plan, implementa la siguiente tarea y marca completado"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

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

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Envía el código, crea un Pull Request y usa la plantilla: ..."

Reemplazo de variables: en el flujo de trabajo puedes usar estas variables integradas:

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

• $1, $2, $3 — parámetros posicionales
• $ARGUMENTS — todos los parámetros
• $ARTIFACTS_DIR — el directorio de salida del run actual del flujo de trabajo
• $WORKFLOW_ID — ID del run del flujo de trabajo
• $BASE_BRANCH — nombre de la rama principal
• $LOOP_USER_INPUT — comentarios introducidos manualmente por la aprobación (approval gate)

Paso 8: Web UI + integración en múltiples plataformas

Archon no es solo CLI: tiene un Web Dashboard completo. Arranque rápido:

archon serve
# Descarga la Web UI (la primera vez) y luego inicia en http://localhost:4000

La Web UI ofrece:

• Página de Chat — conversación en tiempo real con la IA, ver salidas en streaming y llamadas a herramientas
• Dashboard — monitoriza el estado de ejecución de todos los flujos de trabajo (desde todas las plataformas: CLI, Slack, Telegram, etc.)
• Workflow Builder — editor visual de DAG, con arrastrar y soltar para crear flujos
• Workflow Execution — ver paso a paso el proceso de ejecución de cualquier flujo

Integrar plataformas de chat (opcional):

Después de integrarlo, puedes disparar flujos de trabajo directamente desde Slack o Telegram, y los resultados se enviarán en tiempo real dentro de la misma conversación.

---

Resolución de problemas comunes

1. Claude Code no encuentra el comando de Archon

Esto suele ocurrir cuando, tras la instalación rápida, no se ejecutó el setup wizard:

# Reejecutar el setup
cd your-project
claude
# di "Set up Archon" o "Use archon to set up"

# o actualizar manualmente los archivos de habilidades
archon update

2. Fallo al crear Worktree

La causa más común es falta de espacio en disco o problemas de permisos:

# Revisar espacio en disco
df -h

# Revisar versión de git (Worktree requiere 2.23+)
git --version

# Limpiar Worktree antiguo manualmente
archon isolation cleanup

3. La lista de flujos de trabajo está vacía

# Confirmar que existe el directorio .archon/workflows/
ls .archon/workflows/

# Activar manualmente la detección de flujos de trabajo
archon workflow list --verbose

Si los flujos integrados tampoco aparecen, revisa la versión de Archon:

archon --version

4. Ciclo de dependencias entre nodos YAML

Si depends_on crea un ciclo, Archon fallará con un error:

Error: Circular dependency detected in workflow

Solución: revisa el archivo YAML y asegúrate de que no haya nodos dependiendo mutuamente (que un nodo con depends_on apunte a sí mismo o a un nodo “descendiente”).

5. El Approval Gate interactivo no responde en CLI

El Approval Gate requiere intervención humana. En CLI, el flujo se pausa esperando entrada:

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

Si se ejecuta en Web UI, los nodos con interactive: true mostrarán automáticamente los botones de aprobación.

6. Cambiar entre PostgreSQL y SQLite

Archon usa SQLite por defecto (sin configuración). Los datos se guardan en ~/.archon/archon.db. Si deseas cambiar a PostgreSQL:

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

# Configurar la cadena de conexión en .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# Reiniciar Archon
archon serve

---

Lecturas adicionales / Direcciones avanzadas

Detalle de 17 flujos de trabajo integrados: Archon ofrece una cadena completa de herramientas, desde asistencia diaria (archon-assist) hasta revisiones complejas (archon-comprehensive-pr-review). Por ejemplo, archon-refactor-safely incluye hooks de type-check; archon-architect realiza un escaneo de salud de la arquitectura; y archon-ralph-dag admite iteraciones de implementación a partir de un PRD.

Tipos de Node personalizados: además de los nodos integrados, puedes escribir command: para invocar archivos de comandos personalizados (Markdown), script: para ejecutar scripts TypeScript/Python (con soporte de instalación de dependencias mediante deps: y control de timeout:), y approval: para definir flujos de aprobación humana personalizados.

Desarrollo de adaptadores de plataforma: la capa de adaptadores de Archon (IPlatformAdapter) permite integrarse con cualquier plataforma de chat. Consulta las implementaciones para Slack, Telegram y Discord en packages/adapters/src/ y podrás conectar plataformas locales como WeChat Work y Feishu.

Análisis en profundidad de la arquitectura de Archon: el núcleo es el motor de ejecución de DAG en el paquete @archon/workflows (dag-executor.ts) + el Orchestrator de @archon/core (ruteo de mensajes y gestión de sesiones). El YAML del flujo de trabajo se parsea y valida mediante loader.ts; los nodos se conectan formando el grafo topológico usando depends_on, y luego se ejecutan en orden topológico.

Estandarización de flujos de trabajo para equipos: sube .archon/workflows/ a Git; después de clonar, cada miembro del equipo recibe automáticamente el mismo conjunto de definiciones. Combinado con la inyección de normas de codificación del equipo en .archon/config.yaml, todo el contenido que genere la IA seguirá las reglas acordadas del equipo.