안녕하세요! 오늘은 AI 코딩 에이전트를 위한 오픈소스 harness builder인 Archon v0.3.6에 대해 알아보겠습니다. Archon은 Claude Code SDK, OpenAI Codex SDK를 harness하여 구조화된 워크플로우로 변환하는 프레임워크입니다. 특히 YAML 정의 DAG 워크플로우로 AI 코딩을 결정론적(deterministic)이고 반복 가능한 파이프라인으로 만들어줍니다. 이 블로그에서는 Archon의 핵심 기능, Bun 설치 방법, 실제 활용 사례, CLI 사용법에 대해 상세히 설명하겠습니다.
"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."
🤖 Archon이란 무엇인가?
Archon은 "세계 최초의 오픈소스 AI 코딩 harness builder"입니다. Cole Medin(coleam00)이 개발한 이 프레임워크는 현재 GitHub 18k+ 스타를 기록하며 AI 코딩 에이전트 분야에서 급부상하고 있습니다.
Harness Builder란 AI 코딩 에이전트를 감싸서(wrap) 구조화된 워크플로우로 변환하는 시스템입니다. 자유형식(form-free) AI 상호작용을 결정론적(deterministic), 버전 관리 가능한 파이프라인으로 바꿉니다.
Archon의 핵심 가치는 "AI 코딩을 결정론적으로 만든다"는 점입니다. Claude Code나 OpenAI Codex CLI는 강력한 도구지만, 실행 결과가 예측 불가능할 수 있습니다. Archon은 이를 YAML 정의 워크플로우로 감싸서:
- AI 창의적 단계와 결정론적 명령 단계(테스트 실행 등)를 교배 배치
- 테스트가 통과할 때까지 반복 루프 실행
- 프로젝트 요구사항에 정확히 부합하는 결과 보장
- 모든 워크플로우를 버전 관리 시스템에서 추적
⚙️ Archon 핵심 아키텍처
Archon v0.3.6은 Bun + TypeScript + SQLite/PostgreSQL로 구성된 통합 서비스 아키텍처를 사용합니다:
| 패키지 | 역할 | 설명 |
|---|---|---|
| @archon/server | API 서버 | HTTP API + SSE streaming + Web UI 서빙 |
| @archon/web | Web UI | React + Vite + Tailwind + shadcn/ui |
| @archon/workflows | 워크플로우 엔진 | DAG 실행, YAML 로더, 루프 노드 |
| @archon/providers | AI Provider | Claude SDK, Codex SDK 연동 |
| @archon/git | Git 작업 | Worktree, Branch, PR 관리 |
| @archon/cli | CLI | 터미널에서 워크플로우 실행 |
단일 서비스 구조
Archon은 단일 포트로 모든 기능을 제공합니다:
- 기본 포트: 3000 (변경 가능)
- Web UI:
http://localhost:3000 - API:
http://localhost:3000/api/* - SSE Streaming:
http://localhost:3000/api/stream/*
핵심 기능:
- Workflow Engine: YAML 정의 DAG 워크플로우 실행
- Git Worktree Isolation: 각 워크플로우가 독립 worktree에서 실행
- Multi-Platform Adapter: Slack, Telegram, GitHub, Discord, Web
- Session Management: AI 세션 추적 및 재개
Archon은 "Remote Agentic Coding Platform"으로 Claude Code나 Codex CLI를 원격에서 제어하고, Slack, Telegram, GitHub 등에서 AI 코딩을 실행할 수 있는 시스템입니다.
🚀 Archon 핵심 기능
1. YAML 정의 워크플로우
Archon의 가장 강력한 기능은 YAML 파일로 워크플로우 정의입니다. 이를 통해:
- 워크플로우를 버전 관리(Git) 가능
- 재사용 및 공유 가능
- 팀 간 표준화된 프로세스
- CI/CD 파이프라인과 통합
2. Knowledge & Task Management
Archon은 AI 코딩 에이전트를 위한 지식 기반과 작업 관리 시스템을 제공합니다:
- Knowledge Base: 프로젝트 문서, 코드 스니펫, 패턴 저장
- Task Tracking: 작업 상태, 진행률, 결과 관리
- Context Curation: AI가 필요한 컨텍스트 자동 추출
💡 핵심 가치: "어떤 프로젝트를 빌드하든, 새 프로젝트든 기존 프로젝트든 - Archon의 지식 및 작업 관리 기능은 모든 AI 코딩의 출력을 개선합니다."
3. Iterative Feedback Loops
Archon은 반복 루프를 통해 AI 코딩 결과를 개선합니다:
- 테스트 실행 → 결과 분석 → 수정 → 재실행
- 테스트가 통과할 때까지 자동 반복
- Planning → Execution → Feedback → Refinement 사이클
4. Multi-Agent Orchestration
Archon은 "AI 에이전트 군대"를 자율적으로 운영할 수 있습니다:
- 여러 AI 에이전트가 협업
- 각 에이전트가 특정 역할 담당
- 자동 작업 분배 및 결과 통합
🚀 Archon 설치 가이드
사전 요구사항
- Bun 1.3+ (Node.js 대신 Bun 사용)
- Claude Code CLI 또는 Codex CLI 설치 및 로그인
- Git 설치
설치 방법 1: Bun 직접 실행 (권장)
# 1. GitHub에서 클론
git clone https://github.com/coleam00/Archon.git archon-ai
cd archon-ai
# 2. 환경 변수 설정 (.env 파일 생성)
cp .env.example .env
# .env 내용:
# CLAUDE_USE_GLOBAL_AUTH=true
# PORT=3005 (기본 3000과 충돌 방지)
# DEFAULT_AI_ASSISTANT=claude
# 3. 의존성 설치 (Bun 사용)
bun install
# 4. Web UI 빌드
bun run build:web
# 5. 서버 시작
PORT=3005 bun run dev
설치 방법 2: Docker Compose
Docker로 실행하면 프로덕션 배포에 적합합니다:
# 1. 환경 변수 설정
cp .env.example .env
# 2. Docker로 실행
docker compose up -d
# 3. 로그 확인
docker compose logs -f
알리바바 코딩플랜 GLM-5 사용자 설정
⚠️ 중요: Archon은 기본적으로 Claude SDK 또는 Codex SDK를 사용합니다. GLM-5 API를 사용하려면 추가 설정이 필요합니다.
알리바바 코딩플랜(CodingPlan)은 GLM-5 모델을 Anthropic-compatible API 형식으로 제공합니다. Claude Code가 이미 GLM-5로 설정된 경우, Archon에서도 동일하게 사용할 수 있습니다. 하지만 registry.ts 수정이 필요합니다.
문제 원인
Archon의 model validation에서 Claude provider는 기본적으로 sonnet, opus, haiku, claude-*, inherit만 인식합니다. glm-5 모델은 이 리스트에 없어서 validation 에러가 발생합니다.
해결 방법
방법 1: config.yaml 설정
# ~/.archon/config.yaml
assistants:
claude:
model: glm-5 # GLM-5 모델 설정방법 2: registry.ts 수정 (필수)
packages/providers/src/registry.ts 파일에서 Claude provider aliases에 glm-5를 추가해야 합니다:
// packages/providers/src/registry.ts
// Claude provider isModelCompatible 함수 수정
isModelCompatible: (model: string): boolean => {
const aliases = ['sonnet', 'opus', 'haiku', 'glm-5']; // ← glm-5 추가
return aliases.includes(model) || model.startsWith('claude-') || model === 'inherit';
},방법 3: 워크플로우에서 직접 명시
워크플로우 YAML 파일의 노드에 직접 model: glm-5를 명시할 수도 있습니다:
# .archon/workflows/my-workflow.yaml
nodes:
- id: my-node
model: glm-5 # 직접 명시
prompt: "..."💡 권장: 방법 2 (registry.ts 수정)를 사용하면 모든 워크플로우에서 glm-5가 자동 인식됩니다. 수정 후 서버를 재시작하세요.
서비스 접속 URL
| 기능 | URL | 설명 |
|---|---|---|
| Web UI | http://localhost:3005 |
React 기반 웹 인터페이스 |
| API Health | http://localhost:3005/api/health |
서버 상태 확인 |
| Workflows API | http://localhost:3005/api/workflows |
워크플로우 목록 |
| SSE Streaming | http://localhost:3005/api/stream/:id |
실시간 메시지 스트리밍 |
🔗 CLI로 워크플로우 실행
터미널에서 워크플로우 실행
Archon CLI를 사용하여 터미널에서 직접 워크플로우를 실행할 수 있습니다:
# 워크플로우 목록 확인
bun run cli workflow list
# 워크플로우 실행
bun run cli workflow run archon-assist "이 프로젝트 구조를 설명해줘"
# 워크플로우 상태 확인
bun run cli workflow status
# PR 생성 워크플로우
bun run cli workflow run archon-idea-to-pr "새로운 기능 추가"Web UI에서 워크플로우 관리
Web UI(http://localhost:3005)에서 워크플로우를 시각적으로 관리할 수 있습니다:
- 워크플로우 빌더: YAML 워크플로우 생성 및 수정
- 실행 상태: 실시간 워크플로우 진행 상황
- 프로젝트 관리: Codebase 등록 및 환경 변수 설정
- 채팅 인터페이스: AI와 직접 대화하며 워크플로우 실행
📊 다른 도구와 비교
| 기능 | Archon | Claude Code | Cursor | n8n |
|---|---|---|---|---|
| 워크플로우 정의 | YAML | 자연어 | 자연어 | Visual |
| 버전 관리 | ✅ Git | ❌ | ❌ | ❌ |
| MCP 서버 | ✅ | ✅ Client | ✅ Client | ❌ |
| Knowledge Base | ✅ | ❌ | ❌ | ❌ |
| Task Management | ✅ | ❌ | ❌ | ✅ |
| 반복 루프 | ✅ Auto | ❌ | ❌ | ✅ Manual |
| 오픈소스 | ✅ | ❌ | ❌ | ✅ |
| GitHub 스타 | 13.9k | - | - | 50k+ |
💡 실제 활용 사례
1. 프로젝트 지식 기반 구축
기존 프로젝트의 문서, 코드 패턴, 아키텍처를 Archon Knowledge Base에 저장합니다. 새 기능 개발 시 AI가 이 지식을 참조하여 프로젝트 스일에 맞는 코드를 생성합니다.
2. 테스트-수정 반복 자동화
워크플로우에서 "테스트 실행 → 실패 분석 → 수정 → 재테스트" 루프를 자동으로 실행합니다. 테스트가 통과할 때까지 AI가 자율적으로 코드를 수정합니다.
3. AI 에이전트 자동 생성
Archon의 "Agenteer" 기능으로 새 AI 에이전트를 자율적으로 생성합니다. Pydantic AI, LangGraph 등 다양한 프레임워크의 에이전트를 빌드합니다.
4. 팀 협업 워크플로우
YAML 워크플로우를 Git에 저장하여 팀 전체가 표준화된 AI 코딩 프로세스를 사용합니다. CI/CD 파이프라인과 통합하여 자동화 수준을 높입니다.
⚠️ 한계점과 주의사항
⚠️ Claude Code 세션 내 실행: Claude Code 세션 내에서 워크플로우를 실행하면 "hang"이 발생할 수 있습니다. 일반 터미널에서 archon serve로 실행하는 것이 권장됩니다.
- Claude Code 또는 Codex CLI 필요: Archon은 이 두 도구를 harness합니다
- Bun 환경: Node.js 대신 Bun 1.3+ 필요
- YAML 학습: 워크플로우 정의를 위해 YAML 문법 학습 필요
- Git Worktree: 각 워크플로우가 독립 worktree에서 실행됩니다
🎯 맺음말
지금까지 Archon v0.3.6에 대해 알아보았습니다. Archon은 GitHub 13.9k 스타를 기록한 세계 최초의 오픈소스 AI 코딩 harness builder입니다. 특히 YAML 정의 워크플로우, DAG 실행, Git Worktree Isolation, 반복 루프 기능을 통해 AI 코딩을 결정론적이고 반복 가능한 파이프라인으로 변환합니다.
Archon은 Claude Code CLI 또는 Codex CLI를 harness하여 작동합니다. 이미 Claude Code를 사용 중이면 설정을 자동으로 로드합니다. Bun으로 직접 실행하면 더 빠르고 편리합니다.
여러분도 한번 Archon을 GitHub에서 직접 설치해보시길 추천드리면서 저는 다음 시간에 더 유익한 정보를 가지고 다시 찾아뵙겠습니다. 감사합니다.
📚 참고 문헌 및 출처
- Cole Medin. (2026). Archon: The first open-source harness builder for AI coding. Retrieved from https://github.com/coleam00/Archon
- MCP Market. (2026). Archon: Autonomous AI Agent Builder & Optimizer. Retrieved from https://mcpmarket.com/server/archon
- MindStudio. (2026). What Is the Archon Harness Builder?. Retrieved from https://www.mindstudio.ai/blog/what-is-archon-harness-builder-ai-coding/
- Stork AI. (2026). Archon: The Open-Source AI Coding Harness for Agentic Workflows. Retrieved from https://www.stork.ai/blog/this-tool-tames-chaotic-ai-agents
'AI 도구' 카테고리의 다른 글
| 🚀 Hermes Agent v2026.4.13: 84k 스타 오픈소스 AI 에이전트 + 웹 대시보드 + 16개 플랫폼 지원 완벽 가이드 (1) | 2026.04.16 |
|---|---|
| ⚡1,500줄로 Claude Code 대체: OpenHarness 사용법 완벽 가이드 (0) | 2026.04.15 |
| 🤖 Cursor + Claude Code + Codex: 누구도 계획하지 않은 AI 코딩 스택 통합 (1) | 2026.04.13 |
| 💡 컨텍스트 스트레스 날려주는 Context Mode MCP: Hermes Agent 설치 가이드 (1) | 2026.04.12 |
| 🐍 CheetahClaws v3.05: Claude Code를 Python으로 재구현한 오픈소스 AI 코딩 어시스턴트 설치 가이드 (2) | 2026.04.12 |
