Введение в Archon: изоляция Git Worktree + DAG-воркфлоу — приручаем неопределённость при AI-программировании

Для новичков | около 20 минут | Вы освоите ключевые концепции Archon (изоляция Worktree, типы DAG-узлов, синтаксис YAML-воркфлоу), установку и настройку, а также 3 типовых практических сценария

---

Обзор проекта

Сначала признаем одну вещь: если вы попросите AI починить баг, он может заодно изменить то, что вы вообще не собирались трогать; если попросить добавить функциональность, на этот раз всё может заработать, а в следующий раз — опять запустить «то же самое» и снова сбиться с курса; если попросить написать PR, то в описании каждый раз будет разный стиль.

Эти проблемы — не потому, что AI намеренно «шалит». Просто во всём процессе отсутствует «структура». AI получает расплывчатую команду, а результат целиком зависит от настроения модели и контекста на момент выполнения.

Archon делает ровно одну вещь: добавляет структуру AI-программированию. Он описывает процесс разработки через YAML — планирование, проверка, code review, создание PR — и заранее фиксирует, что является каждым шагом, от чего зависит, и когда шаг считается завершённым. Затем он «встраивает» AI в этот каркас: пусть свободно творит внутри заданной структуры, а не мечется где попало.

Ещё одна ключевая возможность — изоляция Git Worktree: каждый воркфлоу запускается в отдельной git-ветке и рабочей директории, так что даже 5 задач, выполняемых параллельно, не будут наступать друг другу на пятки. Когда всё готово — выполняется слияние обратно с основной веткой; если что-то пошло не так — Worktree просто удаляется, быстро и чисто.

---

Портрет целевой аудитории

• Разработчики, использующие Claude Code или Codex
• Команды, которым нужна стандартизация AI-программирования
• Хотите получать от AI воспроизводимые, проверяемые результаты для пользователей

Базовые зависимости и окружение

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (нужно при полноценной установке)

Полное дерево структуры проекта

.archon/                     # На уровне проекта (генерируется setup wizard)
├── commands/                # Пользовательские команды (Markdown-файлы)
├── workflows/               # Пользовательские воркфлоу (YAML)
│   └── defaults/            # Встроенные шаблоны воркфлоу
└── config.yaml              # Конфигурация проекта (модель assistant и т.д.)

~/.archon/                   # Глобальная конфигурация пользователя
├── workspaces/owner/repo/  # Изолированная среда по GitHub-пользователю/репозиторию
│   ├── source/             # Клон репозитория или локальный путь
│   ├── worktrees/          # Директория изоляции Git Worktree
│   └── artifacts/          # Результаты воркфлоу (не попадают в git)
└── config.yaml             # Глобальная конфигурация

---

Пошаговые действия

Шаг 1: Установка Archon

Есть два способа — выберите подходящий под вашу ситуацию.

Способ 1: Полная установка (рекомендуется, 5 минут)

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

Затем введите для Claude Code: "Set up Archon". Он запустит интерактивный мастер настройки, поможет настроить учётные данные GitHub, выбрать интеграцию платформы, проверить подключение и в конце скопирует файлы навыков Archon в ваш целевой проект.

Способ 2: Быстрая установка (30 секунд, если Claude Code уже есть)

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

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

# или через Homebrew
brew install coleam00/archon/archon

Быстрая установка ставит только CLI и не настраивает автоматически учётные данные и воркфлоу внутри проекта — инициализацию нужно сделать вручную.

Шаг 2: Запуск Setup Wizard (для пользователей полной установки)

Если вы выбрали полную установку, setup wizard проведёт вас через следующие шаги:

1. Установка CLI — установка бинарника archon в PATH
2. Аутентификация GitHub — gh auth login, чтобы Archon получил право работать с вашим репозиторием
3. Выбор платформы — подключение Telegram / Slack / Discord (по желанию)
4. Целевой проект — выбор директории проекта для регистрации; wizard скопирует файл(ы) с навыком в .archon/

После завершения в вашем целевом проекте появятся следующие элементы:

.archon/
├── commands/       # Файлы команд, которые может вызывать AI
└── workflows/      # Определения воркфлоу

Шаг 3: Инициализация целевого проекта

Если вы использовали быструю установку, нужно выполнить инициализацию вручную:

cd your-project
archon init
# или скажите в Claude Code: "Use archon to set up"

