긴 코딩 작업을 한 대화에서 끝까지 밀어붙이면 계획이 바뀌어도 이미 수정한 코드를 기준으로 판단하기 쉽다. LazyCodex는 이런 작업을 계획, 실행, 검증으로 나누는 서드파티 에이전트 하네스다. OpenAI 공식 기능이나 새 모델이 아니라, OmO의 명령·스킬·훅·에이전트 역할을 Codex에 연결하는 오픈소스 배포판이다. 핵심은 모든 명령을 차례대로 붙이는 것이 아니다. 계획이 필요한 일은 $ulw-plan과 $start-work를 잇고, 범위가 선명한 단일 과제는 $ulw-loop라는 별도 경로로 실행과 검증을 묶는다.
먼저 설치 상태와 권한 경계를 확인하기
LazyCodex는 Codex 설정에 여러 구성 요소를 더하므로, 설치 직후에는 npx lazycodex-ai doctor로 플러그인 캐시, 훅, MCP 서버, 에이전트와 설정 상태를 확인한다. 다음 Codex 실행 때 표시되는 훅 승인 내용도 읽는다. 공식 문서상 훅은 승인 전에는 실행되지 않는다. 첫 실습은 깨끗한 브랜치나 별도 워크트리에서 시작하고, 수정 가능한 디렉터리와 실행 가능한 명령을 좁힌다. 운영 브랜치 직접 병합, 비밀정보 접근, 배포와 데이터 변경은 루프 밖의 수동 승인 단계로 둔다.
$ulw-plan에서 코드보다 결정을 먼저 완성하기
$ulw-plan "만들 기능"은 계획을 plans/<slug>.md에 쓰고 제품 코드는 수정하지 않는 명령이다. 현행 LazyCodex 명령 문서도 이를 구현자가 아닌 전략 계획 도구로 구분한다. 목표만 던지고 바로 실행하지 말고, 성공 조건·제외 범위·관련 테스트·되돌리는 방법을 계획에 포함시킨다. 승인 전에는 대상 파일이 근거와 함께 적혔는지, 새 의존성이나 마이그레이션이 드러났는지, 각 단계의 확인 명령이 있는지 본다. 모르는 요구가 남았다면 계획을 고친 뒤 다시 검토한다. 계획 문서는 실행자가 추가 추측 없이 체크박스를 처리할 수 있는 계약이어야 한다.
$start-work에는 승인된 계획만 넘기기
계획이 승인되면 $start-work [plan-name]으로 실행을 시작한다. 다른 워크트리에서 실행할 때의 문서상 형식은 $start-work [plan-name] --worktree <absolute-path>다. 자동 생성된다고 가정하지 말고, 사용할 워크트리의 절대 경로를 지정한다. 이 단계에서 새 기능 요구를 끼워 넣으면 계획과 실제 변경의 대응 관계가 깨진다. 범위를 바꿔야 한다면 실행을 멈추고 계획으로 돌아간다. 실행 중에는 완료된 체크박스 수보다 예상 밖 파일 변경, 실패한 진단, 생략된 테스트를 먼저 본다. ORCHESTRATION COMPLETE는 모든 상위 체크박스가 끝났다는 신호이지, 제품 인수 보증은 아니다.
범위가 선명한 단일 과제는 $ulw-loop로 실행하기
$ulw-loop "과제"는 계획 실행 뒤에 붙이는 사후 검사 명령이 아니다. 스스로 계획 문서를 만들지 않고, 범위가 이미 분명한 단일 과제를 직접 실행한 뒤 Oracle이 증거를 승인할 때까지 반복하는 별도 경로다. $start-work에도 자동 검사와 수동 QA 등 자체 증거 관문이 있으므로 두 명령을 의무적으로 연달아 실행할 필요가 없다. 루프에는 “잘 작동할 때까지”보다 “지정 테스트 통과, 변경 화면 확인, 이번 변경으로 새로 생긴 미해결 진단 0건”처럼 관찰 가능한 종료 조건을 준다.
내장 반복·동일 실패 한도를 먼저 확인하고, 정한 시간 예산을 넘기면 사람이 중단한다. 끝난 뒤에는 변경 파일, 실행한 검사, 실행하지 못한 검사와 남은 위험을 따로 기록한다. 처음에는 파일 몇 개와 테스트 하나로 끝나는 작업에서 두 경로를 나눠 연습한다. 계획에 없던 파일이 바뀌거나 검증에서 새 문제가 나오면 어느 가정이 틀렸는지 남긴다. LazyCodex를 잘 쓴다는 것은 오래 자동 실행하는 일이 아니라, 과제의 모호성에 맞는 경로를 고르고 완료 근거를 보존하는 일이다.
참고 자료
확인 기준: 2026년 7월 29일, LazyCodex 문서 v0.2.2.