ggwhite/4x: AI 코딩 에이전트 오케스트레이션 CLI

English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Español

4x는 AI 코딩 에이전트를 다중 역할 개발 루프(multi-role development loop)로 오케스트레이션하는 오픈 소스 CLI입니다. 각 역할(Design, Code, Review, Test)은 격리되어 독립적으로 실행되며 결정론적 가드레일(deterministic guardrails)을 갖추고 있어 기능이 프로덕션 환경에서 접촉해도 살아남게 합니다. 4X 전략 게임처럼 (eXplore, eXpand, eXploit, eXterminate), 이 이름은 고유한 강점을 가진 개별 역할들이 수렴하여 복잡성을 정복하는 시스템을 반영합니다.

20가지 이상의 CLI 명령어
run, batch, live, doctor, clean, verify, mcp 등, 페이즈 훅(phase hooks), 상태 검사(health checks), 구조화된 로깅(structured logging) 기능 등이 제공됩니다.
자체 진화(Self-Evolution)
과거 실행 기록에서 히스토리 마이닝(History mining)을 수행하고, 자동 발견되는 기능 풍부화(auto-discovered feature enrichment)를 통해 발전합니다. 또한 안티-해킹(anti-hack) 기능을 갖춘 진화 가치 게이트(evolution value gate), 자체 수정 범위 보호(self-modification scope guard), 그리고 지속적인 개선 구동기(4x evolve)가 있습니다. 4x는 스스로의 실패로부터 학습하고 반복적으로 자신을 개선합니다.

단일 에이전트 코딩은 빠르지만 취약합니다. 하나의 AI에게 설계, 구현, 검토, 테스트를 모두 같은 맥락에서, 동일한 편향성을 가지고 요청하는 것입니다. 작은 작업에는 효과적이지만, 실제 기능(real features)에서는 무너집니다.

4x는 이 루프를 분리합니다. 각 역할은 집중된 임무와 제한된 범위를 가지며, 다른 역할의 추론 과정에 접근할 수 없습니다. 디자이너가 코드를 작성하지 않습니다. 코더가 자신의 작업을 판단하지 않습니다. 리뷰어는 설계상 적대적(adversarial)입니다. 테스터는 구현 전에 작성된 기준에 따라 검증합니다.

그 결과: 프로덕션 환경과 접촉하는 것을 견뎌내는 기능들이 탄생합니다.

4x를 선택한다는 것은 속도와 비용을 구조와 정확성으로 교환하겠다는 의미입니다. 귀하의 프로젝트가 이러한 교환이 필요한지 솔직하게 판단해야 합니다.

역할 격리가 자체 검토 편향성을 제거합니다. 코더는 자신의 작업을 결코 스스로 판단하지 않습니다. 리뷰어는 설계상 적대적입니다. 단일 에이전트 워크플로우는 동일한 모델이 코드 작성과 승인을 모두 하게 하지만, 4x는 그렇지 않습니다.
결정론적 가드레일은 AI의 판단에 의존하지 않습니다. 범위 잠금(Scope lock), 상태 기계(state machine), 증거 요구 사항(evidence requirements) 등은

gate는 AI가 작업했다고 표시하기 전에 항상 사람이 검토하도록 보장합니다. AI가 제안하고, 사용자가 처리(dispose)합니다.**대규모 리팩터링을 다루기 용이함.**단일 AI 세션으로는 너무 큰 변경 사항—거대한 객체 분리(splitting god objects), 패키지 추출(extracting packages), API 마이그레이션(migrating APIs)—은 적절한 프로필을 가진 종속적인 기능으로 나눌 수 있습니다. 4x는 단일 컨텍스트 창으로는 처리하기 어려울 여러 단계에 걸친 순서 지정, 검토 및 검증을 처리합니다.**배치 모드로 확장 가능함.**종속성을 인식하는 스케줄링(Dependency-aware scheduling)을 통해 밤새 수십 개의 기능을 대기열에 넣고 아침에 검토할 수 있습니다.