После инициализации проверьте:

archon workflow list
# должно быть 17 встроенных воркфлоу

Шаг 4: Понимание структуры YAML-воркфлоу

Воркфлоу Archon — это DAG (ориентированный ациклический граф), где каждый узел соответствует шагу выполнения. Зависимости между узлами задаются через depends_on: Archon запускает узлы в топологическом порядке, а те, у которых нет зависимостей, могут выполняться параллельно.

Полный пример воркфлоу выглядит так:

# .archon/workflows/my-feature.yaml
nodes:
  # Узел 1: планирование (без зависимостей, выполняется сразу)
  - id: plan
    prompt: "Исследуйте репозиторий и сформируйте план реализации"

  # Узел 2: реализация (зависит от plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # Узел AI-цикла
      prompt: "Читайте план, выполните следующую задачу, запустите валидацию"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # В каждом цикле — новая AI-сессия

  # Узел 3: запуск тестов (зависит от implement, bash-узел — детерминированное выполнение)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Узел 4: code review (зависит от успешных тестов)
  - id: review
    depends_on: [run-tests]
    prompt: "Проверьте все изменения, сопоставьте с планом и исправьте любые проблемы"

  # Узел 5: ручное согласование (интерактивный gate)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Покажите содержимое изменений и отработайте любые замечания"
      until: APPROVED
    interactive: true                        # Пауза в ожидании ввода человека

  # Узел 6: создание PR
  - id: create-pr
    depends_on: [approve]
    prompt: "Отправьте код и создайте Pull Request"

Сводка по типам узлов:

Шаг 5: Практика — от GitHub Issue до PR

Один из самых популярных воркфлоу: вы даёте GitHub Issue на вход, на выход получаете PR.

Просто скажите в Claude Code:

Use archon to fix issue #42

Archon автоматически:

1. Создаёт изолированную ветку Worktree (archon/fix-42-xxx)
2. Запускает воркфлоу archon-fix-github-issue: классификация проблемы → исследование → планирование → реализация → валидация → создание PR
3. Если тесты не проходят — автоматически переходит в self-fix-цикл
4. По завершении вы работаете прямо в Worktree, не влияя на вашу локальную основную ветку

Пример того, что вы увидите в процессе:

→ Создание изолированного worktree на ветке archon/fix-42-abc...
→ Планирование...
→ Исследование issue #42...
→ Реализация (задача 1/3)...
→ Реализация (задача 2/3)...
→ Тесты не проходят — итерация...
→ Тесты проходят после 2 итераций
→ Code review завершён — 0 issues
→ PR готов: https://github.com/you/project/pull/47

Шаг 6: Практика — от идеи до PR

Если у вас нет готового Issue, а есть только идея:

Use archon to add dark mode to the settings page

Archon использует воркфлоу archon-idea-to-pr:

→ Идея фичи → plan → implement → validate → PR → 5 параллельных code review → self-fix

В процессе AI будет:

1. Сначала исследовать репозиторий и понять текущую архитектуру
2. Сформировать план реализации (вы можете вмешаться и поменять его по ходу)
3. В цикле реализовывать задачи через loop-узел, пока всё не будет выполнено
4. Запустить валидацию (bun run validate)
5. Параллельно прогнать 5 агентов для code review (стиль, безопасность, производительность, сопровождаемость, документация)
6. На основе ответов self-fix
7. Создать PR и приложить полный итоговый summary code review

Шаг 7: Написание пользовательских воркфлоу

Встроенные воркфлоу — отличный старт: просто скопируйте один и измените.

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

Затем отредактируйте YAML-файл. Например, если вы хотите убрать этап ручного согласования и просто объединить:

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Проанализируйте требования и составьте план реализации"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Читайте план, реализуйте следующую задачу, отмечайте завершение"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

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

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Отправьте код, создайте Pull Request, используя следующий шаблон:..."

Замена переменных: в воркфлоу можно использовать встроенные переменные:

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

• $1, $2, $3 — позиционные параметры
• $ARGUMENTS — все параметры
• $ARTIFACTS_DIR — директория артефактов текущего запуска воркфлоу
• $WORKFLOW_ID — ID запуска воркфлоу
• $BASE_BRANCH — имя основной ветки
• $LOOP_USER_INPUT — обратная связь, которую человек ввёл в approval gate

