스프쌤
AI엔지니어링

Claude Code와 Codex를 묶는 하네스 팀 프롬프트 설계

✍ 야금야금⏱ 18분 소요2026-10-31👁
← 목록으로 돌아가기

단일 프롬프트에 아무리 긴 지시문을 쏟아부어도 복잡한 프로덕션 코드베이스에서 테스트를 통과하지 못하는 이유는 무엇일까요?

✦ AI Key Summary & Global Takeaways

이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.

✦ KR 주제: Claude Code 및 Codex 기반 하네스 팀 아키텍처

✦ KR 핵심 요약: 단일 AI 코딩 에이전트에 작업을 위임할 때 발생하는 환각과 맹점을 제어하기 위해 5인 가상 하네스 팀과 독립 검수 체계를 구축해야 합니다. 각 에이전트의 벤치마크 특성에 맞추어 실행과 리뷰를 분리하고, 실패 로그를 공용 스킬 파일로 누적하면 자동화 신뢰도가 비약적으로 향상됩니다.

🌐 Global Takeaway: Single-agent LLM coding workflows often suffer from compounding errors and cognitive biases during large refactoring tasks. By orchestrating a harness team that decouples execution from obsessive auditing and persisting failures into shared skill specifications, developers achieve high-assurance automation across Claude Code and OpenAI Codex.

아래 그림은 단일 에이전트의 즉각 실행 방식과 5인 하네스 검수 팀 구조의 작업 흐름 차이를 보여줍니다.

단일 에이전트 방식 vs 5인 하네스 팀 구조
단일 에이전트 방식
  • 단일 컨텍스트 프롬프트 의존
  • 오류 누적 후 전체 작업 재시도
  • 자가 검증 시 확증 편향 발생
VS
5인 하네스 팀 구조
  • 기획·구현·검수 역할 분리
  • 단계별 결과물 독립 검증
  • 실패 로그 기반 공용 스킬 동기화
단일 에이전트의 즉시 실행 방식과 다중 에이전트 승인 루프 방식의 구조적 차이입니다.
에이전트 하네스 계층 스택
검수 계층엄격한 기준의 테스트 통과 여부 및 린트 검증
실행 계층Claude Code 및 Codex 터미널 CLI 엔진 구동
지침 계층CLAUDE.md 및 AGENTS.md를 통한 프로젝트 규칙 주입
환경 계층로컬 터미널 환경 및 서브 프로세스 제어
실행 계층부터 규칙 파일, 검수 엔진으로 이어지는 아키텍처 계층입니다.

🚨 1. 터미널 AI 에이전트의 한계와 실무 현장의 페인포인트

최근 소프트웨어 개발 현장에서는 개발자가 직접 코드를 한 줄씩 타이핑하는 대신 터미널 환경에서 실행되는 AI 에이전트를 적극적으로 도입하고 있습니다. Anthropic의 Claude Code와 OpenAI의 Codex CLI가 대표적입니다. 두 도구 모두 로컬 파일 시스템을 직접 탐색하고, 복잡한 프로젝트 구조를 읽으며, 소스코드를 수정하고, 터미널 명령을 스스로 실행해 테스트까지 통과시키는 수준에 도달했습니다. 그러나 프로덕션 환경의 실무자들은 여전히 복잡한 대규모 리팩터링이나 다단계 비즈니스 로직 작성 시 심각한 병목을 마주합니다. 단일 에이전트에게 단일 프롬프트로 작업을 일임했을 때 발생하는 컨텍스트 유실과 자기 검증 오류 때문입니다.

