설계는 Opus, 구현은 Codex. Claude Code에 개발 에이전트 조직을 추가한 의도

「AI에게 구현을 맡기면 빠르지만, 설계의 일관성이 무너진다」 「그렇다고 가장 똑똑한 모델에게 전부 시키면, 비용도 쿼터(Quota)도 금방 바닥난다」. AI 코딩을 일상적으로 사용하는 사람이라면 누구나 한 번쯤은 이 딜레마에 직면했을 것이다.

이 기사는 그 딜레마를 「1체의 만능 에이전트」가 아니라 「역할을 나눈 조직」으로 해결한 기록이다. 결론부터 말하겠다. 설계 판단은 Opus, 무거운 구현은 Codex로 나누고, 그 사이에 추론하지 않는 접수원을 한 명 끼워 넣는 3층 구성으로 만들었다. 왜 그런 경계선을 그었는지, 설계 의도를 남겨두고 싶다.

다 읽고 나면, 단일 에이전트를 강하게 만드는 것과는 다른 방향, 즉 「역할을 나누어 문맥(Context)을 끊는다」라는 선택지의 윤곽이 보일 것이다.

무엇을 만들었는가

자신의 로컬 환경(Claude Code)에 개발 전용 3층 구성을 추가했다. 도식화하면 다음과 같다.

사용자
│
▼
...

포인트는 똑똑한 모델을 1체 두어 전부 시키는 것이 아니라, 「생각하는 사람」, 「손을 움직이는 사람」, 「전달하는 사람」을 나누었다는 점에 있다. 각각이 보는 문맥도, 사용하는 모델도 다르다.

왜 「1체」가 아니라 「조직」으로 만들었는가

단일 에이전트에게 설계부터 구현까지 통째로 맡기면, 대화가 길어질수록 문맥이 비대해진다. 설계 논의, 시행착오를 거친 구현 로그, 테스트 출력 결과가 모두 하나의 문맥에 쌓이게 되어, 후반부에는 판단이 흔들리기 쉽다.

조직으로 만드는 목적은 똑똑함을 더하는 것이 아니다. 문맥을 끊는 것이다. 설계는 설계의 문맥에서, 구현은 구현의 문맥에서 진행하면 각각이 봐야 할 것만 볼 수 있다. 역할을 나눈다는 것은 책임을 나누는 것이며, 동시에 문맥을 나누는 것이기도 하다. 이 발상이 이번 구성의 토대가 되었다.

역할 분담 ①: 설계는 Opus, 구현은 Codex

가장 전달하고 싶은 것은 이 경계선이다. 두뇌와 손발을 서로 다른 모델에 할당했다.

architect(Opus)가 하는 일은 기본 설계와 그 성과물인 설계서 작성, 그리고 리뷰까지다. 설계서는 프로젝트의 docs/design/에 Markdown 형식으로 둔다. 이것을 「Codex에 대한 계약」으로 규정했다. 모호함을 남기지 않고, 후속 구현은 모두 이 설계서를 따르게 한다. 설계서의 경로를 전달하며 다음과 같이 지시한다.

codex exec --sandbox workspace-write \
-C "<worktree의 절대 경로>" \
"docs/design/<기능명>.md에 따라 상세 설계·구현·테스트를 수행하라"

왜 여기서 선을 그었는가? 이유는 두 가지다.

첫 번째는 일관성이다. 설계라는, 가장 흔들려서는 안 될 판단을 긴 구현 로그로 오염되지 않은 Opus의 문맥 안에 가두고 싶었다. 설계의 머리와 구현의 손을 물리적으로 별개의 프로세스로 나누면, 설계 의도가 구현의 편의성 때문에 희석되지 않는다.

또 다른 하나는 현실적인 제약이다. 구현 엔진으로 사용하는 Codex(Plus 범위)는 5시간의 롤링 윈도우(Rolling Window)로 쿼터가 정해져 있어, 상시 사용이나 CI 연동에는 적합하지 않다. 그래서 「설계와 가벼운 리뷰는 Opus가 스스로 수행하고, Codex로의 위임은 무거운 구현과 테스트 구현에 한정한다」라는 규칙을 세웠다. 쿼터가 다 떨어지면 급한 건은 architect가 직접 손을 움직인다. 똑똑한 모델을 사치스럽게 다 써버리는 것이 아니라, 결정적인 순간의 무거운 구현에만 Codex를 투입한다. 분업의 선은 품질과 자원 양쪽 측면에서 그어졌다.

역할 분담 ②: 사이에 「추론하지 않는 접수원」을 두다

조직의 또 다른 핵심은 사용자과 architect 사이에 concierge라는 접수원을 끼워 넣은 것이다. 그리고 concierge에게는 개발 태스크에서 설계나 태스크 분해를 시키지 않는다.

언뜻 보면 무의미한 중계처럼 보인다. 왜 추론하지 않는 직원을 굳이 두는 것일까?

