발음: "swee-AF" (한 단어)

단 한 번의 API 호출 → 전체 엔지니어링 팀 구성 → 코드 배포.

Quick Start (빠른 시작) • Why SWE-AF (SWE-AF를 사용하는 이유) • In Action (실행 예시) • Factory Control (팩토리 제어) • Benchmark (벤치마크) • Modes (모드) • API • Architecture (아키텍처)

단 한 번의 API 호출로 제품 관리자(Product Managers), 아키텍트(Architects), 코더(Coders), 리뷰어(Reviewers), 테스터(Testers)로 구성된 완전한 자율 엔지니어링 팀을 가동하여, 복잡한 소프트웨어를 처음부터 끝까지 정의하고, 구축하고, 적응시키고, 배포합니다.
SWE-AF는 **자율 소프트웨어 엔지니어링 팩토리 (Autonomous Software Engineering Factories)**를 향한 첫 번째 단계로, 단순한 목표부터 수백에서 수천 번의 에이전트 호출(Agent Invocations)이 필요한 까다로운 다중 이슈 프로그램까지 확장 가능합니다.

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \"\n-H "Content-Type: application/json" \"\n-d @- <<'JSON'\n...\n```

`models.default`와 모든 역할 키(`coder`, `qa`, `architect` 등)를 귀하의 런타임(Runtime)이 지원하는 모든 모델로 교체하십시오.

SWE-AF는 두 가지 모드로 작동합니다: 단일 리포지토리(Repository)를 대상으로 지정하거나, 한 번의 빌드에서 여러 리포지토리에 걸친 조정된 변경 사항을 오케스트레이션(Orchestrate)할 수 있습니다.

**기본 모드 (The default):** `repo_url` (원격) 또는 `repo_path` (로컬)를 전달하면 SWE-AF가 모든 것을 처리합니다:

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build "\n-H "Content-Type: application/json" "\n-d '{\n...\n```

작업 범위가 여러 코드베이스(Codebases)에 걸쳐 있는 경우 — 기본 앱과 공유 라이브러리, 모노레포(Monorepo) 하위 프로젝트, 또는 의존 관계에 있는 마이크로서비스(Microservices) 등 — config.repos를 역할(Roles)이 포함된 배열로 전달하십시오:

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build \"\n-H "Content-Type: application/json" \"\n-d '{\n...\n```

**역할 (Roles):**

`primary` — 메인 애플리케이션. 여기서의 변경 사항이 빌드를 주도하며, 실패 시 진행이 차단됩니다.
`dependency` — 기본 리포지토리를 지원하기 위해 수정되는 라이브러리 또는 서비스. 실패가 기록되지만 진행을 차단하지는 않습니다.

**사용 사례 (Use cases):**

- 기본 앱 + 공유 SDK 또는 유틸리티 라이브러리
- 별도의 리포지토리에 존재하는 모노레포 하위 프로젝트
- 여러 마이크로서비스에 걸친 기능 (예: API + 워커 큐 (Worker Queue))

Rust 기반 Python 컴파일러 벤치마크 (자율적으로 구축됨):

| 지표 (Metric) | CPython (subprocess) | RustPython (SWE-AF) | 개선 사항 (Improvement) |
|---|---|---|---|
| 정상 상태 실행 (Steady-state execution) | 기준점 (~19ms) | 최적화된 인프로세스 런타임 (Optimized in-process runtime) | 88.3x-602.3x 더 빠름 |
| ... | |

## 측정 방법론 (Measurement methodology)

처리량 (Throughput) 비교는 서로 다른 실행 모델을 측정합니다: CPython 서브프로세스 생성 (subprocess spawn, 호출당 ~19ms → ~52 ops/s) 대 RustPython 사전 예열된 인터프리터 풀 (pre-warmed interpreter pool, 인프로세스 방식). 이는 시스템이 최적화하기 위해 구축된 실제 환경의 트레이드오프 (tradeoff)입니다 — 즉, 짧은 코드 조각 (short-snippet) 실행을 위해 반복적인 서브프로세스 호출을 지속적인 풀 (persistent pool)로 대체하는 것입니다.