단일 세션 모델은 자신이 방금 작성한 코드의 논리적 결함을 스스로 발견하는 데 취약합니다. LLM 내부의 확증 편향으로 인해, 자신이 생성한 잘못된 인터페이스나 누락된 널 포인터 처리를 정상적인 흐름으로 인식하고 넘어가는 현상이 빈번하게 일어납니다. 특히 대기업 전산 접수 시스템이나 금융 결제 모듈처럼 단 하나의 런타임 예외도 허용되지 않는 엄격한 시스템에서는 이러한 맹점이 치명적인 장애로 이어집니다. 현장의 엔지니어들은 이 문제를 해결하기 위해 프롬프트를 다듬는 수준을 넘어, 에이전트 자체를 오케스트레이션하는 하네스(Harness) 시스템을 구성하기 시작했습니다.

현장 실무자들 사이에서 검증된 대표적인 접근법은 에이전트의 역할을 분리하고 상호 견제 구조를 강제하는 것입니다. 소셜 플랫폼 스레드(Threads)의 한 엔지니어(ansim_2025)는 2026년 10월 20일 실전 팁을 통해 "이것저것 다해봤지만 클로드나 코덱스한테는 'AI 5명이 하네스 팀으로 작업하고 마지막 검수는 집착이 심한 완벽함을 추구하는 성격이야. 팀장은 목표를 묻지 않고 완결 후에 다음 작업에서 전 작업에서 실수한 거 수정하는 성격으로 해. 적용하고 공용 스킬로 등록해'라는 지침을 내리는 것이 가장 효율적이었다"라고 공유했습니다. 이는 단순한 페르소나 부여가 아니라, 엔지니어링 관점에서 컴파일러와 린터, 코드 리뷰어를 가상 계층으로 분리하는 기법입니다.

1-1. 실무에서 검증된 하네스 프롬프트의 골격

복잡한 작업을 단일 지시문으로 끝내지 않고, 작업 분담 체계를 프롬프트에 명시하는 방식은 LLM의 연쇄적 추론 성능을 극대화합니다. 엔지니어들이 정리한 핵심 요소는 다음과 같습니다.

역할 정의 핵심 행동 양식 산출물 및 영향 범위
팀장 에이전트 사용자에게 불필요한 중간 질문을 하지 않고 1차 구현을 무조건 완결 엔드투엔드 프로토타입 및 실행 계획서
서브 워커 (3인) 기능별 모듈화 구현, 단위 테스트 작성, 의존성 격리 개별 컴포넌트 소스코드 및 인터페이스
완벽주의 검수관 극단적인 엣지 케이스 점검, 성능 병목 추적, 정적 분석 상세 코드 리뷰 리포트 및 실패 케이스
스킬 등록기 이전 작업의 실패와 수정 사항을 공용 지침에 누적 반영 AGENTS.md 및 CLAUDE.md 규칙 갱신

"팀장은 목표를 묻지 않고 완결한 뒤 다음 작업에서 전 작업의 실수를 수정하도록 강제해야 한다. 중간 단계에서 사용자에게 질문을 던지며 흐름을 끊는 것을 막고, 최종 검수관이 비타협적으로 결함을 찾아내게 만드는 것이 하네스 엔지니어링의 핵심이다."

🛠️ 2. 하네스 아키텍처의 원리와 규칙 파일 동작 메커니즘

하네스 팀 구조가 유의미하게 작동하기 위해서는 각 에이전트가 공유하는 프로젝트 컨텍스트와 규칙 엔진이 백그라운드에 명확히 정의되어 있어야 합니다. 터미널 기반 도구인 Claude Code와 Codex는 프로젝트 루트 디렉터리에 위치한 지침 파일을 기본 컨텍스트로 불러와 실행 컨텍스트에 주입합니다. Claude Code는 CLAUDE.md를 우선적으로 읽으며, 파일이 없을 경우 AGENTS.md를 참조합니다. Codex 역시 AGENTS.md를 기본 규칙 파일로 인식하여 프로젝트 전반의 컨벤션과 에이전트 역할을 파악합니다.

