본 기사는 개인 개발 중인 HD-2D 탐색 액션 어드벤처 Anemora 제작에 사용하고 있는 Codex CLI의 서브 에이전트 운용 패턴 「Cycle」의 설계와 수치 결과에 대해 다룹니다. AI 협업의 세션 간 동기화에 대해서는 선행 기사 (Codex CLI의 동기화 설계)를 참조해 주세요.

TL;DR

• 하나의 구현 사이클을 「parent (gpt-5.5)가 절차서를 작성한다 → cycle-worker 서브 에이전트 (gpt-5.4-mini)가 1개 파일 (+ 명시된 관련 파일)을 구현한다 → 4단계 배치(batch)로 자동 commit/push한다」는 형태로 고정했습니다. - per-thread 토큰 소비가 **약 36.7M → 약 6.0M (약 1/6, 84% 감소)**로 낮아졌습니다 (Anemora 관련 348 스레드, state_5.sqlite 직접 확인) - 연속 자율 주행 시간도 늘어났습니다. 최장 **22.5시간 연속으로 동작한 런(run)**이 있었으며, 제가 리뷰용으로 별도의 프롬프트를 삽입한 지점이 끊기는 부분입니다. 추상도가 높은 목표라면 더욱 길게 돌릴 수 있습니다 - workers 서브 에이전트 자체는 이행 전부터 사용하고 있었습니다. 경계의 본질은 「workers를 도입했다」가 아니라 「사용법을 재설계했다」는 것입니다 - 모든 자동 체크를 통과하더라도 외관상의 결함이 남는 케이스 (후술)는 그대로 남습니다. 자동 체크는 육안 확인을 대신할 수 없습니다 - 배포 키트를 GitHub에서 공개하고 있습니다: https://github.com/marvelousu/codex-cycle-kit

1. 무엇을 바꾸었는가

선행 기사 Codex CLI의 동기화 설계 시점에서도, parent (gpt-5.5) + worker 수 대의 병렬 운용은 이미 구성되어 있었습니다. 다만 worker 측에도 gpt-5.5를 할당하여 어느 정도 규모가 있는 태스크를 한 번에 넘겨주었기 때문에, 1 세션당 토큰 소비가 컸고, 실패 시의 리커버리(recovery)도 수작업 중심이라 parent의 손이 비지 않는다는 규모의 벽에 부딪혔습니다. 그래서 「역할 편성」, 「절차서」, 「1 Cycle의 형태」라는 3가지 포인트를 동시에 변경했습니다.

1.1 역할 편성 (모델의 배분)

• parent (gpt-5.5): 무거운 의사결정, 절차서 작성, 캡처 이미지 확인, 커밋 내용 리뷰를 담당합니다. 구현은 하지 않습니다.
• cycle-worker (gpt-5.4-mini): 메인 파일 1개와 허가 리스트 형식으로 명시한 관련 파일만 편집하는 소형 워커입니다. helper 메서드를 하나 추가하여 기존 호출 측에 한 줄로 연결하는 것이 기본 패턴입니다.
• cycle-runner (PowerShell): 검증 → 캡처 → 빌드 → 동작 확인의 4단계를 순차적으로 실행하며, 모두 통과하면 commit + push까지 진행하는 자동화 스크립트입니다.

1.2 「절차서」의 정의

parent가 worker에게 전달하는 scoped prompt (작업 지시서)의 항목을 채워 고정형으로 만들었습니다.

이 템플릿을 ~/.codex/skills/cycle-start/에 skill로서 배치하고, parent 세션에서 /skill cycle-start로 호출합니다.

1.3 1 Cycle의 형태

1 cycle = 1 파일 (+ 관련) 구현 + 1 commit + 1 push + 1 screenshot + 1 devlog (개발 기록 md 파일, Anemora에서는 docs/devlog/ 하위에 배치)를 1 단위로 했습니다.

[parent] /skill cycle-start로 scoped prompt 생성
↓ multi_agent.spawn(cycle-worker)
[worker] 1 파일 + 관련 파일을 편집 → WORKER_RESULT를 반환
...

parent의 몫으로는 「작업 지시서의 항목을 채우기」, 「캡처 이미지를 육안으로 확인하기」의 2가지 포인트만 남습니다. 또한 cycle-runner는 -SkipPush

를 붙이면 push를 억제하고 commit 단계에서 멈출 수 있습니다 (자세한 내용은 다음 절).

1.4 왜 push까지 자동화했는가

각 사이클(Cycle)이 완료될 때 push까지 자동으로 진행되도록 기본 설정한 이유는, AI가 제가 잠든 사이나 외출 중에도 계속 돌아가기 때문에, 나중에 각 사이클을 거슬러 올라가며 확인할 수 있는 증적과, 스마트폰으로 GitHub를 통해 진행 상황을 살펴보는 원격 감시를 겸하기 위한 개인 개발의 사정 때문입니다. 팀 개발에서 PR 리뷰가 전제라면, cycle-runner에 -SkipPush를 전달하여 push를 끊고 commit 단계에서 멈출 수 있습니다.

