| |

“생각하지 말고 그냥 프롬프트만 쳐라” — LazyCodex, Codex를 위한 궁극의 에이전트 오케스트레이션 심층 분석

개발감자

“Codex for no-brainers. You don’t need to think. Just prompt with ultrawork.”

깃허브 저장소 소개 문구부터 도발적이다. code-yeongyu/lazycodex는 별 98개짜리(모체인 oh-my-openagent 기준으로는 6만 개가 넘는) 작은 설치 스크립트지만, 그 뒤에는 “에이전트 하네스”라는 요즘 AI 코딩 생태계에서 가장 뜨거운 화두가 통째로 깔려 있다. OpenAI Codex CLI 사용자에게 “생각을 꺼도 되는” 개발 경험을 약속하는 이 프로젝트를, 설치 스크립트 한 줄부터 그 뒤에 숨은 철학까지 파헤쳐 본다.

1. LazyCodex는 정확히 무엇인가

결론부터 말하면 LazyCodex 자체는 거대한 신규 프로젝트가 아니다. 공식 문서는 스스로를 이렇게 정의한다.

“LazyCodex is a light port of OmO into Codex. It does not ship the full harness — it ports one role, Hephaestus, the autonomous deep worker, and the workflows that keep its runs honest.”

즉 LazyCodex는 oh-my-openagent(이하 OmO)라는 거대한 에이전트 하네스 프로젝트에서, OpenAI Codex CLI에 이식 가능한 부분만 골라 담은 “가벼운 배포판”이다. 저자들이 즐겨 쓰는 비유가 정확하다.

“LazyVim made Neovim usable for the rest of us. LazyCodex does the same for Codex.”

lazy.nvim 위에 올라간 LazyVim이 Neovim 설정의 진입장벽을 없앤 것처럼, LazyCodex는 “OmO는 좋다는데 세팅이 너무 복잡하다”는 사람들을 위한 원클릭 배포판인 셈이다. 실제로 설치 명령은 다음 명령과 완전히 동일하다.

npx lazycodex-ai install
# 이것과 완전히 동일한 동작:
npx --yes --package oh-my-openagent omo install --platform=codex

완전 자동(무프롬프트) 설치를 원한다면 아래처럼 쓴다.

npx lazycodex-ai install --no-tui --codex-autonomous

중요한 점: npm install -g나 bun add -g 같은 전역 설치는 명시적으로 비권장한다. 항상 npx로 그때그때 실행하는 것이 원칙이다. 문서는 심지어 “설치도 에이전트에게 시켜라”라고 권한다 — 아래 문장을 그대로 Codex에게 붙여넣으면 구독·모델·프로바이더 인증까지 자동으로 처리된다.

https://github.com/code-yeongyu/lazycodex

Install LazyCodex from this repository.

2. 모체 OmO의 진짜 크기 — LazyCodex는 “빙산의 일각”

LazyCodex의 실체를 이해하려면 모체인 OmO가 얼마나 큰 프로젝트인지 알아야 한다. OmO는 두 개의 “에디션”으로 배포된다.

에디션 대상 플랫폼 포함 내용
Ultimate Edition OpenCode (네이티브) 에이전트 11종, 라이프사이클 훅 54개 이상, MCP 서버 5종, 전체 슬래시 커맨드, Team Mode, ulw-loop, ultrawork, 해시 기반 편집 도구까지 — 풀세트
Light Edition (LazyCodex가 패키징하는 부분) Codex CLI rules, comment-checker, git-bash, lsp, ultrawork, ulw-loop, start-work-continuation, telemetry + 몇몇 스코프 MCP. 에이전트 오케스트레이션과 team_* 도구는 빠져 있다 — 이건 Codex CLI 자체의 몫이라는 설명이다.

다시 말해 LazyCodex = OmO Light Edition을 Codex 사용자에게 원클릭으로 배포하는 브랜드/설치 래퍼다. 풀세트 OmO(Ultimate)에는 오케스트레이터 Sisyphus가 Hephaestus·Oracle·Librarian·Explore 등 여러 전문 에이전트에게 작업을 분배하는 “AI 개발팀” 구조가 있지만, LazyCodex 쪽엔 오케스트레이터가 없다. Hephaestus 단 하나가 읽기 전용 서브 에이전트를 병렬로 부려가며 처음부터 끝까지 스스로 작업을 완수한다.