이러한 구조에서 '공용 스킬'로 등록한다는 의미는 에이전트가 한 번 범한 실수나 프로젝트 고유의 예외 처리 패턴을 이 지침 파일에 명시적 룰셋으로 영속화하는 것을 뜻합니다. 만약 데이터베이스 커넥션 풀을 해제하지 않아 메모리 누수가 발생했다면, 검수 에이전트가 이를 지적한 후 스킬 등록 계층이 AGENTS.md에 "모든 DB 세션은 명시적인 try-finally 블록 또는 컨텍스트 매니저를 통해 즉시 닫아야 한다"는 규칙을 추가합니다. 이렇게 등록된 규칙은 다음 세션에서 Claude Code나 Codex가 구동될 때 시스템 프롬프트의 일부로 로드되어 동일한 실수를 사전에 차단합니다.

5인 하네스 팀 구조는 실제로 모델을 5개 동시에 띄우는 복잡한 인프라가 없더라도, 단일 터미널 세션 내부의 서브에이전트(Sub-agent) 디스패치 기능과 다단계 추론(Multi-turn reasoning)을 통해 구현됩니다. Claude Code와 Codex 모두 내부적으로 툴 유즈(Tool Use)와 서브 프로세스 실행 권한을 가지고 있으므로, 메인 에이전트가 서브 태스크를 쪼개어 가상 워커에게 할당하고 최종적으로 검수 프롬프트를 통과시키는 워크플로우를 스스로 구축할 수 있습니다.

2-1. 지침 파일 자동 연동 표준화

프로젝트 루트에 에이전트 지침을 구성할 때는 환경별 차이를 고려해야 합니다. 팀 프로젝트 환경에서는 양대 도구 모두와 호환되도록 표준 파일을 관리하는 것이 유리합니다.

# 프로젝트 루트에 공용 에이전트 지침 파일 생성 및 심볼릭 링크 연결
touch AGENTS.md
ln -s AGENTS.md CLAUDE.md

위 명령을 통해 두 에이전트가 동일한 규칙 소스를 바라보도록 설계할 수 있습니다. 이를 통해 Claude Code에서 검수관이 수정한 지침이 Codex CLI 작업 시에도 누락 없이 즉각 반영되는 상호 운용성을 확보하게 됩니다.

📊 3. Claude Code와 Codex의 벤치마크 및 토큰 효율 수치 비교

하네스 팀을 설계할 때 중요한 의사결정 기준은 어떤 모델을 '실행 워커'로 두고 어떤 모델을 '검수관'으로 배치할 것인가입니다. Anthropic의 Claude Opus 4.6(및 이후 버전)과 OpenAI의 Codex 5.3(및 GPT 계열)은 추론 특성과 리소스 소비 패턴에서 뚜렷한 대비를 보입니다. 벤치마크와 실사용 환경에서 집계된 성능 지표를 분석하면 두 도구의 배치 전략이 명확해집니다.

실전 터미널 제어 능력을 측정하는 대표적인 벤치마크인 NxCode 분석(2026) 기준 Terminal-Bench 2.0에서 Codex 5.3은 77.3%의 높은 성공률을 기록하여 Claude Opus 4.6(65.4%)을 11.9%포인트 앞섰습니다. 반면 실제 오픈소스 저장소의 버그를 해결하는 능력을 평가하는 SWE-bench Verified에서는 Claude Opus 계열이 복잡한 코드 문맥 파악과 전체적 리팩터링 품질에서 리딩하는 것으로 나타났습니다. 컨텍스트 윈도우 지원에 있어서도 큰 차이가 존재합니다. Opus는 최대 1M 토큰의 컨텍스트를 지원하여 대규모 레거시 파일 전체를 한 번에 검토할 수 있는 반면, Codex는 256K 토큰을 지원합니다. 대규모 컨텍스트 회상 능력을 평가하는 MRCR v2 테스트에서 Opus가 76%를 기록한 배경입니다.

Terminal-Bench 2.0 성능 비교
Codex 5.3
77.3%
Claude Opus 4.6
65.4%
터미널 환경 작업 해결율 벤치마크 수치 비교입니다.