2. 망가뜨리지 않고 돌리는 가드레일 (4개 층)

서브 에이전트(Sub-agent)에게 맡겨도 폭주하지 않도록 4개의 가드레일을 설치했습니다.

• 편집 스코프(Scope) = 1 + N의 허가 목록: worker는 메인 파일 1개와 명시적으로 열거된 관련 파일만 편집합니다. 와일드카드 (glob)는 전달하지 않습니다. 이것이 깨지면 1 사이클의 추적이 불가능해집니다.
• 「helper 메서드 + 1행 연결」 구현 패턴: 기존 호출 측의 리팩토링, 메서드 이름 변경, 새로운 최상위 구조 (class / module / service) 추가는 금지됩니다. 이것들은 parent의 영역입니다.
• WORKER_RESULT 계약: worker는 마지막에 authored_file / side_effect_files / validate_method / capture_method를 코드 블록으로 반환합니다. cycle-runner는 이 4가지로 기동합니다.
• 스코프 확장의 신고 경로 유지: worker가 스코프 내에서 구현할 수 없다고 판단하면, status: scope_widen_required를 이유와 함께 반환합니다. 이것이 없으면 처리 능력이 부족한 worker가 몰래 스코프를 넓혀버려 비용 절감이 무너집니다.

3. 결과

수치는 Codex CLI의 내부 상태 DB인 ~/.codex/state_5.sqlite의 threads 테이블을 직접 SELECT 하여 집계했습니다. Anemora 관련 348 / 410 스레드 (first_user_message와 cwd의 문자열 필터 적용, 85% 커버)를 대상으로 합니다.

3.1 Era별 1 스레드당 평균 토큰

평균 토큰 소비가 **약 36.7M → 약 6.0M (약 1/6, 84% 감소)**가 되었습니다. 스레드 수 (= 사이클 수)는 Era2에서 오히려 동등하거나 그 이상으로 나오고 있으므로, "수를 줄여서 합계를 낮춘 것"이 아니라, "1 사이클당 비용이 정말로 가벼워진" 결과입니다.

참고로, worker 서브 에이전트 자체는 Era1부터 이미 사용하고 있었습니다 (agent_role='worker'의 첫 등장은 2026-05-05, 프로젝트 2일째). 다만 당시에는 worker도 gpt-5.5로 구동하며 큰 태스크를 한 번에 넘겼기 때문에, 출발점이 원래 높았다는 점에는 주의해야 합니다. 84% 감소라는 숫자는 이 높은 출발점으로부터의 상대적인 값이며, 처음부터 경량 모델로 서브 에이전트를 돌리고 있는 프로젝트에서는 절감 폭이 작아집니다. Era 경계의 본질은 workers를 도입한 것이 아니라, 그 사용법을 재설계한 것입니다.

Era 경계는 칼로 자르듯 나뉘는 것이 아니라, Fast VS 공개 (2026-05-18)를 계기로 05-19 ~ 05-20 사이의 며칠 동안 단계적으로 이행되었습니다. 일 단위로 보면, 05-17의 평균 30.1M이 다음 날인 05-18에 3.5M, 05-19에 4.4M, 05-20에 6.5M으로 급감했습니다.

3.2 인과 분석

1 사이클당 토큰 감소는 대체로 다음 4가지로 나눌 수 있습니다 (내역의 수치 배분은 엄격하게 측정하지 않았으므로, 기여의 방향성입니다).

• 1 사이클에서 다루는 파일을 1개 + 관련 파일로 압축함으로써, 다른 파일들을 가로질러 읽어오는 비용이 사라졌다.
• worker를 거의 전부 gpt-5.4-mini에 태우고, 긴 문맥(Long Context)을 다룰 수 있는 무거운 모델 (gpt-5.5)은 구현을 하지 않는 parent의 지휘 역할에만 전념시켰다.
• 자유 대화 형식의 QA를 그만두고, 정해진 검증 메서드를 호출하는 자동 체크로 교체했다.
• 실패 시 스코프 확대(Scope Expansion)를 신고하는 경로 (scope_widen_required)를 WORKER_RESULT에 포함했기 때문에, 모델의 처리 능력 부족이 폭주 사이클로 이어지지 않고 빠른 단계에서 표면화되도록 했다.

3.3 연속 자율 주행 시간

또 다른 지표로 "1 세션이 몇 시간 동안 연속으로 멈추지 않았는가"가 있습니다. Cycle 운용에 도입한 후 최장 기록은 22.5시간이며, 이는 제가 리뷰용 프롬프트를 삽입한 시점에서 끊긴 것입니다. 추상도가 높은 지시(예를 들어 그래픽 개선과 같은 큰 목표)를 내린다면, 원리상으로는 사이클 열을 끊지 않고 연속 실행할 수 있습니다. 제목의 "장시간 연속 자율 주행"은 이 부분이 근거입니다.

4. 막혔던 부분

처리 능력 부족 시, 스코프 확대 경로를 생략하지 말 것