“Is LazyCodex a replacement for OmO? No. It is a focused subset. The full OmO has deeper orchestration. LazyCodex takes the parts that work well inside Codex and packages them as a repeatable install.”

Hephaestus — “정당한 장인”

그리스 신화의 대장장이 신에서 이름을 딴 Hephaestus는 목표 지향적으로 움직인다. 단계별 레시피가 아니라 목표만 주면 스스로 코드베이스를 탐색하고, 패턴을 연구하고, 끝까지 실행한다. 별명이 재밌는데, “The Legitimate Craftsman(정당한 장인)”이라 붙여놓고 README에는 이런 농담이 적혀 있다.

“Anthropic blocked OpenCode because of us. That’s why Hephaestus is called ‘The Legitimate Craftsman.’ The irony is intentional.”

OmO 진영이 Anthropic 모델을 지나치게 좋아해서(?) 결국 접근이 막혔고, 그래서 Codex(OpenAI) 쪽으로 방향을 튼 것이 LazyCodex 탄생의 배경이라는, 다소 자학적이면서도 자신감 있는 코멘트다.

Hephaestus의 작업 루프는 5단계로 명확히 정의되어 있다.

  1. Explore — 코드를 절대 추측하지 않고 실제로 읽는다. 뭔가 쓰기 전에 2~5개의 병렬 탐색 서브 에이전트를 먼저 띄운다.
  2. Plan — 변경할 파일·의존성을 update_plan으로 기록한다.
  3. Implement — 기존 코드베이스의 네이밍·들여쓰기·에러 처리 스타일을 그대로 따라간다. 그린필드였다면 다르게 짰을 코드라도 스타일을 맞춘다.
  4. Verify — 변경된 파일에 대한 LSP 진단, 관련 테스트, 빌드를 (가능하면 병렬로) 돌린다.
  5. Manual QA — 실제 표면(HTTP 호출, tmux, 브라우저)으로 결과물을 직접 구동해보고 최종 메시지를 쓴다.

그리고 이 원칙들은 절대 타협하지 않는다: 서브 에이전트의 자기보고를 절대 신뢰하지 않는다. 읽지 않은 코드에 대해 절대 추측하지 않는다. 턴이 끝날 때 미해결 작업을 절대 남기지 않는다 — 모든 계획 항목은 완료 / 사유가 명시된 차단 / 사유가 명시된 삭제, 셋 중 하나로 종료돼야 한다.

여러 병렬 서브 에이전트가 코드베이스를 함께 작업하는 모습
Hephaestus는 오케스트레이터 없이도 읽기 전용 서브 에이전트를 병렬로 부리며 작업을 끝까지 완수한다

3. 핵심 철학: ultrawork — “말로만 끝났다고 하지 마라”

LazyCodex/OmO를 관통하는 단 하나의 사상은 이 문장에 압축돼 있다.

“An agent saying it is done does not mean the work is done. The work is done when observable evidence verifies it.”
(에이전트가 다 됐다고 말하는 것과 실제로 끝난 것은 다르다. 관찰 가능한 증거가 검증했을 때만 끝난 것이다.)

ultrawork 증거 기반 검증 루프 개념 이미지
“됐다”는 선언이 아니라 관찰 가능한 증거가 검증될 때까지 도는 것이 ultrawork 루프다

이 철학을 발동시키는 트리거가 바로 ultrawork(줄여서 ulw) 키워드다. Claude Code에 ultrathink를 넣으면 사고 깊이가 올라가는 것처럼, 프롬프트 어디에든 ultrawork나 ulw를 넣으면 하네스가 최대 정밀도·결과 중심·증거 기반 오케스트레이션 모드로 전환된다. 별도로 스킬을 호출할 필요 없이 내부적으로 자동 활성화된다.

# 이렇게만 써도 된다
ulw add authentication
fix the flaky checkout test ultrawork

