Codex 5.6 제대로 쓰는 법 총정리: Sol·Terra·Luna 모델 배치부터 서브에이전트와 Context 압축 설정까지

GPT-5.6이 Codex에 들어오면서 모델을 선택하는 방식이 이전보다 복잡해졌다.

이제 단순히

가장 좋은 모델 하나를 선택한다.

로 끝나지 않는다.

Codex에서는 다음을 함께 결정해야 한다.

어떤 모델을 메인 Agent로 사용할까?

서브에이전트는 어떤 모델을 사용할까?

Reasoning Effort는 어느 정도가 적당할까?

병렬 Agent는 몇 개까지 띄울까?

Context 압축은 언제 일어나게 할까?

AGENTS.md에는 어디까지 적어야 할까?

Desktop 앱과 CLI 설정은 어떻게 나눌까?

2026년 8월 기준 Codex에서 사용할 수 있는 GPT-5.6 제품군은 다음과 같다.

GPT-5.6 Sol
→ 복잡한 계획·구현·검증을 담당하는 주력 모델

GPT-5.6 Terra
→ 속도·성능·비용의 균형이 좋은 작업 모델

GPT-5.6 Luna
→ 빠르고 범위가 명확한 반복 작업용 모델

Codex는 Main Agent와 Subagent의 모델을 다르게 설정할 수 있다.

그래서 다음과 같은 구조를 만들 수 있다.

Main Agent
GPT-5.6 Sol high

├── Code Explorer
│   GPT-5.6 Luna medium
│
├── Documentation Researcher
│   GPT-5.6 Luna medium
│
├── Reviewer
│   GPT-5.6 Terra high
│
└── Implementation Worker
    GPT-5.6 Terra medium

하지만 여기서 흔히 생기는 오해가 있다.

Sol을 Main으로 쓰고
Subtask는 Luna max로 돌리면
가장 효율적이지 않을까?

항상 그렇지는 않다.

Luna에 max Reasoning을 적용하면 빠르고 저렴한 모델을 선택한 장점이 줄어든다.

작업이 복잡해서 Luna가 max까지 생각해야 한다면, 차라리 Terra medium이나 high가 더 안정적인 경우가 많다.

실전에서는 보통 다음 구조가 더 현실적이다.

Main
Sol medium / high

일반 Worker
Terra medium

복잡한 Review
Terra high 또는 Sol high

빠른 탐색·문서 확인
Luna low / medium

최종 고난도 판단
Sol max

이번 글에서는 이 구성을 실제 Codex Desktop과 CLI에서 설정하는 방법부터 Context가 너무 자주 압축되는 문제를 줄이는 방법까지 정리한다.

1. 먼저 Codex를 최신 버전으로 맞춘다

GPT-5.6을 Codex에서 사용하려면 지원되는 버전 이상이어야 한다.

현재 안내 기준 최소 버전은 다음과 같다.

ChatGPT Desktop App Codex Mode

26.707.30751 이상

Codex CLI

0.144.0 이상

CLI 버전을 확인한다.

codex --version

업데이트한다.

codex --upgrade

npm으로 설치했다면 다음 방식도 사용할 수 있다.

npm install -g @openai/codex

Desktop 앱은 앱 메뉴의 업데이트 기능을 사용한다.

모델이 보이지 않는다면 먼저 다음을 확인한다.

Codex 버전

로그인 계정

ChatGPT 플랜

관리형 Workspace의 모델 정책

점진적 Rollout 여부

2. Codex 5.6 모델 선택 기준

GPT-5.6 Sol

다음 작업에 적합하다.

요구사항이 모호한 기능

여러 Module을 건드리는 변경

복잡한 Bug

Architecture 판단

긴 Tool Workflow

여러 Agent 결과 통합

대규모 Refactoring

최종 검증

Main Agent로 가장 무난하다.

Sol medium
→ 일반적인 복잡 작업

Sol high
→ 복잡한 구현과 Debugging

Sol max
→ 실패 비용이 크거나 매우 어려운 판단

처음부터 모든 작업에 max를 사용할 필요는 없다.

max는 응답 시간과 사용량이 늘어날 수 있다.

GPT-5.6 Terra

다음 작업에 잘 맞는다.

일반 기능 구현

테스트 작성

코드 리뷰

파일 여러 개의 구조 분석

UI 문제 재현

중간 난이도 Debugging

대량 코드 검토

Subagent 기본 모델로 가장 균형이 좋다.

Terra medium
→ 기본 Worker

Terra high
→ Reviewer / Debugger / Security 검사

GPT-5.6 Luna

다음처럼 범위가 좁고 결과가 명확한 작업에 적합하다.

파일 위치 찾기

호출 흐름 정리

문서 확인

반복적인 코드 분류

테스트 목록 수집

특정 Pattern 검색

로그 요약

대량 파일 Metadata 확인

추천 Effort는 보통 다음과 같다.

Luna low
→ 매우 단순한 반복 작업

Luna medium
→ 탐색·정리·문서 확인

Luna high
→ 좁지만 주의가 필요한 검토

Luna max를 기본 Subagent 설정으로 사용하는 것은 권하지 않는다.

