최근 AI 코딩 도구를 사용하는 개발자 사이에서 "병렬 에이전트"라는 표현이 자주 등장하고 있습니다. 한 명의 AI에게 긴 작업을 모두 맡기는 대신, 여러 AI 에이전트가 조사와 검토와 구현을 나누어 처리하는 방식입니다. Claude Code에서 서브에이전트나 여러 작업 세션을 경험한 개발자라면 이 개념이 아주 낯설지는 않으실 것입니다. 다만 Codex의 병렬 에이전트는 별도의 마법 같은 설치 패키지라기보다, 이미 제공되는 기능을 올바르게 구성하고 운영하는 문제에 가깝습니다.
이 글은 일반 사용자와 초보 개발자도 따라올 수 있도록 용어부터 천천히 설명합니다. Codex CLI 설치, AGENTS.md, .codex/config.toml, 커스텀 에이전트, 권한, Worktree를 실제 설정 예시와 함께 다룹니다. 그 뒤에는 여러 에이전트를 언제 병렬로 움직이고 언제 한 줄로 세워야 하는지 설명합니다. 마지막에는 탐색, 구현, 검증을 반복 가능한 개발 루프로 만드는 프롬프트와 운영 체크리스트까지 제공합니다.
이 글은 2026년 8월 13일의 공식 OpenAI 문서를 기준으로 작성되었습니다. Codex는 빠르게 바뀌는 제품이므로, 설정 필드와 모델 이름은 발행 이후 달라질 수 있습니다. 특히 이전 문서나 예제에 보이는 agents.max_threads는 현재 문서에서 레거시 별칭으로 안내되며, 새 구성에는 agents.max_concurrent_threads_per_session이 사용됩니다. 독자는 실제 프로젝트에 적용하기 전에 연결된 공식 문서에서 현재 필드와 사용 가능한 모델을 다시 확인하는 것이 안전합니다. 이 글에서 말하는 하네스와 루프는 제품의 단일 버튼 이름이 아니라, 여러 Codex 기능을 묶어 운영하는 설계 방식입니다.
이 글을 읽은 독자는 메인 에이전트와 서브에이전트의 책임을 구분하고, 병렬화할 작업과 직렬로 남겨 둘 작업을 판단할 수 있게 됩니다. 최신 Codex 클라이언트를 설치한 뒤 현재 작업 디렉터리와 권한, 모델과 실행 중인 에이전트 스레드를 확인하는 방법도 알게 됩니다. 저장소에 AGENTS.md, .codex/config.toml과 역할별 TOML을 배치하여 반복 가능한 하네스를 만드는 흐름도 따라갈 수 있습니다. 마지막에는 읽기 전용 조사부터 제한된 구현과 독립 리뷰까지 작은 팀 형태로 운영하는 실습을 설계할 수 있게 됩니다.
긴 글을 처음부터 끝까지 한 번에 따라 할 필요는 없습니다. 처음 사용하는 독자는 개념과 설치, 가장 작은 읽기 전용 실습까지만 진행해도 병렬 에이전트의 기본 동작을 확인할 수 있습니다. 저장소 규칙을 정리하려는 개발자는 하네스와 AGENTS.md, config와 커스텀 에이전트 장을 묶어서 읽는 편이 이해하기 쉽습니다. 이미 Claude Code에서 역할과 훅을 운영해 본 독자는 Worktree, 검증 루프와 대응표부터 읽은 뒤 필요한 설정 장으로 돌아가도 됩니다.
1. 병렬 에이전트는 무엇인가
서브에이전트는 메인 에이전트가 특정 범위의 일을 맡기기 위해 새로 시작하는 보조 에이전트입니다. 각 서브에이전트는 자신만의 작업 스레드에서 파일을 읽고, 명령을 실행하고, 결과를 정리합니다. 메인 에이전트는 하위 결과를 회수한 뒤 서로 충돌하는 내용을 비교하고 최종 답변이나 변경 계획으로 통합합니다. 공식 문서는 이 구조를 "subagent workflow"라고 부르며, 현재 Codex 릴리스에서는 기본으로 활성화되어 있다고 설명합니다. OpenAI Docs: Subagents
사람으로 비유하면 메인 에이전트는 업무를 분배하고 최종 책임을 지는 기술 리더에 가깝습니다. 서브에이전트는 코드 구조 조사, 테스트 누락 확인, 보안 검토처럼 경계가 명확한 일을 맡는 팀원에 가깝습니다. 여러 에이전트가 하나의 긴 대화를 그대로 공유하는 방식은 아닙니다. 각자는 제한된 컨텍스트에서 일한 뒤 요약을 돌려줍니다. 이 분리는 메인 대화가 수천 줄의 로그와 중간 추론으로 어지러워지는 문제를 줄여 줍니다.
병렬 실행과 동시 실행은 같은 말이 아닙니다
동시성은 여러 작업이 같은 시간 구간에 진행될 수 있도록 관리하는 성질을 가리킵니다. 병렬성은 그중에서도 실제로 여러 작업이 겹쳐 실행되는 모습을 가리키며, 일상 대화에서는 두 표현이 자주 섞여 사용됩니다. Codex를 운영할 때 더 중요한 질문은 용어 구분보다 두 작업 사이에 기다려야 할 선행 관계가 있는지입니다. 앞 작업의 결과가 나와야 뒤 작업을 시작할 수 있다면 화면에서 동시에 시작해도 유용한 병렬 작업이 되지 못합니다.
예를 들어 로그인 오류의 원인을 찾는 동안 한 에이전트는 서버 코드를, 다른 에이전트는 브라우저 재현 절차를 읽을 수 있습니다. 두 조사는 서로의 결론을 기다리지 않아도 되므로 같은 시간에 진행해도 결과가 흔들리지 않습니다. 반면 원인 분석이 끝나기 전에 구현 에이전트 세 명이 각각 수정하면 서로 다른 가정을 코드에 반영할 수 있습니다. 이 경우에는 조사만 병렬로 진행하고 원인과 수정 범위가 합의된 뒤 구현을 한 명에게 맡기는 편이 빠릅니다.
메인 에이전트는 단순한 전달자가 아닙니다
메인 에이전트는 사용자의 목표를 보존하고, 작업을 나누며, 결과의 충돌을 해소하고, 최종 완료를 판단합니다. 서브에이전트가 보고한 내용을 그대로 이어 붙이기만 하면 같은 발견이 반복되거나 서로 반대되는 결론이 함께 남을 수 있습니다. 따라서 메인 에이전트는 확인된 사실과 추론을 구분하고, 더 강한 근거가 있는 결론을 선택하며, 확인하지 못한 부분을 남겨야 합니다. 좋은 오케스트레이션은 많은 작업을 보내는 기술이 아니라 여러 결과를 하나의 의사결정으로 줄이는 기술에 가깝습니다.
서브에이전트의 산출물도 최종 사용자에게 보내는 완성 보고서와는 다릅니다. 탐색가는 파일과 심볼, 실행 경로를 돌려주고 테스트 역할은 재현 조건과 명령 결과를 돌려주는 식으로 중간 증거에 집중합니다. 메인 에이전트는 이 증거가 공통 목표에 어떤 의미가 있는지 해석하고 다음 단계가 조사인지 구현인지 판단합니다. 역할별 반환 형식을 미리 정하면 메인 대화가 원문 로그를 다시 읽는 시간을 줄이고 비교 가능한 결과를 얻을 수 있습니다.
컨텍스트 분리는 작업 품질을 위한 장치입니다
하나의 긴 대화에는 요구사항, 파일 내용, 명령 출력, 오류 로그와 중간 가설이 계속 쌓입니다. 중요한 결정이 오래된 로그 사이에 묻히면 에이전트가 이미 폐기한 가정을 다시 사용하거나 최신 범위를 놓칠 수 있습니다. 공식 문서는 이런 문제를 설명하면서 서브에이전트가 탐색과 로그 분석 같은 소음을 메인 스레드 밖에서 처리하도록 권합니다. 메인 스레드에는 요구사항과 결정, 압축된 결과만 남기므로 긴 작업에서 판단의 중심을 유지하기 쉬워집니다.
다만 컨텍스트를 나누면 모든 에이전트가 같은 배경을 자동으로 아는 것은 아닙니다. 서브에이전트에게는 자신이 맡은 목표, 읽을 범위, 금지 사항과 반환 형식을 별도로 전달해야 합니다. 부모 대화의 미묘한 합의가 자동으로 전달될 것이라고 기대하면 결과가 빠르게 엇갈릴 수 있습니다. 반복해서 필요한 배경은 긴 프롬프트에 매번 붙이기보다 AGENTS.md와 커스텀 역할 파일에 옮기는 편이 안정적입니다.
위 그림에서 병렬화되는 구간은 세 서브에이전트의 조사 과정입니다. 최종 범위 결정과 결과 통합은 메인 에이전트가 한 번에 담당합니다. 이 구조를 지키면 같은 결정을 여러 에이전트가 제각각 내리는 상황이 줄어듭니다. 반대로 메인 에이전트까지 구현에 뛰어들어 같은 파일을 수정하면 조정 비용이 빠르게 커집니다.
2. 병렬 에이전트가 항상 빠른 것은 아닙니다
병렬 실행은 독립된 작업이 충분히 클 때 시간을 줄여 줍니다. 예를 들어 프런트엔드, 백엔드, 테스트 디렉터리를 각각 읽는 일은 서로 기다릴 이유가 거의 없습니다. 반면 하나의 함수에서 발생한 작은 오류를 에이전트 세 명이 동시에 고치면 같은 파일을 읽고 비슷한 결론을 내느라 토큰만 더 사용하게 됩니다. 공식 문서도 처음에는 탐색, 테스트, 분류, 요약 같은 읽기 중심 작업부터 병렬화하고, 쓰기 중심 작업에는 더 조심하라고 안내합니다. OpenAI Docs: Why subagent workflows help
병렬화 여부를 결정할 때는 업무량보다 공유 상태를 먼저 살펴보는 편이 안전합니다. 두 작업이 같은 파일, 같은 데이터베이스, 같은 개발 서버 포트, 같은 마이그레이션 순서를 공유한다면 실제로는 독립 작업이 아닙니다. 이런 작업은 선행 관계를 정하고 직렬로 실행하거나, 뒤에서 설명할 Worktree와 별도 데이터 환경으로 격리해야 합니다. "에이전트 수가 많을수록 성능이 좋다"는 생각은 서버 스레드 수를 무작정 늘리는 것과 비슷한 오해입니다.
네 가지 질문으로 실행 방식을 고릅니다
- 첫 번째 질문은 각 작업이 다른 작업의 결과를 기다리지 않고 시작할 수 있는가입니다. 프런트엔드 구조 조사와 데이터베이스 마이그레이션 조사는 독립적으로 읽을 수 있지만, 마이그레이션 구현은 현재 스키마 조사가 끝나야 범위를 정할 수 있습니다. 선행 관계가 있다면 앞 단계만 병렬로 나누고 결정 이후의 단계는 하나의 순서로 다시 모아야 합니다. 작업 목록을 적은 뒤 화살표로 의존 관계를 그려 보는 것만으로도 불필요한 동시 실행을 상당히 줄일 수 있습니다.
- 두 번째 질문은 두 작업이 같은 상태를 바꾸는가입니다. 같은 파일뿐 아니라 잠금 파일, 데이터베이스 스키마, 테스트 스냅샷, 로컬 서버 포트와 외부 샌드박스 계정도 공유 상태에 포함됩니다. 파일 경로가 다르더라도 한 에이전트가 의존성 버전을 올리고 다른 에이전트가 기존 잠금 파일을 기준으로 테스트하면 결과가 서로 맞지 않을 수 있습니다. 공유 상태가 있다면 소유자를 하나로 정하거나 상태 자체를 복제할 수 있는지 먼저 확인해야 합니다.
- 세 번째 질문은 각 결과를 독립적으로 검증할 수 있는가입니다. 문서 링크 검사와 단위 테스트처럼 결과가 명확한 작업은 여러 에이전트가 나누어도 메인 에이전트가 합치기 쉽습니다. 반대로 “전체 구조를 더 우아하게 바꾼다”처럼 기준이 주관적이면 여러 구현이 서로 다른 방향으로 흘러갈 가능성이 큽니다. 이런 작업은 조사와 대안 비교만 병렬로 진행하고 설계 선택과 실제 변경은 하나의 책임 아래 두는 편이 낫습니다.
- 네 번째 질문은 결과를 합치는 비용이 절약되는 시간보다 작은가입니다. 10분짜리 조사 세 개를 병렬로 실행해 10분 안에 끝내더라도 결과를 정리하는 데 30분이 들면 전체 시간은 줄지 않습니다. 각 에이전트가 같은 형식으로 근거를 반환하고 파일 범위를 겹치지 않게 나누면 통합 비용을 미리 낮출 수 있습니다. 반대로 범위와 출력 형식을 정하는 시간이 작업 자체보다 길다면 단일 에이전트가 처리하는 편이 단순합니다.
동시성 상한은 목표가 아니라 안전판입니다
동시 실행 상한을 네 개로 설정했다고 해서 매번 네 에이전트를 모두 사용해야 하는 것은 아닙니다. 상한은 한 세션이 너무 많은 작업을 만들어 비용과 상태 추적을 어렵게 하지 않도록 막는 최대치입니다. 실제 위임 수는 독립 작업의 개수, 사람이 진행 상태를 이해할 수 있는 범위와 저장소의 런타임 자원을 보고 결정합니다. 처음에는 두세 개의 읽기 전용 역할로 시작하고 중복 조사 비율과 대기 시간을 확인한 뒤 늘리는 편이 안전합니다.
병렬 실행은 같은 일을 싸게 만드는 기능도 아닙니다. 공식 문서가 안내하듯 각 서브에이전트는 별도의 모델 호출과 도구 작업을 수행하므로 단일 실행보다 더 많은 토큰을 사용합니다. 시간 단축이 중요한 대형 조사에는 비용을 감수할 이유가 있지만, 짧은 질문이나 하나의 작은 수정에는 추가 비용이 더 클 수 있습니다. 운영팀은 실행 시간뿐 아니라 사용량, 중복 발견 수, 실제로 채택된 결과와 통합 시간을 함께 기록해야 판단이 정확해집니다.
| 작업 | 권장실행방식 | 판단 근거 |
| 코드베이스 구조 조사 | 병렬 | 디렉터리나 관심사를 겹치지 않게 나누기 쉽습니다. 각 결과는 읽기 전용 보고서로 통합할 수 있습니다. |
| 보안·테스트·유지보수성 리뷰 | 병렬 | 같은 변경을 서로 다른 기준으로 검토하므로 독립적인 관점이 도움이 됩니다. 코드를 수정하지 않으면 충돌도 적습니다. |
| 하나의 버그 수정 | 대체로 직렬 | 원인 분석, 재현 테스트, 구현이 앞 단계 결과에 의존합니다. 조사만 병렬화하고 실제 수정은 한 에이전트가 맡는 편이 낫습니다. |
| 서로 다른 두 기능 구현 | 조건부 병렬 | 수정 파일과 런타임 자원이 겹치지 않아야 합니다. 겹칠 가능성이 있으면 기능별 Worktree가 필요합니다. |
| 최종 통합과 릴리스 결정 | 직렬 | 여러 결과의 충돌을 한곳에서 해소해야 합니다. 책임 주체도 하나여야 합니다. |
3. 설치 | 별도 멀티에이전트 플러그인은 필요하지 않습니다
현재 Codex 릴리스에서는 서브에이전트 도구가 기본으로 활성화됩니다. 따라서 사용자는 "멀티에이전트 확장 프로그램"을 따로 찾기보다 최신 Codex 클라이언트를 설치하고 로그인하면 됩니다. Codex는 ChatGPT 데스크톱 앱, CLI, IDE 확장에서 서브에이전트 활동을 표시합니다. 표면마다 화면 구성은 다르지만, 독립 작업을 서브에이전트에게 위임하고 결과를 메인 작업으로 모으는 원리는 같습니다. OpenAI Docs: Availability
터미널 작업이 익숙한 개발자는 Codex CLI로 시작하는 편이 가장 이해하기 쉽습니다. macOS와 Linux에서는 공식 설치 스크립트가 제공되며, 설치 뒤 프로젝트 디렉터리에서 codex를 실행합니다. 첫 실행에서는 ChatGPT 계정 로그인 또는 화면에 제공되는 다른 인증 방식을 선택합니다. 공식 설치 페이지는 작업 전후에 Git 체크포인트를 만들어 되돌릴 수 있는 상태를 확보하라고도 권합니다. OpenAI Docs: Codex CLI
# macOS 또는 Linux용 공식 설치 명령
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 프로젝트 디렉터리로 이동한 뒤 실행
cd /path/to/project
codex
회사 보안 정책이 원격 스크립트를 셸로 직접 전달하는 방식을 금지할 수도 있습니다. 그 경우에는 명령을 우회해서 실행하지 말고, 공식 설치 페이지의 npm 또는 Homebrew 탭과 조직의 패키지 설치 절차를 따르는 편이 맞습니다. 설치가 끝나면 codex를 실행하고 /status로 현재 모델과 권한, 작업 디렉터리를 확인할 수 있습니다. /permissions는 실행 권한을 선택하고, /model은 모델과 추론 강도를 고르는 데 사용됩니다.
데스크톱 앱을 선호하는 사용자는 ChatGPT 데스크톱 앱을 설치한 뒤 폴더를 열고 Codex를 선택하면 됩니다. Worktree를 버튼으로 만들고 여러 채팅을 시각적으로 관리하려면 데스크톱 앱이 특히 편리합니다. CLI는 /agent 명령으로 현재 실행 중이거나 완료된 에이전트 스레드를 살펴볼 수 있습니다. IDE 확장은 에디터 안에서 같은 흐름을 제공하므로, 파일을 직접 보면서 결과를 확인하려는 개발자에게 어울립니다.
설치 직후에는 현재 위치부터 확인합니다
Codex는 열린 프로젝트와 현재 작업 디렉터리를 기준으로 파일과 지침을 찾습니다. 다른 폴더에서 실행하면 의도한 AGENTS.md나 .codex/config.toml을 읽지 못하고 엉뚱한 저장소를 조사할 수 있습니다. CLI를 시작하기 전에 pwd와 저장소 상태를 확인하고, 시작한 뒤 /status에서 표시되는 작업 위치와 모델을 다시 비교하는 편이 좋습니다. 처음 실습은 중요한 변경이 없는 별도 브랜치나 되돌릴 수 있는 작은 저장소에서 진행하면 결과를 비교하기 쉽습니다.
# 셸에서 현재 위치와 Git 상태를 먼저 확인하는 예
pwd
git status --short --branch
# 해당 위치에서 Codex 시작
codex
pwd 결과가 예상한 프로젝트 루트와 다르면 cd로 이동한 뒤 다시 시작해야 합니다. Git 저장소가 아닌 학습 폴더에서도 Codex는 사용할 수 있지만 Worktree와 브랜치 기반 복구 절차는 사용할 수 없습니다. 기존 변경이 있는 저장소라면 git status 결과를 기록해 두어 Codex의 변경과 사용자의 변경을 나중에 구분할 수 있어야 합니다. 공식 CLI 문서가 작업 전후 Git 체크포인트를 권하는 이유도 에이전트의 결과를 되돌릴 수 있는 상태로 남기기 위해서입니다.
모델과 권한을 먼저 확인합니다
/model에서는 현재 선택된 모델과 추론 강도를 확인하거나 바꿀 수 있습니다. 공식 모델 페이지는 복잡하고 열린 작업에는 Sol, 일상적인 작업에는 Terra, 명확하고 반복적인 작업에는 Luna를 안내합니다. 추론 강도가 높을수록 어려운 판단에 도움이 될 수 있지만 응답 시간과 토큰 사용량도 늘어나므로 기본값부터 시작하는 편이 좋습니다. 병렬 에이전트는 각자 모델 작업을 수행하므로 부모와 모든 자식에 높은 강도를 고정하는 선택은 비용에 더 크게 반영됩니다. OpenAI Docs: Models
/permissions에서는 파일과 명령에 적용되는 현재 권한 범위를 확인합니다. 읽기 전용 조사를 시작하려는데 전체 시스템 쓰기 권한이 선택되어 있다면 먼저 범위를 줄이는 편이 맞습니다. 반대로 구현 실습에 필요한 저장소 쓰기가 막혀 있다면 에이전트가 실패한 이유를 코드 문제로 오해하지 않도록 권한 상태를 기록해야 합니다. 부모 작업의 실시간 권한 선택은 새 서브에이전트에도 영향을 줄 수 있으므로 위임하기 전에 확인하는 순서가 중요합니다.
4. 가장 작은 실습부터 시작합니다
설정 파일을 만들기 전에 한 번은 아무 구성 없이 병렬 위임을 실행해 보는 것이 좋습니다. 그래야 어떤 부분이 제품 기본 기능이고 어떤 부분이 사용자가 추가한 하네스인지 구분할 수 있습니다. 첫 실습에서는 코드 수정을 금지하고 탐색만 맡기면 실패했을 때 복구할 것도 거의 없습니다. 아래 프롬프트는 프로젝트 구조, 테스트, 보안을 서로 다른 에이전트가 읽도록 명시합니다.
현재 저장소를 읽기 전용으로 조사해 주세요.
병렬 작업:
- 탐색 에이전트 1명은 프로젝트 구조와 주요 실행 경로를 조사해 주세요.
- 테스트 에이전트 1명은 테스트 명령, 테스트 구조, 눈에 띄는 누락을 조사해 주세요.
- 리뷰 에이전트 1명은 인증, 권한, 비밀정보 처리와 관련된 위험을 조사해 주세요.
공통 제약:
- 어떤 파일도 수정하지 마세요.
- 추측과 확인한 사실을 구분하세요.
- 모든 주장은 파일 경로, 심볼 또는 실행한 명령을 근거로 제시하세요.
동기화:
- 세 에이전트가 모두 끝날 때까지 기다리세요.
- 결과가 서로 충돌하면 어느 부분이 다른지 적으세요.
- 마지막에는 발견 사항, 근거, 위험, 다음 액션 순서로 하나의 보고서를 작성하세요.
좋은 위임 프롬프트는 작업을 어떻게 나눌지, 모든 결과를 기다릴지, 어떤 형식으로 요약할지를 함께 적습니다. "알아서 병렬로 해 주세요"라고만 요청하면 메인 에이전트가 경계를 추정해야 하므로 결과가 매번 달라질 수 있습니다. 공식 문서도 분할 기준, 대기 조건, 반환 형식을 좋은 서브에이전트 프롬프트의 핵심으로 설명합니다. OpenAI Docs: Triggering subagent workflows 실습이 끝난 뒤에는 각 에이전트가 실제로 독립된 근거를 가져왔는지, 같은 일을 세 번 반복하지는 않았는지 확인해야 합니다.
실습 전에 성공 조건을 적습니다
이 실습의 성공은 세 에이전트가 모두 실행되었다는 화면으로 판단하지 않습니다. 프로젝트 구조 보고서에는 시작점과 주요 디렉터리가, 테스트 보고서에는 실제 명령과 테스트 위치가, 보안 보고서에는 확인한 인증 경로가 있어야 합니다. 각 보고서는 파일 경로나 심볼처럼 다시 찾을 수 있는 근거를 포함하고 확인하지 못한 부분을 별도로 표시해야 합니다. 메인 결과에는 세 보고서의 중복을 제거한 요약과 다음에 확인할 작업이 우선순위 순서로 남아야 합니다.
읽기 전용이라는 제한도 성공 조건의 일부입니다. 실습 전후 git status --short 결과가 같아야 하며 새 파일이나 수정 파일이 생겼다면 원인을 확인해야 합니다. 에이전트가 좋은 의도로 문서를 정리했더라도 이번 실습 범위를 벗어난 변경이므로 그대로 받아들이지 않습니다. 병렬 운영은 산출물의 품질뿐 아니라 정해진 경계를 지켰는지도 함께 평가해야 반복 가능한 방식이 됩니다.
진행 중에는 개입보다 상태를 확인합니다
서브에이전트마다 조사 범위가 다르면 완료 시간도 달라집니다. 한 역할이 먼저 끝났다고 메인 에이전트가 곧바로 결론을 만들면 늦게 오는 반대 근거를 놓칠 수 있습니다. 프롬프트에 모든 역할을 기다리라고 적은 이유는 단순한 예절이 아니라 결과가 모이는 동기화 지점을 만들기 위해서입니다. 진행 상태를 볼 때는 누가 바쁜지보다 각 역할이 자신의 범위 안에서 새로운 근거를 찾고 있는지를 확인합니다.
같은 디렉터리를 세 역할이 모두 읽고 있다면 작업 분할이 충분히 구체적이지 않았다는 신호입니다. 그 경우 실행을 무조건 중단할 필요는 없지만 최종 보고서에서 중복된 조사 시간을 기록해야 합니다. 다음 실행에서는 디렉터리, 관심사 또는 질문을 더 좁게 나누어 같은 정보가 반복되는 정도를 비교할 수 있습니다. 좋은 하네스는 처음부터 완벽한 구성이 아니라 관찰한 낭비를 다음 규칙으로 옮기는 과정에서 만들어집니다.
결과는 한 장의 통합 보고서로 받습니다
통합 보고서의 첫 부분에는 확인된 사실만 배치합니다. 프로젝트 시작 명령, 테스트 명령, 핵심 실행 경로와 인증 진입점처럼 파일이나 명령으로 다시 확인할 수 있는 정보가 여기에 해당합니다. 그다음에는 위험과 불확실성을 나누어 적고, 추론에 불과한 내용은 어떤 추가 조사가 필요한지 함께 표시합니다. 마지막에는 즉시 수정이 아니라 다음 행동의 순서를 제시하여 사람이 범위를 승인할 수 있게 합니다.
[통합 보고서 형식]
1. 확인된 사실
- 발견 내용
- 파일과 심볼 또는 실행 명령
- 다른 역할의 교차 확인 여부
2. 위험과 불확실성
- 예상 영향
- 아직 확인하지 못한 조건
- 추가로 필요한 증거
3. 다음 행동
- 우선순위
- 예상 수정 범위
- 실행 전에 필요한 승인 또는 결정
이 형식은 보고서를 길게 만드는 장치가 아닙니다. 세 역할이 같은 주장을 했는지, 서로 다른 증거로 같은 결론에 도달했는지, 아니면 실제로 충돌하는지를 메인 에이전트가 구분하게 합니다. 중복 주장은 한 항목으로 합치되 여러 근거가 있다는 사실을 남기고, 충돌하는 주장은 어느 쪽을 선택했는지 설명해야 합니다. 모든 조사가 끝났는데도 수정 범위가 명확하지 않다면 구현으로 넘어가지 않고 다음 읽기 작업을 제안하는 것이 올바른 종료입니다.
5. 하네스 엔지니어링이 필요한 이유
하네스는 원래 장비나 동물을 안정적으로 연결하고 통제하는 장치를 뜻합니다. AI 개발에서 하네스 엔지니어링은 에이전트가 어떤 규칙으로, 어떤 도구를 사용해, 어디까지 수정하고, 무엇으로 완료를 증명할지 정하는 작업입니다. 좋은 모델을 선택하는 것만으로는 매번 같은 품질을 얻기 어렵지만, 작업 계약과 검증 명령이 갖춰지면 결과의 편차를 줄일 수 있습니다. 이 글에서는 AGENTS.md, Codex 설정, 커스텀 에이전트, 권한, Worktree, 테스트 명령을 하나의 하네스로 봅니다.
이 구조에서 AGENTS.md는 "어떻게 일해야 하는가"를 설명하는 작업 계약입니다. .codex/config.toml은 동시 실행 수, 기본 모델, 권한처럼 런타임이 읽을 기계적 설정을 담당합니다. .codex/agents/*.toml은 탐색가나 리뷰어처럼 경계가 분명한 역할을 정의합니다. 테스트와 리뷰는 에이전트의 말이 아니라 실제 결과를 받아들일 수 있는지 판정하는 출구입니다.
하네스의 여섯 계층은 서로 다른 실패를 막습니다
지침계층
지침 계층은 프로젝트가 어떤 제품인지와 어떤 행동을 금지하는지 설명합니다. 이 계층이 비어 있으면 에이전트는 저장소의 파일을 보고 규칙을 추정하며, 추정이 틀려도 스스로 알아차리기 어렵습니다. 설치와 테스트 명령, 수정 금지 영역과 완료 기준을 짧게 적어 두면 모든 역할이 같은 출발점에서 작업할 수 있습니다. 지침은 정답을 대신하지 않지만 프로젝트마다 다른 기본 가정을 명시하여 불필요한 시행착오를 줄입니다.
설정계층
설정 계층은 동시성, 기본 모델, 승인 정책과 sandbox처럼 런타임이 읽을 값을 담당합니다. 사람에게 읽히는 문장과 기계가 읽는 설정을 한 파일에 섞으면 어느 값이 실제로 적용되는지 확인하기 어려워집니다. AGENTS.md에는 선택의 이유와 행동 규칙을 적고 .codex/config.toml에는 정확한 키와 값만 두는 분리가 도움이 됩니다. 설정이 적용되지 않을 때는 프롬프트를 고치기 전에 파일 위치, 프로젝트 신뢰 상태와 우선순위를 확인할 수 있습니다.
역할계층
역할 계층은 탐색가, 구현자와 리뷰어가 무엇을 맡고 무엇을 하지 않는지 정합니다. 모든 역할에 “코딩을 잘하는 전문가”라고 쓰면 이름만 다르고 행동은 같은 에이전트가 만들어집니다. 탐색가는 근거 수집, 구현자는 승인된 변경, 리뷰어는 독립 검증처럼 산출물이 서로 달라야 역할을 나눈 효과가 생깁니다. 도구와 sandbox도 역할에 맞게 줄이면 지침을 어겼을 때 실제 피해 범위를 제한할 수 있습니다.
도구계층
도구 계층에는 셸, 브라우저, MCP, Skills와 프로젝트 스크립트가 들어갑니다. 도구가 많다고 항상 좋은 것은 아니며 문서 조사 역할에 배포 도구를 주거나 리뷰어에게 쓰기 도구를 주면 범위가 흐려집니다. 각 역할이 목표를 달성하는 데 필요한 최소 도구만 연결하고, 반복되는 확인 절차는 스크립트나 Skill로 고정하는 편이 좋습니다. 도구 실패가 발생하면 모델의 판단과 환경의 문제를 구분할 수 있도록 명령, 종료 코드와 오류 출력을 결과에 남겨야 합니다.
격리계층
격리 계층은 역할이 실수하거나 서로 다른 가정을 선택했을 때 변경이 섞이지 않도록 막습니다. 읽기 전용 sandbox는 조사 작업의 쓰기를 차단하고 Worktree는 기능별 파일 체크아웃을 분리합니다. 여기에 별도 포트, 테스트 데이터베이스와 외부 계정을 더해야 실제 실행 환경까지 독립적으로 만들 수 있습니다. 격리는 에이전트를 더 자유롭게 만드는 수단이 아니라 실패를 작은 범위 안에 가두는 안전장치입니다.
검증계층
검증 계층은 결과가 받아들일 수 있는 상태인지 판정합니다. 테스트, lint, build, 브라우저 동작, 성능 지표와 독립 리뷰가 여기에 들어가며 작업에 필요한 항목만 선택합니다. 검증 명령이 너무 느리면 변경 중에는 관련 테스트를 실행하고 통합 전에는 전체 검증을 실행하는 두 단계로 나눌 수 있습니다. 중요한 점은 에이전트의 “완료했습니다”와 검증기의 성공을 서로 다른 신호로 취급하는 것입니다.
6. AGENTS.md: 저장소의 작업 계약 만들기
Codex는 작업을 시작하기 전에 적용 가능한 AGENTS.md 파일을 읽습니다. 전역 범위에서는 기본적으로 ~/.codex/AGENTS.md를 읽고, 프로젝트에서는 Git 루트부터 현재 작업 디렉터리까지 내려오며 지침을 합칩니다. 더 가까운 디렉터리의 파일이 뒤에 추가되므로 세부 모듈의 규칙이 상위 규칙보다 우선할 수 있습니다. 같은 위치에 AGENTS.override.md가 있으면 일반 AGENTS.md보다 먼저 선택됩니다. OpenAI Docs: AGENTS.md discovery
초보 개발자는 처음부터 긴 철학 문서를 만들기보다 실행 가능한 규칙만 적으면 충분합니다. 설치 명령, 테스트 명령, 수정 금지 영역, 완료 기준, 병렬 위임 원칙이 있으면 충분합니다. "좋은 코드를 작성하세요" 같은 추상적인 문장은 에이전트가 검증할 수 없습니다. 반면 "JavaScript를 수정하면 npm test를 실행하세요"는 행동과 증거가 모두 분명합니다.
# AGENTS.md
## 프로젝트 개요
- 이 저장소는 Node.js 기반 웹 애플리케이션입니다.
- 패키지 관리자는 npm을 사용합니다.
## 필수 명령
- 의존성 설치: `npm ci`
- 개발 서버: `npm run dev`
- 정적 검사: `npm run lint`
- 테스트: `npm test`
- 프로덕션 빌드: `npm run build`
## 변경 원칙
- 요청과 직접 관련된 파일만 수정합니다.
- 기존 사용자 변경을 되돌리지 않습니다.
- 새 프로덕션 의존성을 추가하기 전에 승인을 요청합니다.
- 버그 수정 전에는 실패하는 테스트 또는 재현 절차를 확보합니다.
## 병렬 에이전트 원칙
- 서브에이전트는 독립적인 읽기 작업에 우선 사용합니다.
- 쓰기 작업을 위임할 때는 에이전트마다 소유 파일을 명시합니다.
- 같은 파일을 두 에이전트가 동시에 수정하지 않습니다.
- 메인 에이전트는 모든 결과를 통합하고 최종 검증을 직접 확인합니다.
## 완료 기준
- 관련 테스트가 통과해야 합니다.
- lint와 build가 성공해야 합니다.
- 최종 보고서에는 실행한 명령과 결과를 포함합니다.
루트 AGENTS.md에는 저장소 전체가 공유하는 규칙만 두는 편이 관리하기 쉽습니다. 결제 모듈처럼 별도 보안 규칙이나 테스트 명령이 필요한 경로에는 가까운 디렉터리에 추가 지침을 둘 수 있습니다. 다만 파일이 너무 많으면 어느 규칙이 적용되는지 사람이 추적하기 어려워지므로, 실제 차이가 있는 경로에만 계층을 추가해야 합니다. 공식 문서에서 안내하는 결합 크기의 기본 한도는 32 KiB이므로, 긴 배경 설명보다 짧고 실행 가능한 규칙을 우선해야 합니다.
지침은 실제 실행 경로에서 읽혀야 합니다
전역 지침은 기본적으로 Codex 홈의 AGENTS.override.md가 있으면 그것을 읽고, 없으면 AGENTS.md를 읽습니다. 프로젝트에서는 루트에서 현재 작업 디렉터리까지 내려오며 각 디렉터리에서 적용할 파일 하나를 선택합니다. 가까운 디렉터리의 지침이 결합된 내용의 뒤에 오므로 특정 모듈의 예외가 저장소 공통 규칙보다 우선할 수 있습니다. 새 세션에서 한 번 구성되는 지침 체인을 바꾸었다면 현재 실행이 자동으로 새 내용을 읽는다고 가정하지 말고 세션을 다시 시작하는 편이 확실합니다.
설정한 규칙이 무시되는 것처럼 보일 때는 먼저 Codex를 시작한 디렉터리를 확인합니다. Git 루트라고 생각한 폴더가 실제 프로젝트 루트가 아니거나 하위 폴더에서 시작해 상위 지침을 찾지 못하는 상황이 생길 수 있습니다. 같은 위치의 AGENTS.override.md가 일반 파일을 대신 선택하고 있지는 않은지도 확인해야 합니다. 규칙 문장을 더 강하게 반복하기 전에 발견 경로와 우선순위를 확인하면 원인을 훨씬 빨리 찾을 수 있습니다.
좋은 규칙은 행동과 증거를 한 문장에 담습니다
“안전하게 작업합니다”라는 규칙은 사람에게도 해석 범위가 넓고 에이전트에게도 검증 기준을 주지 못합니다. “데이터베이스 마이그레이션을 만들기 전에 스키마 테스트를 실행하고 결과를 보고합니다”처럼 행동과 증거를 연결해야 합니다. “기존 변경을 보존합니다”라는 원칙에는 시작 전 git status 확인과 관련 없는 diff를 되돌리지 않는 행동을 붙일 수 있습니다. 규칙을 읽고 실제로 지켰는지 명령 결과나 diff에서 확인할 수 있다면 하네스의 일부로 기능합니다.
반대로 오류를 한 번 겪을 때마다 세부 규칙을 계속 추가하면 지침이 운영 일지처럼 비대해집니다. 드문 사건의 긴 배경은 별도 문서에 두고 AGENTS.md에는 반복해서 적용되는 행동만 남기는 편이 좋습니다. 서로 모순되는 규칙이 생기면 가까운 지침이 이기더라도 사람이 의도를 추적하기 어려워지므로 상위 규칙을 함께 정리해야 합니다. 좋은 지침 파일은 많은 내용을 담는 문서가 아니라 에이전트가 작업 전에 반드시 알아야 할 차이를 압축한 계약입니다.
7. .codex/config.toml: 병렬 실행의 기계적 설정
개인 기본 설정은 ~/.codex/config.toml에 두고, 저장소 전용 설정은 프로젝트의 .codex/config.toml에 둘 수 있습니다. CLI와 IDE 확장은 같은 설정 계층을 공유하며, 프로젝트 설정은 사용자가 신뢰한 저장소에서만 읽힙니다. 우선순위는 CLI 플래그, 프로젝트 설정, 선택한 프로필, 사용자 설정, 시스템 설정, 내장 기본값 순서입니다. 이 구조 덕분에 개인의 안전한 기본값을 유지하면서 특정 프로젝트에서만 동시성이나 모델을 조정할 수 있습니다. OpenAI Docs: Config basics
처음 구성에서는 병렬 도구를 켜고 동시 서브에이전트를 네 개로 제한하는 정도면 충분합니다. 네 개는 성능의 정답이 아니라, 메인 에이전트 한 개와 보조 역할 몇 개를 사람이 추적하기 쉬운 출발점입니다. 현재 공식 필드명은 agents.max_concurrent_threads_per_session이며, 기본값을 비워 두면 Codex가 결정합니다. 예전 예제의 agents.max_threads도 레거시 별칭으로 동작할 수 있지만, 새 구성은 현재 필드명으로 작성하는 것이 혼란을 줄입니다. OpenAI Docs: Config reference
# .codex/config.toml
# 프로젝트가 신뢰된 상태에서만 프로젝트 설정 계층이 적용됩니다.
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[agents]
enabled = true
max_concurrent_threads_per_session = 4
interrupt_message = true
approval_policy = "on-request"는 필요한 작업에서 Codex가 승인을 요청할 수 있게 합니다. sandbox_mode = "workspace-write"는 작업 공간 안의 파일 수정은 허용하되 시스템 전체에 대한 자유로운 쓰기를 막는 일반적인 출발점입니다. 권한을 넓게 주면 중간 승인이 줄어드는 대신 잘못된 명령의 영향 범위가 커집니다. 초보자는 불편하더라도 처음에는 좁은 권한으로 시작하고, 반복적으로 필요한 안전한 명령만 점진적으로 허용하는 접근이 안전합니다.
설정 우선순위를 알아야 값이 적용됩니다
CLI 플래그와 --config로 준 일회성 값은 프로젝트 파일보다 우선합니다. 프로젝트 .codex/config.toml은 현재 디렉터리에 가까울수록 우선하고, 그다음 선택한 프로필과 사용자 설정, 시스템 설정, 내장 기본값이 적용됩니다. 따라서 사용자 파일에서 동시성을 네 개로 정했는데 실행 명령에서 다른 값을 넘겼다면 프로젝트 파일을 고쳐도 결과가 바뀌지 않습니다. 설정 문제를 진단할 때는 값 자체와 함께 어느 계층에서 왔는지를 기록해야 같은 상황을 재현할 수 있습니다.
프로젝트를 신뢰하지 않은 상태에서는 프로젝트 범위의 .codex/ 설정, 훅과 규칙이 건너뛰어질 수 있습니다. 파일이 올바른 위치에 있어도 적용되지 않는다면 문법 오류만 찾지 말고 프로젝트 신뢰 상태를 확인해야 합니다. 조직에서 관리하는 환경은 위험한 승인 정책이나 넓은 sandbox를 별도 요구사항으로 제한할 수도 있습니다. 개인 환경에서 동작한 예제가 회사 환경에서 거부될 때는 우회하기보다 관리 정책과 충돌하는 값을 확인하는 편이 맞습니다.
네 개라는 값은 관찰을 위한 시작점입니다
max_concurrent_threads_per_session = 4는 메인 스레드를 제외하고 동시에 열 수 있는 자식 스레드의 상한입니다. 작은 저장소에서 두 개의 독립 조사만 있다면 실제로는 두 역할만 실행하는 것이 맞고 나머지 두 자리를 채울 이유는 없습니다. 큰 저장소에서도 여섯 역할이 같은 파일 목록을 반복해서 읽는다면 상한을 늘리는 대신 분할 기준을 다시 작성해야 합니다. 일주일 정도 실행 시간, 사용량, 중복 발견과 통합 시간을 기록한 뒤 팀에 맞는 값을 선택하는 편이 근거가 있습니다.
8. 커스텀 에이전트 | 역할을 좁게 정의합니다
Codex에는 일반 작업용 default, 구현용 worker, 읽기 중심 조사용 explorer가 기본 역할로 제공됩니다. 프로젝트에 맞는 역할이 필요하면 사용자 범위의 ~/.codex/agents/ 또는 저장소 범위의 .codex/agents/에 TOML 파일을 추가할 수 있습니다. 각 파일에는 name, description, developer_instructions가 반드시 있어야 하며, 모델과 추론 강도와 sandbox 같은 설정도 선택적으로 넣을 수 있습니다. 공식 문서는 좋은 커스텀 에이전트일수록 역할이 좁고 분명하며, 맡지 말아야 할 일도 명시한다고 설명합니다. OpenAI Docs: Custom agents
초보자에게 권장할 만한 첫 구성은 탐색가, 구현자, 리뷰어 세 역할입니다. 탐색가는 읽기 전용으로 근거를 모으고, 구현자는 승인된 계획과 소유 파일 안에서만 코드를 변경합니다. 리뷰어는 구현 결과를 독립적으로 읽고 버그와 회귀와 테스트 누락을 찾지만 직접 고치지는 않습니다. 이 분리는 "자신이 만든 코드를 자신이 다시 칭찬하는" 자기 검증 문제를 줄이는 데 도움이 됩니다.
project/
├── AGENTS.md
├── .codex/
│ ├── config.toml
│ └── agents/
│ ├── repo-explorer.toml
│ ├── implementer.toml
│ └── reviewer.toml
├── package.json
└── src/읽기 전용 탐색 에이전트
탐색 에이전트의 임무는 해결책을 빨리 제시하는 것이 아니라 사실을 정확하게 찾는 일입니다. 따라서 수정 권한을 주지 않고, 파일 경로와 심볼과 실제 실행 경로를 결과에 포함하도록 요구합니다. 넓은 저장소를 처음부터 끝까지 읽게 하기보다, 빠른 검색과 필요한 파일의 부분 읽기를 우선하도록 지시합니다. 메인 에이전트는 이 보고서를 바탕으로 수정 범위를 정하므로, 탐색가의 산출물은 결론보다 근거가 중요합니다.
# .codex/agents/repo-explorer.toml
name = "repo_explorer"
description = "코드 수정 전에 실행 경로와 관련 파일을 읽기 전용으로 조사하는 에이전트"
sandbox_mode = "read-only"
developer_instructions = """
읽기 전용 탐색만 수행합니다.
실제 실행 경로를 따라가고 파일 경로, 심볼, 관련 테스트를 근거로 제시합니다.
부모 에이전트가 요청하지 않으면 해결책을 구현하거나 파일을 수정하지 않습니다.
넓은 전체 읽기보다 검색과 필요한 범위의 파일 읽기를 우선합니다.
확인한 사실, 추론, 확인하지 못한 부분을 구분해서 보고합니다.
"""범위가 제한된 구현 에이전트
구현 에이전트는 스스로 제품 범위를 넓히지 않고 승인된 계획을 코드로 옮깁니다. 위임 프롬프트에는 이 에이전트가 소유하는 파일이나 디렉터리를 명시해야 합니다. 재현 테스트가 필요한 버그라면 테스트가 먼저 실패하는지 확인한 뒤 최소 변경으로 통과시키도록 지시합니다. 다른 에이전트가 동시에 작업하는 저장소에서는 기존 변경을 되돌리지 말라는 문장도 반드시 필요합니다.
# .codex/agents/implementer.toml
name = "implementer"
description = "승인된 계획과 지정된 파일 범위 안에서 기능 또는 버그 수정을 구현하는 에이전트"
sandbox_mode = "workspace-write"
developer_instructions = """
부모 에이전트가 승인한 계획만 구현합니다.
할당받은 파일 또는 모듈만 소유하며, 다른 에이전트와 사용자의 변경을 되돌리지 않습니다.
버그 수정은 실패하는 테스트나 재현 절차를 먼저 확인합니다.
요청하지 않은 리팩터링, 설정, 의존성, 기능을 추가하지 않습니다.
작업 뒤에는 관련 테스트를 실행하고 변경 파일과 검증 결과를 짧게 보고합니다.
"""독립 리뷰 에이전트
리뷰 에이전트는 코드 스타일 취향보다 실제 동작 위험을 찾도록 설계합니다. 정확성, 보안, 회귀, 테스트 누락을 우선하고, 발견 사항마다 재현 방법이나 파일 근거를 붙입니다. 리뷰 과정에서 코드를 직접 수정하게 하면 문제를 발견하는 일과 해결하는 일이 뒤섞이므로 읽기 전용이 기본입니다. 문제가 없을 때도 "좋아 보입니다"가 아니라 확인한 범위와 남은 불확실성을 보고하게 해야 합니다.
# .codex/agents/reviewer.toml
name = "reviewer"
description = "구현 결과에서 정확성, 보안, 회귀, 테스트 누락을 찾는 읽기 전용 리뷰어"
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = """
저장소 소유자의 관점에서 변경을 검토합니다.
정확성, 보안, 동작 회귀, 누락된 테스트를 우선합니다.
스타일 취향만을 근거로 한 지적은 피합니다.
발견 사항에는 위험도, 파일과 심볼, 재현 또는 검증 절차를 포함합니다.
코드를 수정하지 말고, 확인한 범위와 남은 불확실성을 함께 보고합니다.
"""
모델을 파일에 고정하지 않으면 에이전트는 부모 세션과 [agents] 기본값을 바탕으로 설정을 선택할 수 있습니다. 공식 모델 페이지는 복잡한 코딩에는 gpt-5.6-sol, 일상적인 작업에는 gpt-5.6-terra, 빠르고 비용을 낮춘 좁은 작업에는 gpt-5.6-luna를 안내합니다. 그러나 모델 이름은 제품 변화에 민감하므로, 팀이 비용이나 재현성 때문에 고정해야 할 이유가 없다면 처음에는 생략하는 편이 관리가 쉽습니다. 리뷰어의 model_reasoning_effort = "high"처럼 역할 특성상 깊은 추론이 필요한 경우에만 선택적으로 고정하는 접근이 실용적입니다. OpenAI Docs: Models
9. 좋은 병렬 프롬프트에는 여섯 가지가 들어갑니다
역할 파일을 잘 만들어도 위임 프롬프트의 목표가 모호하면 결과는 흔들립니다. 메인 에이전트는 공통 목표, 분할 기준, 각 역할의 범위, 금지 사항, 반환 형식, 동기화 조건을 알아야 합니다. 특히 "모두 끝날 때까지 기다리기"와 "서로 같은 파일을 수정하지 않기"는 병렬 작업의 마감 방식을 결정합니다. 아래 템플릿은 코드 조사, PR 리뷰, 기능 계획에 공통으로 사용할 수 있는 기본 골격입니다.
[공통 목표]
현재 브랜치와 main의 차이를 검토하고 실제 배포 위험을 찾아 주세요.
[병렬 작업]
- repo_explorer: 변경된 파일이 영향을 주는 실행 경로를 조사해 주세요.
- reviewer 1: 정확성, 예외 처리, 데이터 손상 가능성을 검토해 주세요.
- reviewer 2: 인증, 권한, 비밀정보 노출 가능성을 검토해 주세요.
- reviewer 3: 테스트 누락과 불안정한 테스트 가능성을 검토해 주세요.
[공통 제약]
- 파일을 수정하지 마세요.
- 같은 발견을 반복하지 말고, 중복이면 근거가 더 강한 결과로 합치세요.
- 추측만으로 문제라고 단정하지 마세요.
[동기화]
- 모든 에이전트가 끝날 때까지 기다리세요.
- 서로 다른 결론이 나오면 메인 에이전트가 근거를 비교하세요.
[출력 형식]
- 심각도
- 문제 요약
- 파일과 심볼
- 재현 또는 검증 절차
- 권장 수정 방향
위 템플릿에서 "reviewer 1, 2, 3"은 같은 역할의 인스턴스를 서로 다른 관점으로 사용하는 예입니다. 역할 파일 하나를 여러 번 실행하더라도 위임 범위가 다르면 서로 독립된 검토를 수행할 수 있습니다. 다만 보안과 유지보수처럼 판단 기준이 크게 다르면 별도 커스텀 에이전트로 분리하는 편이 결과가 더 안정적입니다. 어느 방식이든 메인 에이전트가 결과를 기다리고 중복과 충돌을 해소한다는 책임은 바뀌지 않습니다.
공통 목표는 한 문장으로 판정할 수 있어야 합니다
공통 목표는 “코드를 잘 검토합니다”보다 “현재 브랜치가 main에 비해 배포 시 만들 수 있는 동작 위험을 찾습니다”처럼 결과의 범위를 보여 줘야 합니다. 목표에 비교 대상, 대상 사용자와 실패의 의미가 포함되면 각 역할이 다른 파일을 보더라도 같은 문제를 향할 수 있습니다. 설계 탐색과 실제 수정처럼 성격이 다른 일을 한 목표에 넣으면 어느 시점에 쓰기가 시작되어도 되는지 모호해집니다. 조사 목표가 끝난 뒤 메인 에이전트가 계획 게이트를 통과해야 구현 목표가 열리는 식으로 단계를 나누는 편이 명확합니다.
분할 기준은 파일보다 질문이 될 수 있습니다
저장소를 프런트엔드, 백엔드와 테스트로 나누는 방법은 이해하기 쉽지만 하나의 버그가 세 영역을 모두 통과할 수 있습니다. 그럴 때는 “사용자 입력이 어디에서 검증되는가”, “세션이 어디에서 만들어지는가”, “어떤 테스트가 이 동작을 보장하는가”처럼 질문으로 나눌 수 있습니다. 각 역할은 자신의 질문을 따라 여러 디렉터리를 읽더라도 다른 역할과 같은 결론을 반복할 가능성이 줄어듭니다. 분할 기준은 저장소 구조와 문제의 성격 가운데 결과가 덜 겹치는 쪽을 선택해야 합니다.
소유권과 금지 사항은 쓰기 전에 더 구체적이어야 합니다
읽기 작업은 범위가 조금 겹쳐도 주로 비용 문제가 되지만 쓰기 작업의 겹침은 변경 충돌과 데이터 손상으로 이어질 수 있습니다. 구현 역할에는 소유 파일, 생성 가능한 파일, 변경하면 안 되는 모듈과 새 의존성 승인 여부를 구체적으로 적습니다. 같은 작업 공간을 사용할 때는 다른 에이전트와 사용자의 기존 변경을 되돌리지 말라는 문장도 필요합니다. 소유권을 파일로 나누기 어렵다면 구현을 직렬로 바꾸거나 기능별 Worktree를 만드는 것이 더 안전합니다.
반환 형식은 메인 에이전트의 통합 비용을 결정합니다
어떤 역할은 긴 서술형 보고서를, 다른 역할은 짧은 목록을 반환하면 메인 에이전트가 결과를 다시 해석하는 시간이 늘어납니다. 심각도, 발견 내용, 근거, 재현 절차와 불확실성처럼 공통 필드를 정하면 서로 다른 관점을 같은 기준으로 비교할 수 있습니다. 파일 위치는 가능한 한 경로와 심볼을 함께 적고 명령 결과는 성공 여부와 핵심 출력만 남기게 합니다. 원문 로그 전체가 필요할 때는 별도 파일이나 에이전트 스레드에 남기고 메인 결과에는 결론을 뒷받침하는 부분만 가져오는 편이 좋습니다.
대기 조건과 계획 게이트는 다음 단계를 통제합니다
병렬 작업을 시작했다면 어느 결과가 모여야 다음 단계로 갈 수 있는지 적어야 합니다. “모든 조사 역할이 끝날 때까지 기다립니다”는 완전한 동기화이고, “보안 차단 이슈가 발견되면 다른 결과를 기다리지 않고 중단합니다”는 조기 종료 조건입니다. 결과가 도착한 뒤 바로 구현하지 않고 메인 에이전트가 원인과 수정 파일을 제시하는 계획 게이트를 두면 잘못된 가정이 코드로 퍼지는 것을 막을 수 있습니다. 사용자의 승인이나 제품 결정이 필요한 경우도 이 게이트에서 질문을 남기고 쓰기를 멈춰야 합니다.
좋은 프롬프트도 결과를 보고 수정합니다
첫 실행에서 세 역할이 같은 파일을 읽었다면 분할 기준을 더 좁히고, 근거가 빠졌다면 반환 형식에 파일과 명령 필드를 추가합니다. 한 역할만 지나치게 오래 걸린다면 범위가 넓거나 높은 추론 강도가 불필요한지 확인할 수 있습니다. 모든 결과가 짧지만 실제 결론에 도움이 되지 않았다면 에이전트 수보다 공통 목표와 성공 기준이 흐렸을 가능성이 큽니다. 프롬프트를 템플릿으로 저장하기 전에 두세 번의 실제 결과를 보고 반복되는 실패를 규칙으로 옮겨야 합니다.
10. 권한과 sandbox는 위임 전에 정합니다
서브에이전트는 기본적으로 부모 작업의 sandbox와 권한 정책을 상속합니다. 따라서 메인 작업이 시작된 뒤 무심코 넓은 권한을 선택하면, 새로 생성되는 에이전트도 그 영향 범위 안에서 동작할 수 있습니다. 개별 커스텀 에이전트 파일에서 sandbox_mode = "read-only"처럼 더 좁은 권한을 지정할 수 있지만, 부모의 실시간 권한 선택이 다시 적용되는 상황도 공식 문서에 설명되어 있습니다. 위임 프롬프트를 보내기 전에 /permissions 또는 앱의 권한 선택 영역을 확인하는 습관이 필요합니다. OpenAI Docs: Approvals and sandbox controls
최소 권한은 역할 설계와 함께 정합니다
탐색가에게는 저장소와 필요한 문서를 읽을 권한만 있으면 충분합니다. 리뷰어도 변경을 찾는 역할이므로 기본적으로 읽기 전용이 맞고, 검증 명령이 캐시나 임시 파일을 만든다면 그 범위만 별도로 고려합니다. 구현자는 작업 공간 쓰기가 필요하지만 홈 디렉터리, 셸 시작 파일과 시스템 설정까지 바꿀 이유는 거의 없습니다. 문서 조사자가 네트워크에 접근하더라도 배포 서비스나 운영 데이터베이스 도구까지 함께 받을 필요는 없습니다.
권한을 좁히면 승인 요청이 늘어날 수 있지만 그 요청은 하네스가 놓친 필요를 발견하는 신호가 되기도 합니다. 같은 안전한 테스트 명령이 매번 승인 대기한다면 팀은 규칙이나 권한 프로필에 그 명령을 명시할 수 있습니다. 반대로 일회성 배포나 외부 댓글 작성 요청을 편의 때문에 영구 허용하면 다음 작업의 영향 범위까지 넓어집니다. 반복 빈도와 실패 시 피해를 함께 보고 지속 권한과 매번 승인할 행동을 구분해야 합니다.
승인 대기는 코드 오류와 다른 실패입니다
서브에이전트가 명령을 실행하지 못하면 구현이 틀렸다고 단정하기 전에 권한 요청이 표시되었는지 확인합니다. CLI에서는 현재 보고 있지 않은 에이전트 스레드에서 승인 오버레이가 생길 수 있고, 출처 역할을 열어 명령 내용을 확인할 수 있습니다. 비대화형 실행은 새로운 승인을 받을 수 없으면 해당 작업이 실패하고 오류가 부모 워크플로로 전달될 수 있습니다. 이 실패를 같은 프롬프트로 재시도하면 권한 조건이 바뀌지 않았으므로 같은 지점에서 다시 멈출 가능성이 큽니다.
승인 요청을 받을 때는 명령 문자열만 보지 않고 실행 위치와 영향을 받는 파일을 함께 확인합니다. 의존성 설치는 잠금 파일과 스크립트를 바꿀 수 있고 테스트 명령도 스냅샷 갱신 옵션이 붙으면 소스 파일을 수정할 수 있습니다. 외부 서비스 명령은 파일 변경이 없어도 댓글, 배포와 데이터 변경을 만들 수 있으므로 별도 범위로 판단해야 합니다. 허용한 뒤에는 에이전트가 원래 맡은 역할 안에서 그 권한을 사용했는지도 최종 보고서에서 확인합니다.
베타 권한 프로필과 기존 sandbox를 섞지 않습니다
공식 권한 문서는 새로운 프로필 방식을 베타로 표시하며 활발하게 변경될 수 있다고 안내합니다. 프로필은 파일 시스템과 네트워크 규칙을 이름 있는 정책으로 묶지만 기존 sandbox_mode와 함께 합성되지 않습니다. 어느 설정 계층에라도 sandbox_mode가 남아 있으면 예상한 프로필 대신 기존 sandbox 방식이 사용될 수 있습니다. 팀이 프로필을 도입한다면 사용자, 프로젝트와 관리 설정 전체에서 오래된 키를 조사하고 한 방식을 선택해야 합니다.
이 글은 초보자가 여러 체계를 동시에 배우지 않도록 예제를 sandbox_mode 방식으로 통일합니다. 베타 프로필이 필요한 조직은 별도 테스트 저장소에서 실제 파일 읽기와 쓰기, 네트워크 허용과 거부를 확인해야 합니다. 문서에 적힌 정책 이름만 보고 적용되었다고 판단하지 말고 허용해야 할 명령과 차단해야 할 명령을 각각 실행해 증거를 남겨야 합니다. 권한 체계를 바꾸는 작업은 에이전트 역할 추가와 분리하여 문제가 생겼을 때 원인을 한 축으로 좁히는 편이 좋습니다.
11. Worktree | 대화뿐 아니라 파일 작업도 분리합니다
서브에이전트 스레드는 컨텍스트를 분리하지만, 같은 체크아웃을 사용하면 파일은 여전히 공유될 수 있습니다. 서로 다른 기능을 동시에 구현하거나 장시간 백그라운드 작업을 돌릴 때는 Git Worktree가 한 단계 더 강한 격리를 제공합니다. Worktree는 같은 Git 저장소의 메타데이터를 공유하면서 파일 체크아웃은 별도로 만드는 Git 기능입니다. Codex의 Worktree 화면은 현재 공식 문서 기준으로 ChatGPT 데스크톱 앱의 Codex에서 제공됩니다. OpenAI Docs: Worktrees
대화 격리와 파일 격리를 구분합니다
서브에이전트 스레드는 각 역할이 보는 대화와 중간 출력을 분리합니다. 하지만 같은 체크아웃에서 실행된다면 한 역할이 저장한 파일은 다른 역할과 메인 에이전트에게 곧바로 보일 수 있습니다. 읽기 중심 작업에서는 이 공유가 큰 문제가 아니지만 두 구현자가 같은 파일을 수정하면 마지막 쓰기가 앞선 변경을 덮을 수 있습니다. 따라서 “서브에이전트가 따로 실행된다”는 사실만으로 코드 작업까지 격리되었다고 판단해서는 안 됩니다.
Worktree는 같은 저장소에서 파일 체크아웃을 별도로 만들어 이 문제를 한 단계 줄입니다. 각 Worktree는 자신의 파일 트리와 작업 상태를 가지므로 다른 기능의 미완성 변경을 보지 않고 테스트할 수 있습니다. 그러나 커밋과 브랜치 정보를 담는 Git 메타데이터는 공유하므로 브랜치 이름과 통합 순서에는 여전히 조정이 필요합니다. 파일 공간이 분리되었다는 사실과 최종 결과가 자동으로 합쳐진다는 기대도 서로 다른 문제입니다.
Worktree를 쓸 작업과 쓰지 않을 작업을 나눕니다
서로 다른 기능이 각자 별도 디렉터리와 테스트를 수정하고 몇 시간 이상 진행된다면 Worktree의 이점이 큽니다. 메인 개발자는 Local에서 기존 작업을 이어 가고 Codex는 Worktree에서 배경 작업을 진행한 뒤 준비된 결과를 Handoff할 수 있습니다. 반면 한 줄 설정 수정이나 10분 안에 끝나는 읽기 조사에는 새 체크아웃과 의존성 설치 비용이 작업보다 클 수 있습니다. Worktree는 모든 병렬 작업의 기본값이 아니라 장시간 쓰기 충돌 위험이 실제로 있을 때 사용하는 격리 장치입니다.
하나의 기능을 프런트엔드와 백엔드로 나누었더라도 두 부분이 같은 API 계약을 동시에 바꾸면 완전히 독립적이지 않습니다. 이때는 계약을 먼저 확정한 뒤 각 Worktree에 같은 기준을 전달하거나 한쪽이 계약을 소유하고 다른 쪽이 소비하게 해야 합니다. 데이터베이스 마이그레이션 순서와 생성 코드처럼 통합 지점이 많은 작업은 Worktree가 있어도 직렬 계획이 필요합니다. 파일 충돌이 사라져도 의미 충돌은 남으므로 최종 통합 전에 전체 테스트와 계약 검토를 다시 수행해야 합니다.
실행 환경은 별도로 이름을 붙입니다
두 Worktree가 모두 기본 포트 3000으로 개발 서버를 시작하면 두 번째 서버는 실행에 실패하거나 첫 번째 서버를 잘못 검증할 수 있습니다. Worktree별 환경 변수에 포트 번호를 지정하고 로그에도 체크아웃 이름을 표시하면 어느 서버를 보고 있는지 구분할 수 있습니다. 테스트 데이터베이스도 같은 이름을 사용하면 한 작업의 마이그레이션이나 정리가 다른 작업의 데이터를 바꿀 수 있습니다. 가능하다면 데이터베이스 이름, 임시 디렉터리와 브라우저 프로필에 Worktree 식별자를 붙이는 편이 안전합니다.
외부 샌드박스 계정과 API 쿼터는 로컬 파일처럼 쉽게 복제되지 않습니다. 결제 테스트 계정, 이메일 수신함과 배포 미리보기 환경을 공유한다면 실행 순서나 예약 규칙을 별도로 마련해야 합니다. 에이전트가 사용하는 자원 목록을 파일, 프로세스, 데이터와 외부 서비스로 나누어 적으면 숨은 공유 상태를 찾기 쉽습니다. Worktree 도입 뒤에도 간헐적 테스트 실패가 남는다면 코드보다 이 실행 자원 충돌을 먼저 확인할 가치가 있습니다.
Handoff 전에는 변경을 설명할 수 있어야 합니다
Worktree에서 작업이 끝났다고 곧바로 Local로 옮기기보다 변경 파일, 검증 결과와 남은 위험을 먼저 정리합니다. Handoff는 채팅과 변경을 다른 작업 공간으로 이동하는 편의 기능이지 미완성 설계를 자동으로 승인하는 검증기가 아닙니다. Local에서 기존 변경과 합쳐질 때 새로운 충돌이 생길 수 있으므로 최종 diff와 전체 테스트를 다시 확인해야 합니다. 작업이 불필요해졌다면 어떤 파일도 옮기지 않고 Worktree 결과를 폐기할 수 있어야 격리의 장점을 살릴 수 있습니다.
12. 루프 엔지니어링 | 완료를 말이 아니라 증거로 판단합니다
루프 엔지니어링은 에이전트가 한 번에 정답을 내기를 기대하지 않고, 관찰과 검증을 반복하도록 작업을 설계하는 방식입니다. 개발자가 코드를 작성한 뒤 테스트를 돌리고 실패 원인을 다시 고치는 과정과 본질적으로 같습니다. 차이는 각 단계의 입력과 종료 조건을 프롬프트와 저장소 규칙에 더 명확히 적어야 한다는 점입니다. 검증 없이 "완료했습니다"라는 문장만 받으면 에이전트가 여러 명이어도 신뢰도는 높아지지 않습니다.
관찰 단계는 증상을 재현 가능한 입력으로 바꿉니다
“로그인이 가끔 풀립니다”라는 설명만으로는 어떤 환경과 순서에서 실패하는지 알 수 없습니다. 사용한 계정 종류, 브라우저 동작, 요청 순서, 시간 간격과 실제 오류 메시지를 기록하면 여러 조사 역할이 같은 사건을 보게 됩니다. 재현이 되지 않는다면 그 사실도 결과이며 로그 위치와 추가 관측 방법을 먼저 마련해야 합니다. 관찰 없이 시작한 병렬 조사는 각 에이전트가 서로 다른 버그를 상상하게 만들 수 있습니다.
계획 단계는 사실과 가설 사이에 문을 둡니다
조사 결과에서 확인한 코드 경로와 가능한 원인을 분리하면 구현 범위를 고르기 쉬워집니다. 쿠키 만료 계산이 의심스럽다는 가설과 실제 만료 값이 잘못되었다는 재현 결과는 같은 강도의 근거가 아닙니다. 메인 에이전트는 어떤 가설을 선택했는지와 선택하지 않은 이유를 짧게 남겨 다음 실패에서 되돌아볼 수 있어야 합니다. 수정 파일과 성공 기준을 고정하지 못했다면 구현 역할을 시작하지 않는 것도 계획 단계의 유효한 결론입니다.
실행 단계는 변경을 작게 유지합니다
원인이 확인된 뒤에는 구현 역할 한 명이 실패하는 테스트나 재현 절차를 먼저 확보합니다. 수정은 해당 실패를 해결하는 최소 범위로 제한하고 관련 없는 정리와 의존성 교체는 다음 작업으로 분리합니다. 변경이 작으면 독립 리뷰어가 원인과 해결의 연결을 확인하기 쉽고 실패 시 되돌릴 범위도 작아집니다. 병렬 조사에서 많은 개선 아이디어가 나왔더라도 한 루프 안에서 모두 구현하면 어떤 변경이 실제 문제를 해결했는지 알기 어렵습니다.
검증 단계는 여러 종류의 증거를 구분합니다
관련 단위 테스트는 수정한 함수의 동작을 빠르게 확인하지만 시스템 전체의 통합을 보장하지는 않습니다. lint와 타입 검사는 코드의 일관성을 확인하지만 사용자가 겪은 화면 동작을 대신 재현하지 못합니다. 브라우저 또는 API 수준 재현은 실제 흐름을 확인하지만 다른 기능의 회귀를 모두 찾지는 못합니다. 작업 위험에 맞춰 관련 테스트, 전체 테스트, 정적 검사와 실제 동작 가운데 필요한 증거를 조합해야 합니다.
독립 리뷰는 명령이 찾기 어려운 가정과 누락을 확인합니다. 리뷰어가 구현자의 설명만 읽지 않고 최종 diff, 관련 코드와 테스트를 직접 확인해야 같은 가정을 반복하는 일을 줄일 수 있습니다. 리뷰에서 새 문제가 발견되면 즉시 수정하기보다 심각도와 재현 가능성을 확인해 계획 단계로 돌려보냅니다. 검증은 마지막에 한 번 붙이는 의식이 아니라 다음 행동을 결정하는 루프의 제어 신호입니다.
종료 조건은 성공과 안전 중단을 따로 적습니다
성공 종료는 재현 테스트 통과, 관련 테스트와 전체 검증 통과, 독립 리뷰에서 차단 문제가 없다는 증거로 구성할 수 있습니다. 모든 작업에 같은 검증 묶음을 강제하기보다 변경 위험과 프로젝트 규칙에 맞는 조건을 사전에 정해야 합니다. 성공 기준이 작업 도중 바뀐다면 메인 에이전트가 변경 이유와 새 범위를 보고하고 다시 승인받는 편이 맞습니다. 완료라는 표현은 이 조건을 실제 최종 상태에서 확인한 뒤에만 사용합니다.
안전 중단은 성공하지 못했지만 더 진행하는 것이 불리한 상태입니다. 같은 실패가 연속으로 반복되거나 새 증거가 없고, 시간 또는 사용량 예산이 끝나거나 필요한 권한과 제품 결정을 얻지 못한 경우가 해당합니다. 중단할 때는 시도한 방법, 실패 증거, 현재 변경 상태와 다음 사람에게 필요한 결정을 남겨야 합니다. 이 보고서가 있으면 다음 실행이 같은 실패를 처음부터 반복하지 않고 새로운 입력에서 시작할 수 있습니다.
13. 실전 사례 | 하나의 버그를 병렬 조사하고 직렬로 수정합니다
예시 상황은 로그인 직후 사용자가 간헐적으로 다시 로그인 화면으로 돌아오는 버그입니다. 이 문제에는 프런트엔드 라우팅, 백엔드 세션, 만료 시간, 테스트 환경이 함께 얽힐 수 있습니다. 조사는 여러 관점으로 나눌 수 있지만, 실제 수정은 원인이 확인된 뒤 한 에이전트가 맡는 편이 안전합니다. 아래 흐름은 병렬화와 직렬화를 한 작업 안에서 섞는 전형적인 예입니다.
- 메인 에이전트는 증상과 성공 기준을 먼저 고정합니다.
"로그인 후 30초 동안 세션이 유지되고 회귀 테스트가 통과한다"처럼 관찰 가능한 문장으로 적습니다. - 탐색 에이전트 세 명이 프런트엔드 리다이렉트, 백엔드 세션 발급, 관련 테스트를 각각 조사합니다.
이 단계에서는 파일 수정을 금지하고 실행 경로와 근거만 반환하게 합니다. - 메인 에이전트는 세 보고서를 비교해 하나의 원인 가설과 수정 범위를 만듭니다.
보고서가 충돌하면 코드와 재현 결과가 더 강한 쪽을 채택하고 불확실한 부분은 추가로 확인합니다. - 구현 에이전트 한 명이 실패하는 회귀 테스트를 만들고 최소한의 코드를 수정합니다.
이 에이전트에는 소유 파일과 실행해야 할 테스트 명령을 명시합니다. - 리뷰 에이전트는 변경을 읽기 전용으로 다시 검토합니다.
메인 에이전트는 최종 테스트와 diff를 확인한 뒤 성공 기준을 충족할 때만 완료로 판단합니다.
로그인 후 세션이 즉시 사라지는 버그를 조사하고 수정해 주세요.
1단계: 병렬 조사
- repo_explorer A는 프런트엔드 로그인 성공 후 라우팅 경로만 조사합니다.
- repo_explorer B는 서버의 세션 생성, 쿠키 옵션, 만료 계산만 조사합니다.
- repo_explorer C는 관련 테스트와 재현 가능한 누락 시나리오만 조사합니다.
- 세 에이전트 모두 파일을 수정하지 않습니다.
2단계: 계획 게이트
- 모든 조사 결과가 끝난 뒤 메인 에이전트가 원인 가설과 수정 파일을 제시합니다.
- 근거가 부족하면 구현하지 말고 추가 확인 항목을 보고합니다.
3단계: 구현
- implementer 한 명만 승인된 파일을 수정합니다.
- 실패하는 회귀 테스트를 먼저 확인한 뒤 최소 수정으로 통과시킵니다.
4단계: 독립 검증
- reviewer가 정확성, 보안, 회귀, 테스트 누락을 읽기 전용으로 검토합니다.
- 메인 에이전트는 테스트, lint, build와 최종 diff를 확인하고 결과를 통합합니다.
이 예제에서는 구현 속도를 높인다는 이유만으로 여러 에이전트에게 코드를 쓰게 하지 않습니다. 원인 후보가 많은 조사 구간만 병렬화하고, 공유 상태를 바꾸는 구현과 통합은 직렬로 처리합니다. 덕분에 세 명이 같은 세션 코드를 서로 다른 방식으로 고치는 충돌을 피할 수 있습니다. 병렬 에이전트의 목적은 작업자 수를 늘리는 것이 아니라 기다리지 않아도 되는 일을 동시에 처리하는 것입니다.
첫 단계는 버그를 측정 가능한 문장으로 바꾸는 일입니다
간헐적이라는 표현은 조사 범위를 지나치게 넓게 만듭니다. 메인 에이전트는 로그인 성공 시각, 다시 로그인 화면으로 이동한 시각, 쿠키 존재 여부와 서버 응답 코드를 기록하는 재현 절차를 먼저 만듭니다. 실패 빈도가 낮다면 자동 반복 횟수와 중단 조건도 정하여 무한히 재현을 시도하지 않게 합니다. 이 기록은 프런트엔드, 백엔드와 테스트 역할이 서로 같은 실패를 조사하고 있는지 확인하는 공통 입력이 됩니다.
[재현 계약 예시]
- 테스트 계정으로 로그인합니다.
- 로그인 성공 응답 시각과 Set-Cookie 헤더를 기록합니다.
- 30초 동안 보호된 페이지를 5초 간격으로 요청합니다.
- 로그인 화면으로 이동하면 해당 요청의 상태 코드와 쿠키 만료 값을 기록합니다.
- 10회 안에 재현되지 않으면 재현 실패로 중단하고 관측 로그의 부족을 보고합니다.
이 재현 계약은 실제 프로젝트의 API와 보안 정책에 맞게 바꾸어야 하는 예시입니다. 운영 계정이나 실제 고객 데이터로 반복하지 않고 로컬 또는 승인된 테스트 환경을 사용해야 합니다. 세션 값과 쿠키에는 민감한 정보가 있을 수 있으므로 보고서에는 원문 토큰 대신 필요한 속성과 시각만 남깁니다. 재현 스크립트를 만들었다면 테스트 종료 뒤 세션과 테스트 데이터를 정리하는 절차도 함께 확인합니다.
조사 결과는 시간 순서로 합칩니다
프런트엔드 역할은 로그인 성공 뒤 상태 저장과 라우터 전환 시점을, 서버 역할은 세션 발급과 만료 계산 시점을 보고합니다. 테스트 역할은 기존 테스트가 어느 구간까지만 확인하고 있는지와 실패를 재현할 최소 시나리오를 찾습니다. 메인 에이전트는 세 보고서를 파일별 목록으로 붙이지 않고 사용자 요청이 이동하는 시간 순서로 배열합니다. 이렇게 하면 쿠키가 잘못 발급된 것인지, 올바른 쿠키를 클라이언트가 잃은 것인지, 테스트가 어느 경계를 놓쳤는지 비교하기 쉽습니다.
구현자는 한 가지 원인만 고칩니다
예를 들어 서버가 초 단위 만료 값을 밀리초로 해석한다는 사실이 확인되었다면 구현자는 그 계산과 회귀 테스트를 소유합니다. 같은 파일에 오래된 변수명이나 중복 함수가 보여도 이번 버그와 관계가 없으면 변경하지 않습니다. 테스트가 수정 전 실패하고 수정 후 통과하는지 확인하면 원인과 해결의 연결을 직접 증명할 수 있습니다. 여러 원인을 한 번에 고치면 어떤 변경이 테스트를 통과시켰는지 알기 어려우므로 별도 작업으로 나누는 편이 낫습니다.
독립 리뷰는 구현의 빈틈을 찾습니다
리뷰어는 만료 계산이 고쳐졌다는 설명을 전제로 읽지 않고 원래 재현 조건과 최종 diff를 비교합니다. 쿠키 보안 속성, 시간대와 경계값, 기존 세션 갱신 로직과 테스트가 실제로 실행되는지 확인할 수 있습니다. 스타일 취향은 뒤로 미루고 잘못된 로그인 유지, 보안 약화와 기존 사용자 세션 회귀처럼 실제 위험을 우선합니다. 발견이 없더라도 검토한 파일, 확인한 경계와 실행하지 못한 테스트를 남겨 검토 범위를 알 수 있게 합니다.
14. Claude Code 경험을 Codex 개념으로 옮겨 보기
Claude Code를 사용해 본 개발자는 기존에 익숙한 책임이 Codex의 어느 표면에 놓이는지 먼저 비교하면 이해가 빠릅니다. 다만 아래 표는 기능의 책임 범위를 이해하기 위한 대응표이며, 설정 파일을 기계적으로 이름만 바꾸라는 뜻은 아닙니다. 각 제품은 지침 발견 순서, 권한 모델, UI, 확장 방식이 다르므로 기존 설정을 그대로 복사하면 예상과 다른 동작이 나올 수 있습니다. 특히 Codex에서는 영속적인 저장소 규칙, 재사용 워크플로, 에이전트 역할, 명령 정책을 서로 다른 표면으로 나누어야 책임이 선명해집니다.
| 익숙한 목적 | Codex 설정파일 | 확인할 부분 |
| 저장소 공통 지침 | AGENTS.md | 루트부터 현재 디렉터리까지 계층적으로 읽습니다. 하위 규칙과 override의 우선순위를 확인해야 합니다. |
| 역할이 정해진 보조 에이전트 | .codex/agents/*.toml | 이름, 설명, 개발자 지침이 필수입니다. 권한과 모델을 역할별로 좁힐 수 있습니다. |
| 개인·프로젝트 실행 설정 | ~/.codex/config.toml, .codex/config.toml | 신뢰된 프로젝트에서만 프로젝트 계층이 적용됩니다. CLI 플래그가 가장 높은 우선순위를 가집니다. |
| 반복 가능한 작업 절차 | Skills | 한 번의 저장소 규칙보다 구체적인 순서와 참고 자료가 필요한 워크플로에 맞습니다. |
| 명령 실행 통제 | Rules와 권한 설정 | 허용·승인·차단 정책을 지침 문장만으로 처리하지 않고 기계적 정책으로 분리합니다. |
| 병렬 파일 작업 | Codex 앱 Worktree | 서브에이전트 스레드와 달리 체크아웃 자체를 분리합니다. 데이터베이스와 포트는 별도로 격리해야 합니다. |
AGENTS.md에 모든 것을 넣으면 처음에는 편해 보이지만 시간이 지나면 책임이 섞입니다. 저장소에서 항상 지켜야 할 규칙은 AGENTS.md, 반복 절차는 Skill, 좁은 역할은 커스텀 에이전트, 명령 정책은 Rules가 담당하는 구성이 이해하기 쉽습니다. 외부 서비스나 최신 문서를 실제로 읽어야 한다면 MCP 같은 도구 계층을 연결합니다. 이 구분은 에이전트가 규칙을 찾기 쉽게 만들 뿐 아니라 사람이 문제가 생긴 위치를 추적하기도 쉽게 만듭니다.
제품 이름보다 책임을 옮깁니다
Claude Code에서 사용하던 파일이나 명령과 이름이 비슷하다고 같은 동작을 기대하면 마이그레이션이 어려워집니다. 먼저 기존 구성에서 저장소 규칙, 반복 절차, 역할 정의, 명령 통제와 격리가 각각 어떤 책임을 맡았는지 적어야 합니다. 그다음 Codex의 AGENTS.md, Skills, 커스텀 에이전트, Rules·권한과 Worktree 가운데 같은 책임을 맡을 표면을 선택합니다. 이 순서를 따르면 제품별 문법이 달라도 팀이 지키려던 운영 원칙은 잃지 않을 수 있습니다.
15. 자주 실패하는 운영 패턴
병렬 에이전트의 실패는 모델 능력보다 작업 분할과 검증 방식에서 자주 발생합니다. 서로 의존하는 일을 동시에 시작하거나, 같은 파일을 여러 에이전트가 수정하거나, 종료 조건 없이 반복시키는 경우가 대표적입니다. 문제가 생기면 더 많은 에이전트를 추가하기 전에 공유 상태와 선행 관계를 먼저 다시 그려 봐야 합니다. 아래 항목은 첫 도입에서 특히 자주 확인해야 할 운영 실수입니다.
- 같은 파일을 두 구현 에이전트가 동시에 수정합니다.
파일 소유권을 명시하거나 기능별 Worktree를 만들어 쓰기 영역을 분리해야 합니다. - 역할 이름만 다르고 실제 지침은 모두 같습니다.
각 역할이 수집할 근거, 금지할 행동, 반환할 형식을 다르게 정의해야 합니다. - 모든 결과를 기다리라는 조건이 없습니다.
메인 에이전트가 일부 결과만 보고 결론을 내리지 않도록 동기화 게이트를 명시해야 합니다. - 에이전트의 "테스트가 통과했습니다"라는 보고만 믿습니다.
최종 상태에서 메인 에이전트가 명령과 종료 코드를 다시 확인해야 합니다. - 동시 실행 한도를 목표치처럼 모두 채웁니다.
max_concurrent_threads_per_session은 상한선이며, 실제 작업에는 필요한 수만 사용해야 합니다. - 읽기 전용 조사에도 넓은 쓰기 권한을 부여합니다.
역할별 sandbox를 좁히면 잘못된 판단이 변경으로 이어질 가능성을 줄일 수 있습니다. - 실패한 루프를 같은 입력으로 계속 반복합니다.
재시도 전에는 새로운 로그, 재현 결과, 수정된 가설 중 하나가 반드시 추가되어야 합니다.
증상, 원인, 확인과 복구 순서로 문제를 봅니다
서브에이전트가 시작되지 않는다면 먼저 현재 클라이언트와 기능 가용성, 직접적인 위임 문구와 [agents] 설정을 확인합니다. agents.enabled = false가 높은 우선순위 설정에 있거나 프로젝트 설정이 신뢰 상태 때문에 읽히지 않는 경우도 있습니다. CLI에서는 /agent 목록으로 실제 스레드가 만들어졌는지 보고, 일반 답변만 돌아왔다면 분할과 대기 조건을 더 명시합니다. 설정 파일을 여러 곳에서 동시에 바꾸지 말고 가장 높은 우선순위의 값을 하나씩 확인해야 원인을 놓치지 않습니다.
에이전트가 실행되지만 모두 같은 내용을 보고한다면 모델 문제가 아니라 분할 기준이 겹쳤을 가능성이 큽니다. 각 역할이 읽은 파일과 검색 질문을 비교하고, 디렉터리 기준과 관심사 기준 가운데 어느 쪽이 중복을 줄일지 다시 선택합니다. 공통 배경은 공유하되 각 역할의 질문과 반환 필드는 다르게 적어야 독립 관점이 생깁니다. 다음 실행에서 중복 발견 수가 줄었는지 비교하면 프롬프트 수정의 효과를 측정할 수 있습니다.
한 역할이 멈춘 것처럼 보인다면 승인 요청, 긴 테스트, 네트워크 대기와 실제 오류를 구분합니다. 해당 스레드를 열어 마지막 도구 호출과 출력을 확인하고, 필요한 승인이라면 명령의 범위와 위치를 검토합니다. 테스트가 장시간 실행 중이면 같은 명령을 다른 역할에서 중복으로 시작하지 말고 예상 종료 시간과 자원 사용을 봅니다. 오류가 반복되면 실패 로그를 부모에게 돌려보내 계획을 줄이고, 새 증거 없이 같은 역할을 다시 시작하지 않습니다.
파일 충돌이 발생하면 어느 변경이 마지막에 저장되었는지만 보고 한쪽을 선택해서는 안 됩니다. 각 에이전트의 소유 범위와 원래 의도를 확인하고, 공유 파일이 필요했다면 통합 책임자를 한 명으로 다시 지정합니다. 되돌릴 때는 사용자의 기존 변경과 다른 에이전트의 작업을 함께 지우지 않도록 diff를 파일별로 검토합니다. 충돌이 반복되는 작업은 다음 실행에서 Worktree로 분리하거나 선행 관계를 두어 쓰기를 직렬화합니다.
테스트는 통과하지만 실제 동작이 틀리다면 검증기가 성공 기준을 충분히 표현하지 못한 상태입니다. 사용자가 겪은 재현 절차가 테스트에 포함되었는지, 테스트 파일이 실제 명령에서 실행되는지와 assertion이 올바른 값을 보는지 확인합니다. 에이전트가 검증 명령 자체를 약화하거나 스킵 처리를 추가하지 않았는지도 최종 diff에서 봐야 합니다. 문제를 고친 뒤에는 해당 실패를 다시 잡을 수 있는 검증을 하네스에 남겨 같은 유형이 반복되지 않게 합니다.
16. 복사해서 사용하는 도입 체크리스트
처음부터 완벽한 에이전트 조직을 만들 필요는 없습니다. 한 저장소에서 읽기 전용 조사 세 개를 병렬로 실행하고, 결과를 한 번 통합해 보는 것만으로도 충분한 출발이 됩니다. 그 과정에서 반복되는 역할이 보이면 커스텀 에이전트로 옮기고, 반복되는 절차가 보이면 Skill로 분리합니다. 쓰기 충돌이 실제로 발생하는 시점에 Worktree를 추가하면 설정이 필요 이상으로 복잡해지는 일을 피할 수 있습니다.
- 최신 Codex CLI 또는 ChatGPT 데스크톱 앱을 설치하고 로그인합니다.
프로젝트에서 /status와 /permissions를 확인해 작업 디렉터리와 권한이 예상과 같은지 봅니다. - 저장소 루트에 짧은 AGENTS.md를 만듭니다.
설치, 테스트, lint, build, 수정 금지 영역, 완료 기준을 실행 가능한 문장으로 적습니다. - 첫 병렬 작업은 읽기 전용으로 실행합니다.
프로젝트 구조, 테스트, 보안처럼 독립된 관점을 나누고 모든 결과를 기다리게 합니다. - .codex/config.toml에서 동시 실행 상한을 작게 시작합니다.
네 개 정도로 시작한 뒤 실제 대기 시간과 비용과 통합 난이도를 보고 조정합니다. - 반복해서 필요한 역할만 .codex/agents/*.toml로 만듭니다.
역할마다 임무, 금지 사항, 근거 형식, sandbox를 구체적으로 적습니다. - 쓰기 작업은 파일 소유권을 지정하거나 Worktree로 격리합니다.
같은 파일과 같은 런타임 자원을 동시에 쓰지 않는지 확인합니다. - 완료 조건에는 명령과 증거를 포함합니다.
테스트 결과, lint와 build, 최종 diff, 독립 리뷰를 확인한 뒤에만 완료로 판단합니다.
맺음말
Codex 병렬 에이전트의 시작점은 에이전트 수가 아니라 작업 경계입니다. 서로 기다릴 필요가 없는 조사와 검토는 병렬로 보내고, 공유 상태를 바꾸는 구현과 통합은 책임자를 하나로 두는 편이 안전합니다. AGENTS.md와 커스텀 에이전트와 권한 설정은 이 경계를 반복 가능하게 만들고, Worktree는 파일 수준의 충돌을 줄여 줍니다. 마지막으로 테스트와 리뷰가 결과를 증명할 때 병렬 실행은 흥미로운 데모를 넘어 실제 개발 방법이 됩니다.
병렬 에이전트를 처음 도입하는 팀은 읽기 전용 조사부터 시작하면 됩니다. 그다음에는 구현 에이전트 한 명과 독립 리뷰어 한 명을 붙여 작은 검증 루프를 운영해 볼 수 있습니다. 운영 과정에서 대기와 충돌이 줄고 검증 증거가 선명해진다면 그때 동시성을 조금씩 늘리면 됩니다. 좋은 병렬 시스템은 많은 에이전트가 바쁘게 움직이는 모습보다, 필요한 결과가 예측 가능한 형식으로 돌아오는 모습에 가깝습니다.
공식 참고 자료
- Codex CLI
설치, 로그인, 기본 명령과 터미널 작업 방식은 이 페이지에서 최신 내용을 확인할 수 있습니다. - Subagents
활성화 상태, 위임 방법, 커스텀 에이전트 스키마, 동시성, 모델과 권한 동작을 설명합니다. - Custom instructions with AGENTS.md
전역과 프로젝트 지침의 탐색 순서, override, 계층 적용 방식을 설명합니다. - Config basics
사용자와 프로젝트 설정 위치, 우선순위, 승인과 sandbox 기본값을 설명합니다. - Config reference
병렬 에이전트 동시성 필드를 포함한 현재 TOML 설정 키와 허용값을 설명합니다. - Models
Codex 모델별 권장 용도와 추론 강도를 선택할 때 고려할 기준을 설명합니다. - Permissions
승인 정책, sandbox, 베타 권한 프로필의 구성 방식과 주의점을 설명합니다. - Git Worktrees
Codex 데스크톱 앱에서 Worktree를 만들고 Local과 Handoff하는 흐름을 설명합니다.
'AI 활용' 카테고리의 다른 글
| Hermes Agent를 Mac Mini에서 효율적으로 운영하기 (0) | 2026.05.01 |
|---|---|
| Atomic Hermes - 터미널없이 시작하는 간단한 에이전트 (0) | 2026.04.27 |
| Hermes Agent - AI 에이전트를 활용한 생활 속 자동화 (0) | 2026.04.27 |
| NemoClaw를 라즈베리파이 5에 설치하고 운영하기 (0) | 2026.03.24 |
| NVIDIA - NemoClaw 설치부터 활용까지 (0) | 2026.03.24 |