아티팩트 추적 (Artifact trail)에는 계획 (planning), 코딩 (coding), 리뷰 (review), 머지 (merge), 검증 (verification) 전반에 걸쳐 **175개의 추적된 자율 에이전트 (autonomous agents)**가 포함됩니다.

상세 정보: `examples/llm-rust-python-compiler-sonnet/README.md`

대부분의 에이전트 프레임워크 (agent frameworks)는 단일 코더 루프 (coder loop)를 감싸는 형태입니다. SWE-AF는 조정된 엔지니어링 팩토리 (engineering factory)입니다 — 계획, 실행, 거버넌스 (governance) 에이전트가 실시간으로 적응하는 제어 스택 (control stack)으로서 작동합니다.

**난이도 인지 실행 (Hardness-aware execution)** — 쉬운 이슈는 빠르게 통과하며, 어려운 이슈는 맹목적인 재시도 (blind retries) 대신 더 깊은 적응과 DAG 레벨의 재계획 (replanning)을 트리거합니다.

**팩토리 아키텍처 (Factory architecture)** — 단일 에이전트 래퍼 (single-agent wrapper)가 아닙니다. 계획, 실행, 거버넌스 에이전트가 조정된 제어 스택으로서 실행됩니다 — 이 아키텍처는 프롬프트 (prompts)가 아닌 엔지니어링 전략을 인코딩합니다 (The Atomic Unit of Intelligence 참조).

**멀티 모델, 멀티 프로바이더 (Multi-model, multi-provider)** — 역할별로 서로 다른 모델을 할당합니다 (`coder: opus`, `qa: haiku`). Claude, OpenRouter, OpenAI, Google과 함께 작동합니다.

**지속적 학습 (Continual learning)** — `enable_learning=true`를 통해 가능합니다.

, 초기에 발견된 컨벤션(conventions) 및 실패 패턴(failure patterns)이 하위 이슈(downstream issues)에 주입됩니다. **에이전트 규모의 병렬성 (Agent-scale parallelism)** — 의존성 수준의 스케줄링(dependency-level scheduling)과 격리된 git 워크트리(git worktrees)를 통해 브랜치 충돌 없이 대규모 팬아웃(fan-out)이 가능합니다. **플릿 규모의 오케스트레이션 (Fleet-scale orchestration)** — 많은 SWE-AF 노드들이 AgentField를 통해 병렬로 지속적으로 실행될 수 있으며, 동시 빌드 과정에서 수천 번의 에이전트 호출(agent invocations)을 수행합니다. **명시적 부채 추적 (Explicit compromise tracking)** — 범위(scope)가 완화될 때, 기술 부채(debt)는 유형화되고 심각도가 평가되어 전파됩니다. **장기 실행 신뢰성 (Long-run reliability)** — 체크포인트가 설정된 실행(checkpointed execution)은 충돌이나 중단 발생 후 `resume_build`를 지원합니다.

PR #179: Go SDK DID/VC 등록 — 전적으로 SWE-AF(Claude 런타임 및 haiku급 모델 사용)에 의해 구축되었습니다. 단 한 번의 API 호출로, 인간의 코드 작성은 전혀 없었습니다.

| 지표 (Metric) | 값 (Value) |
|---|---|
| 완료된 이슈 (Issues completed) | 10/10 |
| ... | 총 비용 (Total cost) |
| | $19.23 |

## 에이전트 역할별 비용 상세 내역 (Cost breakdown by agent role)

| 역할 (Role) | 비용 (Cost) | 비율 (%) |
|---|---|---|
| 코더 (Coder) | $5.88 | 30.6% |
| ... | |

79회의 호출(invocations), 2,070회의 대화 턴(conversation turns). 플래닝 에이전트(Planning agents)는 범위를 설정하고 분해하며, 코더(coders)는 격리된 워크트리에서 병렬로 작업합니다. 리뷰어(reviewers)와 QA는 각 이슈를 검증하고, 머저(merger)는 브랜치를 통합하며, 베리파이어(verifier)는 제품 요구 사양서(PRD)에 따라 수락 기준(acceptance criteria)을 확인합니다.

