10분 만에 읽을 수 있는 · AI 시스템 아키텍트가 집필

주력 분야: AGENTS.md · Skills · Automations · 비용 최적화

대부분의 사람들이 Codex를 잘못된 방식으로 사용하고 있습니다.

악의가 있는 것은 아닙니다. Codex의 동작 방식이 직관과 다르기 때문입니다. 당신은 Codex를 '더 똑똑한 ChatGPT'라고 생각하시나요? 실제로는 다릅니다.

Codex는 매번 기억 상실 상태로 프로젝트 디렉토리에 들어오는 새로운 동료와 같습니다. 프로그래밍 지식은 있지만, 당신의 프로젝트 구조도, 사용 중인 테스트 프레임워크도, 건드려서는 안 될 디렉토리도 아무것도 모릅니다.

Codex의 진가를 끌어내는 열쇠는 더 좋은 프롬프트를 쓰는 것이 아닙니다. 프로젝트에 관한 영구적인 기억을 부여하는 것입니다.

OpenAI의 공식 Codex 문서에서는 이를 **6가지 기둥 (6 Pillars)**과 **8가지 흔한 실수 (8 Common Mistakes)**로 정리하고 있습니다. 본 기사에서는 3개월 동안 Codex를 매일 사용해 온 경험을 바탕으로, 각 항목을 실례와 함께 자세히 설명합니다.

Codex에게 필요한 것은 '더 많은 지시'가 아니라 '더 안정적인 컨텍스트 (Context)'입니다.

Codex를 실행할 때마다 당신의 프로젝트를 읽고 구조를 이해합니다. 하지만 설정이 영구화되지 않으면 세션마다 모든 것을 잊어버립니다. 6가지 기둥은 이 문제를 단계적으로 해결하기 위한 시스템입니다:

AGENTS.md → 설정 (Settings) → MCP → Skills → Automations

각각은 이전 기둥 위에 구축됩니다. 첫날부터 전부 구현할 필요는 없습니다.

Codex에 작업을 요청하기 전에 다음 정보를 확보하세요:

프로젝트 구조: 소스 코드, 테스트, 설정 파일의 위치 -
기술 스택 (Tech Stack): 언어, 프레임워크, 빌드 도구 -
규약 (Conventions): 코드 스타일, 명명 규칙, 과거의 교훈 -
현재 상태: 변경 내용, 발생한 에러

매번 프롬프트에 직접 써도 괜찮습니다. 하지만 더 스마트한 방법이 있습니다. 기둥 2에서 설명하겠습니다.

AGENTS.md는 AI 에이전트를 위해 작성된 README입니다. Codex는 세션 시작 시 자동으로 이 파일을 읽습니다. 이는 Codex의 출력 품질을 높이기 위해 할 수 있는 가장 효과적인 조치입니다.

~/.codex/AGENTS.md → 개인의 글로벌 기본값
리포지토리 루트/AGENTS.md → 팀 공유 표준
서브 디렉토리/AGENTS.md → 로컬 규칙 (최우선 적용)

작업 디렉토리에 가까운 파일일수록 우선순위가 높아집니다. 프론트엔드와 백엔드에 서로 다른 규칙을 작성할 수도 있습니다.

Codex CLI에서 /init을 실행하면 초기 버전이 자동으로 생성됩니다. 그 후 프로젝트의 실정에 맞게 편집하세요.

짧고 정확한 AGENTS.md는 길고 모호한 것보다 훨씬 유용합니다.

기본 항목만 작성하고, Codex가 같은 실수를 반복할 때만 규칙을 추가해 나갑니다.

실례: TypeScript 프로젝트에서 Codex가 2번 any 타입을 사용했다고 가정해 봅시다. 당신은 수동으로 수정했습니다. 이때 AGENTS.md에 다음과 같이 추가합니다:

수정: any 타입은 사용하지 않는다. unknown + 타입 가드 (Type Guard)로 대체한다.

이후에는 이 문제가 발생하지 않을 것입니다.

판단 기준: Codex에게 같은 일을 두 번 주의했다면, AGENTS.md에 기록해야 합니다.

AGENTS.md는 Codex에게 '프로젝트의 규칙'을 가르칩니다. 설정 파일은 Codex에게 '자신의 행동 방식'을 가르칩니다.

3층 구조:

~/.codex/config.toml → 개인 기본값 (Individual Default)
.codex/config.toml → 리포지토리 전용 (Repository-specific)
CLI 플래그 (CLI Flags) → 일시적인 덮어쓰기 (Temporary Overrides)

설정 가능한 항목: 기본 모델 (Default Model), 추론 레벨 (Reasoning Level), 샌드박스 모드 (Sandbox Mode), 승인 전략 (Approval Strategy), MCP 서버.

편집 방법은 두 가지입니다: config.toml을 수동으로 편집하거나, Codex에게 직접 "config를 업데이트해줘"라고 요청하거나. 어느 쪽이든 상관없습니다.

MCP (Model Context Protocol)를 사용하면 Codex를 데이터베이스, API, Jira, Notion 등과 같은 외부 도구에 연결할 수 있습니다.

