Guia de entrada no Archon: isolamento com Git Worktree + fluxo DAG, domando a incerteza da programação com IA

Para iniciantes | ~20 minutos | Você vai dominar os conceitos centrais do Archon (isolamento via Worktree, tipos de nós do DAG, sintaxe de workflow em YAML), a instalação e a configuração — além de colocar em prática 3 fluxos de trabalho típicos

---

Visão geral do projeto

Vamos admitir um fato: quando você pede para a IA corrigir um bug, ela pode acabar alterando também lugares que você não queria mexer; quando pede para adicionar uma funcionalidade, desta vez até roda — mas na próxima, a mesma instrução gera explicações e se desvia do caminho; quando você manda a IA escrever um PR, o estilo das descrições muda a cada vez.

Esses problemas não acontecem porque a IA está “sabendo bagunçar”, e sim porque todo o processo não tem “estrutura”. A IA recebe uma instrução vaga, e a saída depende totalmente do humor do modelo e do contexto naquele momento.

O Archon faz exatamente isso: dar estrutura à programação assistida por IA. Ele usa YAML para definir o fluxo de desenvolvimento — planejamento, validação, revisão de código, criação de PR — deixando claro o que acontece em cada etapa, quais dependências existem e quando cada parte pode ser considerada concluída. Em seguida, encaixa a IA dentro desse framework para ela poder “improvisar” dentro da estrutura, e não sair disparando sem controle.

Outra capacidade central é o isolamento via Git Worktree: cada workflow roda em uma branch e em um diretório de trabalho independentes; mesmo se 5 tarefas rodarem em paralelo, elas não se pisam. Quando a tarefa termina, você faz o merge de volta na branch principal; quando falha, basta apagar o Worktree e pronto — limpo e direto.

---

Perfil de leitores-alvo

• Desenvolvedores que usam Claude Code ou Codex
• Times que precisam padronizar fluxos de programação com IA
• Quem quer que a IA gere resultados repetíveis e revisáveis por humanos

Dependências e ambiente essenciais

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (necessária na instalação completa)

Estrutura completa do projeto

.archon/                     # Por nível de projeto (gerado pelo setup wizard)
├── commands/                # Comandos customizados (arquivos Markdown)
├── workflows/               # Workflows customizados (YAML)
│   └── defaults/            # Templates de workflows embutidos
└── config.yaml              # Configuração do projeto (modelo do assistant etc.)

~/.archon/                   # Configuração global por usuário
├── workspaces/owner/repo/  # Ambientes isolados por usuário/ repositório do GitHub
│   ├── source/             # Clone do repositório ou caminho local
│   ├── worktrees/          # Diretório de isolamento do Git Worktree
│   └── artifacts/          # Artefatos do workflow (não entram no git)
└── config.yaml             # Configuração global

---

Passo a passo

Etapa 1: Instalar o Archon

Há duas formas de instalar — escolha uma de acordo com seu cenário.

Opção 1: Instalação completa (recomendada, ~5 minutos)

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

Depois, diga ao Claude Code: "Set up Archon". Ele vai iniciar um guia interativo, orientar na configuração das credenciais do GitHub, escolher a integração de plataforma, testar a conexão e, por fim, copiar os arquivos de habilidades do Archon para seu projeto alvo.