**Claude, 오픈 소스(open-source), 그리고 Codex 모델 지원**: 어떤 런타임(runtime)으로든 빌드를 실행할 수 있으며, 하나의 평면적인 설정 맵(flat config map)에서 역할별로 모델을 조정할 수 있습니다.

`runtime: "claude_code"`는 Claude 백엔드로 매핑됩니다.
`runtime: "open_code"`는 OpenCode 백엔드(OpenRouter/OpenAI/Google/Anthropic 모델 ID)로 매핑됩니다.
`runtime: "codex"`는 OpenAI Codex CLI 백엔드로 매핑됩니다.

SWE-AF는 작업 난이도에 실시간으로 적응하기 위해 세 가지 중첩된 제어 루프(control loops)를 사용합니다:

| 루프 (Loop) | 범위 (Scope) | 트리거 (Trigger) | 작업 (Action) |
|---|---|---|---|
| 내부 루프 (Inner loop) | 단일 이슈 (Single issue) | QA/리뷰 실패 (QA/review fails) | 코더가 피드백과 함께 재시도 (Coder retries with feedback) |
| ... | |

이것이 핵심적인 공장 제어(factory-control) 동작입니다: 제어 에이전트(control agents)가 작업 에이전트(worker agents)를 감독하며, 현실이 변함에 따라 계획을 지속적으로 재구성합니다.

클릭 한 번으로 SWE-AF + AgentField 제어 평면(control plane) + PostgreSQL을 배포합니다. Railway에서 두 개의 환경 변수를 설정하십시오:

`CLAUDE_CODE_OAUTH_TOKEN`

— Claude Code CLI에서 `claude setup-token`을 실행합니다 (Pro/Max 구독 크레딧 사용)

`GH_TOKEN` — PR 생성을 위한 `repo` 스코프(scope)가 포함된 GitHub 개인 액세스 토큰 (Personal Access Token)

배포가 완료되면, 빌드를 트리거합니다:

curl -X POST https://<control-plane>.up.railway.app/api/v1/execute/async/swe-planner.build
-H "Content-Type: application/json"
-H "X-API-Key: this-is-a-secret"
...

- Python 3.12+
- AgentField 제어 평면 (control plane) (`af`)
- AI 제공업체 API 키 (Anthropic, OpenRouter, OpenAI 또는 Google)

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
...

af # :8080에서 AgentField 제어 평면을 시작합니다
python -m swe_af # 노드 ID "swe-planner"를 등록합니다

기본값 (Claude 사용)

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build
-H "Content-Type: application/json"
...

`open_code`를 사용하는 OpenRouter의 경우, `openrouter/<provider>/<model>` 형식(예: `openrouter/minimax/minimax-m2.5`)의 모델 ID를 사용하십시오.

ChatGPT 구독 인증을 사용하는 Codex의 경우, 호스트에 Codex CLI를 설치하고 `codex login`을 실행하십시오. 이 프로세스를 위해 `OPENAI_API_KEY`는 설정하지 않은 상태로 두고, `SWE_CODEX_AUTH_MODE=chatgpt` 또는 `auto`로 설정하십시오. OpenAI API 플랫폼 과금 방식을 사용하는 경우, `SWE_CODEX_AUTH_MODE=api_key` 및 `OPENAI_API_KEY`를 설정하십시오.

Docker 이미지를 사용하는 Codex 배포는 모든 빌드의 `config` 내 `models: {"default": "gpt-5.3-codex"}` 환경 변수에 `SWE_DEFAULT_MODEL=gpt-5.3-codex`를 설정(또는 전달)해야 합니다. 해당 이미지는 OpenCode 폴백(fallback)으로 `HARNESS_MODEL=openrouter/moonshotai/kimi-k2.6`을 내장하고 있으며, SWE-AF의 모델 결정(model-resolution) 환경 변수 캐스케이드(cascade)는 `HARNESS_MODEL`을 읽습니다. 따라서 `SWE_DEFAULT_MODEL`이 설정되지 않으면 Codex CLI는 처리할 수 없는 OpenRouter 모델 ID를 받게 되어 약 13초 내에 Product Manager 추론기(reasoner)가 실패합니다. `SWE_DEFAULT_MODEL`을 설정하면 캐스케이드가 모든 역할을 Codex 모델로 고정합니다.

