Codex CLI 비대화형(Headless) 실행 가이드 ㅡ codex exec와 JSON 스트림 파이프라인 구축

이 글에서 사용하는 주요 용어 정의

본격적인 아키텍처 설계와 설정 방법을 살펴보기에 앞서, 본문에서 핵심적으로 다루는 개념들을 명확히 정리합니다.

용어정의

서브에이전트(Subagents)	메인 세션과 분리된 독립 컨텍스트 윈도우에서 특정 하위 작업을 전담하여 실행하고 최종 결과 요약만 보고하는 보조 에이전트
컨텍스트 오염(Context Bloat)	대규모 파일 검색 결과와 원시 터미널 로그가 단일 대화 세션에 누적되어 토큰 비용이 상승하고 모델의 추론 집중도가 저하되는 현상
도구 격리(Tool Isolation)	서브에이전트에 읽기 전용 도구만 부여하고 파일 수정 및 셸 실행 도구를 차단하여 코드베이스의 무단 변경을 방지하는 권한 제어 방식
모델 계층화(Model Tiering)	단순 탐색과 검색에는 경량·저비용 모델을, 복잡한 설계와 코드 작성에는 고성능 추론 모델을 나누어 배치하는 최적화 구성 전략
순차 체이닝(Sequential Chaining)	복잡한 개발 작업을 독립된 단일 책임을 가진 하위 에이전트들에 차례대로 넘겨가며 정제된 결과물을 이어받는 실행 패턴
중첩 서브에이전트(Nested Subagents)	상위 서브에이전트가 더 세분화된 하위 작업을 분할 처리하기 위해 내부에서 추가로 생성하여 실행하는 다계층 작업 구조

 

위 용어들은 다중 에이전트 기반의 개발 자동화 환경을 구축하고 대화 맥락의 효율성을 극대화하기 위한 핵심 기준입니다.

---

도입

수많은 디렉터리와 모듈로 구성된 대규모 모노레포나 복잡한 엔터프라이즈 소프트웨어 프로젝트에서 Claude Code를 운영하다 보면, 작업 세션이 길어질수록 모델의 응답 속도가 현저히 느려지고 토큰 소비가 가파르게 증가하는 문제를 마주하게 됩니다. 단일 대화 세션 안에서 프로젝트 전체의 디렉터리 순회, 파일 검색, 코드 문법 파싱, 아키텍처 설계, 실제 코드 수정에 이르기까지 모든 과정을 하나의 맥락에서 처리하기 때문입니다.

이러한 모놀리식 단일 세션 방식에서는 광범위한 파일 검색과 정규식 탐색 과정에서 수많은 원시 텍스트 로그가 메인 대화 세션의 컨텍스트 윈도우를 가득 채우게 됩니다. 결국 모델이 한 번에 기억할 수 있는 용량을 초과하여 세션 압축(Context Compaction)이 작동하게 되며, 이 과정에서 대화 초기에 사용자가 전달했던 핵심 비즈니스 로직 제약이나 아키텍처 설계 규칙이 뒤로 밀려나 유실되는 위험이 발생합니다.

이 글에서는 Claude Code의 커스텀 서브에이전트(Subagents) 기능을 활용하여 코드베이스 탐색과 구현 계획 수립을 독립된 세션으로 안전하게 격리하고, 메인 세션에는 정제된 핵심 요약만 반환하도록 설계하는 아키텍처를 소개합니다. 이를 통해 메인 대화 세션의 컨텍스트를 장시간 깨끗하게 보존하고 작업의 정확도를 안정적으로 유지할 수 있습니다. 본문에서 다루는 설정 문법과 기술 사양은 2026-09-25 기준 최신 공식 규격을 바탕으로 합니다.

 