코드를 작성하기 전에 데이터베이스 스키마를 확인하거나, GitHub Issue를 자동으로 가져오는 등—이러한 작업들을 Codex가 직접 실행할 수 있게 됩니다.

황금률: 처음에는 1~2개의 가치 높은 MCP 서버만 연결하세요. 한꺼번에 수십 개를 설정하면 Codex가 혼란을 겪습니다.

특정 워크플로우가 반복적으로 등장하기 시작하면, 긴 프롬프트에 의존하는 것을 멈추세요. Skill로서 캡슐화(Encapsulation)하세요.

Skill의 본체는 SKILL.md 파일입니다. CLI, IDE, Codex App 모두에서 동작합니다.

개인용: $HOME/.agents/skills — 자신만의 Skill 라이브러리
팀용: 리포지토리 내의 .agents/skills — git 커밋이 가능하며, 새 멤버도 clone만 하면 바로 사용 가능

워크플로우가 안정되면 Codex가 자동으로 실행하게 하세요.

Codex App → Automations 탭에서 설정: 대상 프로젝트, 프롬프트 (Skills 호출 가능), 실행 빈도, 작업 환경 (worktree인지 로컬인지).

Skills가 방법을 정의하고, Automations가 리듬을 정의합니다. 사람의 개입이 필요한 플로우는 먼저 안정적인 Skill로 만든 후 자동화를 검토하세요.

다음은 OpenAI 공식 문서에서 명시하고 있는 8가지 실수입니다. 대부분의 사람들이 최소 4~5개는 경험하고 있습니다.

1. 코딩 규약, 코드 스타일, 제약 조건을 매번 수동으로 작성한다. 한 번 잊어버리면 그것으로 끝입니다.

✅
해결책: 규칙은 AGENTS.md에 작성하세요. 한 번 작성하면 영구적으로 유효합니다.

2. "이 코드를 수정해줘"라는 지시만 내린다. Codex는 수정 후에 검증할 수 없으므로, 감각적으로 "아마 괜찮겠지"라고 판단할 수밖에 없습니다.

✅
해결책: AGENTS.md에 검증 명령어를 명시하세요. 각 태스크의 "완료 조건"에도 구체적인 확인 단계를 넣으세요.

3. 갑자기 구현을 시작하여 시스템을 이해할 시간을 주지 않는다. 결과적으로 겉보기에는 합리적이지만 프로젝트 구조와 전혀 맞지 않는 솔루션이 생성됩니다.

✅
해결책: 복잡한 태스크에서는 반드시 Plan 모드 (/plan)를 사용하세요. 또는 "먼저 설명하고, 그다음에 구현해줘"라고 지시하세요.

4. "권한이 클수록 편리할 것"이라고 생각하여 갑자기 완전 액세스(Full Access)로 설정한다. 그 결과, 예기치 않은 전역적인(Global) 변경이 발생합니다.

✅
해결책: 먼저 Chat/읽기 전용 모드부터 시작하세요. 워크플로우를 이해한 후, 필요한 범위만큼 점진적으로 권한을 넓히세요.

5. 여러 개의 Codex 세션이 동일한 파일 그룹에서 동시에 작업한다. 변경 사항이 충돌하여 어떤 버전이 올바른지 알 수 없게 됩니다.

✅
해결책: 병렬 작업은 반드시 독립된 git worktree에서 수행하세요.

6. "이 플로우 괜찮은데?"라고 생각하자마자 즉시 Automation을 설정한다. 불안정한 동작이 그대로 확장(Scale)되어 버립니다.

✅
해결책: 먼저 Skill로 만드세요. 수동으로 몇 번 검증하여 안정성을 확인한 후에 Automation을 설정하세요.

7. 주니어 엔지니어를 감시하듯 Codex의 모든 작업을 옆에서 지켜본다. 비동기 및 병렬 작업의 장점을 전혀 활용하지 못합니다.

✅
해결책: 태스크를 시작했다면 다른 일을 하세요. 나중에 결과를 리뷰하는 것만으로 충분합니다. Codex는 백그라운드 태스크이며, 실시간 대화가 아닙니다.

8. 하나의 스레드에 프로젝트의 모든 작업 이력을 축적한다. 컨텍스트(Context)가 팽창하여 Codex가 노이즈 속에서 관련 정보를 찾아내지 못하게 됩니다.

✅

해결책: 태스크 또는 독립된 작업 단위별로 새 스레드를 생성하십시오. /fork를 사용하면 컨텍스트(Context)를 유지한 채로 분기할 수 있습니다.

많은 사람이 API 비용을 직접 지불하는 것이 아니라, ChatGPT Plus(월 $20) 또는 Pro(월 $200) 구독을 통해 Codex를 사용하고 있습니다. 이 경우 신경 써야 할 것은 달러 가격이 아니라, 크레딧 소비 속도입니다.

각 모델은 토큰당 크레딧 소비량이 다릅니다:

이 숫자가 의미하는 것: GPT-5.4 Mini를 GPT-5.5 대신 사용하면, 동일한 월간 구독으로 6배의 작업량이 가능합니다.

현명한 구분 사용 전략:

