LazyCodex 사용법: Codex 프로젝트 기억, 계획, 검증 워크플로

열 개가 넘는 파일에 걸친 기능을 수정한 뒤 Codex가 “완료”라고 보고합니다. 이를 믿고 배포했지만 예외 분기 하나가 빠졌다는 사실을 나중에 알게 됩니다. 복잡한 코드베이스에서 흔한 문제입니다. 새 대화를 열 때마다 agent는 프로젝트를 다시 이해해야 하고, 모델은 무엇을 바꿨는지는 말해도 주변 로직을 빠뜨렸는지는 적극적으로 알려주지 않습니다.

LazyCodex는 OmO(oh-my-openagent) 가운데 Codex에 맞는 기능을 경량 agent harness로 묶은 도구입니다. 프로젝트 기억, 작업 계획, 증거 기반 완료 검증에 초점을 둡니다. 아래에서는 $init-deep, $ulw-plan, $start-work, $ulw-loop가 어떻게 협력하는지, 계층형 AGENTS.md가 대규모 저장소에 어떻게 컨텍스트를 제공하는지, 도구를 설치하지 않아도 적용할 수 있는 엔지니어링 원칙이 무엇인지 설명합니다.

LazyCodex란: OmO의 Codex용 경량 배포판

LazyCodex는 Neovim에 대한 LazyVim의 관계와 비슷합니다. 핵심 기능은 oh-my-openagent(OmO)에서 오고, LazyCodex는 Codex 플러그인 시스템에 맞는 부분을 기존 환경에 설치하는 배포 계층입니다. 프로젝트는 GitHub에 MIT 라이선스로 공개되어 있습니다. 2026년 7월 기준 공식 문서는 이를 OmO의 Codex Light 버전으로 부르며, OmO Ultimate의 완전한 포팅으로 설명하지 않습니다.

Codex만 사용할 때와 LazyCodex의 핵심 차이

비교 항목	Codex만 사용	LazyCodex(Codex Light)
프로젝트 기억	주로 현재 저장소 지침과 세션에 컨텍스트를 의존하며, 준비된 심층 초기화 절차는 없습니다	$init-deep이 계층형 AGENTS.md를 생성해 복잡한 디렉터리에 로컬 지침을 제공합니다
완료 판단	경계 조건을 적극적으로 검증하는지는 작업 설명과 현재 실행 습관에 달려 있습니다	$start-work의 다섯 가지 증거 게이트와 $ulw-loop의 oracle 검증이 완료 기준을 명시합니다
프로세스 규율	바로 편집할 수 있으며, 계획과 실행의 분리는 사용자가 직접 요구해야 합니다	$ulw-plan은 계획만 만들고, $start-work는 계획을 실행하며, $ulw-loop는 증거 루프를 닫습니다
영속성	Codex 세션과 프로젝트 파일로 컨텍스트를 보존합니다	.omo/boulder.json이 계획 실행 상태를 저장하고 Stop hook이 미완료 작업을 계속 진행할 수 있습니다
도구 계층	Codex가 현재 제공하는 skills, MCP, 병렬 기능을 사용합니다	OmO의 rules, hooks, skills, LSP, AST 검색, 모델 라우팅 설정을 추가로 설치합니다

이 harness는 Codex 모델의 핵심 능력을 바꾸지 않습니다. 대신 프로젝트 기억을 만들고, 계획하고, 실행한 뒤 증거로 검증하는 사용 방식을 표준화합니다. OmO Ultimate의 완전한 전문 agent 오케스트레이션과 team_* 도구는 Codex Light에 포함되지 않습니다. LazyCodex의 병렬 작업은 현재 Codex가 제공하는 subagent 또는 team surface를 전제로 합니다.

설치: 전역 설치 없이 npx 한 줄

LazyCodex의 공식 기본 설치 경로는 항상 npx를 사용하며 npm i -g는 필요하지 않습니다.

# 표준 설치
npx lazycodex-ai install

# 같은 의미의 명령(OmO 패키지와 Codex 플랫폼을 직접 지정)
npx --yes --package oh-my-openagent omo install --platform=codex