**상당히 높은 토큰 비용.**모든 기능은 최소 4개 이상의 별도 LLM 호출을 거칩니다. 검토 실패는 이 배수를 두 배로 만듭니다. 동일한 작업을 수행하는 단일 에이전트 접근 방식에 비해 3~10배의 토큰 비용이 발생할 것으로 예상하십시오. 비용 추정치는 사용 가이드(Usage Tips)를 참조하십시오.**간단한 작업에는 느림.**한 줄짜리 버그 수정에도 디자이너, 검토자, 테스터가 필요하지 않습니다. 전체 루프의 오버헤드는 사소한 변경 사항에 낭비됩니다. 빠른 수정에는 단일 에이전트 도구를 사용하십시오.설정 비용.4x init, 기능 YAML, 설정 구성 등 시작하기 전에 절차가 있습니다. 임시 스크립트에는 가치가 없습니다.**경직된 루프 구조.**디자인 → 코드 → 검토 → 테스트 순서는 고정되어 있습니다. 워크플로우가 네 가지 역할을 맞추지 못하면 프레임워크를 사용하는 대신 싸우게 될 것입니다.**품질은 프롬프트 품질에 달려 있음.**모호한 기능 설명은 모호한 사양을 낳고, 이는 잘못된 코드를 만듭니다. 4x는 구조를 추가하지만, 여전히 쓰레기 입력(garbage in)은 쓰레기 출력(garbage out)을 의미합니다—단지 더 많은 단계를 거칠 뿐입니다.

• 정확해야 하는 기능(결제, 인증, 데이터 파이프라인)

• 적대적 검토가 도움이 되는 작업(보안에 민감한 코드)

• 기능 백로그의 배치 처리

• AI 생성 코드를 감사 추적(audit trails)하고 싶은 팀

• 간단한 일회성 수정 또는 탐색적인 프로토타이핑

• 속도가 정확성보다 더 중요한 작업

• 토큰 예산이 빠듯한 프로젝트

• 어차피 본인이 직접 검토할 소규모 해킹 세션

You
|
v
...

Layer 1 — CLI는 범위 유효성 검사(scope validation), 상태 전이(state transitions), 기준 스냅샷(baseline snapshots), 증거 수집(evidence collection) 등 모든 결정론적(deterministic) 작업을 처리합니다. 이 레이어는 LLM을 호출하지 않습니다. 가드레일(Guardrails)은 AI의 판단에 의존하지 않습니다.Layer 2 — Runners는 CLI 프로토콜과 사용자가 선택한 AI 도구 사이를 연결하는 역할을 합니다. Claude Code, Codex, Gemini, Antigravity, Copilot, Cursor 등 각 도구는 동일한 .4x/ 파일 프로토콜을 사용하지만 자체 플랫폼 기능을 활용합니다.Layer 3 — Live는 다중 프로젝트 대시보드입니다. AI 에이전트가 실시간으로 작동하는 것을 관찰하고, 단계 전이(phase transitions)를 확인하며, 로그를 스트리밍할 수 있습니다. REST + SSE API를 사용합니다.

brew install ggwhite/tap/fourx

go install github.com/ggwhite/4x/cmd/4x@latest

curl -sSfL https://raw.githubusercontent.com/ggwhite/4x/main/install.sh | sh

이 셸 스크립트는 다운로드된 파일의 체크섬(checksum)을 자동으로 확인하며, 실패할 경우 중단됩니다. Releases 페이지에서 릴리스 아카이브나 바이너리를 수동으로 다운로드하는 경우에는 추출하기 전에 직접 검증해야 합니다: 해당 릴리스의 checksums.txt 파일을 같은 디렉토리에 다운로드한 후 다음 명령어 중 하나를 실행합니다:

# Linux (및 coreutils가 있는 macOS)
sha256sum --check --ignore-missing checksums.txt
# macOS (기본값)
...

체크섬이 OK라고 보고할 때만 바이너리를 추출하고 실행하십시오.

macOS, Linux, Windows(amd64 / arm64)용 사전 구축된 바이너리는 Releases 페이지에서 확인할 수 있습니다.

# 프로젝트 초기화
cd my-project
4x init
...

4x run은 디자인-코드-리뷰-테스트(Design-Code-Review-Test) 루프를 자동으로 구동합니다. 리뷰 단계에서 문제가 발견되면, 코드가 다시 한 번 실행됩니다. 테스트가 실패하면, 이 루프는 반복됩니다. --max-rounds 및 --timeout 플래그를 사용하여 제어권을 유지할 수 있습니다.

각 역할은 격리되어 있습니다. Coder는 Reviewer의 이전 피드백을 볼 수 없습니다. Tester는 Coder가 아닌 Designer가 작성한 기준에 따라 검증합니다. 이러한 분리는 단일 에이전트 워크플로우에서 발생하는 사각지대를 방지합니다.

Designer → Coder → Reviewer → Tester → 승인(Accept) → 검토 대기(Pending Review) → 완료(Done)
↓ ↓ ↑
수정(amending) ←─────┘ 인간의 최종 승인(human sign-off)

