Codex Context 관리법: /compact로 토큰 낭비 줄이고 긴 프로젝트 이어가기
Codex로 프로젝트를 오래 진행할수록 대화창에는 이전 지시, 파일 탐색 결과, 오류 로그가 계속 쌓인다. 이 글에서는 컨텍스트를 줄이는 기능과, 긴 프로젝트를 안정적으로 이어 가는 실전 작업 흐름을 정리한다.
Context가 길어지면 왜 불편할까?
컨텍스트(Context)는 Codex가 현재 작업을 위해 참고하는 정보의 묶음이다. 이전 대화, 지시사항, 읽은 파일, 명령 실행 결과, 오류 로그 등이 포함된다. 그래서 “아까 만든 기능을 조금 수정해줘” 같은 요청을 이해하기 편하다.
하지만 대화가 길어질수록 이미 끝난 논의와 긴 로그까지 함께 남는다. 지금의 작업과 관계없는 정보가 많아지면, 같은 파일을 반복해서 확인하거나 과거 결정과 충돌하는 제안을 할 가능성도 커진다.
핵심은 대화를 무조건 이어 가는 것이 아니라, 필요한 정보만 남겨서 이어 가는 것이다.
가장 간단한 방법: /compact
Codex CLI를 사용 중이라면 대화가 길어졌을 때 아래 명령을 입력할 수 있다.
/compact/compact는 지금까지의 긴 대화를 핵심 요약으로 바꾸는 기능이다. 프로젝트의 중요한 결정, 현재 진행 상태, 남은 작업은 가능한 한 유지하면서 오래된 세부 대화와 긴 출력 내용을 줄인다.
예를 들어 이미지 변환 기능을 구현하며 오류 로그를 여러 번 확인했다면, 그 모든 로그를 들고 가는 대신 “이미지 변환 기능 구현 완료, 브라우저 내 처리 방식 사용, 특정 형식의 예외 처리 보완 필요”처럼 압축된 정보만 남긴다.
알아둘 점: Codex는 대화가 길어지면 자동으로 압축하기도 한다. 다만 기능 하나가 끝났을 때 직접
/compact를 실행하면 작업 전환 시점을 더 깔끔하게 정리할 수 있다.
/compact는 Codex CLI의 슬래시 명령이다. Codex 앱을 사용한다면 같은 목적을 위해 새 작업을 시작하고, 아래의 인수인계 문서를 활용하는 방식이 가장 확실하다.
/compact와 새 작업은 무엇이 다를까?
| 상황 | 추천 방법 | 이유 |
|---|---|---|
| 같은 기능을 계속 다듬는 중 | /compact | 핵심 진행 상황을 유지한 채 대화만 가볍게 만들 수 있다. |
| 기능 하나를 완료하고 다음 기능으로 이동 | 새 작업 | 이전 작업의 세부 사항을 과감히 분리할 수 있다. |
| 기획이 크게 변경됨 | 새 작업 | 오래된 요구사항이 새 요구사항과 섞이는 것을 막는다. |
| 오류 로그와 시행착오가 많이 쌓임 | /compact 또는 새 작업 | 현재 상태만 요약해 불필요한 출력 기록을 줄인다. |
CLI에서 새 대화를 시작하려면 아래 명령을 사용한다.
/new새 대화는 이전 대화의 컨텍스트를 이어받지 않는다. 하지만 프로젝트 폴더 안의 코드와 AGENTS.md는 그대로 있으므로, Codex가 필요한 규칙과 현재 파일 상태를 다시 읽고 작업할 수 있다.
가장 추천하는 방식: 인수인계 문서 + 새 작업
프로젝트를 오래 진행한다면, 기능이 끝날 때마다 Codex에게 짧은 인수인계 문서를 만들게 하는 방식이 가장 실용적이다.
지금까지 완료한 작업, 주요 결정, 남은 작업, 주의사항을
NEXT_TASK.md에 인수인계 문서로 정리해줘.그다음 새 작업에서 아래처럼 시작한다.
AGENTS.md와 NEXT_TASK.md를 먼저 읽고,
현재 프로젝트 상태를 확인한 뒤 남은 작업을 이어서 진행해줘.이 방식은 대화는 새로 시작해 가벼워지고, 프로젝트에 꼭 필요한 결정은 파일로 남는다는 장점이 있다. 며칠 뒤 다시 작업하거나 다른 Codex 대화에서 이어 가더라도 같은 문서를 기준으로 시작할 수 있다.
실제 프로젝트에서는 이렇게 나누면 좋다
Next.js로 온라인 게임 사이트를 만든다고 가정해 보자. 하나의 대화에서 처음부터 끝까지 진행하기보다, 기능 단위로 나누는 편이 좋다.
- 프로젝트 구조와 공통 규칙 설계
- 오델로 게임 규칙과 보드 구현
- 컴퓨터 AI 난이도 구현
- LocalStorage 저장·이어 하기 기능
- 모바일 UI와 다국어 지원
- 테스트, 버그 수정, 배포 점검
각 단계가 끝나면 NEXT_TASK.md를 갱신하고, 다음 단계는 새 작업에서 시작한다. 이렇게 하면 Codex가 과거의 모든 시행착오 대신 현재 단계에 필요한 코드와 인수인계 내용에 집중할 수 있다.
불필요한 Context를 처음부터 줄이는 프롬프트
컨텍스트는 대화뿐 아니라 Codex가 출력하는 내용 때문에도 커진다. 특히 긴 빌드 로그, 파일 전체 내용, 반복되는 테스트 출력이 쌓이면 빠르게 길어진다.
긴 로그와 파일 전체 내용을 대화에 출력하지 말고 핵심 결과만 요약해줘.
작업 중간 결과는 필요한 경우 프로젝트 파일로 저장해줘.
이미 확인한 파일은 변경 가능성이 없으면 반복해서 읽지 마.
테스트 실패 시 전체 로그 대신 원인과 관련 부분만 간단히 알려줘.이렇게 요청한다고 Codex가 필요한 파일을 읽지 않는 것은 아니다. 대화창에 쌓이는 불필요한 출력과 반복 설명을 줄여 중요한 정보에 더 많은 공간을 남기는 방식이다.
AGENTS.md에 넣어 둘 수 있는 Context 관리 규칙
프로젝트마다 같은 원칙을 적용하고 싶다면 AGENTS.md에 아래 규칙을 추가해 두면 좋다.
## 컨텍스트 관리
- 진행 상황은 짧고 명확하게 보고한다.
- 요청이 없으면 파일 전체나 긴 명령 실행 로그를 대화에 출력하지 않는다.
- 테스트 결과와 오류는 원인 및 관련 내용만 요약한다.
- 중요한 구조 결정은 docs/DECISIONS.md에 기록한다.
- 의미 있는 기능을 완료했거나 새 작업을 권장하기 전에는 NEXT_TASK.md를 갱신한다.다만 AGENTS.md 자체가 너무 길어지면 매 작업마다 읽어야 할 지시사항이 늘어난다. 공통 규칙만 짧게 유지하고, 기능별 상세 설명은 NEXT_TASK.md, docs/, 이슈 문서처럼 목적에 맞는 파일로 분리하는 편이 좋다.
정리: 계속 이어 가기보다, 잘 정리해서 이어 가기
같은 기능을 계속 다듬는 중이라면 /compact로 핵심만 남긴다. 기능이나 단계가 바뀌면 NEXT_TASK.md에 인수인계를 남긴 뒤 새 작업을 시작한다. 모든 작업에 적용할 공통 규칙은 AGENTS.md에 짧게 유지한다.
- 같은 작업을 이어 갈 때:
/compact - 기능 단계가 바뀔 때:
NEXT_TASK.md작성 후 새 작업 - 항상 적용할 공통 규칙:
AGENTS.md
참고 자료
- OpenAI Codex CLI 명령어 문서 —
/compact,/new, 자동 컨텍스트 압축 - OpenAI Codex Configuration Reference — 자동 압축 임계값 설정
- OpenAI Codex AGENTS.md 가이드 — 프로젝트 지침 파일 활용 방식
댓글
댓글 쓰기