> 핵심 요약 (Key Takeaways)
> - 컨텍스트 격리: 대규모 파일 검색과 코드 조사를 독립된 서브에이전트 세션으로 격리하여 메인 세션의 불필요한 토큰 누적과 조기 세션 압축을 효과적으로 예방합니다.
> - 도구 및 권한 통제: 탐색 전담 서브에이전트에는 Write, Edit, Bash를 명시적으로 차단하여 코드베이스의 무단 수정을 원천적으로 방지하는 읽기 전용 환경을 구축합니다.
> - 모델 별칭과 상속 체계: 최신 공식 규격의 모델 별칭(haiku, sonnet, inherit)을 적용하고, 내장 Explore의 모델 상속 동작과 목적에 맞는 커스텀 경량 모델 지정을 명확히 구분합니다.
> - 계층 및 통신 설계: 공식 문서가 보장하는 기본 최대 3계층 중첩 생성과 에이전트 간 메시지 전달 기능을 이해하고, 무한 루프 위험을 차단하는 순차 체이닝 패턴을 구현합니다.

 

---

배경과 동작 구조

Claude Code의 서브에이전트는 완전히 격리된 별도의 컨텍스트 윈도우(Isolated Context Window)에서 실행됩니다. 메인 세션에서 파일 수십 개를 직접 탐색하면 그 내용이 대화 기록에 고스란히 남아 누적되지만, 서브에이전트 내부에서 실행된 수많은 읽기 및 검색 작업은 해당 서브에이전트의 독립된 컨텍스트 안에서만 소비되고 소멸합니다.

서브에이전트 격리 및 데이터 반환 메커니즘

메인 대화 세션과 개별 서브에이전트가 상호작용하는 전체 작업 구조는 아래 도식과 같은 데이터 흐름으로 운영됩니다.

[ 메인 대화 세션 (Lead Orchestrator) ]
   │
   ├── (1) 탐색 위임 ─────────► [ 코드 탐색 서브에이전트 (haiku) ]
   │                              - 격리된 독립 컨텍스트 윈도우
   │                              - Read, Grep, Glob 도구만 실행
   │   ◄── (2) 요약 보고서 반환 ──┘ (정제된 파일 경로 및 핵심 심볼 요약)
   │
   ├── (3) 계획 수립 위임 ─────► [ 아키텍처 계획 서브에이전트 (sonnet) ]
   │                              - permissionMode: plan (읽기 전용 계획)
   │                              - 파일 간 영향도 분석 및 변경 순서도 작성
   │   ◄── (4) 구현 계획안 반환 ──┘ (단계별 작업 체크리스트 보고)
   │
   └── (5) 최종 코드 구현 및 검증 (메인 컨텍스트의 핵심 지침과 규격 유지)

 

서브에이전트가 맡은 작업을 완료하면 오직 정제된 최종 분석 요약(Summary)만 메인 대화 세션으로 전달됩니다. Anthropic Claude Code 공식 문서에 따르면, 각 서브에이전트의 구체적인 실행 기록은 메인 세션과 분리되어 로컬 디렉터리(~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl)에 독립적인 트랜스크립트 파일로 영구 보존됩니다. 따라서 메인 세션에서 장기 대화로 인해 압축이 일어나더라도 하위 에이전트가 수행했던 상세한 탐색 및 판단 로그는 손상되지 않고 언제든 감사 및 디버깅 목적으로 확인할 수 있습니다.

설정 파일 위치와 계층별 우선순위

서브에이전트는 마크다운(.md) 파일로 정의되며, 팀 협업 환경과 개인 작업 환경에 맞추어 유연하게 배치할 수 있습니다. Claude Code는 다양한 환경 설정을 지원하기 위해 5단계의 엄격한 우선순위 규칙을 따릅니다.

