아콘(Archon) 입문: Git Worktree 격리 + DAG 워크플로로 AI 코딩의 불확실성을 길들이기

입문급 | 약 20분 | Archon의 핵심 개념(Worktree 격리, DAG 노드 타입, YAML 워크플로 문법)을 익히고, 설치/설정 방법과 3가지 전형적인 워크플로 실습을 진행합니다

---

프로젝트 소개

먼저 한 가지 사실부터 인정하자면: AI에게 버그를 고치게 시키면, 원치 않았던 부분까지 “덤으로” 바꿔버릴 수도 있습니다. 기능을 추가하라고 하면, 이번엔 돌아가지만 다음에도 똑같이 해보면 또 말만 번지르르하고 엇나갈 수 있어요. 그리고 PR을 작성시키면, 설명(서술) 스타일이 매번 달라집니다.

이 문제들은 AI가 일부러 훼방을 놓는 게 아닙니다. 전체 과정에 「구조」가 없기 때문이에요. AI가 받는 건 애매한 지시 한 줄뿐이고, 출력은 그때그때 모델의 컨디션과 컨텍스트에 전적으로 달려버립니다.

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/                # 커스텀 명령(마크다운 파일)
├── workflows/               # 커스텀 워크플로(YAML)
│   └── defaults/            # 내장 워크플로 템플릿
└── config.yaml              # 프로젝트 설정(assistant 모델 등)

~/.archon/                   # 사용자 레벨 전역 설정
├── workspaces/owner/repo/  # GitHub 사용자/레포 기준 격리 환경
│   ├── source/             # 레포 클론 또는 로컬 경로
│   ├── worktrees/          # Git Worktree 격리 디렉터리
│   └── artifacts/          # 워크플로 산출물(깃에 들어가지 않음)
└── 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: 코드 리뷰(테스트 통과에 의존)
  - id: review
    depends_on: [run-tests]
    prompt: "모든 변경 사항을 검토하고 계획에 맞지 않는 부분을 수정"

  # 노드 5: 수동 승인(인터랙티브 게이트)
  - 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 안에서 작업하므로 로컬 메인 브랜치에 영향을 주지 않음

여러분이 보게 되는 대략적인 흐름:

→ 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

6단계: 실습 — 아이디어에서 PR까지

이미 있는 Issue가 없고, 아이디어만 있다면:

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개를 병렬로 실행합니다(스타일, 보안, 성능, 유지보수성, 문서)
6. 리뷰 피드백에 따라 self-fix
7. PR을 생성하고, 전체 리뷰 요약을 첨부합니다

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 — 현재 워크플로 실행(run)의 산출물 디렉터리
• $WORKFLOW_ID — 워크플로 실행 ID
• $BASE_BRANCH — 메인 브랜치 이름
• $LOOP_USER_INPUT — approval gate에서 사람이 입력한 피드백

8단계: Web UI + 멀티 플랫폼 연동

Archon은 단순 CLI가 아닙니다. 완전한 Web Dashboard가 있습니다. 빠르게 실행:

archon serve
# Web UI 다운로드(처음 1회), 그 후 http://localhost:4000에서 실행

Web UI가 제공하는 것들:

• Chat 페이지 — 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이 자기 자신이나 하위 노드를 가리키고 있지 않은지).

5. CLI에서 인터랙티브 Approval Gate가 반응하지 않음

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)부터 복잡한 리뷰(archon-comprehensive-pr-review)까지, 완전한 도구 체인을 제공합니다. 그중 archon-refactor-safely는 type-check hooks를 포함하고, archon-architect는 아키텍처 건강도 스캔을 수행하며, archon-ralph-dag는 PRD 반복 구현을 지원합니다.

커스텀 Node 타입: 내장 노드 외에도 command:로 커스텀 명령 파일(마크다운)을 호출할 수 있고, script:로 TypeScript/Python 스크립트를 실행할 수 있습니다( deps:로 의존성 설치, timeout:으로 타임아웃 제어 지원 ). 또한 approval:으로 커스텀 수동 승인 플로우도 만들 수 있습니다.

플랫폼 어댑터 개발: Archon의 어댑터 계층(IPlatformAdapter)은 어떤 채팅 플랫폼이든 연동할 수 있도록 지원합니다. packages/adapters/src/ 아래의 Slack, Telegram, Discord 구현을 참고하면, 국내 플랫폼인 기업 위챗, 미팅 앱 등에도 연동할 수 있습니다.

Archon 아키텍처 심층 분석: 핵심은 @archon/workflows 패키지의 DAG 실행 엔진(dag-executor.ts)과 @archon/core의 Orchestrator(메시지 라우팅과 세션 관리)입니다. 워크플로 YAML은 loader.ts로 파싱/검증되고, 노드는 depends_on로 위상 그래프를 만든 뒤 위상 순서대로 실행됩니다.

팀 워크플로 표준화: .archon/workflows/를 Git에 커밋해 두면, 팀원들이 매번 clone한 뒤 동일한 워크플로 정의를 자동으로 얻습니다. .archon/config.yaml에 팀의 코딩 규칙을 주입하면, AI가 생성하는 모든 내용이 팀의 합의된 방식에 맞춰지게 됩니다.