리뷰 실패(판정이 FAIL이거나 CRITICAL 발견 사항) 시 코드를 수정하기 위해 되돌림. 테스트 실패(verify가 통과하지 않음) 시 코드를 수정하기 위해 되돌림. 에스컬레이션(명세 불일치, 기준 오류) 발생 시 Designer에게 재라우팅. 검토 대기 게이트는 완료로 표시되기 전에 항상 인간의 검토를 거치도록 보장. 라운드 예산(기본값 5)은 무한 루프를 방지합니다.

AI 판단이 아닌 CLI에 의해 강제됨:

4x batch plan # 의존성을 고려한 실행 계획 생성
4x batch run --runner claude # 순서대로 모든 적격 기능을 실행
4x batch stop # 현재 기능 완료 후 정상 종료

Model Context Protocol (MCP) 서버 시작:

4x mcp

4x는 Claude Code 세션에서 파이프라인을 구동하기 위한 두 가지 선택적 Claude Code Skills를 제공합니다. npx skills로 설치하세요.

— 이 저장소를 클론할 필요 없음:

npx skills add ggwhite/4x --skill 4x-audit # 과거 실행 아티팩트 스캔, 보고서 및 선택적 기능 격차(gap features) 파일 생성
npx skills add ggwhite/4x --skill 4x-autopilot # 전체 프로세스(선택 → 실행 → 병합 → 다음 루프)를 수동 확인 없이 구동
npx skills add ggwhite/4x --all # 둘 다 설치

— 발견된 기능 격차, 에스컬레이션/검토 보고서, 반복되는 학습 패턴을 스캔합니다. 범주화된 HTML 보고서를 생성하며 선택적으로 기능 YAML 파일을 일괄 생성할 수 있습니다. 4x-audit

— 4x 상태를 폴링하고 기능을 전체 라이프사이클(디자인 → 코드 → 검토 → 테스트 → 병합)을 거쳐 확인 대기 없이 구동합니다. 여기에는 병합 과정도 포함됩니다. 4x-autopilot

소유자 전용 — 공유 레포지토리에서 사용하기 전에 스킬의 경고를 읽으십시오.

4x는 비대화형 모드(non-interactive mode)로 AI 에이전트를 실행합니다. 4x init 중, 러너들은 루프가 자율적으로 실행되도록 권한 프롬프트를 건너뛰는 플래그(--dangerously-skip-permissions, -y, approval: full-auto)와 함께 구성됩니다.

CLI의 결정론적 가드레일(deterministic guardrails) (스코프 잠금, 기준선 스냅샷, 상태 기계)이 안전 경계를 제공합니다.

자율 AI 에이전트 실행에 익숙한 프로젝트에서만 4x를 실행하십시오.

4x/
cmd/4x/ CLI 진입점 (Cobra)
internal/
...

Q: 4x가 LLM API를 직접 호출하나요?
아니요. 이 CLI는 순수 Go로 작성되었으며 LLM 의존성이 전혀 없습니다. 러너들이 자체 플랫폼 기능을 사용하여 모든 AI 상호 작용을 처리합니다.

Q: 역할별로 다른 LLM을 사용할 수 있나요?
예. .4x/settings.json에서 역할별 모델을 구성할 수 있습니다. 디자인에는 Claude를, 코드에는 Gemini를 사용하세요. 각 모델은 동일한 .4x/ 파일을 읽습니다.

Q: Devin / SWE-agent / OpenHands와 무엇이 다른가요?

그것들은 모든 것을 한 번에 처리하는 자율 에이전트(autonomous agents)입니다. 4x는 결정론적 가드레일(deterministic guardrails)을 갖춘 다중 역할 협업을 구조화하는 프레임워크입니다. 단일 자율 에이전트라기보다는 AI를 위한 CI 파이프라인에 가깝습니다.

4x는 대규모 플랫폼 재작성 과정에서 60개 이상의 기능을 출시한 DCT(Designer-Coder-Tester)라는 프로덕션 시스템 내부에서 탄생했습니다. 그중 살아남은 패턴들 — 역할 격리(role isolation), 파일 기반 프로토콜(file-based protocol), 결정론적 범위 확인(deterministic scope checking), 증거 기반 테스트(evidence-based testing) — 이 4x가 되었습니다. 반면, 살아남지 못한 부분들 — LLM 특화 해킹(LLM-specific hacks), 공유 컨텍스트 가정(shared context assumptions), 신뢰 기반 가드레일(trust-based guardrails) — 은 의도적으로 제외되었습니다.

git clone https://github.com/ggwhite/4x.git
cd 4x
go build ./cmd/4x
...

AI가 올바른 코드를 작성하기를 바라는 것을 멈추세요. 대신, 검증하는 것부터 시작하세요.