1. 명령줄 실행 옵션 (CLI Flags): 실행 시점에 사용자가 직접 전달하는 최상위 인자
2. 관리형 설정 (Managed / Organization Policies): 엔터프라이즈 환경 또는 조직 차원에서 보안을 위해 강제하는 전역 정책
3. **프로젝트 레벨 (.claude/agents/*.md): 현재 작업 저장소 전용으로 정의되며 Git을 통해 팀원들과 형상 관리를 공유하는 설정
4. 사용자 전역 레벨 (~/.claude/agents/*.md): 개발자의 개인 로컬 환경 전체에서 모든 프로젝트에 공통으로 적용되는 설정
5. 플러그인 설정 (Installed Plugins)**: 외부 확장 도구나 커뮤니티 패키지를 통해 제공되는 기본 서브에이전트 설정

동일한 식별자를 가진 서브에이전트가 여러 위치에 정의되어 있다면 상위 우선순위의 설정이 하위 설정을 덮어씁니다. 예를 들어 사용자 전역 레벨에 정의된 code-explorer가 있더라도 현재 프로젝트 루트의 .claude/agents/code-explorer.md가 존재한다면 프로젝트 전용 설정이 우선 적용됩니다. 따라서 팀 전체가 공유해야 하는 저장소 아키텍처 규칙은 프로젝트 레벨에 저장하고, 개인적인 단축 명령이나 보조 도구는 사용자 전역 레벨에 배치하는 것이 바람직합니다.

내장 에이전트와 커스텀 에이전트의 모델 동작 차이

Claude Code는 기본적으로 Explore와 Plan 같은 내장 서브에이전트를 제공합니다. 여기서 많은 개발자들이 간과하기 쉬운 부분이 바로 내장 Explore 에이전트의 모델 상속 동작입니다. 버전 2.1.198 이후의 현행 공식 규격에서 내장 Explore는 무조건 경량 모델인 Haiku로 고정되어 실행되는 것이 아니라, 메인 대화 세션의 활성 모델을 그대로 상속(inherit)받아 동작합니다.

만약 메인 대화 세션이 고성능 추론 모델을 사용하고 있다면, 내장 탐색 도구를 호출했을 때도 동일한 고성능 모델이 호출되어 단순 탐색 작업에 불필요하게 높은 비용과 지연이 발생할 수 있습니다. 반면 본 가이드에서 다루는 커스텀 서브에이전트를 직접 정의하면 model: haiku처럼 가벼운 모델 별칭을 명시적으로 강제할 수 있어, 반복적이고 광범위한 파일 탐색 작업을 빠르고 경제적으로 분리 실행할 수 있습니다.

---

핵심 내용: 탐색과 계획의 분리 아키텍처

안정적인 다중 에이전트 개발 환경을 구축하기 위해 에이전트의 책임을 세 단계로 나누는 3계층 아키텍처를 설계합니다. 탐색(Explorer), 계획(Planner), 실행(Lead Orchestrator)을 분리하여 각 단계에 최적화된 도구 권한과 모델을 할당합니다.

 

 

1계층: 코드베이스 탐색 전담 에이전트 (Explorer)

코드베이스 탐색은 대량의 소스 코드를 읽고 검색해야 하므로 컨텍스트 소모량이 매우 큽니다. 그러나 고난도의 시스템 아키텍처 추론 능력을 필요로 하지는 않으므로, 읽기 전용 도구와 경량 모델 별칭인 haiku를 결합하여 구성하는 것이 가장 효율적입니다.

프로젝트 루트의 .claude/agents/code-explorer.md 파일에 아래와 같이 작성합니다.

> ※ 아래 설정은 공식 문서를 기반으로 한 미검증 예제 코드이며, 프로젝트 환경 및 CLI 버전에 따라 지원되는 모델 식별자나 세부 옵션이 다를 수 있습니다.

---
name: code-explorer
description: 코드베이스에서 관련 파일, 함수 정의, 모듈 구조를 검색하고 맵핑할 때 호출합니다.
tools:
  - Read
  - Grep
  - Glob
disallowedTools:
  - Write
  - Edit
  - Bash
model: haiku
---

당신은 코드베이스 탐색 전담 서브에이전트입니다.

### 작업 지침
1. Read, Grep, Glob 도구만 사용하여 요청받은 파일 경로와 심볼 위치를 신속하게 추적합니다.
2. 발견한 파일의 전체 소스 코드를 불필요하게 출력하지 마십시오.
3. 정확한 파일 경로, 관련 라인 번호, 3~5줄 내외의 핵심 인터페이스 요약만 보고서로 반환합니다.
4. 코드 수정이나 임의의 셸 명령어 실행은 권한상 허용되지 않으므로 시도하지 마십시오.

위 설정에서 주목할 점은 disallowedTools에 Write와 Edit뿐만 아니라 Bash까지 명시적으로 지정했다는 사실입니다. 만약 셸 실행 권한이 열려 있다면 파일 수정 도구가 없더라도 셸 스크립트나 터미널 명령어를 통해 파일이 변경될 위험이 있으므로, 완전한 읽기 전용 보안을 위해 셸 도구도 함께 차단해야 합니다.

또한 실무 프롬프트 지침에서 Glob을 통한 디렉터리 구조 파악 후 Grep으로 핵심 심볼을 좁혀가도록 유도하면, 서브에이전트의 자체 컨텍스트 윈도우마저도 절약되어 훨씬 빠르고 정확한 파일 경로 목록을 얻을 수 있습니다.

2계층: 아키텍처 계획 수립 에이전트 (Planner)

탐색 에이전트가 찾아낸 정보를 바탕으로 실제 코드 변경 계획과 영향도 분석을 수행하는 단계입니다. 이 작업은 시스템 아키텍처 전반의 의존성과 사이드 이펙트를 면밀히 검토해야 하므로 높은 논리적 추론력이 요구됩니다. 따라서 고성능 모델 별칭인 sonnet을 지정하고, 권한 모드를 계획 수립 전용인 plan으로 설정합니다.

프로젝트 루트의 .claude/agents/code-planner.md 파일에 다음 설정을 저장합니다.

> ※ 아래 설정은 공식 문서를 기반으로 한 미검증 예제 코드이며, 실제 적용 시 조직의 보안 정책과 프로젝트 구조를 고려하여 점검하시기 바랍니다.

---
name: code-planner
description: 새로운 기능을 구현하거나 대규모 리팩터링을 진행하기 전 영향도 분석과 단계별 구현 계획을 세울 때 사용합니다.
tools:
  - Read
  - Grep
disallowedTools:
  - Write
  - Edit
model: sonnet
permissionMode: plan
---

당신은 소프트웨어 아키텍트이자 구현 계획 수립 서브에이전트입니다.

### 작업 지침
1. code-explorer가 제공한 파일 경로와 기존 코드베이스 구조를 바탕으로 구현 방안을 검토합니다.
2. 변경이 필요한 대상 파일 목록과 파일별 예상 수정 범위를 단계별 체크리스트 형식으로 작성합니다.
3. 데이터 흐름의 변화, 기존 API와의 하위 호환성, 발생 가능한 부작용을 사전에 분석하여 명시합니다.
4. 단위 테스트 및 통합 테스트 작성 전략을 함께 수립하여 변경의 안전성을 보장합니다.
5. 직접 소스 코드를 작성하거나 수정하지 않으며, 검증 가능한 논리적 구현 계획서만 작성하여 반환합니다.

이 에이전트는 permissionMode: plan 설정 덕분에 코드 변경 권한 없이 오직 아키텍처 분석과 작업 순서 정의에만 집중할 수 있습니다. 계획 단계에서 잠재적 사이드 이펙트와 테스트 방안을 사전에 명시하도록 지침을 설계하면 실제 구현 단계에서의 시행착오를 크게 줄일 수 있습니다.

3계층: 메인 에이전트의 실행 조율 및 상호작용 규격

메인 대화 세션은 최상위 오케스트레이터로서 하위 에이전트들을 호출하여 협업을 조율합니다. Anthropic Claude Code 커스텀 서브에이전트 가이드의 최신 규격에 따르면, Claude Code의 서브에이전트는 단순히 메인 세션과 단방향으로만 통신하는 데 그치지 않고 더욱 유연한 다계층 협업 기능을 지원합니다.

1. 기본 최대 3계층 중첩 생성 지원 (Nested Subagents):
메인 대화 세션 하위에서 호출된 서브에이전트는 필요에 따라 추가적인 하위 작업을 분담하기 위해 또 다른 서브에이전트를 생성할 수 있으며, 시스템 기본적으로 최대 3계층(3 levels of nesting)까지 중첩 생성이 허용됩니다. 예를 들어 상위 기획 에이전트가 하위의 데이터베이스 분석 에이전트를 호출하고, 그 에이전트가 다시 특정 쿼리 파싱 에이전트를 호출하여 단계별 세부 조사를 완수하게 할 수 있습니다.
2. 에이전트 간 메시지 전달 (Message Passing):
현재 공식 규격은 실행 중인 에이전트들 사이에서 메시지를 직접 주고받는 상호작용 메커니즘을 지원합니다. 따라서 모든 소통이 무조건 메인 세션만을 거쳐야 하는 것은 아니며, 정의된 에이전트 간의 연결을 통해 필요한 문맥을 직접 전달하고 협력 작업을 수행할 수 있습니다.
3. 순차 체이닝 패턴의 권장 (Sequential Chaining):
이러한 다계층 중첩 생성과 메시지 전달이 기술적으로 가능하더라도, 실무 프로젝트에서는 통제 불가능한 에이전트 호출 루프나 토큰 과소비를 방지하기 위해 엄격한 종료 조건을 갖춘 순차 체이닝(탐색 → 계획 → 구현)을 유지하는 것이 권장됩니다. 메인 오케스트레이터가 탐색 결과를 받아 계획 에이전트에 넘기고, 최종 계획안을 확인한 후 메인 세션이 직접 구현과 테스트를 주도하는 흐름이 가장 안전하고 예측 가능합니다.
4. 결과 보고 포맷의 표준화:
체이닝 과정에서 하위 에이전트들이 반환하는 결과 양식을 마크다운 헤더나 체크리스트 형식으로 명확히 규격화해 두면, 다음 단계 에이전트나 메인 오케스트레이터가 내용을 파싱하고 이해하는 데 소모되는 불필요한 추론 토큰을 크게 아낄 수 있습니다.

CLI 환경에서 /agents 명령어를 입력하면 현재 등록된 모든 서브에이전트의 목록과 상태를 한눈에 확인할 수 있습니다. 또한 작업이 진행되는 동안 /tasks 명령어를 실행하면 백그라운드에서 동작 중인 서브에이전트들의 실행 트리 뷰와 진행 상태를 실시간으로 점검할 수 있습니다.

---

실제 적용 효과와 운영 시 주의사항

탐색과 계획을 분리한 3계층 구조를 적용했을 때 얻을 수 있는 구조적 이점과 실무 환경에서 주의해야 할 핵심 한계점을 살펴봅니다.

 

단일 세션 방식과 3계층 서브에이전트 분리 방식 비교

아래 표는 단일 세션에 모든 작업을 맡기는 모놀리식 방식과 서브에이전트를 도입한 분리 방식의 구조적 특성을 객관적으로 비교한 결과입니다.

비교 항목단일 세션 모놀리식 방식3계층 서브에이전트 분리 방식

메인 세션 데이터 누적	파일 검색 결과와 원시 텍스트 로그 전체가 메인 세션에 누적되어 급격한 컨텍스트 팽창 유발	하위 에이전트가 격리된 공간에서 작업한 뒤 정제된 최종 요약 보고서만 전달하여 세션 청결 유지
컨텍스트 압축 위험	대화가 길어질수록 조기 세션 압축(Compaction)이 발생하여 초기에 설정한 시스템 지침과 비즈니스 규칙 유실 가능	대량의 탐색 데이터가 메인 세션을 거치지 않으므로 장기 세션에서도 핵심 프롬프트와 지침 온전히 보존
모델 자원 및 비용 효율	단순 정규식 검색과 디렉터리 순회에도 메인 세션의 고성능 모델 자원이 소모되어 비효율적	파일 탐색에는 가벼운 Haiku 모델 별칭을, 아키텍처 계획에는 고추론 Sonnet을 분리 배치하여 비용 최적화
코드베이스 변경 안전성	정보 탐색 도중 모델의 오작동이나 착오로 인해 원치 않는 소스 코드가 수정될 위험 상존	disallowedTools를 통해 쓰기(Write/Edit)와 셸(Bash)을 차단하여 강력한 읽기 전용 무결성 확보
작업 감사 및 추적성	세션 압축 발생 시 이전의 상세 탐색 과정과 판단 근거를 다시 추적하기 어려움	서브에이전트별 독립 트랜스크립트 JSONL 파일이 로컬 디렉터리에 영구 보존되어 사후 감사 용이

운영 시 주의해야 할 3대 원칙

첫째, 셸 실행 도구(Bash)의 차단 필수성입니다. 서브에이전트 설정에서 Write와 Edit 도구를 금지하더라도 Bash 도구가 허용되어 있다면 cat, sed, echo 같은 터미널 명령어 리다이렉션을 통해 파일이 수정될 수 있습니다. 따라서 안전한 읽기 전용 탐색 에이전트를 구성할 때는 반드시 Bash 도구를 차단 목록에 포함해야 합니다.

둘째, 중첩 계층 제한과 명확한 종료 조건 수립입니다. Claude Code는 기본 최대 3계층까지 중첩 서브에이전트 생성을 지원하지만, 하위 에이전트가 또 다른 에이전트를 연쇄적으로 호출하는 과정에서 종료 조건이 불분명하면 작업 지연이나 불필요한 토큰 낭비가 발생할 수 있습니다. 각 에이전트 프롬프트에 구체적인 반환 데이터 규격과 단일 책임 범위를 명시하여 불필요한 중첩 확장을 방지해야 합니다.

셋째, 에이전트 설명문(Description)의 토큰 관리입니다. 등록된 모든 서브에이전트의 description 필드는 메인 오케스트레이터가 작업을 위임할 대상을 판단하기 위해 항상 컨텍스트에 로드됩니다. 공식 문서에 명시된 대로 전체 서브에이전트의 description 토큰 합계가 15,000 토큰을 넘지 않도록, 호출 목적과 역할만 1~2문장의 간결한 문구로 작성하고 상세한 지침은 마크다운 본문에 기술해야 합니다.

> ※ 본문에 소개된 설정 파일 예제는 공식 사양을 기반으로 작성된 가이드라인 예시이며, 실제 배포 전 프로젝트의 개발 환경과 도구 권한 요구사항에 맞춰 사전 검증을 권장합니다.

---

마무리

Claude Code에서 커스텀 서브에이전트를 체계적으로 설계하는 것은 단순한 편의성 개선을 넘어, 복잡한 대규모 프로젝트를 안정적으로 유지하기 위한 필수적인 아키텍처 전략입니다.

코드베이스 탐색(Explorer)과 아키텍처 계획(Planner)을 메인 대화 세션에서 격리하고 정제된 요약 보고서만 수합함으로써, 빈번한 세션 압축으로 인한 비즈니스 로직 유실 위험을 구조적으로 방지할 수 있습니다. 여기에 가벼운 모델 별칭(haiku)과 고성능 모델(sonnet)을 적재적소에 배치하는 모델 계층화를 결합하면 작업의 속도와 경제성을 동시에 확보할 수 있습니다.

지금 진행 중인 프로젝트 루트에 .claude/agents/ 디렉터리를 만들고, 앞서 소개한 code-explorer.md 설정을 추가하여 첫 번째 읽기 전용 탐색 에이전트를 가동해 보시기 바랍니다. 작은 역할 분리 하나만으로도 훨씬 쾌적하고 안정적인 AI 페어 프로그래밍 환경을 체감하실 수 있을 것입니다.

---

참고 자료

• Anthropic Claude Code 공식 문서 : Claude Code 아키텍처 개요, 도구 권한 체계 및 기본 실행 사양
• Anthropic Claude Code 커스텀 서브에이전트 가이드 : 커스텀 서브에이전트 구성 스펙, 모델 별칭, 중첩 계층 및 체이닝 공식 가이드