좁고 명확한 작업이면 Luna medium으로 충분한 경우가 많다.

Luna가 긴 추론을 계속 요구한다면 작업을 Terra나 Sol로 올리는 편이 낫다.

3. 가장 현실적인 모델 조합

개인 개발자의 기본 구성

Main Agent
Sol high

Subagent Default
Terra medium

빠른 Explorer
Luna medium

Reviewer
Terra high

비용을 조금 더 줄이고 싶을 때

Main Agent
Sol medium

Subagent Default
Terra medium

Explorer
Luna low

Documentation
Luna medium

복잡한 Repository 작업

Planner / Coordinator
Sol high

Code Mapper
Luna medium

Implementation
Terra medium

Reviewer
Terra high

Final Integration
Sol high

중요한 Migration이나 보안 변경

Planning
Sol high

Parallel Exploration
Luna medium

Implementation
Terra high

Security Review
Sol high

Final Verification
Sol max

중요한 것은 모든 Agent에게 최고 모델을 배정하는 것이 아니다.

어려운 판단
→ Sol

일반 실행
→ Terra

빠른 조사
→ Luna

로 역할을 나누는 것이다.

4. Codex 기본 설정 파일 위치

사용자 전체에 적용되는 설정은 다음 파일에 둔다.

~/.codex/config.toml

프로젝트에만 적용할 설정은 Repository 안에 둔다.

.codex/config.toml

구조는 다음과 같다.

MyProject/
├── AGENTS.md
│
├── .codex/
│   ├── config.toml
│   └── agents/
│       ├── code-mapper.toml
│       ├── reviewer.toml
│       └── docs-researcher.toml
│
├── Sources/
└── Tests/

사용자 공통 설정은 ~/.codex/config.toml, 프로젝트 특화 Agent는 .codex/agents/에 두는 편이 관리하기 좋다.

5. 추천하는 기본 config.toml

처음에는 다음 정도로 시작할 수 있다.

model = "gpt-5.6-sol"
model_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

model_auto_compact_token_limit_scope = "body_after_prefix"

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"
interrupt_message = true

각 항목을 살펴보자.

model
→ Main Agent 기본 모델

model_reasoning_effort
→ Main Agent 기본 추론 수준

approval_policy
→ 언제 사용자 승인을 받을지

sandbox_mode
→ 파일 시스템 접근 범위

default_subagent_model
→ 별도 설정이 없는 Subagent 모델

default_subagent_reasoning_effort
→ Subagent 기본 추론 수준

병렬 Agent 숫자는 처음부터 크게 잡지 않는다.

2~4개
→ 개인 프로젝트에서 무난

4~6개
→ 독립적인 분석 Workstream이 많은 작업

8개 이상
→ 비용과 충돌 관리 필요

처음에는 4개 정도가 적당하다.

6. Sol Main + Terra Subagent를 기본으로 추천하는 이유

Main Agent는 다음 정보를 오래 유지한다.

사용자 요구사항

Architecture 제약

현재 Plan

중요한 결정

Subagent 결과

최종 수정 방향

따라서 Main Agent에는 강한 모델을 사용하는 편이 좋다.

Main
→ Sol

Subagent는 보통 범위가 더 좁다.

Auth Module만 분석

관련 Test만 찾기

공식 문서만 확인

Diff의 보안 문제만 검토

이런 작업에는 Terra가 충분한 경우가 많다.

Subagent
→ Terra

Luna는 더 좁게 쓴다.

파일 목록

Pattern 탐색

문서 검색

간단한 요약

이런 구조가 성능과 비용 사이의 균형이 좋다.

7. Subagent 기본값을 Luna로 둘 때

다음 프로젝트라면 Luna를 Subagent 기본값으로 두는 것도 가능하다.

대부분의 Subagent가 Read-only 탐색

반복적인 파일 분류가 많음

명확한 결과 형식이 있음

복잡한 판단은 Main Agent가 담당

설정:

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "medium"

다만 이 설정에서는 Main Agent에게 역할을 명확히 줘야 한다.

Subagent는 증거만 수집한다.

최종 판단은 Main Agent가 한다.

Subagent는 Architecture 결정을 내리지 않는다.

작업 범위를 좁혀야 한다.

8. Custom Agent 만들기

Codex는 다음 위치에서 Custom Agent를 읽는다.

개인 공통 Agent:

~/.codex/agents/

프로젝트 Agent:

.codex/agents/

각 Agent는 별도의 TOML 파일로 만든다.

9. Luna 기반 Code Mapper

.codex/agents/code-mapper.toml

name = "code_mapper"
description = "Read-only codebase explorer that finds relevant files and execution paths."

model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
Stay in exploration mode.

Find the files, symbols, and execution paths related to the assigned task.

Return:

- entry points
- important types and functions
- call flow
- evidence with file paths
- uncertainties

Do not modify code.
Do not propose broad refactors.
Do not return raw logs when a concise summary is sufficient.
"""

이 Agent는 코드 변경을 하지 않는다.

Main Agent Context에 다음 정도만 반환한다.

관련 파일

호출 흐름

의심 지점

근거

10. Terra 기반 Reviewer

.codex/agents/reviewer.toml

name = "reviewer"
description = "Reviewer focused on correctness, regression risk, concurrency, security, and missing tests."

model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Review the assigned diff as a code owner.

Prioritize:

1. correctness
2. behavior regression
3. concurrency
4. security
5. missing test coverage

Return concrete findings with file and symbol references.

Do not focus on style-only comments unless they hide a real defect.
Do not modify code.
"""