# 완전 자동 모드(비대화형이며 자율 권한 설정을 명시적으로 활성화)
npx lazycodex-ai install --no-tui --codex-autonomous

# 설치 후 확인
npx lazycodex-ai doctor

설치 프로그램은 Codex 플러그인 캐시와 관련 설정에 파일을 기록합니다. 표준 대화형 설치는 자율 권한을 설정할지 묻습니다. --codex-autonomous는 권한 구성을 바꾸므로 로컬 환경의 보안 경계를 이해한 경우에만 활성화해야 합니다. 설치나 업그레이드 후에는 Codex 시작 검토에서 OmO hooks를 승인하고 새 세션을 열어 플러그인을 로드해야 합니다.

설치가 끝나면 먼저 네 가지 핵심 명령을 기억합니다.

1. $init-deep: 계층형 AGENTS.md 생성
2. $ulw-plan: 요구사항을 승인 대기 중인 의사결정 완결 계획으로 변환
3. $start-work: 계획을 실행하고 진행 상태를 영속 저장
4. $ulw-loop: 하나의 작업을 계속 실행하고 검증

설치된 내용을 먼저 확인하려면 npx lazycodex-ai doctor를 실행하거나 LazyCodex 공식 README와 공식 문서를 확인합니다.

프로젝트 기억: $init-deep으로 계층형 AGENTS.md 만들기

대규모 저장소의 전형적인 문제는 한 번의 대화로 프로젝트 전체를 설명하기 어렵다는 점입니다. 수백 개 파일과 여러 모듈이 있다면 새 세션의 agent는 다시 탐색하거나, 로컬 제약을 모른 채 잘못된 위치를 수정할 수 있습니다.

$init-deep은 대규모 저장소에 “이정표”를 만듭니다.

1. 저장소를 순회하며 프로젝트의 실제 작업 방식을 결정하는 파일을 읽습니다
2. 루트와 복잡한 하위 디렉터리에 계층형 AGENTS.md를 생성합니다
3. 로컬 지침을 관련 코드와 가장 가까운 위치에 둡니다
4. 이후 agent가 편집 전에 적용 범위의 규칙을 먼저 읽게 합니다

계층화가 중요한 이유는 모든 규칙을 루트 파일에 몰아넣지 않고, 로컬 지침을 필요한 코드 옆에 두기 위해서입니다. agent가 특정 모듈에 들어가면 거대한 전체 설명에서 규칙을 골라내지 않고 해당 디렉터리에 적용되는 지침을 바로 볼 수 있습니다.

이 방식은 Agent 기억 시스템 설계에서 다룬 장기 기억 아키텍처와 완전히 같지 않습니다. AGENTS.md는 자동으로 불러오는 대화 기억보다 버전 관리되는 프로젝트 컨텍스트에 가깝습니다. 하지만 두 방식 모두 계층, 로컬 컨텍스트, 영속성을 강조합니다. 설정 파일 하나로 Claude 제어하기의 CLAUDE.md와도 비슷합니다. AI가 작업 전에 규칙을 읽게 한다는 점이 같습니다.

생성된 AGENTS.md는 일반 Markdown 파일이므로 사람이 검토해야 합니다. 코드베이스를 재구성하거나 디렉터리 역할 또는 명령이 바뀌면 $init-deep을 다시 실행하거나 직접 유지보수해야 합니다. 자동 생성 내용을 영구히 올바른 사실 원천으로 취급해서는 안 됩니다.

기억, 계획, 실행, 검증을 나누는 네 가지 명령

LazyCodex의 핵심 흐름은 프로젝트 기억 초기화, 계획, 실행, 검증의 네 단계입니다. 실제 개발 작업에서는 마지막 세 명령이 계획–실행–검증 사이클을 구성합니다.

$ulw-plan: 승인할 계획만 생성

$ulw-plan "what to build"

이 명령은 계획만 만들고 제품 코드는 작성하지 않습니다.