Шаг 8: Web UI + подключение к нескольким платформам

Archon — это не только CLI: у него есть полноценный Web Dashboard. Быстрый запуск:

archon serve
# скачает Web UI (в первый раз), затем запустите его на http://localhost:4000

Web UI предоставляет:

• Страница чата — общение с AI в реальном времени: смотрите потоковый вывод и вызовы инструментов
• Dashboard — мониторинг статуса всех запусков воркфлоу (из всех платформ: CLI, Slack, Telegram и т.д.)
• Workflow Builder — визуальный DAG-редактор: создавайте воркфлоу перетаскиванием
• Workflow Execution — пошаговый просмотр выполнения любого воркфлоу

Подключение чат-платформ (по желанию):

После подключения вы можете запускать воркфлоу прямо из Slack или Telegram, а результаты будут отправляться в то же самое диалоговое окно в реальном времени.

---

Частые проблемы и диагностика

1. Claude Code не находит команду Archon

Обычно это происходит, если после быстрой установки не запускали setup wizard:

# запустите setup заново
cd your-project
claude
# скажите "Set up Archon" или "Use archon to set up"

# или вручную обновите файлы навыков
archon update

2. Не удалось создать Worktree

Самая частая причина — недостаточно места на диске или проблемы с правами:

# проверить место на диске
df -h

# проверить версию git (Worktree поддерживается начиная с 2.23)
git --version

# вручную очистить старые Worktree
archon isolation cleanup

3. Список воркфлоу пуст

# убедитесь, что директория .archon/workflows/ существует
ls .archon/workflows/

# вручную запустите поиск воркфлоу
archon workflow list --verbose

Если встроенные воркфлоу тоже отсутствуют — проверьте версию Archon:

archon --version

4. Цикл зависимостей в YAML-узлах

Если depends_on образует цикл, Archon выдаст ошибку:

Error: Circular dependency detected in workflow

Решение: проверьте YAML-файл и убедитесь, что узлы не зависят друг от друга — то есть depends_on одного узла не указывает на него самого или на его downstream-узел.

5. Approval Gate в CLI не реагирует

Approval Gate требует ручного вмешательства. В CLI воркфлоу приостановится и будет ждать ввод:

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

Если запуск идёт через Web UI, узлы с interactive: true автоматически показывают кнопки согласования.

6. Переключение PostgreSQL vs SQLite

По умолчанию Archon использует SQLite (без настройки), а данные лежат в ~/.archon/archon.db. Если вы хотите переключиться на PostgreSQL:

# запустить PostgreSQL (Docker)
docker-compose --profile with-db up -d postgres

# задать строку подключения в .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# перезапустить Archon
archon serve

---

Дальнейшее чтение / направление развития

Подробно о 17 встроенных воркфлоу: Archon предоставляет полный набор инструментов — от повседневной помощи (archon-assist) до сложного code review (archon-comprehensive-pr-review). Среди них archon-refactor-safely с hooks для type-check, archon-architect для сканирования «здоровья» архитектуры, archon-ralph-dag поддерживает итерации реализации PRD.

Собственные типы узлов: кроме встроенных узлов можно писать command: для вызова файла пользовательской команды (Markdown), script: для запуска TypeScript/Python-скриптов (поддержка deps: для установки зависимостей и timeout: для контроля тайм-аутов), а также approval: для собственной ручной процедуры согласования.

Разработка адаптеров платформ: слой адаптеров Archon (IPlatformAdapter) поддерживает подключение любой чат-платформы. Смотрите реализации Slack/Telegram/Discord в packages/adapters/src/ — так можно подключать и корпоративный WeChat, Feishu и другие локальные платформы.

Углублённый разбор архитектуры Archon: основа — движок выполнения DAG в пакете @archon/workflows (dag-executor.ts) + Orchestrator из @archon/core (маршрутизация сообщений и управление сессиями). YAML воркфлоу парсится и валидируется через loader.ts, зависимости между узлами формируют топологический граф через depends_on, после чего выполнение идёт в топологическом порядке.

Стандартизация воркфлоу в команде: закоммитьте .archon/workflows/ в Git — после каждого clone участники команды автоматически получают одни и те же определения воркфлоу. В сочетании с внедрением командных код-стандартов через .archon/config.yaml любой контент, сгенерированный AI, будет следовать договорённостям вашей команды.