가격과 구독 정책에 따른 토큰 소진 양상도 고려해야 합니다. Claude Pro와 ChatGPT Plus는 모두 개인용 플랜 기준 월 $20 선에서 시작하지만, 헤비 유저를 위한 월 $200 고성능 구독 플랜에서 두 도구의 사용량 한도는 완전히 다르게 작동합니다. t3.gg의 개발자 Theo의 실전 분석과 커뮤니티 데이터에 따르면, Codex는 월 $200 구독 플랜에서 주간 한도가 매우 관대하여 하루 종일 고강도 작업을 수행해도 주간 한도의 8~16%만 소진되었습니다. 한 사용자는 Codex 구독을 통해 13억 토큰 이상을 처리했음에도 한도의 60%를 넘지 않았습니다.

반면 Claude Code는 심층적인 다단계 리뷰 작업을 한 번 수행하는 것만으로도 4시간 할당량의 3%가 즉각 차감되는 등 컨텍스트 소비량이 매우 공격적입니다. API 비용 측면에서도 Opus 4.6은 200K 이하 기준 입력 $5/M 토큰, 출력 $25/M 토큰 수준이며, 복잡한 마이그레이션 작업 한 번에 수십 달러의 API 비용이 청구되기도 합니다. 반면 Codex 5.2 기준 이전 API 가격은 입력 $1.75/M, 출력 $14/M 수준으로 더 경제적이었습니다. 따라서 코드베이스를 집요하게 파고들며 오류를 끝까지 물고 늘어지는 '검수관'이나 반복적 린트 작업에는 토큰 효율과 터미널 제어력이 높은 Codex를, 대규모 문맥을 조망하며 초기 아키텍처를 잡고 코드를 일괄 생성하는 '팀장'에는 Claude Opus를 배치하는 교차 검증 전략이 최적의 효율을 보장합니다.

3-1. 두 도구의 핵심 사양 및 라이선스 비교

실무 배포 전 각 도구의 인터페이스 지원과 기본 모델을 교차 검토해야 합니다. 2026년 기준 두 엔진의 세부 스펙은 아래와 같이 정리됩니다.

비교 항목 Claude Code (Anthropic) Codex (OpenAI)
기본 기반 모델 Claude Opus 권장 GPT-6.1 Sol / Luna 계열
기본 컨텍스트 창 1M 토큰 지원 256K 토큰 지원
Terminal-Bench 2.0 65.4% 77.3%
개인 진입 가격 Pro 월 $20 (연간 결제 시 월 $17) Free $0 (데스크톱 앱), Plus 월 $20
CLI 및 IDE 지원 터미널 CLI, VS Code, JetBrains 터미널 CLI, IDE 확장, Codex Cloud
기본 지침 파일 CLAUDE.md (대체: AGENTS.md) AGENTS.md

🔄 4. 5인 하네스 팀 구축과 실패 피드백 루프 실전 적용

하네스 팀 아키텍처의 핵심은 질문 없는 실행과 가혹한 사후 검수, 그리고 실패 기록의 지식화입니다. 일반적인 대화형 프롬프트에서는 AI가 모호한 요구사항을 만났을 때 즉시 사용자에게 추가 질문을 던지며 작업 컨텍스트를 중단시킵니다. 이는 자동화 파이프라인의 가장 큰 적입니다. 팀장 에이전트는 목표를 묻거나 확인하지 않고, 현재 주어진 코드베이스와 지침 파일을 기반으로 가설을 수립하여 어떻게든 동작 가능한 코드로 완결해야 합니다.

완결된 결과물은 즉시 두 번째 단계인 '완벽주의 검수관'에게 넘어갑니다. 검수관 에이전트는 작성된 코드의 긍정적인 면을 평가하지 않습니다. 오직 단위 테스트의 경계값 통과 여부, 타입 안정성, 동시성 이슈, SQL 인젝션 가능성 등 잠재적 장애 요인을 집착에 가깝게 찾아내는 임무를 수행합니다. 이 단계에서 테스트 실패나 린트 오류가 발생하면 작업은 사용자가 아닌 팀장에게 반환됩니다. 팀장은 질문 없이 이전 단계의 실패 로그만을 근거로 삼아 패치를 진행합니다.