1. 모호한 표현을 곧바로 구현 명세로 간주하지 않고 대화를 통해 요구사항을 명확히 합니다
2. 코드베이스를 탐색하고 독립적인 검색 작업을 병렬 subagent에 배분합니다
3. 현재 상태와 목표 사이의 차이를 분석합니다
4. 참조, 완료 기준, QA 방식, 커밋 경계를 포함한 계획을 plans/<slug>.md에 기록합니다
5. status: awaiting-approval을 설정하고 사용자의 승인을 기다립니다

핵심 제약은 계획 단계에서 제품 변경을 실행하지 않는 것입니다. 범위와 완료 기준을 먼저 명확히 한 뒤 계획을 실행 단계로 넘깁니다. Subagent로 작업 나누기도 비슷한 작업 분할 원칙을 다루지만, LazyCodex는 이를 계획 워크플로에 포함합니다.

$start-work: 상태를 보존하며 계획 실행

$start-work [plan-name] [--worktree <absolute-path>]

이 명령은 승인된 계획의 모든 최상위 checkbox가 끝날 때까지 실행합니다. 주요 기능은 다음과 같습니다.

1. 영속 Boulder 상태: .omo/boulder.json이 turn과 session을 넘어 진행 상태를 보존합니다
2. Stop hook: 계획이 끝나지 않았다면 다음 작업 라운드를 다시 주입합니다
3. 병렬 subagent: 독립적인 하위 작업을 분산할 수 있으며 실제 병렬 기능은 현재 Codex surface에 따라 달라집니다
4. 엄격한 TDD와 다섯 가지 증거 게이트: 계획 재검토, 자동 검증, 수동 QA, 적대적 QA, 정리
5. 진행 장부: 실행 과정과 checkbox 상태를 저장합니다

모든 작업이 끝나면 ORCHESTRATION COMPLETE를 출력합니다. 이는 워크플로가 모든 checkbox와 증거 게이트를 완료했다고 주장한다는 뜻입니다. 상태 한 줄만 믿지 말고 실제 테스트, 수동 QA, 변경 증거를 확인해야 합니다.

$ulw-loop: 하나의 작업을 지속적으로 검증

$ulw-loop "task" [--completion-promise=TEXT] [--strategy=reset|continue]

이 명령은 범위가 분명하지만 증거 검증이 통과할 때까지 계속 실행해야 하는 단일 작업에 적합합니다. 완전한 사전 계획을 대신하지 않으므로 작업이 모호하면 먼저 $ulw-plan을 실행합니다.

• 반복 상한: ultrawork 모드는 최대 500회, 일반 모드는 최대 100회
• 전략: reset은 매번 루프 컨텍스트를 초기화하고 continue는 현재 상태를 이어갑니다
• Completion promise: 수집할 증거, 반드시 통과할 검증, 누락 정보의 처리 방식을 명시합니다
• 중지 조건: oracle이 증거를 바탕으로 완료 약속이 충족되었는지 판단합니다

반복 횟수는 품질을 보장하지 않습니다. 완료 기준이 모호하면 루프는 모호한 판단을 더 빠르게 반복할 뿐입니다. 테스트, 경계 조건, 수동 QA, 실패 처리를 completion promise에 넣는 것이 중요합니다.

복잡한 코드베이스에서 완료 검증이 중요한 이유

복잡한 코드베이스의 전형적인 위험은 변경이 열 개가 넘는 파일에 걸치고 기본 경로는 동작하지만 예외 분기, 호출자, 설정, 문서가 동기화되지 않는 것입니다. 단순히 모델의 능력 문제만은 아닙니다. 완료 판단에 명시적 증거가 빠져 있기 때문입니다.

모델이 경계를 놓치기 쉬운 상황은 다음과 같습니다.

변경 유형	놓치기 쉬운 부분
기본 흐름 변경	네트워크 실패, 매개변수 검증, 권한 부족 같은 예외 분기
인터페이스 추가	이전 시그니처를 계속 사용하는 호출자와 테스트 대역
모듈 리팩터링	테스트, 설정, 문서, 생성 산출물
기능 삭제	의존 진입점, 분석 이벤트, 로그, 마이그레이션 호환 계층