어느 사이클에서 gpt-5.4-mini의 worker에게 2회 요청했으나, 두 번 모두 모델의 처리 능력 부족으로 실패했습니다. 두 번째 worker는 중간까지의 구현을 남겨두었기에, parent 측에서 컴파일이 통과되지 않을 리스크를 수정하고 사이클을 로컬에서 완료하여 브랜치를 멈추지 않는 판단을 내렸습니다.

교훈으로서, worker로부터 status: scope_widen_required가 반환되었을 때, 혹은 중간까지의 구현이 남았을 때, parent가 이를 인계받는 규율을 남겨두어야 합니다. 스코프 확대 경로를 "다시 요청하면 된다"며 생략해버리면, 처리 능력의 벽에 부딪히는 순간 막히게 됩니다.

자동 체크는 모두 통과했지만, 육안으로는 NG

또 다른 예로, §1.3에서 설명한 4단계(검증 → 캡처 → 빌드 → 동작 확인)가 모두 통과되어 자동으로 commit과 push까지 완료된 사이클이 있었습니다. 그런데 parent 측에서 캡처 이미지를 눈으로 확인해보니, 집 외관의 그림자 처리(검은 벽면 주변)에 위화감이 남아 있었습니다. 다음 사이클에서는 먼저 확인용 카메라의 구도를 조정한 후, 그림자 조정을 다시 수행하는 순서로 판단했습니다.

자동 체크는 육안 확인을 대신할 수 없습니다. 검증 메서드가 통과하는 것, 캡처 이미지가 나오는 것, 이 자체는 "그림체가 OK"인 것이 아니라 "그림체를 판정할 소재가 갖춰졌다"는 것뿐입니다. 마지막 판단은 parent, 혹은 parent 세션을 구동하는 인간이 내립니다.

배포 키트의 hardening(경화)에 대하여

배포 키트의 cycle-runner는 좋은 골격이지만, Anemora 리포에 투입했을 때는 5가지 수정 사항(실패 시 rollback 회피, commit 경로 한정, 배치 인자 전달, 프로세스 완료 대기, 실패 로그 생성)을 넣어야 했습니다. 배포 키트가 그대로 어떤 프로젝트에서도 동작한다고 광고하지는 않겠습니다. 구체적인 플래그나 차이점은 배포 리포(codex-cycle-kit)의 README를 참조하십시오.

5. 재현용 템플릿 (배포 키트)

실물을 배포 키트로서 GitHub에 공개하고 있습니다: https://github.com/marvelousu/codex-cycle-kit

최소 구성으로서, skill만 수동으로 넣는 예시:

git clone https://github.com/marvelousu/codex-cycle-kit.git tmp \\ 
&& cp -r tmp/skills/cycle-start ~/.codex/skills/ \\ 
&& rm -rf tmp
...

cycle-runner는 Unity Editor 기본값이지만, -BatchTool로 다른 배치 명령어로 교체할 수 있습니다. 풀 설치, 비(非) Unity 계열로의 적용, 각 플래그, 프로젝트 고유의 규율 게이트에 대한 상세 내용은 리포의 README를 참조하십시오.

6. 남은 과제

• 커밋 메시지 제목에 BOM과 같은 prefix가 섞임: git log

에서 확인할 수 있습니다. devlog의 .md 파일의 H1 행을 BOM 없는 UTF-8로 읽도록 하는 수정이 다음 cycle-runner 수정 시 필요합니다.

• Unity의 배치 실행(Batch Execution)으로 관련 파일이 dirty 상태가 됨: -CommitPath로 잘못된 커밋(commit)은 방지할 수 있지만, parent는 실행 후에 dirty 상태인 파일을 수동으로 정리해야 하는 문제가 남습니다.
• 실패 시의 처리: -NoRollback을 통해 안전한 방향(리셋하지 않음)으로 설정했지만, 작업 트리(working tree)를 건드리지 않고 devlog에 구조화된 실패 보고서를 추가하는 방향이 본래의 최종 목표입니다.
• 육안 확인은 현재로서는 자동화하지 않음: 이전 장의 사례와 같이, 자동 체크를 통과하더라도 시각적인 결함은 남아 있을 수 있습니다. 마지막 육안 확인을 자동화하는 방식은 현재로서는 채택하지 않을 방침입니다.

7. 마치며

여기까지가 Anemora 제작을 위해 약 1주일 동안 지속해 온 Cycle 운용의 기록입니다. parent와 worker의 역할을 「지휘 / 구현」으로 나누고, 1 사이클을 1 파일(+ 관련 파일) + 1 커밋으로 축소했을 뿐이며, AI 측의 고기능화를 기다리지 않고 요청 방식(prompting/instruction)을 좁혔을 뿐인데 결과가 달라졌습니다. 마찬가지로 Codex CLI나 Claude Code 계열의 서브 에이전트(sub-agent)를 병렬로 구동하고 계신 분들께 참고가 되기를 바랍니다.

덧붙여, 이 Cycle 운용으로 진행 중인 Anemora 자체는 얼마 전 체험 빌드를 공개했습니다. 현재는 핵심 기능인 「시간의 창」을 체험하는 수준이지만, 관심이 있으시다면 그쪽도 확인해 보시기 바랍니다.

Discussion