LazyCodex 사용법, 계획부터 검증까지 멈추지 않는 Codex용 에이전트 하네스

AI 코딩 도구 Codex를 크고 복잡한 프로젝트에서도 안정적으로 쓸 수 있게 해주는 오픈소스 도구가 공개되었습니다. 바로 'LazyCodex'입니다.

Codex에 설치하면 AI가 코드부터 짜는 대신, 프로젝트를 먼저 파악하고 계획을 세운 뒤 작업 결과까지 검증하는 체계적인 흐름이 더해집니다. 

파일 수십 개가 얽힌 큰 작업에서 AI가 맥락을 놓치거나 작업을 끝까지 완수하지 못하는 문제를 줄여줍니다.

이 글에서는 LazyCodex가 무엇인지, 기존 방식과 무엇이 다른지, 왜 개발자들 사이에서 주목받는지 정리하며, 설치 방법부터 실제 프로젝트에 투입해 성능을 검증한 테스트 결과까지 함께 담았습니다.

LazyCodex 핵심 요약

• LazyCodex는 개발자 김영규가 만든 오픈소스 에이전트 하네스입니다. Codex에 설치하면 AI가 코드부터 짜는 대신 프로젝트 파악, 계획 수립, 결과 검증의 절차를 밟습니다.
• 작업은 4개 스킬로 진행합니다. 진행 상황을 파일로 기록해 세션이 끊겨도 이어서 작업합니다.
• 완료는 말이 아닌 증거로 판단합니다. 테스트 통과와 실제 동작 확인을 근거로 삼고, 검증에 실패하면 통과할 때까지 다시 수정합니다.
• 계획과 검증을 거치는 만큼 시간과 토큰 소모가 큽니다. 작은 작업에는 과하고, 수정 범위가 넓어 파일 하나만 놓쳐도 사고로 이어지는 작업에 적합합니다.

LazyCodex란?

* 이미지 출처: LazyCodex 홈페이지

LazyCodex는 개발자 김영규(code-yeongyu)가 만든 오픈소스 도구로, Codex를 복잡한 코드베이스에서 제대로 쓰기 위한 '에이전트 하네스(agent harness)'입니다. 

하네스란 AI가 계획, 실행, 검증 절차를 따라 움직이도록 잡아주는 실행 환경으로 AI가 복잡하고 까다로운 프로젝트를 맥락 안에서 더 안정적으로 해주는 장치로, LazyCodex는 Codex에 이런 하네스 구조를 더해, 큰 코드베이스에서도 작업을 더 체계적으로 진행할 수 있게 해줍니다. 

하네스 엔지니어링에 대해 더 자세히 알고 싶으면 아래 링크를 참고하세요.

▶ 하네스 엔지니어링이란? AI 에이전트 제대로 쓰려면 이것부터

LazyCodex가 주목받는 이유

큰 작업에서도 맥락을 유지합니다.

LazyCodex는 프로젝트 구조와 규칙을 먼저 정리해 기록하고, 이후 세션에서도 그 정보를 참고할 수 있도록 돕습니다. 덕분에 복잡한 코드베이스를 다룰 때 내용을 놓치거나 잘못된 파일을 건드릴 가능성을 줄여줍니다. 

코드를 고치기 전에 계획부터 수립합니다.

복잡한 작업에서는 바로 코드를 수정하기보다, 먼저 코드베이스를 살펴보고 결정이 필요한 부분을 정리합니다. 이후 실행 계획을 만든 뒤 작업에 들어가기 때문에 방향을 먼저 맞출 수 있고, 불필요한 수정과 재작업을 줄이는 데 도움이 됩니다.

말이 아니라 증거로 완료 여부를 판단합니다.

LazyCodex는 AI의 “완료했다”는 선언보다 실제로 됐는지를 확인하는 흐름을 강조합니다. 테스트 통과, 실행 결과 , 실제 동작 확인 같은 증거를 바탕으로 완료 여부를 판단하고, 검증에 실패하면 다시 이어서 수정하도록 설계되어 있습니다. 

LazyCodex 사용법

LazyCodex는 명령어 한 줄로 설치합니다. 먼저 준비물이 있습니다. Codex앱 또는 CLI가 설치되고 로그인돼 있어야 하고, Node.js가 필요합니다. 

▶ Codex CLI 설치 방법 확인하기

LazyCodex 설치하기

위의 명령을 넣으면 LazyCodex가 Codex에 명령, 스킬, 훅, 모델 배정, 검증 기본값을 한 번에 연결합니다. 전역 설치(npm install -g)는 쓰지 말고 반드시 npx로 실행해야 합니다.