LazyCodex의 가치는 “절대 놓치지 않는다”는 보장이 아니라 검증 동작을 워크플로에 고정하는 데 있습니다. 다섯 가지 증거 게이트는 계획 재검토, 자동 검증, 수동 QA, 적대적 검사, 잔여물 정리를 요구합니다. $ulw-loop는 합의한 증거가 충족될 때까지 단일 작업을 계속합니다. “모델이 완료라고 보고”하는 방식에서 “미리 정의한 증거로 완료를 판단”하는 방식으로 바뀝니다.

증거 게이트에는 여전히 프로젝트 자체의 사실 원천과 좋은 완료 기준이 필요합니다. 인터페이스 시그니처가 바뀌면 모든 호출자를 찾아야 하고, 기능을 삭제하면 의존 진입점을 조사해야 하며, UI 변경은 단위 테스트뿐 아니라 실제 상호작용이 필요합니다. harness는 프로세스 제약을 제공하지만 비즈니스 위험을 자동으로 알지는 못합니다.

OmO 전문 agent와 LazyCodex의 skills 계층

LazyCodex는 OmO에서 왔지만 두 제품의 기능 범위를 구분해야 합니다. OmO Ultimate는 완전한 전문 agent 오케스트레이션을 제공합니다. Codex Light는 Codex 플러그인 시스템에 맞는 구성 요소만 포함하고 Codex 자체의 agent surface를 사용합니다.

전문 agent: 완전한 오케스트레이션은 OmO Ultimate에 포함

Agent 이름	역할	LazyCodex Light의 경계
Sisyphus	실행과 검증을 오케스트레이션	역할 설정이 보일 수는 있지만 Light는 OmO Ultimate의 완전한 agent orchestration을 제공하지 않습니다
Hephaestus	작업을 실행하고 파일을 수정	독립 작업은 현재 Codex에서 사용할 수 있는 subagent 기능이 담당합니다
Oracle	증거에 따라 완료 여부를 판단	$ulw-loop는 증거 검증 습관을 유지하지만 Ultimate의 모든 오케스트레이션 도구를 포함하지는 않습니다
Librarian	컨텍스트를 기록하고 검색	프로젝트 기억은 주로 $init-deep과 계층형 AGENTS.md로 구현됩니다

따라서 OmO Ultimate의 Team Mode, 완전한 전문 agent 팀, team_* 도구를 LazyCodex Light의 내장 기능으로 계산해서는 안 됩니다. 실제로 팀원을 병렬 생성할 수 있는지는 현재 Codex App 또는 CLI가 제공하는 기능에도 달려 있습니다.

Skills 계층: 전문 판단을 재사용 가능한 워크플로로 이동

LazyCodex는 여러 skills와 구성 요소를 설치합니다. 현재 공식 문서가 제시하는 대표 기능은 다음과 같습니다.

Skill 또는 구성 요소	용도
review-work	여러 채널로 구현 결과 검토
remove-ai-slops	동작을 유지하면서 틀에 박힌 AI 흔적 제거
frontend	프런트엔드 디자인과 UI 구현 제약
LSP	진단, 정의, 참조, 심볼 단위 작업
AST-grep	구문 구조에 따라 코드를 검색하고 다시 작성
rules / comment-checker	프로젝트 규칙 로드와 주석 품질 검사
git-bash	Bash 의미 체계가 필요한 환경에 호환 도구 제공

이는 Claude의 Skill 기능과 비슷합니다. 명령은 흐름을 제어하고 skill은 도메인별 판단을 담습니다. 구체적인 skill 목록은 버전에 따라 달라질 수 있으므로 설치 후 Codex의 $ 메뉴나 doctor 출력에서 실제 상태를 확인합니다.

모델 라우팅: 작업 위험에 따라 추론 자원 배분

LazyCodex는 역할이나 작업에 적절한 모델과 reasoning level을 배정하도록 모델 라우팅을 설정합니다. 목적은 토큰 절약을 보장하는 것이 아닙니다. 공식 문서는 오히려 계획, 실행, 검증에 충분한 모델과 컨텍스트를 사용한다고 명시합니다.