Codex CLI의 `workspace-write` 샌드박스(sandbox)는 bubblewrap (`bwrap`)을 사용합니다.

) 및 호스트에서 Linux 사용자 네임스페이스 (user namespaces)가 활성화되어 있어야 합니다. 대부분의 프로덕션 Linux 호스트와 관리형 컨테이너 런타임 (Railway 등)은 이를 기본적으로 허용하지만, WSL2 상의 로컬 Docker 또는 보안이 강화된 환경에서는 `bwrap: No permissions to create a new namespace` 오류와 함께 거부될 수 있습니다.

만약 검증기(verifier)가 해당 오류를 보고한다면, 코더(coder)는 실행되었으나 파일을 작성할 수 없었음을 의미합니다. Codex 런타임을 해당 환경에서 사용하기 전에 호스트에서 사용자 네임스페이스를 활성화하십시오.

코딩 및 리뷰 에이전트(agents)는 빌드 과정 중에 외부 문서, 라이브러리 API, 에러 메시지, 그리고 버전/지원 중단(deprecation) 상태를 조회할 수 있습니다. 이는 배포 시 두 가지 환경 변수 (env vars)를 통해 선택적으로 활성화할 수 있습니다:

OPENCODE_ENABLE_EXA=1
EXA_API_KEY=...

설정 시, opencode의 내장된 `websearch` 및 `webfetch` 도구를 open 런타임을 통해 실행되는 모든 추론기(reasoner)가 사용할 수 있게 됩니다. 모델은 작업에 따라 이 도구들을 사용할 시점을 스스로 결정합니다. 키는 exa.ai에서 발급받을 수 있습니다.

또한 코더 추론기(coder reasoner)의 시스템 프롬프트(system prompt)에는 짧은 제한 가이드라인이 추가되어, 긴 코딩 루프가 코드베이스를 읽음으로써 해결할 수 있는 검색 작업에 빠져드는(rabbit-hole) 현상을 방지합니다. 환경 변수 외에 별도의 설정은 필요하지 않으며, 배선(wiring)은 AgentField의 CLI 하네스(harness)를 통해 자연스럽게 부모 환경 변수를 상속받습니다.

이 기능은 open 런타임(opencode)에서 작동합니다. Claude 런타임은 Anthropic의 자체 `WebSearch` / `WebFetch`를 사용하며 현재 여기에는 연결되어 있지 않습니다. 이 기능이 필요하다면 이슈(issue)를 등록해 주세요.

- 코딩이 시작되기 전에 아키텍처가 생성되고 검토됩니다.
- 이슈(Issues)들은 의존성 순서대로 정렬되며, 격리된 워크트리(worktrees)를 통해 병렬로 실행됩니다.
- 각 이슈에는 전담 코더(coder), 테스터(tester), 리뷰어(reviewer) 단계가 할당됩니다.
- 실패한 이슈는 어드바이저(advisor) 주도의 적응(분할, 범위 재설정 또는 에스컬레이션)을 트리거합니다.
- 에스컬레이션(Escalations)이 발생하면 남은 DAG(Directed Acyclic Graph)의 재계획(replanning)이 트리거됩니다.
- 최종 결과물은 병합(merged)되고, 통합 테스트(integration-tested)를 거치며, 수락 기준(acceptance criteria)에 따라 검증됩니다.

일반적인 실행 과정에서는 계획(planning), 실행(execution), QA, 그리고 검증(verification) 전반에 걸쳐 400~500개 이상의 에이전트 인스턴스(agent instances)가 구동됩니다. 더 큰 유향 비순환 그래프(DAGs)와 반복적인 적응/재계획(adaptation/replanning) 사이클의 경우, SWE-AF는 단일 빌드 내에서 수백 개에서 수천 개의 에이전트 호출(agent invocations)까지 확장될 수 있습니다.

**haiku 및 MiniMax를 통한 95/100점 달성**: SWE-AF는 Claude haiku급 라우팅($20)과 오픈 런타임(open runtime)을 통한 MiniMax M2.5($6) 모두에서 95/100점을 기록하며, 동일한 프롬프트(prompt)에서 Claude Code sonnet (73), Codex o3 (62), Claude Code haiku (59)를 능가했습니다.