Opção 2: Instalação rápida (~30 segundos, caso você já tenha 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

A instalação rápida instala apenas o CLI; não configura automaticamente credenciais nem workflows dentro do projeto. Você precisará fazer a inicialização manualmente.

Etapa 2: Rodar o Setup Wizard (para quem fez instalação completa)

Se você usou a instalação completa, o setup wizard vai conduzir você pelos passos a seguir:

1. Instalação do CLI — instalar o binário archon no PATH
2. Autenticação no GitHub — gh auth login, para o Archon ter permissão para operar seu repositório
3. Seleção de plataforma — se deve integrar com Telegram / Slack / Discord (opcional)
4. Projeto alvo — escolher o diretório do projeto a ser registrado; o wizard copia o arquivo de habilidades .archon/ para dentro

Ao final, seu projeto alvo terá adicionado estas coisas:

.archon/
├── commands/       # Arquivos de comandos que a IA pode chamar
└── workflows/      # Definições de workflows

Etapa 3: Inicializar o projeto alvo

Se você fez a instalação rápida, precisa inicializar manualmente:

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

Depois, valide:

archon workflow list
# deve listar 17 workflows embutidos

Etapa 4: Entender a estrutura de workflow YAML

Os workflows do Archon são um DAG (grafo acíclico direcionado), e cada nó representa um passo de execução. As dependências entre nós são declaradas via depends_on; o Archon executa na ordem topológica, e nós sem dependências podem rodar em paralelo.

Um workflow completo fica assim:

# .archon/workflows/my-feature.yaml
nodes:
  # Nó 1: planejamento (sem dependências; executa direto)
  - id: plan
    prompt: "Explore o repositório e defina um plano de implementação"

  # Nó 2: implementação (depende de plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # Nó em loop da IA
      prompt: "Leia o plano, implemente a próxima tarefa e rode a validação"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # Em cada loop, usar uma nova sessão de IA

  # Nó 3: rodar testes (depende de implement; nó bash; execução puramente determinística)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Nó 4: revisão de código (depende de testes aprovados)
  - id: review
    depends_on: [run-tests]
    prompt: "Revise todas as alterações e corrija qualquer problema conforme o plano"

  # Nó 5: aprovação manual (gate interativo)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Mostre o conteúdo das mudanças e responda a qualquer feedback"
      until: APPROVED
    interactive: true                        # Pausa para aguardar input humano

  # Nó 6: criar PR
  - id: create-pr
    depends_on: [approve]
    prompt: "Envie o código e crie um Pull Request"

Tipos de nós (visão geral):

Etapa 5: Prática — de um Issue do GitHub até um PR

Este é um dos workflows mais usados: você fornece um GitHub Issue como entrada e obtém um PR como saída.

No Claude Code, diga diretamente:

Use archon to fix issue #42

O Archon faz automaticamente:

1. Criar uma branch de Worktree isolada (archon/fix-42-xxx)
2. Executar o workflow archon-fix-github-issue: classificar o issue → investigar → planejar → implementar → validar → criar PR
3. Se os testes falharem, entrar automaticamente no ciclo self-fix
4. Ao final, operar dentro do Worktree, sem afetar sua branch principal local

O processo que você vê, de forma geral:

→ 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

Etapa 6: Prática — de uma ideia até um PR

Se você não tem um Issue pronto, mas tem uma ideia:

Use archon to add dark mode to the settings page

O Archon usa o workflow archon-idea-to-pr:

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

Durante o processo, a IA:

1. Explora o repositório e entende a arquitetura atual
2. Define um plano de implementação (você pode intervir e modificar no meio do caminho)
3. Usa um nó loop para implementar repetidamente até todas as tarefas ficarem completas
4. Executa validação (bun run validate)
5. Roda em paralelo 5 Agents de revisão de código (estilo, segurança, performance, manutenibilidade, documentação)
6. Aplica self-fix com base no retorno da revisão
7. Cria o PR e anexa um resumo completo da revisão

Etapa 7: Escrever workflows customizados

Workflows embutidos são um ótimo ponto de partida: copie um e ajuste.

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

Depois, edite o arquivo YAML. Por exemplo, se você quer remover a etapa de aprovação manual, basta fazer a integração direta:

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Analisar os requisitos e definir um plano de implementação"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Ler o plano, implementar a próxima tarefa e marcar como concluída"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

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

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Enviar o código, criar o Pull Request e usar o seguinte template:..."

Substituição de variáveis: no workflow, é possível usar estas variáveis embutidas:

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

• $1, $2, $3 — parâmetros posicionais
• $ARGUMENTS — todos os parâmetros
• $ARTIFACTS_DIR — diretório de artefatos gerados na execução atual do workflow
• $WORKFLOW_ID — ID da execução do workflow
• $BASE_BRANCH — nome da branch principal
• $LOOP_USER_INPUT — feedback digitado manualmente no approval gate

Etapa 8: Web UI + integração com múltiplas plataformas

O Archon não é só CLI; ele tem um Web Dashboard completo. Inicialização rápida:

archon serve
# baixar a Web UI (na primeira vez) e depois iniciar em http://localhost:4000

A Web UI oferece:

• Página de Chat — conversar em tempo real com a IA, acompanhando output em streaming e chamadas de ferramentas
• Dashboard — monitorar o status de todas as execuções de workflows (de todas as plataformas: CLI, Slack, Telegram etc.)
• Workflow Builder — editor visual de DAG, com criação por arrastar e soltar
• Workflow Execution — ver passo a passo a execução de qualquer workflow

Integração com plataformas de chat (opcional):

Depois de integrar, você consegue disparar workflows diretamente no Slack ou Telegram, com os resultados sendo enviados em tempo real para a mesma conversa.

---

Solução de problemas (FAQ)

1. O Claude Code não encontra o comando Archon

Isso normalmente acontece se, após uma instalação rápida, você não rodou o setup wizard:

# execute o setup novamente
cd your-project
claude
# diga "Set up Archon" ou "Use archon to set up"

# ou atualizar os arquivos de skills manualmente
archon update

2. Falha ao criar Worktree

As causas mais comuns são falta de espaço em disco ou problemas de permissões:

# verificar espaço em disco
df -h

# verificar versão do git (Worktree exige 2.23+)
git --version

# limpar Worktree antigo manualmente
archon isolation cleanup

3. A lista de workflows está vazia

# confirmar se o diretório .archon/workflows/ existe
ls .archon/workflows/

# buscar/descobrir workflows disparando manualmente
archon workflow list --verbose

Se os workflows embutidos também não aparecerem, verifique a versão do Archon:

archon --version

4. Ciclo de dependência entre nós YAML

Se depends_on criar um ciclo, o Archon vai retornar um erro:

Error: Circular dependency detected in workflow

Como resolver: verifique o arquivo YAML e garanta que nenhum nó dependa mutuamente (isto é, que o depends_on de um nó não aponte para ele mesmo nem para um nó “abaixo” na cadeia).

5. Approval Gate interativo não responde no CLI

O Approval Gate requer intervenção humana. No CLI, o workflow pausa e aguarda a entrada:

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

Se estiver rodando pela Web UI, nós com interactive: true vão exibir automaticamente os botões de aprovação.

6. Alternar PostgreSQL vs SQLite

Por padrão, o Archon usa SQLite (sem configuração). Os dados ficam em ~/.archon/archon.db. Se você quiser trocar para PostgreSQL:

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

# definir a connection string em .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# reiniciar o Archon
archon serve

---

Leitura adicional / caminhos de aprimoramento

Detalhe de 17 workflows embutidos: o Archon oferece uma cadeia completa de ferramentas — de assistências do dia a dia (archon-assist) a revisões mais complexas (archon-comprehensive-pr-review). Entre eles, archon-refactor-safely traz hooks de type-check, archon-architect faz uma varredura de saúde da arquitetura e archon-ralph-dag suporta implementação iterativa de PRD.

Tipos de Node customizados: além dos nós embutidos, também é possível escrever command: para chamar um arquivo de comando customizado (Markdown), script: para rodar scripts TypeScript/Python (com suporte a deps: para instalar dependências e timeout: para controlar o tempo), e approval: para definir um fluxo de aprovação humana customizado.

Desenvolvimento de adaptadores de plataforma: a camada de adaptadores do Archon (IPlatformAdapter) suporta conectar a qualquer plataforma de chat. Veja as implementações no diretório packages/adapters/src/ para Slack, Telegram e Discord; assim você pode conectar plataformas locais como WeChat corporativo e Feishu.

Análise profunda da arquitetura do Archon: o núcleo é o motor de execução DAG no pacote @archon/workflows (dag-executor.ts) + o Orchestrator do @archon/core (roteamento de mensagens e gerenciamento de sessões). O YAML do workflow é interpretado e validado via loader.ts; os nós usam depends_on para construir o grafo topológico e, então, a execução acontece na ordem topológica.

Padronização de workflows para times: envie .archon/workflows/ para o Git. Após clonar, cada membro do time recebe automaticamente a mesma definição de workflows. Combinado com a injeção de padrões de codificação no .archon/config.yaml, todo conteúdo gerado pela IA segue os acordos do time.