Reviewer는 Luna보다 Terra가 안정적인 경우가 많다.

코드 리뷰는 단순 검색이 아니라 다음을 판단해야 하기 때문이다.

이 변경이 실제 Bug인가?

기존 동작을 깨뜨리는가?

동시성 문제가 있는가?

테스트가 충분한가?

11. Luna 기반 문서 확인 Agent

.codex/agents/docs-researcher.toml

name = "docs_researcher"
description = "Documentation researcher for verifying APIs and version-specific behavior."

model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
Verify APIs, options, and version-specific behavior using approved documentation sources.

Return:

- confirmed behavior
- exact API or option name
- version caveats
- source references
- unresolved questions

Do not modify code.
Do not make unsupported assumptions.
"""

문서 검색과 API 옵션 확인은 Luna가 잘 맞는 대표 작업이다.

12. Terra 기반 Implementation Worker

.codex/agents/implementation-worker.toml

name = "implementation_worker"
description = "Implementation agent for small, bounded code changes after the plan is approved."

model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

developer_instructions = """
Implement only the assigned bounded task.

Rules:

- modify only assigned files
- preserve public APIs unless explicitly requested
- make the smallest defensible change
- do not edit files owned by another agent
- run the smallest relevant validation
- never claim a test passed unless it actually ran

Return:

- modified files
- implementation summary
- validation performed
- unresolved risks
"""

복잡한 Plan을 Terra에게 처음부터 만들게 하기보다, Sol이 Plan을 만든 뒤 Terra가 범위가 정해진 구현을 수행하게 하는 편이 좋다.

13. Custom Agent 사용 프롬프트

Codex에게 역할을 명확하게 지시한다.

이 로그인 Bug를 병렬로 조사해.

code_mapper:
관련 실행 흐름과 파일을 찾고, 코드 변경은 하지 마.

docs_researcher:
사용 중인 Authentication API의 공식 동작을 확인해.

reviewer:
현재 구현에서 Race Condition과 회귀 위험을 검토해.

세 Agent가 모두 끝날 때까지 기다린 뒤,
Main Agent가 결과를 합쳐 하나의 수정 계획을 만들어.

아직 코드는 수정하지 마.

구현 단계:

앞에서 만든 계획 중 P0 수정만 진행해.

implementation_worker에게 범위가 겹치지 않는 작업을 맡기고,
공통 파일은 Main Agent가 직접 수정해.

구현이 끝나면 reviewer가 전체 Diff를 다시 검토해.

실행하지 않은 테스트를 통과했다고 보고하지 마.

14. Ultra와 직접 구성한 Subagent의 차이

max와 ultra를 구분해야 한다.

max

하나의 Agent가
더 깊게 탐색하고 검증한다.

ultra

강한 추론
+
적절한 작업을 Subagent에게 능동적으로 위임

Ultra는 복잡한 작업에서 Codex가 스스로 병렬 위임할 수 있도록 하는 모드다.

다음처럼 독립적인 Workstream이 많을 때 적합하다.

Architecture

Security

Concurrency

Tests

Performance

반대로 하나의 Race Condition을 깊게 파야 하는 경우에는 Sol max가 더 적합할 수 있다.

독립적인 작업이 많다.
→ ultra

하나의 어려운 핵심 문제다.
→ max

Ultra도 사용량이 늘어날 수 있으므로 모든 작업의 기본값으로 두지 않는다.

15. Main Context를 Subagent로 보호한다

Subagent의 중요한 장점은 병렬 처리만이 아니다.

Main Context 오염을 줄일 수 있다.

하나의 Agent가 모든 작업을 직접 수행하면 Main Context에 다음 정보가 계속 쌓인다.

검색 결과

긴 Test Log

Build Output

Stack Trace

문서 원문

실패한 가설

반복적인 파일 내용

시간이 지나면 중요한 요구사항과 결정이 묻힌다.

Context Pollution

Context Rot

이 생긴다.

Subagent를 사용하면 중간 작업은 별도 Thread에서 수행한다.

Main Agent

Requirements
Decisions
Plan
Final Result

        ↑

Subagent

Search
Logs
Experiments
Raw Output

Subagent는 Main Agent에게 압축된 결과만 반환한다.

발견 내용

근거 파일

결론

불확실한 점

이것이 Context 관리에서 매우 중요하다.

16. Subagent에게 Raw Log를 그대로 보내지 못하게 한다

좋지 않은 요청:

테스트를 돌리고 결과를 전부 Main Agent에게 보내.

좋은 요청:

테스트를 실행해.

Main Agent에게는 다음만 반환해.

- 실행한 명령
- exit code
- 실패한 Test 이름
- 핵심 오류 5개 이내
- 전체 Log Artifact 경로

전체 원문 Log는 Main Context에 넣지 마.

Main Thread에는 결론만 남긴다.

Raw Log는 파일이나 Artifact로 보관한다.

17. Context 압축은 왜 발생할까

Codex Session이 길어지면 다음 정보가 쌓인다.

사용자 메시지

Agent 응답

Tool 호출

Tool 결과

파일 내용

Build Log

Subagent 결과

Git Diff

AGENTS.md

Context가 임계치에 도달하면 Codex는 이전 History를 압축한다.

Long Context

↓

Compaction

↓

요약된 Context

압축 자체는 나쁜 기능이 아니다.

문제는 너무 자주 발생할 때다.

18. 압축이 너무 잦을 때 생기는 증상

이미 확인한 파일을 다시 읽는다.

이전에 제외한 가설을 다시 검토한다.

결정한 Architecture를 잊는다.

같은 질문을 반복한다.

수정 범위가 다시 넓어진다.

테스트 결과를 기억하지 못한다.

이런 현상이 반복된다면 Context가 과도하게 커졌거나 압축 기준이 맞지 않을 수 있다.

19. Desktop에서 Context 상태 확인하기

Codex Desktop이나 CLI에서 다음 명령을 사용한다.

/status

현재 Chat ID, Context 사용량과 Rate Limit을 확인할 수 있다.

Desktop과 CLI에서는 Model과 Reasoning도 바꿀 수 있다.

/model

/reasoning

현재 Context를 직접 압축하려면 다음을 사용한다.

/compact

IDE에서 자동 공유되는 Context를 켜거나 끌 때는 다음을 사용할 수 있다.

/ide-context

작업과 관련 없는 IDE Tab이나 Selection이 계속 들어온다면 IDE Context를 잠시 끄는 것도 도움이 된다.

20. Desktop 앱에서 Context 크기를 조절할 수 있을까

현재 공식 Desktop Settings 화면에는 Context Window와 자동 압축 임계치를 직접 조정하는 전용 Slider가 문서화돼 있지 않다.

Desktop에서는 다음 방식으로 관리한다.

/status
→ 현재 Context 확인

/compact
→ 수동 압축

/ide-context
→ IDE Context 공유 제어

~/.codex/config.toml
→ 자동 압축 기준 설정

즉 GUI에서 숫자를 조절하기보다 Codex 설정 파일을 사용한다.

21. 자동 Context 압축 설정

Codex에는 다음 설정이 있다.

model_auto_compact_token_limit = 700000

이 값은 자동 History 압축이 시작되는 Token 기준이다.

하지만 처음부터 숫자를 직접 넣는 것은 권하지 않는다.

기본적으로는 모델의 기본값을 사용하는 편이 안전하다.

# 설정하지 않으면 Model 기본값 사용

먼저 /status로 실제 Context 사용량을 확인한다.

압축이 실제로 너무 자주 일어날 때만 조정한다.

22. 반복 압축을 줄이는 중요한 설정

다음 설정이 특히 중요하다.

model_auto_compact_token_limit_scope = "body_after_prefix"

기본값인 total은 전체 Active Context를 기준으로 임계치를 계산한다.

total

압축 후 유지된 Prefix
+
새로 쌓인 Context

를 모두 센다.

반면 body_after_prefix는 압축 후 유지된 Prefix를 제외하고 새로 쌓인 부분을 중심으로 계산한다.

body_after_prefix

압축 Prefix 제외
+
새로 증가한 Context

그래서 압축 직후 다시 임계치에 가까워져 재압축되는 현상을 줄이는 데 도움이 될 수 있다.

23. Context Window 값을 직접 넣어야 할까

Codex 설정에는 다음 항목도 있다.

model_context_window = 1000000

하지만 OpenAI 기본 모델을 사용하는 일반 사용자는 이 값을 굳이 설정하지 않는 편이 좋다.

Codex의 Model Catalog가 현재 모델의 Context Window를 알고 있기 때문이다.

잘못된 값을 직접 입력하면 다음 문제가 생길 수 있다.

실제 Client 한도와 불일치

모델 전환 시 잘못된 압축 기준 적용

작은 모델에서 지나치게 높은 임계치

Context Overflow

압축 시점 오작동

model_context_window는 Custom Provider나 Model Metadata를 직접 관리해야 하는 환경에서 사용하는 고급 설정에 가깝다.

일반적인 ChatGPT 로그인 기반 Codex라면 기본값을 우선한다.

24. 추천 Context 설정

안전한 시작:

model_auto_compact_token_limit_scope = "body_after_prefix"

직접 임계치를 넣지 않는다.

압축이 여전히 너무 잦다면:

model_auto_compact_token_limit_scope = "body_after_prefix"

# 실제 /status 수치와 Model 한도를 확인한 뒤 조정
model_auto_compact_token_limit = 700000

700000은 예시다.

고정된 정답이 아니다.

다음 정보를 보고 조정해야 한다.

실제 Model Context

Tool Result 크기

파일 읽기 양

출력에 필요한 여유

Subagent 사용 여부

Task 길이

Context Window의 끝까지 채우면 출력과 Tool 결과를 위한 여유가 부족할 수 있다.

25. 수동 /compact는 언제 사용할까

다음 시점에 사용하는 것이 좋다.

분석이 끝나고 구현을 시작할 때

Module 하나가 완료됐을 때

큰 Debugging 가설이 확정됐을 때

PR Review 단계로 넘어갈 때

Task 방향이 크게 바뀔 때

예:

Phase 1
Repository 분석

↓

결정 사항 Artifact 저장

↓

/compact

↓

Phase 2
구현

반대로 작은 수정 도중 계속 /compact를 실행할 필요는 없다.

너무 자주 압축하면 세부 정보가 손실될 수 있다.

26. 압축 전에 Decision Artifact를 남긴다

Context 압축 전에 중요한 정보를 파일로 남긴다.

.ai/
└── tasks/
    └── login-fix/
        ├── goal.md
        ├── decisions.md
        ├── plan.md
        ├── test-result.json
        └── checkpoint.json

decisions.md

# Decisions

- 원인은 TokenStore가 아니라 SessionManager의 refresh race다.
- Public API는 변경하지 않는다.
- 수정 범위는 SessionManager와 관련 Test로 제한한다.
- NetworkClient는 공용 SDK라 수정하지 않는다.

이후 압축이 일어나도 Codex가 파일을 다시 읽을 수 있다.

27. Context를 줄이는 가장 좋은 방법은 압축 설정이 아니다

압축 기준만 높여서는 문제가 해결되지 않을 수 있다.

더 중요한 것은 처음부터 Main Context에 불필요한 내용을 넣지 않는 것이다.

긴 Log
→ Artifact

대량 탐색
→ Subagent

다른 질문
→ Side Chat

대안 실험
→ Fork

프로젝트 공통 규칙
→ AGENTS.md

반복 절차
→ Skill

Context를 정리하는 도구를 적극적으로 사용한다.

28. /side로 Main Chat 보호하기

작업 도중 잠깐 다른 질문이 생겼다고 하자.

이 API 이름이 무슨 뜻이지?

이 Compiler Error만 설명해줘.

다른 구현 방식도 가능할까?

이를 Main Chat에서 계속 묻으면 Context가 섞인다.

Desktop에서는 다음을 사용할 수 있다.

/side

현재 작업을 중단하지 않고 임시 Side Chat을 시작한다.

Side Chat에 적합한 작업:

짧은 API 질문

오류 메시지 설명

대안 아이디어

작은 코드 검토

현재 작업과 직접 관련 없는 질문

Main Thread에는 최종 결정만 가져온다.

29. /fork로 대안 실험하기

두 가지 구현 중 어느 쪽이 나은지 비교하고 싶을 때 Main Chat에서 모두 진행하면 Context가 복잡해진다.

Option A

Actor 기반

Option B

Lock 기반

이럴 때는 다음을 사용한다.

/fork

현재 Chat을 복사해 별도 Chat이나 Worktree에서 실험한다.

결과가 좋은 쪽만 Main Branch에 반영한다.

30. IDE Context를 항상 켜둘 필요는 없다

IDE Context는 현재 열려 있는 파일이나 선택 영역을 Codex에 전달하는 데 편리하다.

하지만 다음 상황에서는 불필요한 Context가 들어갈 수 있다.

관계없는 Tab을 많이 열어둠

이전 작업 파일이 선택돼 있음

대형 Generated File이 열려 있음

현재 Task와 무관한 Diff가 있음

이럴 때는

/ide-context

를 사용해 끄고 필요한 파일을 명시적으로 알려주는 편이 낫다.

이번 작업에서는 아래 파일만 우선 확인해.

- Sources/Auth/SessionManager.swift
- Tests/Auth/SessionManagerTests.swift

31. AGENTS.md는 작게 유지한다

Codex에서 /init을 사용하면 기본 AGENTS.md를 만들 수 있다.

/init

좋은 AGENTS.md는 다음 내용을 담는다.

Repository 목적

Build / Test 명령

Architecture 경계

절대 수정하면 안 되는 파일

코드만 보고 알기 어려운 Gotcha

예:

# Project

Swift 6 + SwiftUI 기반 iOS 애플리케이션.

## Commands

- Build: `make build`
- Unit test: `make test`
- Auth test: `make test-auth`

## Architecture

- 기존 Module 경계를 유지한다.
- View에서 API Client를 직접 호출하지 않는다.
- Domain은 UI Module에 의존하지 않는다.

## Scope

- 현재 Task에 필요한 최소 파일만 수정한다.
- 외부 Dependency 추가 전 사용자에게 확인한다.

## Gotchas

- `Generated/`는 직접 수정하지 않는다.
- `LegacyAuthService`는 아직 Production에서 사용한다.
- API 오류는 `AppErrorMapper`를 거쳐야 한다.

## Validation

- 행동이 변경되면 관련 Test를 실행한다.
- 실행하지 않은 Test는 Passed라고 보고하지 않는다.

여기에 모든 Workflow를 넣지 않는다.

32. AGENTS.md에 넣지 말아야 할 것

코드 리뷰 전체 절차

릴리스 20단계

모든 Git 명령 예제

웹 콘텐츠 점검 규칙

장황한 일반 코딩 상식

현재 Issue의 상세 요구사항

이런 내용은 Skill이나 현재 Prompt로 분리한다.

항상 필요한 프로젝트 정보
→ AGENTS.md

특정 작업 절차
→ Skill

현재 작업 조건
→ Prompt

33. Prompt는 Goal과 Success Criteria 중심으로 쓴다

좋지 않은 요청:

로그인 고쳐줘.

좋은 요청:

Goal:

로그인 세션 갱신 중 발생하는 Race Condition을 수정한다.

Constraints:

- Public API를 변경하지 않는다.
- NetworkClient는 수정하지 않는다.
- 외부 Dependency를 추가하지 않는다.

Workflow:

1. code_mapper가 실행 흐름을 조사
2. reviewer가 Race 가능성을 검토
3. Main Agent가 계획 작성
4. implementation_worker가 최소 수정
5. reviewer가 최종 Diff 검토

Success Criteria:

- 재현 Test 통과
- 기존 Auth Test 통과
- 관련 없는 파일 수정 없음
- 실행하지 않은 Test는 Passed로 표시하지 않음

GPT-5.6은 모든 세부 작업 순서를 강제하지 않아도 목표를 잘 이해하는 편이지만, 다음은 명확하게 주는 것이 좋다.

Hard Constraint

Approval Boundary

Success Criteria

중요한 모호성 처리 방식

34. Plan부터 만들고 구현한다

복잡한 작업은 바로 코드를 수정하게 하지 않는다.

Desktop에서 다음을 사용한다.

/plan

Plan을 검토한다.

좋은 Plan에는 다음이 있어야 한다.

수정 대상

변경 이유

작업 순서

파일 Ownership

검증 방법

위험 요소

계획이 확정되면 구현을 시작한다.

장시간 작업이면 Goal Mode를 사용할 수 있다.

/goal

35. Worktree를 적극적으로 사용한다

여러 Agent나 대안 구현이 같은 파일을 수정하면 충돌할 수 있다.

Desktop에서 다음을 사용할 수 있다.

/worktree

또는

/fork

Worktree를 사용하면 같은 Repository의 독립 작업 공간에서 수정할 수 있다.

main

├── worktree-auth
├── worktree-ui
└── worktree-tests

다만 Agent 수를 늘리기 전에 File Ownership을 먼저 정한다.

Auth Worker
→ Sources/Auth/**

UI Worker
→ Sources/UI/**

Test Worker
→ Tests/Auth/**

같은 파일을 여러 Agent에게 동시에 맡기지 않는다.

36. Subagent는 Read-heavy 작업부터 적용한다

처음부터 여러 Agent에게 코드를 동시에 수정시키지 않는다.

가장 안전한 시작점은 다음이다.

Repository 탐색

Test 조사

로그 분석

문서 확인

보안 Review

Diff Review

모두 Read-only 작업이다.

Subagents
→ 분석

Main Agent
→ 구현

으로 시작한다.

안정되면 일부 구현을 Terra Worker에게 분리한다.

37. Reasoning Effort를 단계별로 바꾼다

모든 Phase에 같은 Reasoning이 필요하지 않다.

탐색

Luna medium

Terra medium

계획

Sol high

일반 구현

Terra medium

Sol medium

Debugging

Terra high

Sol high

최종 Critical Review

Sol high

Sol max

Codex에서는 현재 Chat에서 다음 명령으로 조절할 수 있다.

/reasoning

모델은 다음으로 바꾼다.

/model

38. max를 항상 켜지 말아야 하는 이유

max는 다음 작업에서는 도움이 될 수 있다.

재현이 어려운 Concurrency Bug

Architecture Trade-off

대규모 Migration Plan

중요한 Security Review

여러 Agent의 충돌 결과 통합

하지만 다음 작업에는 과하다.

파일 이름 변경

단순 UI 수정

문서 정리

Test 목록 수집

API 이름 확인

max를 기본으로 두면 응답 시간과 사용량이 늘어날 수 있다.

기본은 medium 또는 high, 필요할 때 max로 올리는 편이 낫다.

39. Luna max보다 Terra medium이 나을 수 있는 이유

Luna는 빠르고 좁은 작업에 최적화된 Tier다.

작업이 다음처럼 복잡하다면

여러 Module 관계 판단

상충하는 요구사항 정리

복잡한 Test 실패 원인 추론

Architecture 수정 결정

Luna에게 높은 Effort를 주는 것보다 Terra나 Sol이 더 적합할 수 있다.

실전 판단 기준:

범위가 좁고 정답 형태가 명확함
→ Luna medium

판단이 여러 단계 필요함
→ Terra medium / high

모호하고 실패 비용이 큼
→ Sol high / max

모델 크기와 Reasoning Effort를 따로 보되, 작은 모델에 Reasoning만 무한히 올리는 방식으로 해결하려 하지 않는다.

40. Permissions는 Main Agent 기준으로 먼저 설정한다

Desktop에서는 Composer 아래 Permission Mode를 선택할 수 있다.

CLI에서는 다음을 사용할 수 있다.

/permissions

Subagent는 Parent Turn의 Permission과 Sandbox 정책을 상속받는다.

따라서 Subagent를 띄우기 전에 Parent 권한을 먼저 확인한다.

41. approval_policy 추천

Interactive Codex에서는 다음이 무난하다.

approval_policy = "on-request"

Codex가 필요한 경우 승인을 요청한다.

비대화형 자동화에서는 새로운 승인을 받을 수 없으므로 승인 필요한 작업이 실패할 수 있다.

never나 강한 자동화 설정을 사용할 때는 Sandbox와 Tool Allowlist를 더 엄격하게 구성해야 한다.

42. Sandbox 기본 추천

sandbox_mode = "workspace-write"

현재 Workspace 안에서는 수정할 수 있지만 임의의 외부 경로까지 접근하지 못하게 한다.

Explorer와 Reviewer는 Custom Agent에서 더 강하게 제한한다.

sandbox_mode = "read-only"

Agent가 문서 확인만 하는데 Write 권한을 가질 필요는 없다.

43. Skill은 반복 Workflow에 사용한다

다음 작업을 매번 Prompt에 길게 적지 않는다.

코드 리뷰

Test 검증

릴리스 노트

Swift Concurrency 점검

API 문서 검증

UI Screenshot 비교

Skill로 만든다.

.agents/
└── skills/
    ├── verification/
    │   └── SKILL.md
    ├── swift-concurrency-review/
    │   └── SKILL.md
    └── pr-review/
        └── SKILL.md

AGENTS.md에는 한 줄만 남긴다.

행동 변경 후 verification Skill을 사용한다.

44. Tool을 많이 연결한다고 좋아지는 것은 아니다

MCP Server와 Plugin이 많아지면 Tool 설명 자체가 Context를 사용한다.

GitHub MCP

Xcode MCP

Database MCP

Browser MCP

Slack MCP

Jira MCP

Internal MCP

현재 Task와 관계없는 Tool은 끈다.

iOS Build 작업

→ Xcode MCP
→ GitHub MCP

Database Migration

→ Database MCP
→ GitHub MCP

모든 Tool을 항상 노출하지 않는다.

45. 세 가지 실전 Workflow

기능 구현

Main
Sol high

code_mapper
Luna medium

implementation_worker
Terra medium

reviewer
Terra high

Prompt:

code_mapper가 관련 실행 경로를 찾고,
Main Agent가 계획을 만든 뒤,
implementation_worker가 범위가 정해진 수정만 수행해.

구현 후 reviewer가 정확성·회귀·Test 누락을 검토해.

복잡한 Bug

Main
Sol high

로그 분석
Luna medium

코드 흐름
Luna medium

재현·Debugging
Terra high

최종 원인 판단
Sol high 또는 max

중간 Log는 Artifact로 보관한다.

Main Context에는 원인 후보와 근거만 올린다.

대형 PR Review

Reviewer 1
Terra high
Correctness

Reviewer 2
Terra high
Concurrency / Security

Reviewer 3
Luna medium
Test Coverage / 변경 파일 조사

Main
Sol high
중복 제거와 우선순위 결정

46. 추천 총합 설정

~/.codex/config.toml

model = "gpt-5.6-sol"
model_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

# 압축 이후 유지되는 prefix 때문에
# 반복적으로 다시 압축되는 현상을 줄이기 위한 설정
model_auto_compact_token_limit_scope = "body_after_prefix"

[agents]
enabled = true
max_concurrent_threads_per_session = 4

# 대부분의 일반 Subtask
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"

interrupt_message = true

프로젝트 구조:

MyProject/
├── AGENTS.md
│
├── .codex/
│   ├── config.toml
│   │
│   └── agents/
│       ├── code-mapper.toml
│       ├── docs-researcher.toml
│       ├── reviewer.toml
│       └── implementation-worker.toml
│
├── .ai/
│   └── tasks/
│       └── current-task/
│           ├── goal.md
│           ├── decisions.md
│           ├── plan.md
│           ├── checkpoint.json
│           └── artifacts/
│
├── Sources/
└── Tests/

47. 처음 사용하는 사람에게 추천하는 단계

1단계

Sol high
+
AGENTS.md

하나의 Agent로 시작한다.

2단계

Subagent 기본

Terra medium

을 추가한다.

3단계

Luna Explorer

Terra Reviewer

역할을 나눈다.

4단계

/side

/fork

/worktree

로 Main Context를 보호한다.

5단계

body_after_prefix

/compact

Decision Artifact

로 장시간 Context를 관리한다.

6단계

Ultra

여러 Worker

Final Reviewer

를 큰 작업에만 적용한다.

48. 피해야 할 설정

모든 작업 Sol max

느림

사용량 증가

작은 작업에도 과도한 추론

모든 Subagent Luna max

작은 모델의 속도 장점 감소

복잡한 판단 안정성 부족 가능

Terra medium보다 비효율적일 수 있음

Subagent 10개 이상 무조건 병렬

Context와 사용량 증가

중복 조사

File 충돌

결과 통합 비용 증가

Context Window를 임의로 최대값 설정

Client 실제 한도와 불일치

모델 전환 문제

압축 기준 오작동

AGENTS.md에 모든 절차 넣기

모든 Session의 Context 증가

현재 Task와 무관한 규칙

지시 충돌

Raw Log를 Main Agent에 모두 전달

Context Pollution

중요한 요구사항과 결정이 묻힘

49. 가장 중요한 운영 원칙

Codex 5.6을 잘 쓰는 것은 가장 좋은 모델을 계속 선택하는 것이 아니다.

작업마다 역할을 나누는 것이다.

Sol

목표
계획
복잡한 판단
최종 통합

Terra

일반 구현
Debugging
Review
중간 난이도 Worker

Luna

탐색
분류
문서 확인
반복 작업

Context도 같은 방식으로 나눈다.

Main Context

요구사항
결정
Plan
최종 결과

Subagent Context

검색
로그
실험
중간 조사

Artifact

긴 Log
Test 결과
결정 기록
Checkpoint

50. 마무리

Codex 5.6에서 가장 무난한 기본 구성은 다음이다.

Main Agent

GPT-5.6 Sol high

Default Subagent

GPT-5.6 Terra medium

Fast Explorer

GPT-5.6 Luna medium

Complex Reviewer

GPT-5.6 Terra high

Final Critical Decision

GPT-5.6 Sol max

Context 압축은 임계치를 무작정 크게 올리기보다 다음 순서로 대응한다.

1. Main Context에 Raw Output을 넣지 않는다.

2. 탐색과 로그 분석을 Subagent로 분리한다.

3. /side와 /fork를 사용한다.

4. Decision과 Test 결과를 Artifact로 남긴다.

5. model_auto_compact_token_limit_scope를
   body_after_prefix로 설정한다.

6. 그래도 자주 압축될 때만
   /status를 기준으로 임계치를 조정한다.

Desktop에서는 현재 Context 전용 GUI Slider보다 다음 명령과 설정 파일을 사용하는 방식이 중심이다.

/status

/compact

/ide-context

~/.codex/config.toml

한 줄로 정리하면 이렇다.

Codex 5.6을 잘 쓰는 방법은
Sol을 항상 max로 돌리는 것이 아니라,

Sol은 판단에,
Terra는 실행과 검토에,
Luna는 빠른 탐색에 배치하고,

Main Context에는
결정과 결과만 남기는 것이다.

좋은 Codex 환경은 모델 하나가 모든 일을 하는 환경이 아니다.

모델·Reasoning·Subagent·Context·권한·검증을 작업 성격에 따라 나눠 놓은 환경이다.

참고 자료

OpenAI — GPT-5.6: Frontier intelligence that scales with your ambition
GPT-5.6 Sol·Terra·Luna의 역할, Codex 제공 범위, max와 ultra 지원 내용을 확인할 수 있는 공식 발표 자료.
OpenAI — GPT-5.6 in ChatGPT and Codex
Codex에서 GPT-5.6을 사용하기 위한 Desktop 앱과 CLI 최소 버전, 플랜별 모델 제공 범위를 확인할 수 있는 공식 도움말.
OpenAI Codex Docs — Subagents
Main Agent와 Subagent를 병렬로 사용하는 방법, Sol·Terra·Luna 모델 선택 기준, Custom Agent 파일과 기본 Subagent 모델 설정을 설명하는 공식 문서.
OpenAI Codex Docs — Configuration Reference
model, model_reasoning_effort, agents.default_subagent_model, model_auto_compact_token_limit, model_auto_compact_token_limit_scope 등 Codex 설정 항목의 공식 Reference.
OpenAI Codex Docs — Slash Commands
/model, /reasoning, /status, /compact, /side, /fork, /worktree, /ide-context, /plan, /goal 사용법을 확인할 수 있는 공식 문서.
OpenAI Codex Docs — AGENTS.md and Skills
프로젝트 공통 지침과 반복 Workflow를 분리해 Context를 관리하는 방법을 확인할 수 있는 공식 자료.

핵심 참고 포인트

Codex의 현재 공식 Subagent 문서는 Sol을 복잡한 계획·도구 사용·검증이 필요한 Agent, Terra를 빠르고 비용 효율적인 탐색·리뷰·병렬 Worker, Luna를 명확하고 반복적인 고속 작업에 적합한 모델로 설명한다.

Custom Agent는 개인용 ~/.codex/agents/ 또는 프로젝트용 .codex/agents/에 TOML 파일로 만들 수 있으며, Agent별 model, model_reasoning_effort, sandbox_mode, MCP와 Skill 설정을 지정할 수 있다.

Codex 전역 설정의 [agents]에서는 default_subagent_model, default_subagent_reasoning_effort, 동시 Agent 수를 설정할 수 있다.

Context 자동 압축은 model_auto_compact_token_limit으로 임계치를 설정하며, model_auto_compact_token_limit_scope = "body_after_prefix"를 사용하면 기존 압축 Prefix를 제외하고 이후 증가분을 중심으로 임계치를 계산할 수 있다.

현재 공식 Desktop Settings 문서에는 Context Window나 자동 압축 임계치를 변경하는 별도의 GUI Slider가 명시돼 있지 않다. 대신 /status, /compact, /ide-context와 ~/.codex/config.toml을 이용해 관리한다.

이경규

iOS 앱 개발자

이전 포스트

CLAUDE.md를 지워도 될까: Claude Code 5의 Context·Output Style·Skill을 다시 나누는 방법

다음 포스트