| 차원 (Dimension) | SWE-AF (haiku) | SWE-AF (MiniMax) | CC Sonnet | Codex (o3) | CC Haiku |
|---|---|---|---|---|---|
| 기능적 측면 (Functional, 30) | 30 | 30 | 30 | 30 | 30 |
| 구조 (Structure, 20) | 20 | 20 | 10 | 10 | 10 |
| 위생 (Hygiene, 20) | 20 | 20 | 16 | 10 | 7 |
| Git (15) | 15 | 15 | 2 | 2 | 2 |
| 품질 (Quality, 15) | 10 | 10 | 15 | 10 | 10 |
| 총점 (Total) | 95 | 95 | 73 | 62 | 59 |
| 비용 (Cost) | ~$20 | ~$6 | ? | ? | ? |
| 시간 (Time) | ~30-40분 | 43분 | ? | ? | ? |

**전체 벤치마크 세부 정보 및 재현**

여러 에이전트에 대해 동일한 프롬프트로 테스트를 진행했습니다. Claude 런타임(haiku급 모델 매핑)을 사용한 SWE-AF는 400개 이상의 에이전트 인스턴스를 사용했으며, 오픈 런타임을 통한 MiniMax M2.5 기반의 SWE-AF는 70%의 비용 절감으로 동일한 품질을 달성했습니다.

**모든 에이전트에 사용된 프롬프트:**

add, list, complete, delete 명령어가 포함된 Node.js CLI 할 일(todo) 앱을 구축하세요. 데이터는 JSON 파일에 영구 저장되어야 합니다. git을 초기화하고, 테스트를 작성하며, 작업 내용을 커밋(commit)하세요.

| 차원 (Dimension) | 점수 (Points) | 측정 항목 |
|---|---|---|
| 기능적 측면 (Functional) | 30 | CLI 동작 및 테스트 통과 여부 |
| ... | |

SWE-AF (Claude 런타임, haiku급 매핑) - $20, 30-40분

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build
-H "Content-Type: application/json"
...

**MiniMax M2.5 측정 지표 (2026년 2월):**

- 99.22% 코드 커버리지 (code coverage, 측정된 커버리지를 보유한 유일한 에이전트)
- 4가지 커스텀 에러 타입 (TodoError, ValidationError, NotFoundError, StorageError)
- 999 LOC (Lines of Code), 4개 모듈, 74개 테스트, 9개 커밋

**Production Quality Analysis (프로덕션 품질 분석):** 모든 에이전트(agents)에 걸쳐 측정 가능한 지표를 객관적으로 비교합니다.

벤치마크 자산(Benchmark assets), 로그(logs), 평가기(evaluator) 및 생성된 프로젝트는 `examples/agent-comparison/`에 위치합니다.

코드를 배포한 후, 이를 감사(audit)하십시오: SEC-AF는 귀하의 코드베이스를 대상으로 동일한 멀티 에이전트 아키텍처(multi-agent architecture)를 실행합니다 — 250개의 에이전트, 94%의 노이즈 감소, 모든 발견 사항은 검증되었습니다.

cp .env.example .env

API 키를 추가하세요: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY 또는 GOOGLE_API_KEY

선택적으로 PR 워크플로우를 위한 GH_TOKEN을 추가하세요

...

빌드 제출:

기본값 (Claude)

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build
-H "Content-Type: application/json"
...

워커(workers) 확장:

`docker compose up --scale swe-agent=3 -d`

Docker 컨트롤 플레인(control-plane) 서비스 대신 호스트 컨트롤 플레인(host control plane)을 사용하십시오:

`docker compose -f docker-compose.local.yml up -d`

실행 후 SWE-AF가 저장소를 클론(clone)하고 PR을 생성할 수 있도록 `repo_path` 대신 `repo_url`을 전달하십시오.

curl -X POST http://localhost:8080/api/v1/execute/async/swe-planner.build
-H "Content-Type: application/json"
-d @- <<'JSON'
...

요구 사항:

`.env` 파일 내의 `GH_TOKEN`

`repo` 스코프(scope) 포함 — 해당 토큰에 대한 저장소(Repo) 접근 권한