ultrawork 모드가 강제하는 규율은 구체적이다.

  • 엄격한 TDD: RED → GREEN → SURFACE → CLEAN 사이클
  • 작업 위험도에 맞춰 최소 3개 이상의 현실적인 QA 시나리오
  • HTTP 호출, tmux, 브라우저, 컴퓨터 사용, CLI 출력, 데이터 diff 등 “진짜 표면”을 통한 수동 QA
  • 완전히 끝날 때까지 루프를 도는 구속력 있는 검증 게이트

여기서 흥미로운 숫자 제한이 두 겹으로 존재한다. 하나는 전체 반복 상한선이고, 다른 하나는 세부 실패 허용치다.

제한 종류 ultrawork 모드 일반 모드
전체 루프 반복 상한 500회 100회
하나의 목표에서 완전 통과 없이 반복 가능한 횟수 5회 —
같은 기준에서 동일한 실패가 반복 가능한 횟수 3회 —

진행 상태는 .omo/ulw-loop/brief.md(원 요청과 제약), .omo/ulw-loop/goals.json(목표와 성공 기준), .omo/ulw-loop/ledger.jsonl(pass/fail/block 기록)에 지속적으로 저장된다. 에이전트가 <promise>DONE</promise>라고 스스로 선언해도 그걸로 끝나지 않는다. Oracle이라는 검증 역할이 확인하기 전까지는 “Oracle verification failed. Continuing ULTRAWORK loop.” 메시지를 뿌리며 계속 돈다.

4. 4대 핵심 커맨드 완전 분석

LazyCodex를 설치하면 Codex(또는 OpenCode) 세션에 4개의 워크플로 커맨드가 추가된다.

커맨드 문법 역할
$init-deep $init-deep 계층적 AGENTS.md 컨텍스트 파일을 생성해, 에이전트가 큰 저장소를 파악하기 전에 로컬 가이드부터 읽게 만든다.
$ulw-plan $ulw-plan "무엇을 만들지" 전략 기획자 Prometheus 역할. 소크라테스식 질문 → 병렬 코드베이스 탐색 → 갭 분석(Metis) → plans/<slug>.md에 계획서 작성. 절대 제품 코드를 쓰지 않는다.
$start-work $start-work [plan-name] [--worktree <path>] 계획서의 체크박스가 모두 끝날 때까지 실행. .omo/boulder.json에 진행 상태를 저장해 세션이 끊겨도 이어간다. 완료 시 ORCHESTRATION COMPLETE 출력.
$ulw-loop $ulw-loop "작업 설명" [--completion-promise=TEXT] [--strategy=reset|continue] Oracle이 검증할 때까지 스스로 반복하는 자기참조 루프. 계획 없이도 바로 “끝까지 검증된 완료”를 노릴 때 쓴다.

커맨드를 언제 골라야 할지에 대한 공식 가이드도 명확하다.

상황 커맨드
저장소가 너무 크거나 오래돼서 기억만으로 설명이 안 될 때 $init-deep
코드를 쓰기 전에 결정해야 할 것들이 있을 때 $ulw-plan
계획이 이미 있고 그대로 끝까지 실행하면 될 때 $start-work
결과가 검증될 때까지 에이전트가 계속 물고 늘어지길 바랄 때 $ulw-loop

5. 유즈케이스로 배우는 실전 사용법

이론은 됐고, 실제로 어떤 상황에 어떻게 쓰는지 7가지 시나리오로 정리했다.

유즈케이스 1 — 새 저장소에 처음 투입될 때: 온보딩

수년 묵은 대형 모노레포에 새 에이전트를 붙였을 때, 매번 “이 프로젝트는 어떻게 구성돼 있어” 설명하는 건 비효율적이다. 가장 먼저 할 일은 $init-deep 한 번으로 끝난다.

$init-deep

실행하면 루트에 프로젝트 전체 컨텍스트를 담은 AGENTS.md가, 주요 하위 디렉터리마다 스코프가 좁혀진 AGENTS.md가 생성된다.

project/
├── AGENTS.md              ← 프로젝트 전체 컨텍스트
├── src/
│   ├── AGENTS.md          ← src 전용 컨텍스트
│   └── components/
│       └── AGENTS.md      ← 컴포넌트 전용 컨텍스트

이후 에이전트는 매번 저장소를 처음부터 다시 파악하지 않고 이 파일들을 먼저 읽는다. 대규모 리팩터링·마이그레이션 직후에도 다시 돌려주면 좋다.