LazyCodex의 설치가 완료되었습니다. Codex CLI를 실행한 뒤 입력창에 $를 입력하면 init-deep, ulw-plan, start-work, ulw-loop 같은 스킬 목록이 나타납니다. 

이 스킬들이 보이면 LazyCodex를 바로 사용할 수 있습니다.

LazyCodex의 주요 스킬

프로젝트를 처음 파악할 때 - $init-deep 

크거나 오래된 프로젝트를 처음 다룰 때 씁니다. 이 명령을 실행하면 LazyCodex가 코드베이스를 훑어 구조와 규칙을 정리한 안내 문서를 만듭니다. 

이렇게 만들어둔 맥락을 이후 작업에서 AI가 먼저 참고하므로, 첫 세션에 들인 시간이 이후 모든 작업을 수월하게 합니다.

결정이 필요한 작업을 시작할 때 - $ulw-plan 

바로 코드를 짜기 애매하고 방향부터 정해야 하는 작업에 씁니다. AI가 코드베이스를 살펴보고 필요한 결정을 정리한 계획서를 만듭니다. 이때 실제 코드는 건드리지 않아, 계획을 검토하고 승인한 뒤 실행할 수 있습니다.

계획을 실행할 때 - $start-work 

세워둔 계획을 실제로 실행하는 명령입니다. 계획의 모든 항목이 끝날 때까지 작업을 이어가며, 진행 상태를 기록해둡니다. 그래서 세션이 중간에 끊겨도 이어서 진행할 수 있습니다.

끝까지 검증하며 밀어붙일 때 - $ulw-loop 

결과가 검증될 때까지 작업을 반복하는 명령입니다. AI가 "끝났다"고 해도, 실제로 됐는지 확인(검증)에 통과하지 못하면 작업을 계속합니다. 결제 오류 수정처럼 확실히 해결됐는지가 중요한 작업에 적합합니다.

LazyCodex 성능 테스트

LazyCodex가 실제로 계획을 세우고 검증까지 해내는지 확인하기 위해 직접 테스트를 진행했습니다. 단순한 코드 생성이 아니라, 여러 파일에 흩어진 로직을 추적해야 하는 작업에서 진가가 드러나는지 보는 것이 목적입니다.

테스트 환경 구성

테스트 대상은 Node.js와 Express로 만든 가상의 쇼핑몰 백엔드입니다. 

주문, 배송, 환불, 상품, 회원, 쿠폰, 통계까지 라우터 8개와 서비스 레이어, 테스트 코드 8개로 구성했습니다.

여기에 실제 레거시 프로젝트에서 흔히 보이는 함정을 일부러 심었습니다. 관리자 권한 체크가 파일마다 다른 방식으로 구현되어 있습니다. 

어떤 라우터는 requireAdmin 미들웨어를 체이닝하고, 어떤 핸들러는 req.user.role !== 'admin'을 인라인으로 비교하고, 또 다른 곳은 별도의 roleUtils.isAdmin() 유틸 함수를 호출합니다. 외주 개발사를 여러 번 거친 프로젝트에서 자주 마주치는 형태입니다.

본격적인 테스트에 앞서 기준선부터 확보했습니다.

 LazyCodex에게 프로젝트 의존성 설치와 테스트 실행을 지시하자, 스스로 계획을 세워 npm install과 npm test를 순서대로 진행하고 체크 리스트를 하나씩 지워가며 결과를 보고했습니다.

결과는 355개 패키지 설치에 보안 취약점 0건, 테스트 스위트 3개와 테스트 8개 전부 통과입니다.

테스트 과제

이 프로젝트에 'CS 담당자(cs)' 역할을 추가하는 작업을 맡겼습니다. 주문 조회, 배송 상태 변경, 환불 대기 목록 조회는 허용하되, 환불 승인, 상품 가격 수정, 쿠폰 발행, 회원 역할 변경은 차단해야 합니다.

한두 파일 수정으로 끝나지 않는 과제입니다. 세 갈래로 흩어진 권한 체크를 전부 찾아내야 하고, 회원 역할 변경 API에 하드코딩된 ['admin', 'user'] 화이트리스트까지 고쳐야 운영자가 회원을 cs로 지정할 수 있습니다. 하나라도 놓치면 권한이 잘못 열리거나 잘못 막힙니다.

1단계, 계획 수립하기

이제 CS 담당자 역할 추가 작업을 위해 계획 수립을 진행해보겠습니다. 프롬프트는 아래와 같이 입력했습니다. 

테스트를 진행하고 약 19분 뒤 계획 문서가 완성됐습니다. 제품 코드는 건드리지 않은 상태입니다. 보고 내용의 핵심은 다음과 같습니다.

