Archon 入門：Git Worktree で隔離＋DAG ワークフローで、AI プログラミングの不確実性を飼いならす

入門レベル | 約 20 分 | Archon のコア概念（Worktree 隔離、DAG ノードタイプ、YAML ワークフロー構文）を理解し、セットアップ方法を押さえ、典型的なワークフロー実務を 3 つ体験します。

---

プロジェクト概要

まず、事実を認めましょう。あなたが AI にバグ修正を頼むと、意図していない別の場所もついでに変えてしまうかもしれません。機能追加を頼むと、今回は通ったのに次に同じことをさせると、また説明しながら別の方向へ逸れていくことがあります。PR を書かせれば、毎回説明文の文体がバラバラです。

これらは AI がわざと邪魔をしているわけではなく、プロセス全体に「構造」がないから起きています。AI に届くのは曖昧な指示 1 文で、出力は当時のモデルの気分や状況（コンテキスト）次第で大きく変わります。

Archon がやることは、AI コーディングに構造を足すことです。YAML で開発プロセスを定義します——計画、検証、コードレビュー、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             # グローバル設定

---

手順（ステップごと）

Step 1：Archon をインストール

インストール方法は 2 通り。状況に合わせてどちらかを選んでください。

方法 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 だけを入れます。認証情報の自動設定や、プロジェクトへのワークフロー登録は行われないため、初期化を手動で行う必要があります。

Step 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/      # ワークフロー定義

Step 3：目的のプロジェクトを初期化

クイックインストールの場合は手動で初期化します：

cd your-project
archon init
# または Claude Code で: "Use archon to set up" と言う

初期化後に確認：

archon workflow list
# 17 個の内蔵ワークフローが表示されるはずです

Step 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：コードレビュー（テストが通ったら実行）
  - 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 を作成"

ノードタイプ一覧：

Step 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 内で操作し、ローカルの主ブランチには影響しない

あなたが目にするだいたいの流れ：

→ 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

Step 6：実務——アイデアから PR へ

手元に既存の Issue がない場合でも、アイデアが 1 つあれば十分です：

Use archon to add dark mode to the settings page

Archon は archon-idea-to-pr ワークフローで進めます：

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

この過程で AI は：

1. まずコードベースを探索し、現在のアーキテクチャを理解する
2. 実装計画を立てる（途中であなたが介入して修正できます）
3. loop ノードで、すべてのタスクが完了するまで繰り返し実装する
4. 検証を実行（bun run validate）
5. 並列で 5 つのコードレビュー Agent（スタイル、安全性、パフォーマンス、保守性、ドキュメント）を動かす
6. レビュー結果に基づいて self-fix
7. PR を作成し、完全なレビュー要約を添える

Step 7：カスタムワークフローの作成

内蔵ワークフローは良い出発点です。まず一つコピーして直せばOKです：

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 — 現在のワークフロー実行（run）が生成した成果物ディレクトリ
• $WORKFLOW_ID — ワークフロー実行 ID
• $BASE_BRANCH — メインブランチ名
• $LOOP_USER_INPUT — approval gate で人が入力したフィードバック

Step 8：Web UI＋複数プラットフォーム連携

Archon は CLI だけではありません。Web Dashboard も用意されています。素早く起動：

archon serve
#（初回は）Web UI をダウンロードし、http://localhost:4000 で起動

Web UI でできること：

• チャットページ — AI とリアルタイムに対話。ストリーミング出力やツール呼び出しを確認
• ダッシュボード — すべてのワークフローの実行状態を監視（すべてのプラットフォーム：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 が自分自身または下流ノードを指していないこと）を確かめてください。

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 と 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）から複雑なレビュー（archon-comprehensive-pr-review）までをカバーする完全なツールチェーンを提供します。その中でも archon-refactor-safely には type-check hook があり、archon-architect はアーキテクチャの健全性スキャンを行い、archon-ralph-dag は PRD の反復実装をサポートします。

カスタム Node タイプ：内蔵ノードに加えて、command: でカスタムコマンドファイル（Markdown）を呼び出したり、script: で TypeScript/Python スクリプトを実行したりできます（deps: による依存インストールと、timeout: によるタイムアウト制御に対応）。さらに approval: で人手による承認フローをカスタムできます。

プラットフォームアダプタ開発：Archon のアダプタ層（IPlatformAdapter）は、どんなチャットプラットフォームにも連携できるよう設計されています。packages/adapters/src/ の下にある Slack、Telegram、Discord の実装を参考にすれば、企業向けの WeChat や Fēishu（飛書）など国内サービスの連携も可能です。

Archon アーキテクチャの深掘り解析：中心は @archon/workflows パッケージ内の DAG 実行エンジン（dag-executor.ts）＋ @archon/core の Orchestrator（メッセージルーティングとセッション管理）です。ワークフロー YAML は loader.ts で解析・検証され、ノードは depends_on でトポロジカルグラフを構築し、その後トポロジカル順に実行されます。

チーム向けワークフローの標準化：.archon/workflows/ を Git にコミットしておけば、チームメンバーは毎回 clone 後に同じワークフロー定義を自動で取得できます。さらに .archon/config.yaml を使ってチームのコーディング規約を注入すれば、AI が生成するすべての内容がチームの取り決めに従います。