유즈케이스 2 — 신규 기능 개발: “기획 → 실행”을 완전히 분리

“레이트 리미팅을 API 게이트웨이에 추가해줘” 같은, 코드를 쓰기 전에 결정해야 할 것들이 많은 작업이라면 계획과 실행을 분리하는 것이 이 프로젝트의 핵심 워크플로다.

$init-deep
$ulw-plan "add rate limiting to the api gateway"
$start-work plans/add-rate-limiting.md

$ulw-plan은 모호한 지점에서만 질문하고(불필요한 인터뷰는 하지 않는다), 병렬 서브 에이전트로 실제 코드를 탐색해 결정을 코드베이스에 근거시킨 뒤, plans/add-rate-limiting.md라는 “더 이상 물을 필요 없는” 계획서를 작성한다. 계획서는 status: awaiting-approval 상태로 대기하고, 승인 후 $start-work가 체크박스를 하나씩 지워가며 계획을 실행한다. 실행 중 세션이 끊겨도 .omo/boulder.json이 진행 상태를 들고 있어서 다음 턴에 이어서 진행된다.

유즈케이스 3 — 이미 원인이 뻔한 잔버그 수정: 계획 없이 바로 처리

플레이키 테스트, 뻔한 버그처럼 굳이 계획 단계가 필요 없는 작업엔 ultrawork 키워드만 붙여서 바로 던진다.

ulw fix the flaky checkout test

또는 끝까지 검증된 완료를 명시적으로 원한다면 $ulw-loop를 직접 부른다.

$ulw-loop "fix the payment flow failure and verify end to end"

이 경우 Hephaestus가 스스로 “됐다”고 느껴도 Oracle의 검증을 통과하기 전까지 루프가 끝나지 않는다.

유즈케이스 4 — 작업 완료 후 셀프 리뷰: “review my work”

구현이 끝난 뒤 그대로 커밋하기보단, 5개의 병렬 서브 에이전트가 목표/제약 검증, 실전 QA 실행, 코드 품질, 보안, git·이슈 기록 대조를 각각 맡아 전부 통과해야 넘어가는 리뷰 스킬을 쓸 수 있다.

review my work

유즈케이스 5 — AI가 짜놓은 냄새나는 코드 정리하기

AI가 급하게 짠 코드는 특유의 “AI 냄새”(과도한 방어 코드, 불필요한 추상화 등)가 난다. 행동을 보존하면서 정리하는 전용 스킬 체인이 있다.

ulw plan and manual qa, no behaviour changes, no regressions
/refactor /remove-ai-slops through /programming

250줄이 넘는 순수 로직은 자동으로 모듈 단위 리팩터링 대상이 되고, 5개씩 병렬 배치로 작업자가 돌며, 테스트가 하나라도 실패하면 즉시 되돌린다.

유즈케이스 6 — 프론트엔드 디자인 개선

일반적인 “레이아웃 채우기”가 아니라 실제 브라우저로 검증하는 디자인 작업을 원한다면 frontend 스킬이 라우팅된다.

redesign the sidebar with better spacing and hit Lighthouse 100

Lighthouse 100점, Core Web Vitals, react-scan/react-doctor 같은 실측 기준으로 검증까지 자동으로 이어진다.

유즈케이스 7 — 낯선 아키텍처 리서치

새로운 라이브러리나 낯선 아키텍처를 통째로 파악해야 할 때는 10개 이상의 병렬 검색 레인을 돌리는 리서치 스킬을 부른다.

ulw-research the typeclaw architecture — map every module and find the official docs

단순 문서 요약이 아니라, 리드를 재귀적으로 확장(EXPAND 루프)하고 코드를 직접 실행해 경험적으로 검증한다는 점이 특징이다.

6. 설치 환경과 현실적인 제약

공식 문서가 권장하는 환경은 명확하다.

OS 권장도 비고
Ubuntu 가장 권장 경로·셸·패키지 관리가 예측 가능
macOS 권장 Homebrew + Node.js/npm이면 충분
Windows(네이티브) 비권장 훅·CLI·권한·스크립트에서 셸/경로 마찰이 크다 — 꼭 써야 한다면 WSL2 Ubuntu 안에서 실행하라고 명시