하네스 피드백 루프
목표 완결팀장이 질문 없이 1차 코드베이스 산출 완료
결과물 검수완벽주의 검수관이 테스트 및 엣지 케이스 분석
수정안 반영이전 작업의 오류 지점을 분석하여 즉시 패치
스킬 동기화재발 방지 지침을 공용 AGENTS.md에 자동 추가
↻반복
결과물 완결 후 오류를 누적 학습하여 스킬로 등록하는 순환 체계입니다.

이러한 사이클이 성공적으로 종료되면 마지막 단계인 '스킬 동기화'가 시작됩니다. 검수관이 잡아낸 오류의 패턴과 팀장이 적용한 수정 기법은 요약되어 프로젝트의 AGENTS.md 파일에 새로운 룰로 기재됩니다. 이 과정이 반복될수록 프로젝트 저장소에는 시스템 특화 버그 패턴이 누적되며, 에이전트 팀 전체의 작업 완성도는 단일 프롬프트를 사용할 때와 비교할 수 없을 정도로 고도화됩니다.

4-1. 실제 터미널 환경에서의 실행 워크플로우

터미널에서 하네스 팀 프롬프트를 구동하기 위해 실제 CLI 세션에서 전달할 수 있는 구체적인 실행 명령은 다음과 같습니다. 프로젝트 규칙을 명시적으로 참조하도록 명령줄 인자를 구성합니다.

# Claude Code 터미널 환경에서 하네스 팀 지침을 즉시 주입하여 실행
claude --print -p "AGENTS.md 지침을 준수하여 5인 가상 하네스 팀 모드로 작업을 수행하라. 팀장은 질문 없이 결과물을 완결하고 검수관은 엄격하게 오류를 찾아내어 AGENTS.md에 재발 방지 스킬을 기록하라."
# Codex CLI 환경에서 교차 검증 및 테스트 실행 위임
codex exec "npm test && codex review --rule AGENTS.md"

위 명령을 통해 사용자의 개입 없이 에이전트가 자체적으로 하네스 규칙에 따라 빌드와 테스트, 코드 리뷰를 순차적으로 통과하도록 파이프라인을 자동화할 수 있습니다.

⚠️ 5. 하네스 오케스트레이션 도입 시 주의점과 한계

하네스 팀 기법이 뛰어난 코드 품질을 보장하지만, 실무에 도입하기 전에 반드시 고려해야 할 구조적 트레이드오프가 존재합니다. 가장 대표적인 문제는 토큰 소비량의 급격한 증가입니다. 단일 호출로 끝날 수 있는 단순 CRUD 작업에 5인 하네스 워크플로우를 강제 적용할 경우, 내부적으로 생성되는 검수 로그와 재시도 프롬프트로 인해 평소 대비 4배에서 8배 이상의 입력 및 출력 토큰이 소모됩니다. 월 $20 구독 플랜을 사용하는 경우 순식간에 4시간 또는 일일 사용량 상한선에 도달하여 세션이 잠길 위험이 있습니다.

또한 완벽주의 검수 페르소나가 지나치게 경직될 경우 '환각 기반의 무한 루프'에 빠질 수 있습니다. 정적 분석기나 컴파일러가 실제로 문제 삼지 않는 가상의 보안 위험이나 사소한 코드 스타일 차이를 검수관이 지속적으로 지적하고, 팀장이 이를 고치려다 다른 정상 로직을 깨뜨리는 퇴행(Regression) 현상이 발생할 수 있습니다. 이를 방지하기 위해서는 검수관의 평가 기준을 반드시 객관적인 기계 판정 도구(린터, 정적 분석 툴, 자동화된 단위 테스트 러너)의 종료 코드(Exit Code)와 연동해야 합니다. 주관적인 텍스트 평가가 아니라 실제 터미널 테스트 결과가 'PASS'를 반환하는지 여부를 검수의 절대적 기준으로 삼아야 합니다.