• 일상적인 단순 태스크 → GPT-5.4 Mini (코드 읽기, 작은 버그 수정, 테스트 작성, 질문)
• 중간 정도의 복잡도 → GPT-5.4 (리팩터링 (Refactoring), 디버깅 (Debugging), 기능 추가)
• 고난도 태스크만 → GPT-5.5 (아키텍처 리뷰 (Architecture Review), 보안 감사 (Security Audit), 복잡한 크로스 모듈 변경)

추론 레벨이 높을수록 크레딧 소비도 증가합니다. 일상은 Medium, 단순 태스크는 Low, 복잡한 태스크만 High로 설정하십시오.

동일한 시스템 프롬프트(System Prompt)와 프로젝트 컨텍스트를 반복해서 사용하면 → 캐시(Cache)가 활성화되어 → 소비량이 대폭 감소합니다.

실측 데이터 (1,000만 토큰 처리 시):

• GPT-5.5 캐시 없음: 약 $22.00
• GPT-5.5 높은 캐시 히트 (Cache Hit): 약 $1.25
• GPT-5.4 Mini 높은 캐시: 약 $0.24

동일한 스레드에서 대화를 지속하고, 불필요하게 새로운 세션을 만들지 않는 것이 캐시 히트율을 최대화하는 비결입니다.

프로젝트 단위가 아니라, 태스크 단위로 스레드를 만드십시오.

컨텍스트의 팽창은 출력 품질을 조용히 갉아먹는 가장 큰 요인입니다. 하나의 스레드에 축적되는 정보가 많아질수록, Codex는 노이즈 속에서 관련 정보를 찾아내지 못하게 됩니다.

Codex는 멀티 에이전트 (Multi-agent) 병렬 작업에 대응합니다. 단, 조건은 쓰기 범위가 충돌하지 않는 것입니다.

✅ 좋은 분할:

• 백엔드 변경 + 문서 업데이트
• 한 명은 테스트 작성, 다른 한 명은 근본 원인 조사
• 한 명은 구현, 다른 한 명은 리뷰만 수행
• 여러 명이 각각 대안을 제안

❌ 나쁜 분할:

• 여러 명이 동일한 파일 그룹을 동시에 편집
• 요구사항이 확정되지 않은 상태에서 여러 구현을 병행 실행
• 스키마와 그 호출 측이 조정 없이 동시에 변경

① /init → AGENTS.md 초기 버전 자동 생성
② AGENTS.md 편집 → 빌드 명령어, 제약 사항, 패턴 추가
③ ~/.codex/config.toml 설정 → 모델, 추론 레벨, 승인 전략
...

① 태스크별로 새 스레드 생성
② 4요소 프롬프트 (목표 → 문맥 → 제약 → 완료 조건)
③ 복잡한 태스크는 Plan 모드
...

① 동일한 실수가 2번 발생 → AGENTS.md 업데이트
② Skill이 안정화됨 → Automation 설정
③ 정기적으로 세션을 회고 → 설정 및 AGENTS.md 업데이트

OpenAI 공식 문서의 말을 빌리자면 다음과 같습니다:

"Codex는 단순히 코드를 생성하는 데 그쳐서는 안 됩니다. 적절한 지침(Instructions)이 있다면, 코드를 테스트하고, 점검하며, 리뷰하는 데에도 도움을 줄 수 있습니다."

Codex에게 코드를 작성하게 하는 것만으로는 불충분합니다. 완전한 루프(Loop)를 돌리세요:

코드 변경 → 테스트 작성/업데이트 → 테스트 실행 → lint/타입 체크
→ 동작 확인 → diff 리뷰 → 회귀(Regression) 발견

이 글이 길었으므로, 가장 중요한 3가지 포인트로 요약하겠습니다:

첫째: AGENTS.md를 작성할 것. 10분의 초기 설정으로 매일 30분을 절약할 수 있습니다. Codex를 기억 상실증에 걸린 도구에서, 당신의 프로젝트를 이해하고 있는 팀메이트로 바꾸는 가장 중요한 파일입니다.

둘째: 태스크(Task)에 따라 모델을 선택할 것. 일상적인 단순 작업은 GPT-5.4 Mini + Low 추론으로도 충분합니다. 크레딧 소비를 60~80% 절감할 수 있습니다.

셋째: 1태스크 1스레드, 분기에는 /fork를 사용할 것. 컨텍스트 팽창(Context Bloat)은 Codex의 출력 품질을 조용히 죽이는 가장 큰 요인입니다.

진화의 경로: AGENTS.md → Config → Skills → Automations. 한 걸음씩이면 충분합니다. Skills가 방법을 정의하고, Automations가 리듬을 정의합니다.

📖 초보자 가이드를 아직 읽지 않으셨나요? 먼저 이것부터 확인하세요: 처음 Codex를 사용할 때, 나는 단 세 가지만을 요청했다 — 다운로드부터 첫 코드 변경까지. 본 가이드는 OpenAI 공식 Codex 문서와 커뮤니티의 실전 사례를 바탕으로 작성되었습니다. 가격 정보는 2026년 6월 기준입니다. 최신 정보는 openai.com 에서 확인하시기 바랍니다.