• 함정 4개 전부 발견: 3가지로 흩어진 권한 체크 방식(미들웨어, 인라인 비교, 유틸 함수)을 모두 매핑하고, 가장 놓치기 쉬운 역할 화이트리스트까지 찾아 확장 계획에 포함했습니다.
• 지시하지 않은 설계 판단: requireAdmin에 cs를 끼워 넣는 대신 별도 capability 정책으로 분리했고, 언급되지 않은 기능은 전부 기본 차단으로 처리했습니다.
• 자체 검증 보고: "코드 수정 금지" 지시를 지켰는지 src, tests 폴더 변경 여부를 스스로 확인해 보고했습니다.

계획 수립에 걸린 시간은 18분 40초, 사용한 토큰은 12만 개입니다. 일반적인 AI 코딩 도구라면 이런 계획을 세우지 않고 코드부터 수정했겠지만, LazyCodex는 그 시간을 코드 파악과 계획에 먼저 사용하는 것을 볼 수 있습니다.

2단계: $start-work로 계획 실행하기

이제 계획을 실제 코드 수정으로 옮겨보겠습니다. $start-work는 계획 문서를 체크리스트 삼아 항목을 하나씩 처리하고, 진행 상황을 파일로 기록하면서 계획이 끝날 때까지 작업을 이어갑니다.

이 단계에서 확인할 것은 두 가지입니다. 계획 문서에 정리한 순서대로 실행하는지, 그리고 완료를 말이 아닌 테스트 통과로 증명하는지입니다.

사용한 프롬프트는 아래와 같습니다.

성능 테스트 실행 결과

$start-work 실행에는 약 50분이 걸렸습니다. LazyCodex는 계획을 5개 작업 단위로 나눠 실패하는 테스트 작성 → 중앙 역할 정책 → 라우트 가드 → 화이트리스트 순으로 수정하고, 항목마다 체크리스트를 지워가며 진행했습니다.

구현이 끝나자 스스로 완료를 선언하는 대신 읽기 전용 검증자 4개를 병렬로 띄웠습니다. 

계획 준수, 코드 품질, 실제 QA, 범위 충실도를 각각 감사하고 전원 승인해야 완료 처리하는 구조로, QA 검증자는 서버를 직접 띄워 curl 요청까지 보내고 기록을 증거 파일로 남겼습니다.

npm test 결과 테스트 24개 전부 통과했습니다. 기존 8개는 그대로 유지됐고, cs 역할 검증 테스트 16개가 추가됐습니다. 계획에서 찾아낸 함정 4개도 모두 수정에 반영됐습니다.

흩어진 권한 체크와 숨겨둔 함정 4개를 계획 단계에서 전부 발견했고, 계획-실행 분리 원칙이 실제로 지켜졌으며, 완료 선언이 검증자 교차 감사와 테스트 통과로 뒷받침됐습니다.

* LazyCodex를 테스트하며 느낀 한계점

목표한 설정값에 맞춰 AI 스스로 검수까지하며 작업을 완수하는 모습을 보였습니다. 하지만 토큰 소비 비용이 많고, 시간이 오래걸렸습니다. 계획 19분, 실행 50분에 사용 한도를 거의 소진했습니다. 

LazyCodex는 빠른 도구가 아닙니다. 수정 범위가 넓고 파일 하나만 놓쳐도 사고로 이어지는 작업에서, 시간을 주고 정확성을 사는 도구입니다. 

작은 프로젝트라면 사람이 직접 고치는 편 훨씬 효율적입니다. 

LazyCodex, 이런 작업에 활용해보세요.

큰 코드베이스의 구조 파악

큰 프로젝트에서 기능 하나가 파일 하나 안에 깔끔하게 들어 있는 경우는 드뭅니다. 인증, 결제, 권한 처리 같은 핵심 흐름도 여러 모듈에 나뉘어 있는 일이 많습니다.

LazyCodex의 $init-deep 명령은 복잡한 디렉터리를 분석해 코드 근처에 로컬 가이드를 남기고, 계층형 AGENTS.md 문서를 만들어둡니다. 

에이전트가 코드를 고치기 전에 참고할 이정표를 먼저 세워두는 방식으로, 프로젝트가 커서 매번 구조를 설명하기 어렵다면, 이 프로젝트 메모리가 꽤 큰 도움이 됩니다.

수정 범위가 넓은 기능 개발

관리자 권한 체계를 바꾸거나 검색 기능에 필터와 정렬을 추가하는 작업은 한두 파일만 고쳐서 끝나지 않습니다. 영향 범위를 파악하고, 계획을 세우고, 단계별로 수정하는 과정이 필요합니다.

LazyCodex는 이 흐름을 명령으로 나눠둔 점이 특징입니다. $ulw-plan은 모호한 요구사항을 실행 가능한 계획으로 정리하고, $start-work는 그 계획을 체크리스트처럼 따라가며 진행 상황을 기록합니다. 