비용 측면도 짚어야 한다. LazyCodex/OmO 자체는 MIT 라이선스의 무료 오픈소스지만, 실제로 돌리려면 LLM 구독이 필요하다. 문서는 ChatGPT Pro 이상 사용을 전제로 하며, 풀 OmO 진영에서는 ChatGPT($20), Kimi Code($19), GLM Coding Plan($10) 구독을 조합해 쓰는 걸 추천한다. 제작자는 “개인 프로젝트에 LLM 토큰 2만4천 달러를 태워봤다”는 경험을 공개하며 이 조합을 추천이라기보다 “내가 다 써보고 남긴 결론”이라고 못 박는다.

7. 이 프로젝트를 만든 사람들 — Sisyphus Labs와 “Jobdori”

LazyCodex/OmO의 메인테이너는 Yeongyu Kim(GitHub: code-yeongyu)이며, 소속은 Sisyphus Labs다. Codex 마켓플레이스 네임스페이스가 문자 그대로 sisyphuslabs인 것도 이 때문이다. 흥미로운 건 README에 등장하는 “Jobdori”라는 존재다.

“LazyCodex is maintained by Jobdori, the AI assistant that builds and ships OmO in real-time.”

즉 이 프로젝트는 사람이 아니라 커스텀 AI 어시스턴트가 실시간으로 코드를 짜고 배포하는 방식으로 “빌딩 인 퍼블릭”을 하고 있다는 이야기다. 실제로 README는 “이 프로젝트의 99%는 OpenCode로 만들어졌다. 나는 TypeScript를 잘 모른다”라고 적혀 있다. 회사는 여기서 한발 더 나가 소비자용 AI 어시스턴트 “Dori”의 대기자 명단(sisyphuslabs.ai)까지 운영 중이다 — LazyCodex는 그 방향으로 가는 하나의 쇼케이스이자 실험 결과물로 보인다.

8. 로드맵 — Codex와 OpenCode만으로 끝나지 않는다

README는 진행 중인 “멀티 하네스 에이전트 OS 리팩터링”을 명시하고 있다. 목표는 순수 TypeScript 코어 로직과 MCP 서버·스킬·어댑터 계층을 분리해, OpenCode·Codex뿐 아니라 Pi, Claude Code 등 다른 하네스에도 같은 로직을 재사용 가능하게 만드는 것이다. 지금은 “Anthropic이 우리를 막아서 Codex로 넘어왔다”는 농담이 붙어있지만, 로드맵을 보면 결국 Claude Code 지원도 다시 노리고 있다는 뜻이다.

마무리 — 써볼 가치가 있는가

LazyCodex를 한 줄로 정리하면 “OmO라는 거대한 에이전트 하네스의 정수를 Codex 사용자에게 최소 설정으로 넘겨주는 배포판”이다. 핵심은 신기한 신규 기술이 아니라 운영 철학에 있다. “말로 끝났다고 하지 마라, 증거로 증명하라”는 ultrawork 원칙, 계획과 실행을 분리하는 $ulw-plan/$start-work 구조, 세션이 끊겨도 이어지는 .omo/boulder.json 상태 관리는 실제로 며칠씩 걸리는 에이전트 자동화에서 자주 마주치는 “에이전트가 거짓으로 끝났다고 보고하는” 문제를 정면으로 겨냥한 설계다.

다만 진입 장벽은 분명 있다. 풀세트 기능(팀 모드, 다중 에이전트 오케스트레이션, IntentGate)은 OpenCode 위의 Ultimate Edition에만 있고, Codex Light Edition/LazyCodex는 그중 Hephaestus 하나만 이식한 서브셋이라는 점, Windows 네이티브 환경은 권장하지 않는다는 점, 그리고 결국 ChatGPT Pro 이상의 구독이 사실상 전제된다는 점은 미리 알고 들어가는 게 좋다. 반대로 “그냥 OpenAI Codex CLI를 쓰고 있는데, 계획 없이 던진 프롬프트가 중간에 어영부영 끝나버리는 게 지긋지긋하다”면, npx lazycodex-ai install 한 줄로 시험해볼 만한 가치는 충분하다.