더 안정적인 사용 원칙은 다음과 같습니다.

• 일상 작업에는 중간 추론 강도를 사용합니다
• 실패 비용이 높거나 재검토가 필요한 작업은 추론 강도를 높입니다
• 가장 높은 단계는 정말 무거운 작업에만 사용합니다
• 긴 작업은 먼저 범위를 제한하고 나눠 하나의 thread가 과도한 컨텍스트로 무너지지 않게 합니다

구체적인 모델 이름과 라우팅 매트릭스는 바뀔 수 있으므로 설치 시점의 현재 설정을 기준으로 삼습니다. 특정 시점의 README에 나온 모델명을 장기 프로세스에 넣거나 “다중 모델 라우팅”을 “할당량 절약 보장”과 같게 보면 안 됩니다.

설치하지 않아도 적용할 수 있는 네 가지 엔지니어링 원칙

LazyCodex를 설치하지 않더라도 네 가지 원칙을 다른 agent 워크플로에 옮길 수 있습니다.

원칙 1: 대규모 저장소에 계층형 컨텍스트 파일 작성

$init-deep이 생성하는 AGENTS.md의 본질은 대규모 저장소를 위한 버전 관리 가능한 계층형 컨텍스트입니다. 다음 방식으로 직접 적용할 수 있습니다.

• 모든 규칙을 루트에 쌓지 말고 복잡한 디렉터리에 로컬 지침을 작성합니다
• agent가 디렉터리에 들어갈 때 적용 규칙을 바로 보게 합니다
• 코드 구조나 프로세스가 바뀌면 지침을 함께 갱신합니다
• 오래된 설명이 새로운 오류 원인이 되지 않도록 생성 내용을 검토합니다

최소 형태는 루트 AGENTS.md 하나와 몇 개의 핵심 하위 디렉터리 AGENTS.md입니다. 설정 파일 하나로 Claude 제어하기도 비슷한 방법을 제시합니다.

원칙 2: 계획과 실행 분리