계획 단계에서는 plans 폴더에 문서만 작성하고 제품 코드는 건드리지 않기 때문에, 본격적인 수정 전에 방향을 검토할 여유가 생깁니다.

버그 재현과 원인 추적

특정 조건에서만 깨지는 버그는 로그 몇 줄만 보고 원인을 찾기 어렵습니다. 관련 파일의 흐름과 테스트를 함께 따라가야 할 때가 많습니다.

LazyCodex의 핵심 워커인 Hephaestus는 코드를 쓰기 전에 병렬 탐색 서브에이전트를 실행해 먼저 지형을 파악합니다.

추측으로 접근하기보다 도구로 코드를 직접 읽고, 수정 후에는 LSP 진단, 테스트, 빌드를 병렬로 돌려 실제 동작 여부를 확인합니다.

LazyCodex 사용 시 주의사항 4가지

작은 작업에는 오히려 과합니다. 

LazyCodex는 크고 복잡한 작업을 위한 도구입니다. 한 줄 수정이나 간단한 질문은 계획·검증 과정이 오히려 번거로울 수 있습니다. 

이런 작업은 LazyCodex 없이 Codex만으로 처리하는 것이 빠릅니다. 파일이 많이 얽히거나 오래 걸리는 작업일 때 쓰는 것이 좋습니다.

토큰을 아끼는 도구가 아닙니다. 

LazyCodex는 계획과 검증을 거치는 만큼, 오히려 토큰을 더 쓸 수 있습니다. 

공식 문서도 이 도구가 토큰 절약용이 아니라, 좋은 모델과 충분한 토큰을 들여 작업의 완성도를 높이는 도구라고 설명합니다. 

비용에 민감하다면 이 점을 감안해야 하며, 큰 작업은 작은 단위로 나눠 진행하는 것이 좋습니다.

운영체제 환경을 확인해야 합니다. 

LazyCodex는 우분투(Ubuntu)나 macOS 같은 유닉스 계열 환경에서 가장 안정적으로 작동합니다. 

윈도우도 지원하지만, 셸과 경로 차이 때문에 문제가 생길 수 있어 공식 문서는 권장하지 않습니다. 

윈도우 사용자라면 WSL2(윈도우에서 리눅스를 쓰는 기능) 환경에서 실행하는 것이 안전합니다.

다른 유사 도구와 함께 쓰지 않는 것이 좋습니다. 

LazyCodex는 Codex 위에 올리는 유일한 층으로 작동하도록 설계됐습니다. 비슷한 역할을 하는 다른 도구(OMX 등)를 함께 설치하면 충돌이 생겨, 토큰을 낭비하거나 조용히 실패할 수 있습니다. 설치 과정에서 충돌 경고가 뜨면 하나를 제거하는 것이 좋습니다.

함께 참고하면 유용한 콘텐츠

Ponytail 사용법: AI 코딩 에이전트의 과잉 구현을 줄이는 스킬 실행하기

Codex Goal 사용법, 목표만 설정하면 끝까지 간다

OpenWiki 사용법: 코드베이스를 AI 에이전트의 지식 저장소로 만들기

AI, 결국 사용하는 사람이 중요합니다 

LazyCodex 같은 도구는 AI가 복잡한 개발 작업을 더 체계적으로 수행하도록 돕습니다. 하지만 어떤 도구를 어떤 프로젝트에 적용할지 판단하고, 실제 서비스에 안전하게 반영하는 일은 결국 사람의 몫입니다. 

AI 도구를 프로젝트에 맞게 활용하고, 결과물을 검증하며, 실제 시스템에 통합하려면 그 환경을 이해하는 실무 전문가가 필요합니다.

AI의 가능성을 성과로 바꿀 IT 전문가, 이랜서가 매칭합니다.

이랜서는 27년간 쌓아온 노하우를 바탕으로, 8만 건 이상의 프로젝트 매칭을 진행해왔습니다. 41만 명 규모의 IT 프리랜서 네트워크를 통해 개발 분야의 검증된 전문가를 연결하며, 프로젝트를 등록하면 24시간 내에 적합한 인재를 연결받을 수 있습니다. 

• 삼성·SK·현대 등 주요 기업 프로젝트 매칭 8만 건 +
• 기업 프로젝트 재의뢰율 98%

AX·DX·클라우드·핀테크·개발·기획·디자인 등 프로젝트를 직접 수행해 업무와 현장을 이해하고, 프로젝트 운영과 검증에 빠르게 참여할 수 있는 실무형 IT 프리랜서를 매칭합니다.

▶ 프로젝트 등록하고 현장형 IT 프리랜서 매칭받기