지침 파일인 AGENTS.md의 비대화 역시 주의해야 할 요소입니다. 실패가 발생할 때마다 필터링 없이 새로운 규칙을 파일 하단에 무한정 추가하면, 파일 크기가 수천 줄로 불어나 에이전트의 초기 시스템 프롬프트 용량을 과도하게 점유하게 됩니다. 컨텍스트가 너무 길어지면 오히려 에이전트가 초기에 작성된 핵심 규칙을 무시하는 어텐션 감쇠 현상이 나타납니다. 따라서 스킬 등록 에이전트에게 중복된 규칙을 통합하고 정기적으로 문서를 리팩터링하는 명시적 권한을 부여해야 합니다.

📋 6. 결론 및 실무 워크플로우 권장안

2026년 AI 코딩 도구의 생태계는 단일 모델의 단독 사용 시대에서 벗어나, 상호 보완적인 다중 모델과 하네스 아키텍처를 결합하는 방향으로 완전히 전환되었습니다. Terminal-Bench에서 압도적인 실행력을 입증한 Codex와, 방대한 문맥 이해력과 리팩터링 품질을 가진 Claude Code를 적재적소에 배치하는 것이 실무 생산성의 핵심입니다.

작업을 시작할 때는 이미 결제 중인 도구로 출발하되, 복잡한 비즈니스 로직을 다룰 때는 반드시 두 도구를 교차 검증 구조로 묶어야 합니다. Claude Code를 통해 초기 구현을 주도하고, Codex CLI를 통해 엄격한 코드 리뷰와 린트 검증을 수행하는 하네스 파이프라인을 구축하십시오. 실패한 경험을 지침 파일에 공용 스킬로 축적하는 시스템을 갖춘 개발자만이 LLM의 환각을 완벽히 통제하고 진정한 자동화의 가치를 누릴 수 있습니다.

자주 묻는 질문

Q. 하네스 팀 프롬프트를 사용할 때 왜 팀장은 질문하지 않아야 하나요?
A. 에이전트가 모호성을 이유로 중간에 사용자에게 질문을 던지면 비동기 자동화 파이프라인이 즉시 중단됩니다. 팀장이 일단 주어진 조건 내에서 끝까지 결과물을 완결 짓고, 이후 검수관이 실패 지점을 짚어내어 단계별로 패치하게 만드는 것이 컨텍스트 보존과 작업 속도 측면에서 훨씬 유리합니다.

Q. Claude Code와 Codex를 함께 쓸 때 설정 파일은 어떻게 공유하나요?
A. 프로젝트 루트에 `AGENTS.md` 파일을 생성한 뒤 심볼릭 링크(`ln -s AGENTS.md CLAUDE.md`)를 걸어 연결하면 됩니다. 두 도구 모두 해당 지침을 프로젝트 규칙으로 파싱하므로 일관된 스킬 셋을 유지할 수 있습니다.

Q. 토큰 비용을 아끼면서 하네스 구조를 적용하는 팁이 있나요?
A. 모든 가벼운 작업에 5인 구조를 적용하지 말고, 대규모 리팩터링이나 프로덕션 PR 검토 시에만 선택적으로 사용해야 합니다. 또한 초기 구현은 터미널 제어력이 높고 구독 가성비가 뛰어난 도구를 쓰고, 심층 리뷰나 거대 파일 분석에만 고성능 모델을 호출하는 분리 전략이 효과적입니다.

원본

https://www.threads.com/@ansim_2025/post/DeuXnxcj-wb

https://aicreatorlab.com/blog/claude-code-vs-codex

https://ourblogis.tistory.com/105

함께 보면 좋은 글

댓글 0개