코덱스 기반 다중 에이전트 설계 회고
완벽한 통제가 AI의 발목을 잡을 때
에이전트 하네스 구축
지난 설 연휴 동안, Codex를 기반으로 개인적인 실험 하나를 진행했다. 개인용 작업과 업무용 작업을 모두 아우를 수 있는, 나만의 멀티 에이전트 하네스를 직접 설계해 보는 실험이었다.
결론부터 말하면 처음 구상한 방식은 잘 작동하지 않았다.
하지만 그 실패 덕분에, 에이전트 협업 구조를 어떻게 설계해야 하는지에 대해 꽤 중요한 교훈을 얻었다.
당시 이 실험의 목적은 두 가지였다.
초기 아이디어를 빠르게 구체화하고 MVP까지 만들어보기
반복되는 실무의 생산성을 높이기
당시 참고한 배경에는 최근 조금씩 보편화되고 있는 ‘하네스(Harness)’라는 개념도 있었다. 개인의 생산성을 높이는 수준을 넘어, 자주 쓰는 문맥과 규칙, 도구를 묶어 재사용 가능한 작업 체계로 만드는 흐름이다.
https://toss.tech/article/harness-for-team-productivity
지금은 자주 쓰는 스킬만 추려서 조금씩 고쳐 쓰는 방향으로 정착했다. 기본 스킬과 AGENTS.md를 세팅해 두고, 작업하는 폴더나 레포의 상황에 따라 필요한 규칙과 스킬만 추가하는 방식이다.
아래는 현재 기본 번들로 사용하는 레포다.
https://github.com/roydude/harness-for-k-pm
이 글에는 그보다 앞서, 처음 시도했던 구조가 왜 잘 안 됐는지와 그 과정에서 배운 점을 남겨두려 한다.
Codex용 멀티 에이전트 하네스 컨셉
문제는 위에 말한 두 목적을 하나의 Codex 환경 안에서 동시에 풀고 싶었다는 점이었다.
어떤 스레드는 개인용, 어떤 스레드는 업무용으로 써야 했고, 그 둘을 모두 감당할 수 있는 범용 하네스를 원했다.
Codex ⓒ327roy그래서 당시에는 ‘기획, 디자인, 개발, 비평’ 역할을 분리한 뒤, 이들이 맞물려 돌아가는 구조를 설계했다.
초기 기획안만 던져주면, 각 역할이 알아서 이어받아 프로덕트가 완성되는 형태를 기대했다. 지금 돌아보면 꽤 밀도 높은 바이브 코딩 환경을 상상했던 셈이다.
구조 설계
아키텍처 ⓒ327roy1월에 사내 스터디로 진행했던 GitHub Spec-kit과 따로 사용해 본 Oh-my-opencode를 참고했다. 둘 다 좋은 도구지만, 내가 더 깊게 개입하고 통제할 수 있는 구조를 직접 세팅하고 싶었다. 당시 시점에는 Ralph나 Oh-my-opencode처럼 내장된 방법론을 그대로 따르기보다, 내 방식으로 운영 가능한 체계를 만드는 데 더 관심이 있었기 때문.
다만 Codex는 Claude Code처럼 한 세션 안에서 여러 에이전트가 병렬 실행되는 ‘서브 에이전트’ 개념이 없다. 그래서 Codex의 스킬 기능을, 사실상 서브 에이전트처럼 활용하려는 발상을 했다.
Claude Code의 멀티 에이전트(서브 에이전트)는 “한 개의 세션 내에서 여러 개의 에이전트가 호출되는 구조”다. 각 서브 에이전트별로 자체 컨텍스트 윈도우를 가진 독립적인 서브‑세션이 특징이다.
https://code.claude.com/docs/ko/how-claude-code-works
아키텍처(약식) ⓒ327roy당시 상정한 나와 에이전트의 역할은 대략 이랬다.
나: 아이디어 발제와 방향성 의사결정
오케스트레이터: 스킬 사용을 조율하는 PM
플래너: 상위 기획을 상세 스펙으로 쪼개는 역할
빌더: 화면 디자인과 프론트/백 코드를 만드는 실무 역할
비평가: 타깃 사용자의 관점에서 사용성을 비판하는 역할
이 역할들이 길을 잃지 않게 하려고 project-root 아래에 /docs, /logs, /threads 같은 폴더 구조도 세팅했다. 각 스레드의 작업은 문서와 로그로 남기고, 다른 스레드가 그 산출물을 읽어 이어받도록 하는 구조였다.
회사 실무에 빗대어 보면, docs는 기획서나 스펙 문서에 가깝고, logs는 작업 현황이나 티켓 기록에 가까웠다. 겉으로 보면 꽤 그럴듯했다. 문제는, 실제로 굴려보면 전혀 다르게 드러났다는 점이다.
근데 왜 잘 안 됐나?
1. 첫 번째 착오: 인간의 협업 방식을 너무 선형적으로 본 것
초기 시스템의 가장 큰 패착은, 에이전트 간 소통을 ‘릴레이’처럼 설계했다는 점이다.
예를 들어 기획 에이전트가 스레드 1에서 산출물을 내면, 그걸 디자이너 스레드로 넘기고, 다시 개발 스레드로 전달하는 식이었다. 막상 이 사이클을 돌려보니 시스템은 금방 교착 상태에 빠졌다.
앞선 에이전트가 갖고 있던 맥락은 스레드를 옮길수록 희석됐고, 스킬 간 의존성이 높다 보니 중간에 작은 에러만 나도 전체 파이프라인이 멈췄다.
문제는 에이전트들이 서로를 직접 이어받아야 한다고 가정한 데 있었다. 실제 실무는 그렇게 돌아가지 않는다. 개발자와 디자이너가 서로의 모든 작업 맥락을 실시간으로 직접 전달하지는 않는다. 필요할 때만 소통하고, 각자 맡은 영역은 믿고 진행한다. 대신 기획서나 칸반 보드 같은 공용 기준점을 보며 비동기적으로 맥락을 맞춘다.
이 지점에서 구조를 바꿨다. 에이전트끼리 직접 강하게 의존하게 만드는 대신, 'PROJECT_HUB.md'라는 공유 허브를 단일 소스로 두는 방식이다.
이후에 세운 규칙은 아래와 같았다.
모든 에이전트는 작업 전 허브의 최신 헤더를 읽고 컨텍스트를 동기화한다 (Pull)
작업이 끝나면 오케스트레이터가 개별 로그를 훑고, 허브를 요약 업데이트한다 (Scan)
동시에 시스템이 궤도를 이탈하지 않도록 ‘범위 승인’, ‘아키텍처/계약 승인’, ‘릴리즈 승인’이라는 세 개의 게이트를 두고 사람인 내가 책임 경계를 가진다.
즉, 직접적인 스레드 간 전달을 줄이고, 중앙 허브를 통해 비동기적으로 맥락을 맞추는 구조다. 지금 돌아보면, 이때 처음으로 “에이전트 협업은 연결보다 정렬이 더 중요하다”는 감각을 얻었던 것 같다.
2. 두 번째 착오: 너무 이른 구조화가 오히려 족쇄가 됐다
첫 번째 문제를 보완한 뒤, 이 구조가 꽤 합리적이라고 생각했다.
그래서 언제든 재사용할 수 있도록 'codex-vibekit'이라는 이름의 패키지를 만들어 GitHub에 올렸고(지금은 내림), 새로운 프로젝트 폴더를 파서 테스트 제품 개발도 진행했다.
그런데 예상치 못한 곳에서 다시 막혔다. 문제는 세 가지였다.
첫째, 문서를 남겨야 하는 위치가 너무 고정돼 있었다.
/docs/specs, /logs/change, /threads처럼 초반부터 경로를 촘촘히 정해두었다.
둘째, 남기는 방식도 정해진 포맷에 과하게 묶여 있었다.
에이전트는 유연하게 사고하기보다, “어느 파일에 어떤 형식으로 적어야 하는가”를 더 신경 쓰기 시작했다.
셋째, AGENTS.md와 Skill 간 의존성이 커서 중간 변경에 약했다.
프로젝트가 진행되며 요구사항이 바뀌어도, 초반에 설계한 구조가 그 변화를 자연스럽게 흡수하지 못했다.
실제 프로젝트는 늘 변한다. 프론트엔드 이슈 때문에 기획 스펙을 다시 엎어야 할 수도 있고, 백엔드와 인프라 설계를 동시에 진행해야 할 수도 있다. 그런데 에이전트는 초반에 강제한 폴더 구조와 문서 규칙 안에서만 움직이려 했다.
Codex의 스레드가 더 유연하게 사고하고 맥락을 넓혀주길 기대했지만, 몇 번 더 미니 프로젝트를 돌려보니 오히려 복잡한 디렉터리 규칙을 지키는 데 리소스를 낭비하는 경우가 많았다.
결국 예전에 Spec-kit + Cursor 조합으로 바이브 코딩을 할 때 느꼈던 문제와 비슷했다. 토큰은 문서 구조를 유지하는 데 쓰이고, 작업은 필요 이상으로 무거워졌다. 멀티 스레드 환경을 제어하려고 세운 뼈대가, 오히려 에이전트적인 플로우를 방해한 셈이다.
완벽한 통제보다 점진적 확장이 낫다.
결국 이 실험에서 얻은 가장 큰 교훈은 '에이전트 협업 시스템은 처음부터 완성된 구조를 설계하는 방식보다, 최소 구조로 시작해 점진적으로 확장하는 편이 훨씬 강하다는 점'.
왜냐하면 에이전트 협업에서 더 자주 문제를 만드는 것은 ‘구조의 부재’보다 ‘너무 이른 구조화’였기 때문이다. 초기에 완벽해 보이는 규칙은 실제 프로젝트의 변화 앞에서 가장 먼저 깨진다.
회사에서 채용 에이전트를 기획할 때도 비슷한 딜레마를 자주 느낀다.
사용자의 행동을 미리 예측해 너무 많은 제약과 규칙을 걸어두면, 프로덕트는 금방 무거워지고 사용성은 떨어진다. 조직 협업 프로세스를 설계할 때도, AI를 다루는 시스템을 설계할 때도 마찬가지다. 에이전트와 함께 일한다고 해서, 실무 감각 없이 ‘스킬 구조 세팅’부터 시작하면 안 된다고 느꼈다.
결국 중요한 건 변화하는 환경 속에서 에이전트의 Skill, Config, AGENTS.md를 어떻게 주입하고, 어떻게 맞물리게 만들지 계속 판단하고 개선하는 이터레이션인 것 같다.
지금은 세 가지 원칙만 두고 운영한다.
처음에는 최소한의 뼈대만 둔다.
몇 사이클 돌려보며 실제 병목을 관찰한다.
구조화는 필요가 확인된 뒤에만 추가한다. 작업이 누적되고 정형화 필요가 생기면 그때 폴더를 나누고, 필요한 스킬과 규칙을 추가한다.
프로젝트 성장에 맞춰 프레임워크가 자연스럽게 확장되는 편이 더 바람직하다.
그리고 그 개선 이터레이션을 얼마나 빨리, 정확하게 돌릴 수 있는지가 결국 핵심인 것 같다.
마무리
처음에는 내 통제하에 기계처럼 맞물려 돌아가는 에이전트 조직을 상상했다. 하지만 실제 AI와의 협업은 ‘통제’보다 ‘조율’에 훨씬 가깝다.
그래서 지금은 한 줄짜리 명세만 던져주면 모든 걸 알아서 고도화해 주는 완전한 자동화보다, 초기 계획을 바탕으로 에이전트가 조금 더 자유롭게 맥락과 역할을 확장할 수 있는 이터레이션을 만드는 쪽에 더 관심이 간다.
결국 이번 실험에서 배운 건 단순하다.
좋은 하네스는 처음부터 완성된 구조로 설계되는 것이 아니라, 실제 작업 속에서 병목을 발견하고 그때 필요한 만큼만 확장되며 만들어진다는 점.
내가 PM으로서 구성원들과 소통하며 중간에서 태스크를 관리하는 것처럼, 에이전트도 그렇게 잘 관리할 노하우를 잘 찾으면 좋겠다.
ⓒ 2026. 327roy All rights reserved.