여기서도 이유는 문맥의 분리에 있다. concierge는 의뢰 접수, 배분, 결과 집약 및 일본어(한국어) 보고에 전념한다. 개발의 긴 시행착오는 architect와 Codex 측에 가두고, 사용자가 보는 대화에는 「의뢰」와 「완료 보고」, 그리고 「판단이 필요한 상신」만이 흐르도록 했다. 접수원이 어설프게 추론을 시작하면 그 판단이 사용자용 문맥에 섞여 버린다. 그래서 「전달만 하는 것」으로 역할을 고정했다.

또 하나, 접수 역할을 둘 때 놓치기 쉬운 함정이 있다. concierge는 모든 요청의 통로가 된다. 여기에 무거운 추론까지 맡기면, 상대적으로 성능이 낮은 모델(Sonnet)이 조직 전체의 처리 상한선이 되어 버린다. 가교 역할이 천장이 되는 구조다. 이 「오케스트레이터(Orchestrator)의 모델이 병목(Bottleneck)이 되는 문제」는 이전에 다른 기사에서 한 번 깊이 있게 다룬 적이 있다 (Claude Code에서 Opus를 다 써버리기 — 설계는 Sonnet, 구현은 프로젝트 직접 실행). 이번 3층 구성은 그 배움을 토대로 하고 있다. 대처법은 간단하다. 접수 역할에는 추론을 시키지 않는다. 무거운 판단은 반드시 상위 계층(Opus)으로 넘기고, concierge는 접수·분류·전달에만 철저히 집중한다. 저렴한 통로로는 사용하되, 천장으로 만들지는 않겠다는 결단이다.

접수·두뇌·수족. 3층으로 나눈 이유는 각각의 문맥(Context)을 독립시키고, 층을 넘나들 때 반드시 요약(설계서·완료 보고)을 거치게 하기 위해서다. 요약을 사이에 두는 것이 문맥이 무질서하게 팽창하는 것을 막는 검문소 역할을 한다.

부차적인 설계: 안전과 격리

조직의 골격에서는 조금 벗어나지만, 구현을 외부 엔진에 맡기는 이상 피할 수 없는 설계 판단이 두 가지 있었다. 기록으로 남겨둔다.

하나는 worktree의 격리다. Codex는 반드시 git worktree로 생성한 작업 트리 안에서만 동작하며, 본체의 작업 트리는 절대로 더럽히지 않는다. 실행은 무인(Unattended)을 전제로 하므로, 샌드박스(Sandbox)는 파일 편집만 허용하고 네트워크와 시스템 커맨드는 차단하는 설정으로 되어 있다. 생성된 차분(Diff)은 본체와 격리된 장소에 쌓이며, 리뷰를 통과한 후에야 비로소 본체에 반영된다.

또 하나는 과금 사고 방지다. Codex의 실행 엔진은 ChatGPT (Plus 범위)로 고정하여, API 키를 통한 종량제 과금으로 흐르지 않도록 다층적으로 방어하고 있다. 설정 파일에서 로그인 방법을 chatgpt로 강제하고, 실행할 때마다 환경 변수의 API 키를 제거하며, 실행 전에 여러 차례 체크를 거친다. 프로젝트의 .env에 섞여 들어간 API 키가 로그인 중임에도 묵묵히 종량제 과금을 우선시해 버리는 동작을 경험한 적이 있어, 그 이후로는 「키가 존재하지 않음」을 매번 절차를 통해 확인하고 있다. $0 상한 설정은 이제 사용할 수 없으므로, 방어는 설정과 절차 측면에서 다층적으로 쌓을 수밖에 없다.

이 두 가지가 주인공은 아니다. 다만 「수족을 외주 준다」고 결정한 순간, 격리와 과금 설계가 반드시 따라온다는 사실은 기록해 둘 가치가 있다.

만들어 보며 느낀 체감

before/after로 말하자면, 이전에는 한 명의 에이전트에게 설계부터 구현까지 통째로 맡겼었다. 빠른 대신, 대화가 길어질수록 설계의 초심이 흐려져 무엇을 결정했는지 스스로도 추적하기 어려워졌다.

after인 지금은, 설계서라는 성과물이 Opus 측에 반드시 남는다. Codex는 그 계약에 따라 손을 움직이고, 결과는 격리된 장소에서 리뷰를 기다린다. 사용자의 대화에는 의뢰와 보고만이 흐른다. 똑똑함을 한 점에 몰아넣은 것이 아니라, 역할과 문맥을 분리함으로써 판단의 논리가 통하기 쉬워졌다는 체감이 든다.

물론 만능은 아니다. 층을 늘린 만큼 전달 비용은 증가하며, Plus 범위의 쿼터(Quota) 관리라는 새로운 번거로움도 떠안게 되었다. 그럼에도 「한 명을 강하게 만드는 것」 이외에 「역할을 나누어 문맥을 끊는」 설계라는 선택지를 갖게 된 것은 나에게 큰 수확이다.

AI 에이전트를 조직으로서 설계하는 사람들에게 하나의 실례로서 참고가 된다면 기쁘겠다.

Discussion