먼저 범위, 의존성, 완료 기준, QA, 커밋 경계를 포함한 의사결정 완결 계획을 agent가 작성하게 하고 승인 후 실행합니다. 꼭 plans/*.md 형식을 써야 하는 것은 아닙니다. 계획 단계에서 제품 변경을 몰래 시작하지 않는 것이 핵심입니다.

원칙 3: 완료를 증거에 연결

여러 파일에 걸친 변경에는 검사 목록을 만듭니다. 인터페이스가 바뀌면 호출자를 찾고, 기능을 삭제하면 진입점을 찾으며, UI 변경은 실제 상호작용으로 확인하고, 데이터 마이그레이션은 롤백을 확인합니다. “완료”는 요약이 아니라 구체적인 테스트, 수동 QA, 경계 증거에 연결해야 합니다.

원칙 4: 작업 위험에 따라 모델과 컨텍스트 배분

간단한 질의에는 최고 추론 단계가 필요하지 않습니다. 아키텍처 변경, 마이그레이션, 배포 게이트에는 더 강한 추론과 재검토가 필요합니다. 긴 작업은 토큰 예산만 늘리지 말고 적극적으로 분할해야 합니다.

최소 적용 형태

전체 harness를 설치하지 않으려면 적어도 두 종류의 버전 관리 파일을 유지합니다.

1. 의사결정, 단계, 완료 기준, 미결 사항을 기록한 계획 체크리스트
2. 저장소와 디렉터리 규칙을 기록한 계층형 AGENTS.md

각 변경 유형에 맞는 검증 명령과 수동 QA 목록을 더하면 LazyCodex에서 가장 쉽게 이전할 수 있는 핵심 원칙을 이미 적용한 셈입니다.

LazyCodex가 적합한 경우와 그렇지 않은 경우

LazyCodex는 hooks, 상태 파일, skills, 워크플로 제약을 추가합니다. 모든 프로젝트에 필요한 것은 아닙니다. 다음 표로 판단할 수 있습니다.

적합한 시나리오 판단

비교 항목	LazyCodex가 적합	Codex만 사용하는 편이 간단
저장소 규모	디렉터리 규칙이 많고 파일 간 변경이 잦은 대규모 저장소	소규모 저장소나 단일 파일 프로젝트
작업 복잡도	계획, 실행, 검증이 필요한 장기 작업	일회성 소규모 변경이나 간단한 스크립트
컨텍스트 문제	새 세션마다 디렉터리와 규칙을 자주 다시 탐색	한 세션으로 끝나며 명확한 AGENTS.md가 이미 존재
완료 검증 요구	예외 분기를 놓치기 쉬워 증거 게이트와 수동 QA가 필요	완료 조건이 단순하고 검사 비용이 낮음
프로세스 요구	계획을 먼저 승인하고 실행 상태를 영속화해야 함	추가 상태 계층 없이 바로 편집하기를 원함
권한 수용도	hooks, MCP, 자율 권한 설정을 검토할 수 있음	추가 플러그인이나 Codex 설정 변경을 원하지 않음

이점 판단

저장소가 크고 작업이 길며 완료 검증이 복잡할수록 LazyCodex의 프로세스 제약이 더 유용할 가능성이 큽니다. 대표 사례는 여러 파일에 걸친 리팩터링, 여러 session에 걸친 장기 작업, 자동 테스트와 수동 QA가 모두 필요한 고위험 변경입니다.

비용도 분명합니다. 계층형 컨텍스트를 유지하고, hooks와 권한을 이해하며, .omo/boulder.json 같은 상태 파일을 받아들이고, harness가 만든 계획과 검증 결과를 검토해야 합니다. 설치만으로 누락을 없애는 자동 보험은 아닙니다.

적합하지 않은 시나리오

• 일회성 소규모 변경: 함수, 필드, 문구 하나 수정
• 간단한 스크립트: 한두 파일에 집중되고 완료 조건이 명확한 작업
• 성숙한 기존 프로세스: 신뢰할 수 있는 AGENTS.md, 계획 템플릿, CI, 수동 완료 게이트가 이미 존재
• 추가 설정을 원하지 않음: plugins, hooks, MCP, 자율 권한이 현재 Codex 환경을 바꾸는 것을 원하지 않음

아직 확신이 없다면 전체 도구를 설치하기보다 먼저 계층형 AGENTS.md와 증거 체크리스트를 직접 추가해 봅니다. 프로젝트가 세션 간 컨텍스트 손실, 계획과 실행의 분리, 완료 검증 문제로 실제 어려움을 겪는다는 점을 확인한 뒤 LazyCodex를 평가할 수 있습니다.

결론

복잡한 코드베이스에서 Codex를 사용할 때 어려운 점은 코드를 생성하는 것보다 새 세션이 로컬 규칙을 빠르게 이해하고, 여러 파일에 걸친 변경에서 중요한 경계를 놓치지 않았음을 입증하는 일입니다. LazyCodex는 $init-deep, 계획 승인, Boulder 상태, 증거 게이트를 하나의 Codex Light 워크플로로 묶습니다.

중요한 것은 Sisyphus나 Boulder라는 이름보다 세 가지 검증 가능한 엔지니어링 개선입니다. 컨텍스트를 계층형 파일에 기록하고, 계획과 실행의 경계를 명확히 하며, 완료 판단을 테스트와 수동 QA에 연결합니다. 동시에 LazyCodex는 OmO Ultimate와 같지 않으며 완전한 agent orchestration과 Team Mode를 Light의 기능으로 간주해서는 안 됩니다.

다음 단계로 npx lazycodex-ai doctor를 실행해 환경을 확인하고, 실제 대규모 저장소에서 $init-deep으로 컨텍스트를 생성합니다. 범위가 분명한 다중 파일 작업 하나를 골라 $ulw-plan, $start-work, $ulw-loop 사이클을 끝까지 수행해 봅니다. Codex만 사용할 때와 누락, 컨텍스트 재탐색, 완료 검증 비용을 비교하면 이 harness가 프로젝트에 맞는지 판단할 수 있습니다.