Codex CLI 입문(2) : OpenAI Codex 핵심 개념 4가지 - Prompting, Memories, Sandboxing, Models

안녕하세요! 갓대희 입니다.

Codex를 처음 써본 뒤 "명령이 뜻대로 안 된다"거나 "같은 실수를 반복한다"는 느낌이 든 적이 있다면, 꼭 도구 탓만은 아닐 수 있다. Codex가 무엇을 읽고, 어떤 기준으로 판단하고, 어디까지 실행하는지 모른 채 맡겼을 가능성이 크다.

 

이번 글에서는 Codex를 제대로 쓰기 위해 먼저 알아야 할 네 가지 — 프롬프트(Prompting), 메모리(Memories), 샌드박스(Sandboxing), 모델(Models) — 를 공식 문서를 바탕으로 정리한다.

이 글은 2026년 5월 기준 공식 문서(developers.openai.com/codex)를 바탕으로 작성되었다. 기능은 지속 업데이트되므로 최신 정보는 공식 문서에서 확인한다.

먼저 용어부터 가볍게 잡고 가자

 - 프롬프트 : Codex에게 보내는 지시문이다.

 - 컨텍스트 : Codex가 함께 참고할 파일, 코드, 이미지 같은 자료다.

 - 샌드박스 : Codex가 함부로 파일을 바꾸거나 명령을 실행하지 못하게 막는 안전 울타리이고, 모델은 실제로 답을 만들고 판단하는 AI 엔진이라고 보면 된다.

 - 작업 범위 : Codex에게 맡기는 일의 크기다. 예를 들어 "읽기만 해라", "이 폴더 안 파일만 고쳐라", "위험한 명령은 먼저 물어봐라"처럼 정하는 것이다.

 - 승인 정책 : Codex가 경계를 넘으려 할 때 나에게 먼저 물어볼지 정하는 규칙이다.

앞선 CLI 빠른 시작 편과 이 글의 차이

앞선 글의 샌드박스 설명은 "처음 켤 때 어떤 안전 설정으로 시작할까"에 가까웠다.

이 글에서는 한 단계 더 들어가서 이번 작업을 Codex에게 어디까지 맡겨도 되는지를 고르는 법을 다룬다. 프롬프트·메모리·모델도 결국 이 판단과 함께 움직인다.

즉. Codex가 읽기만 할지, 프로젝트 안에서 수정해도 될지, 명령 실행은 언제 물어봐야 할지를 판단할 수 있도록 이해 하는게 이번글에서의 목표이다..

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (현재 글) Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

목차

1. 프롬프트(Prompting) — 좋은 지시의 4원칙
2. 메모리(Memories) — AGENTS.md와 로컬 메모리
3. 샌드박스(Sandboxing) — 3가지 권한 레벨 선택 가이드
4. 모델(Models) — 어떤 모델을 언제 쓸까
5. 정리: 4개 개념이 어떻게 연결되는가
6. Part 3 예고

4개 개념을 한 장으로 보면

개념	결정하는 것	흔한 실패
프롬프트(Prompting)	이번 작업의 목표와 완료 기준	범위가 넓어져 엉뚱한 파일까지 수정
메모리(Memories) / AGENTS.md	반복해서 지킬 배경 규칙	매번 같은 설명을 다시 하거나 팀 규칙을 놓침
샌드박스(Sandboxing)	Codex가 실제로 실행할 수 있는 경계	권한이 좁아 작업이 막히거나, 너무 넓어 위험해짐
모델(Models)	속도, 비용, 추론 깊이	가벼운 작업에 과한 모델을 쓰거나 복잡한 작업에 너무 약한 모델을 씀

초심자라면 순서를 이렇게 잡으면 편하다. 먼저 프롬프트로 할 일을 정한다. 반복해서 지켜야 할 규칙은 AGENTS.md에 둔다. 샌드박스로 Codex가 건드릴 수 있는 파일과 명령을 제한한다. 마지막으로 작업 난이도와 비용에 맞춰 모델을 고른다.

 

1. 프롬프트(Prompting) — 좋은 지시의 4원칙

Codex는 지시가 명확할수록 더 잘 작동한다.

프롬프트는 쉽게 말해 "Codex에게 보내는 작업 지시서"다. 공식 Prompting 문서에서는 검증 가능성, 작업 분해, 계획 요청, 스레드 같은 기본 개념을 설명한다. 이 글에서는 초심자가 바로 써먹기 쉽도록 4가지 원칙으로 나눠 보자.

 

Codex는 프롬프트를 받으면 모델을 호출하고, 파일을 읽거나 고치고, 도구를 실행하는 Loop를 반복한다. 작업이 끝났다고 판단하거나 내가 취소할 때까지다. 그러니 프롬프트에는 "무엇을 할지"와 함께 "언제 멈추는지"도 같이 적어두는 게 낫다.

 

1.1 검증 가능성(Verifiability): 결과를 확인할 수 있게 만든다

Codex는 자신의 작업을 확인할 방법이 있을 때 더 좋은 결과를 낸다.

버그를 다시 만드는 순서, 기능이 맞게 동작하는지 확인하는 방법, 린트나 프리커밋 체크 실행 방법을 함께 적어 줄수록 좋다. 여기서 린트는 코드 스타일과 흔한 실수를 자동으로 검사하는 도구이고, 프리커밋 체크는 커밋 전에 자동으로 돌리는 검사라고 보면 된다.

 

단순히 "이 버그를 고쳐라"보다 "버그를 고친 후 npm test로 회귀 테스트가 통과하는지 확인하라"처럼 검증 조건을 명시하면 Codex가 스스로 작업 완성 여부를 판단할 수 있다. 회귀 테스트는 고친 문제가 다시 생기지 않는지 확인하는 테스트이다.

 

1.2 작업 분해(Task Decomposition): 작게 나눌수록 잘 처리한다

복잡한 작업은 작게 나눌수록 Codex가 더 잘 처리한다. 예를 들어 "게시판을 개선해줘"보다 "검색 버그를 고치고, 그다음 빈 결과 화면 문구를 바꿔줘"처럼 나누는 식이다. 작은 단위의 작업은 Codex가 테스트하기도 쉽고, 개발자가 결과를 검토하기도 쉽다.

분해 방법을 모른다면, 직접 분해하지 않아도 된다.

 

1.3 계획 먼저(Plan First): 분해가 막히면 계획을 먼저 요청한다

분해 방법이 막힐 때는 Codex에게 먼저 계획을 제안하게 하면 된다. 그러면 Codex가 접근 순서를 먼저 정리하고, 개발자는 그 계획을 보고 다음 구현 지시로 이어갈 수 있다.

예를 들어 "이 기능을 추가할 계획을 먼저 만들어라. 구현은 내가 검토한 뒤 진행하겠다"처럼 지시하면, 실행 전에 방향을 조율할 수 있다.

Plan mode는 초심자에게 특히 중요하다

/plan으로 현재 대화를 계획 모드로 바꿀 수 있다.
큰 리팩토링, 마이그레이션, 원인 모르는 장애처럼 바로 수정하면 위험한 일은 먼저 /plan으로 접근하는 편이 안전하다.
현재 CLI에서는 Shift+Tab으로 모드를 전환할 수 있는 환경도 있지만, 단축키는 키맵에 따라 바뀔 수 있다.

ex) shift + tab 으로 모드를 변경 가능하며 계획을 먼저 세우게 된다. (너무 간단한 내용은 바로 수행하기도 한다.)

 - 계획을 세워주며

 - 해당 계획대로 수행할지, 쌓여있는 context를 비우고 수행할지, 플랜모드를 통해 계속 계획모드를 개선할지 등 선택 가능하다.

 

1.4 컨텍스트 제공(Context): 관련 파일과 이미지를 함께 넣는다

프롬프트를 제출할 때 관련 파일, 이미지 같은 컨텍스트를 함께 넣어야 한다. 컨텍스트는 Codex가 답을 만들 때 참고하는 배경 자료다. Codex IDE 확장을 쓴다면 열린 파일 목록과 선택된 텍스트 범위가 자동으로 컨텍스트에 포함된다.

 

CLI에서는 스레드(thread) 개념을 이해하면 컨텍스트 관리가 쉬워진다. (어려운 용어면 데충 넘어가자)

CLI는 터미널에서 명령어로 쓰는 방식이고, 스레드는 "Codex의 한 번의 작업 세션"에 가깝다. 처음 보낸 프롬프트, Codex의 답변, 도구 실행 기록이 한 스레드 안에 쌓인다. 한 스레드 안에 여러 프롬프트를 이어서 넣을 수 있고, 나중에 이어서 재개할 수도 있다.

 

다만 여러 스레드를 동시에 돌릴 때는 주의해야 한다.

공식 문서는 여러 스레드를 동시에 실행할 수는 있지만, 두 스레드가 같은 파일을 동시에 수정하지 않도록 피하라고 안내한다.

초심자라면 한 작업이 끝난 뒤 다음 작업을 맡기는 방식이 가장 안전하다.

 

스레드는 실행 위치에 따라 로컬 스레드와 클라우드 스레드로도 나눠 볼 수 있다.

로컬 스레드는 내 컴퓨터에서 샌드박스 안에 실행되고, 클라우드 스레드는 저장소를 별도로 가져와 원격 환경에서 작업한다.

처음에는 로컬에서 흐름을 익히고, 병렬 작업이나 위임이 필요해졌을 때 클라우드 작업을 보는 편이 이해하기 쉽다.

CLI 컨텍스트 팁: IDE 확장은 열린 파일과 선택한 코드가 자동으로 컨텍스트에 들어가는 편이다. CLI에서는 보통 파일 경로를 직접 적거나, /mention <path>로 관련 파일을 현재 대화에 붙이는 것이 좋다.

 

프롬프트 예시 5가지

상기 이미지 처럼 하고자 하는 내용을 잘 설명 하면 되는게 프롬프트가 아닐까? 

( 모르는 것은 AI에게 도움을 받고, 내가 잘 설명할수있는것은 잘 설명 하는 것??)

 

5개의 예시로 상기 내용을 이해해보자.

💡 왜 영문 프롬프트인가?

Codex를 포함한 대부분의 AI 코딩 도구는 영문 프롬프트에서 더 정확하고 일관된 결과를 낸다.

학습 데이터의 대부분이 영어 코드베이스·문서이기 때문이다.

실제 사용 시에는 영문으로 작성하는 것을 권장한다. 다만 처음 접하는 독자의 이해를 돕기 위해 각 예시 아래에 한글 번역을 함께 제공한다.

 

예시 1 — 프로젝트 분석 (Workflows 문서 제공 예시)

Explain how the request flows through the selected code.

Include:
- a short summary of the responsibilities of each module involved
- what data is validated and where
- one or two "gotchas" to watch for when changing this

한글로 이해하기

선택한 코드를 통해 요청이 어떻게 흐르는지 설명해줘.

포함할 내용:
- 관련된 각 모듈의 역할 요약
- 어디서 어떤 데이터가 검증되는지
- 이 부분을 수정할 때 주의해야 할 함정 1~2가지

단순히 "이 코드를 설명해라"보다 포함할 항목을 명시하면 Codex가 더 유용한 분석을 돌려준다.

 

예시 2 — 기능 추가 (Prompting 문서 제공 예시)

Add a new command-line option `--json` that outputs JSON.

한글로 이해하기

JSON을 출력하는 새 커맨드라인 옵션 `--json`을 추가해줘.

범위가 명확한 요청이다. 새 옵션의 이름과 동작을 한 줄로 정했기 때문에 Codex가 어디서부터 어디까지 작업해야 하는지 판단하기 쉽다.

 

예시 3 — 디버깅 (Workflows 문서 제공 예시)

Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.

Repro:
1) Start the app: npm run dev
2) Go to /settings
3) Toggle "Enable alerts"
4) Click Save
5) Refresh the page: the toggle resets

Constraints:
- Do not change the API shape.
- Keep the fix minimal and add a regression test if feasible.

Start by reproducing the bug locally, then propose a patch and run checks.

한글로 이해하기

버그: 설정 화면에서 "저장" 버튼을 누르면 "저장됨"이 표시되는데,
실제로는 변경사항이 유지되지 않는 경우가 있다.

재현 방법:
1) 앱 실행: npm run dev
2) /settings 이동
3) "알림 활성화" 토글
4) 저장 클릭
5) 페이지 새로고침 → 토글이 원래대로 돌아옴

제약 사항:
- API 구조는 변경하지 않는다.
- 수정은 최소한으로 하고, 가능하면 회귀 테스트를 추가한다.

버그를 로컬에서 먼저 재현한 다음, 패치를 제안하고 검사를 실행한다.

이 예시가 잘 작동하는 이유는 세 가지다. 재현 단계를 구체적으로 적었고, 건드리면 안 되는 범위를 못 박았고, Codex가 먼저 문제를 재현한 뒤 패치를 제안하도록 순서를 정했다.

 

예시 4 — 리팩토링 전 계획 세우기 (/plan 응용)

/plan Refactor the payment validation flow safely.

Start by reading the current validation path and tests.
Do not edit files yet.

Return:
- files that probably need changes
- behavior that must stay the same
- risks and edge cases
- the smallest implementation steps
- tests to run before and after the change

한글로 이해하기

/plan 결제 유효성 검사 흐름을 안전하게 리팩토링한다.

현재 유효성 검사 경로와 테스트를 먼저 읽는다.
아직 파일을 편집하지 않는다.

반환할 내용:
- 변경이 필요할 가능성이 있는 파일
- 그대로 유지해야 하는 동작
- 위험 요소와 엣지 케이스
- 가장 작은 구현 단계
- 변경 전후에 실행할 테스트

이런 프롬프트는 "바로 고쳐줘"보다 안전하다. Codex가 먼저 영향 범위와 테스트 기준을 정리하므로, 개발자는 계획을 보고 범위를 줄이거나 빠진 조건을 보완한 뒤 실행으로 넘어갈 수 있다.

 

예시 5 — 실패한 테스트를 기준으로 원인 좁히기

Test failure:
- command: pnpm test -- auth
- failing test: should refresh an expired session token
- error: expected 200, received 401

Goal:
Find the root cause and make the smallest safe fix.

Constraints:
- Do not change the public API response shape.
- Do not rewrite the auth module.
- Add or update one regression test if the fix changes behavior.

Completion:
Run the focused auth test, then tell me what changed and why.

한글로 이해하기

테스트 실패:
- 명령어: pnpm test -- auth
- 실패 테스트: 만료된 세션 토큰을 갱신해야 한다
- 오류: 200 예상, 401 수신

목표:
근본 원인을 찾고 가장 작고 안전한 수정을 한다.

제약 사항:
- 공개 API 응답 형태를 변경하지 않는다.
- auth 모듈을 재작성하지 않는다.
- 수정이 동작을 바꾼다면 회귀 테스트를 하나 추가하거나 업데이트한다.

완료 기준:
집중 auth 테스트를 실행하고, 무엇이 왜 바뀌었는지 알려준다.

개발자에게 가장 와닿는 프롬프트는 보통 실패한 명령, 실패한 테스트 이름, 바꾸면 안 되는 계약, 완료 조건을 함께 준다. 이렇게 쓰면 Codex가 "대충 고쳐 보기"보다 원인을 좁혀서 움직이기 쉽다.

 

더 많은 프롬프트 패턴은 공식 Workflows 문서에서 확인한다.

초심자용 프롬프트 점검표

• 목표: 무엇을 고치거나 만들 것인지 한 문장으로 적었는가?
• 맥락: 관련 파일, 화면, 오류 메시지, 재현 단계를 줬는가?
• 제약: 바꾸면 안 되는 API, UI 문구, 파일 범위를 적었는가?
• 완료 기준: 어떤 테스트나 확인이 통과해야 끝인지 적었는가?

 

1.5 따라 해보는 실전 튜토리얼 프롬프트 3가지

앞의 예시들은 실무 코드베이스에서 쓰는 방식이었다. Codex가 처음이거나 개발을 막 시작한 사람이라면 어디서부터 써야 할지 막막할 수 있다. 여기서는 "지금 바로 따라 해볼 수 있는" 시나리오 세 가지를 프롬프트 한 줄씩 뜯어보면서 설명한다.

공통 패턴: 세 예시 모두 같은 구조를 따른다 — 목표(Goal) → 설정(Setup) → 기능/규칙 → 제약(Constraints) → 완료 기준(Completion). 이 순서를 익히면 어떤 작업에도 응용할 수 있다.

 

"넌 전문가야" — 꼭 써야 하나?

예전에 ChatGPT 쓸 때 "넌 시니어 개발자야", "넌 HTML/CSS 전문가야" 같은 역할 주입을 많이 했다. 효과가 있었다. 지시가 모호하니까 역할로 방향을 잡으려던 거다.

 

Codex 같은 에이전트 도구에서는 점점 안 써도 되는 방향으로 흐르고 있다. 이유는 단순하다. Constraints가 페르소나보다 정확하게 범위를 잡아준다.

"넌 바닐라 JS 전문가야"는 스타일 힌트다. 반면 "외부 라이브러리 없이 index.html 하나로 동작해야 한다"는 범위 제한이다. Codex는 후자를 훨씬 잘 따른다.

 

페르소나가 여전히 쓸모 있는 경우는 있다. 설명 수준("초보자에게 설명하듯 주석을 달아라"), 피드백 스타일("시니어 코드 리뷰 스타일로"), 특정 관점("프론트엔드 입장에서 UX 문제를 찾아라") 같은 뉘앙스는 Constraints로 잡기 어렵다. 코드 생성 작업이라면 Goal + Constraints + Completion이 "넌 전문가야" 한 줄보다 낫다.

 

그런데… 꼭 이렇게 써야 할까?

지금까지 설명한 구조화된 프롬프트는 분명히 효과가 있다. 하지만 반대 관점도 있다. 모델이 계속 발전하면서, 오히려 규칙을 모르는 채로 자유롭게 바이브 코딩(vibe coding)하는 사람들이 더 창의적인 결과를 낸다는 이야기가 나온다. 머릿속에 있는 걸 그냥 말하듯 던지면, 모델이 알아서 채워준다는 것이다.

어느 쪽이 맞다기보다, 모델이 강해질수록 프롬프트의 최소 요건이 낮아진다는 말이 더 정확하다. 구조를 알면 정확하게 쓸 수 있고, 몰라도 일단 시작할 수 있다. 아래 예시에서는 두 가지 버전을 모두 보여준다. 먼저 구조화된 프롬프트로 어떻게 작동하는지 보고, 그다음 한두 줄짜리 바이브 버전으로 여러분이 직접 해보자.

 

예시 A — HTML 파일 하나로 게임 만들기

요즘 LLM은 숫자 맞추기 같은 간단한 게임을 넘어선 지 오래다. 갤러그, 1945 스타일의 슈팅 게임도 싱글 프롬프트 하나면 동작하는 코드가 나온다. 모델이 얼마나 발전했는지 직접 체감하고 싶다면, 이 예시부터 시작해보자. HTML 파일 하나를 브라우저로 열기만 하면 된다.

Goal:
싱글 HTML 파일로 갤러그 스타일 우주 슈팅 게임을 만들어라.

Rules:
- 플레이어 우주선은 좌우 방향키(또는 A/D)로 이동, 스페이스바로 총알 발사
- 적 우주선은 위에서 아래로 내려오며 화면 하단에 닿으면 게임 오버
- 총알이 적에게 맞으면 적이 사라지고 점수가 오른다
- 웨이브마다 적 생성 속도가 빨라진다
- 플레이어는 목숨 3개 — 적과 충돌 시 1개 감소
- 화면 상단에 점수와 남은 목숨 표시
- 게임 오버 시 최고 점수와 함께 "다시 시작" 화면 표시

Constraints:
- HTML, CSS, JavaScript를 index.html 파일 하나에 모두 작성한다
- 외부 라이브러리 없이 브라우저에서 파일을 열기만 해도 동작해야 한다
- Canvas API로 렌더링한다

Completion:
index.html을 크롬으로 열어 적 5마리를 격추하고,
일부러 적과 충돌해 목숨이 줄어드는지 확인한다.
"다시 시작"을 눌러 점수가 초기화되는지 확인한다.

프롬프트 줄별 해설

• Goal: "게임 만들어줘"보다 "갤러그 스타일 우주 슈팅 게임"이 구체적이다. 레퍼런스 타이틀 하나로 UI·조작감·난이도 흐름까지 Codex가 공통 인식을 갖는다.
• Rules (목록으로): 조작키, 충돌 판정, 목숨 수를 미리 못 박지 않으면 Codex가 임의로 채운다. 나중에 "왜 목숨이 5개야"라며 다시 고치는 수고를 줄인다.
• Constraints의 핵심 줄: "Canvas API로 렌더링한다" — 이 줄을 빠뜨리면 Codex가 DOM 엘리먼트를 CSS로 움직이는 방식을 택할 수 있다. 게임 루프가 필요한 작업엔 렌더링 방식을 명시하는 게 낫다.
• Completion: "동작 확인"이 아니라 "적 5마리 격추 → 충돌 → 다시 시작"처럼 검증 시나리오를 구체적으로. Codex가 어떤 흐름으로 테스트해야 하는지 알 수 있다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 두 줄을 그대로 Codex에 붙여넣고 어떤 결과가 나오는지 확인해보자.

갤러그 스타일 우주 슈팅 게임을 HTML 파일 하나로 만들어줘.
방향키로 움직이고 스페이스바로 쏘는 거야. 외부 라이브러리 없이.

ex) 결과 캡쳐

 - 3분 34초 만에 개발 완료 하였다.

 - 사용 모델 5.5 / reasoning effort : high / fast 모드 사용

   (지금은 모델을 알 필요 없다. 모델과 관련된 자세한 내용은 단락 4에 작성해 두었다.)

 

예시 B — React로 할 일 목록 앱 만들기

처음 React를 배울 때 가장 많이 만드는 게 할 일 목록이다. 상태 관리와 이벤트 처리 두 가지를 익히기에 딱 맞다. 백엔드는 없어도 된다.

Goal:
Vite + React로 간단한 할 일 목록(To-do) 앱을 만들어라.

Setup:
프로젝트가 없다면 아래 명령으로 만든다:
  npm create vite@latest my-todo-app -- --template react
  cd my-todo-app && npm install

Features:
- 입력창에 할 일을 입력하고 버튼(또는 Enter)으로 추가한다
- 각 항목에 완료 체크박스와 삭제 버튼이 있다
- 완료된 항목은 텍스트에 취소선이 생긴다

Constraints:
- 상태 관리는 useState만 쓴다 (Redux, Context, Zustand 불필요)
- 백엔드와 데이터베이스 없이 컴포넌트 상태로만 동작한다
- 스타일은 App.css 파일 하나에 간단히 작성한다

Completion:
npm run dev 실행 후 http://localhost:5173 에서
할 일 추가 → 체크 → 삭제 순서로 동작하는지 확인한다.

프롬프트 줄별 해설

• Setup 줄: "Vite + React"로 기술 스택을 고정했다. 이 줄이 없으면 Codex가 Create React App, Next.js, Parcel 중에서 하나를 알아서 골라 만들어 온다. 처음엔 어떤 차이인지 파악하기 어려우니 그냥 막막해진다.
• Features의 구체성: "CRUD 기능을 구현해라"보다 "버튼 또는 Enter로 추가, 체크박스로 완료, 삭제 버튼"처럼 UI 동작을 써주면 Codex가 빠뜨리는 기능이 줄어든다.
• Constraints의 핵심 줄: "useState만 쓴다"와 "백엔드 없이". 이 두 줄을 빠뜨리면 Redux Toolkit에 Firebase까지 붙여 오는 경우가 생긴다. 초보자에겐 지금 당장 필요 없는 것들이다.
• Completion: "추가 → 체크 → 삭제 순서로"처럼 시나리오를 주면 Codex가 어떤 흐름으로 테스트해야 하는지 명확하게 안다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

React로 할 일 목록 앱 만들어줘. 추가, 완료 체크, 삭제 되는 거. useState만 써.

ex) 결과 요약

 - 직접 서버를 띄우고, 브라우저까지 띄워 테스트 완료 하였다. 

  - 완료 결과 보고 

  - 직접 브라우저로 결과 확인

 

예시 C — Next.js로 간단한 소개 페이지 만들기

Next.js는 React 기반 프레임워크다. 배포가 쉽고 SEO 설정이 편리해 개인 포트폴리오나 소개 페이지를 만들 때 많이 쓴다. 백엔드 없이 정적 페이지 2개만 만드는 것부터 시작하자.

Goal:
Next.js로 간단한 개인 소개 사이트를 만들어라.

Setup:
프로젝트가 없다면 아래 명령으로 만든다:
  npx create-next-app@latest my-profile --app --tailwind --no-src-dir --no-typescript
  cd my-profile

Pages:
- app/page.js (홈): 이름, 한 줄 소개, 간단한 자기소개 문단
- app/about/page.js (소개): 기술 스택 목록 (HTML, CSS, JavaScript 등)

Navigation:
- 상단에 "홈"과 "소개" 페이지를 오가는 링크를 넣는다

Constraints:
- 데이터베이스 없음, 로그인 없음, 서버 API 없음
- 정적 페이지 2개와 nav만 만든다
- Tailwind CSS로 간단히 스타일을 입힌다

Completion:
npm run dev 후 홈과 소개 페이지 이동이 되는지,
nav 링크가 양쪽 방향으로 동작하는지 확인한다.

프롬프트 줄별 해설

• Setup 플래그들: --app(App Router 사용), --tailwind(Tailwind 포함), --no-typescript(TypeScript 제외). 플래그를 생략하면 Codex가 추측해서 TypeScript 파일로 만들어 올 수 있다. 초보자라면 TypeScript는 나중에 배워도 늦지 않는다.
• Pages 줄: 파일 경로(app/page.js, app/about/page.js)를 명시했다. "소개 페이지도 만들어줘"보다 경로까지 주면 Codex가 어디에 파일을 만들지 결정하지 않아도 된다.
• Constraints의 "없음 3가지": 데이터베이스 없음, 로그인 없음, 서버 API 없음. 이 세 줄이 핵심이다. 안 적으면 "소개 페이지"라는 말에 Codex가 서버 컴포넌트나 API Route까지 만들어 올 수 있다. 지금 필요한 건 정적 페이지뿐이다.
• Completion의 "양쪽 방향으로": nav 링크를 홈→소개, 소개→홈 둘 다 눌러보라는 뜻이다. 이렇게 적으면 Codex가 한쪽 링크만 만들어두고 완료라고 할 가능성이 줄어든다.

여러분이 직접 해보자 — 바이브 코딩 버전

구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.

Next.js로 내 소개 페이지 만들어줘. 홈이랑 소개 탭 두 개, Tailwind로 예쁘게.

ex) 결과 요약

 - 직접 서버를 띄우고, 브라우저까지 띄워 테스트 완료 하였다. 

 - 결과 

 - 한방에 끝내기 하쉽다면 여기서 계속 개선 사항을 요구하여 이어 나가면 된다. 

ex) 지금 결과를 목 데이터로 채워도 상관없으니, 디자인 개선을 하고싶은데 사람인 스타일 또는 링크드인 스타일로 변경해줘

  - 개선 결과

세 예시에서 반복된 패턴

기술 스택과 파일 구조를 명시하고, 제약 조건으로 범위를 좁히고, 완료 기준을 구체적으로 준다. 이 세 가지만 챙겨도 Codex가 "알아서 결정"하는 일이 크게 줄어든다.

 

2. 메모리(Memories) — AGENTS.md와 로컬 메모리

Codex에는 메모리와 AGENTS.md 같은 지속 지침이 따로 있다.

메모리는 이전 대화의 맥락을 이어 주고, AGENTS.md는 작업할 때 따라야 할 지침을 담는다.

둘 다 Codex에게 배경지식을 주지만, 쓰임새는 다르다.

( 해당 세션은 중요한 주제인데, 초반에 무겁게 다루기엔 어려운 내용이니 최대한 간단히 알아보고 나중에 자세히 다루기로 한다. )

 

2.1 AGENTS.md — 반복 규칙을 저장소에 남기는 장치

AGENTS.md는 Codex가 작업할 때 계속 참고하는 지침 파일이다.

예를 들면 "테스트는 이 명령으로 실행한다", "새 의존성(외부 라이브러리)은 함부로 추가하지 않는다" 같은 반복 규칙을 넣는다.

공식 Customization 문서와 AGENTS.md 가이드에 따르면 전역 지침, 저장소 지침, 하위 폴더 지침을 함께 사용할 수 있다.

구분	역할	이 글에서 기억할 것
전역 지침	개인 기본값	모든 프로젝트에서 유지하고 싶은 습관
저장소 지침	팀 공통 규칙	빌드·테스트 명령, 리뷰 기준, 금지 변경
하위 폴더 지침	특정 영역 규칙	프론트엔드, 백엔드, 문서 폴더처럼 영역별로 다른 기준

Codex는 전역 지침을 먼저 보고, 프로젝트 루트에서 현재 작업 폴더 방향으로 지침을 이어 붙인다.

 

이 글에서 필요한 수준은 여기까지다.

실제 파일 배치, 예외 파일, 길이 제한, Rules 정책처럼 팀 운영에 필요한 세부 내용은 별도 AGENTS.md · Rules 편에서 다루는 편이 낫다.

이 글의 경계: 여기서는 "AGENTS.md는 반복 규칙을 담는 배경 지침"이라는 역할만 잡는다. 구체적인 파일 배치, 예외 파일, 지침 길이 관리, 명령 실행 정책과 충돌 처리는 AGENTS.md · Rules 편의 본문 주제다.

 

AGENTS.md에 Karpathy의 4원칙 넣기

AGENTS.md를 어떻게 채울지 막막하다면 출발점으로 쓸 수 있는 원칙이 있다. 2026년 초 AI 연구자 Andrej Karpathy가 LLM 코딩의 반복 실패 패턴을 정리하면서 화제가 된 4가지 원칙이다. Forrest Chang이 이를 CLAUDE.md(Claude Code의 같은 역할 파일)로 만들어 공개했고, GitHub 10만 스타를 넘겼다. 이 원칙들은 AGENTS.md에도 그대로 적용된다.

코드 변경 시 4가지 원칙 (우선순위와 무관하게 모든 코드 변경 작업에 적용)

1. 가정하지 말고 표면화하라 — 불확실하면 멈추고 묻는다. 해석이 여러 개면 모두 제시한다.
2. 단순함이 우선 — 요청된 것만 구현한다. 추측성 추상화·유연성·방어 코드 금지.
3. 외과적 변경 — 요청과 직접 연결되지 않은 줄은 건드리지 않는다. 본인이 만든 orphan만 정리한다.
4. 검증 가능한 목표 — 작업 시작 전 성공 기준을 명시하고, 끝난 뒤 그 기준으로 자체 검증한다.

AGENTS.md에 넣으면 어떤 차이가 생기는지 두 가지 시나리오로 비교해본다. 아래 예시는 실제로 Codex에게 같은 프롬프트를 줬을 때 나오는 반응 차이다. (실제 결과 스크린샷은 직접 확인해보자.)

 

위치는 Codex로 작업할 프로젝트 폴더의 루트 경로에 추가하면 된다.

ex) 방금 생성한 NextJS 앱의 예시

 

 

비교 1 — 날짜 처리: 기존 라이브러리를 쓸까, 새로 설치할까

프롬프트: "결제 날짜를 'YYYY년 MM월 DD일' 형식으로 포맷하는 함수를 추가해줘"

 

AGENTS.md 없을 때

// Codex가 알아서 판단: "dayjs가 좋겠다"
// 먼저 설치하라고 안내하거나, 직접 package.json에 추가함
import dayjs from 'dayjs';

export function formatPaymentDate(date) {
  return dayjs(date).format('YYYY년 MM월 DD일');
}

프로젝트에 이미 date-fns가 있어도 Codex는 모른다. 새 의존성이 들어오고, 팀에서 "왜 갑자기 dayjs?"라는 리뷰 코멘트가 달린다.

 

AGENTS.md 있을 때

# AGENTS.md (저장소 루트)
## 의존성 규칙
- 날짜 처리는 이미 설치된 date-fns를 쓴다
- 새 npm 패키지를 추가하기 전에 반드시 물어봐라

// Codex가 AGENTS.md를 읽고: "date-fns를 써야 한다"
import { format } from 'date-fns';
import { ko } from 'date-fns/locale';

export function formatPaymentDate(date) {
  return format(new Date(date), 'yyyy년 MM월 dd일', { locale: ko });
}

새 의존성이 생기지 않고, 리뷰어가 따로 지적할 일도 없다. Karpathy의 "단순함이 우선" 원칙이 여기서 동작한다 — 이미 있는 것을 쓰고, 없으면 먼저 물어본다.

 

비교 2 — 버그 수정 후: 테스트를 자동으로 돌릴까, 안 돌릴까

프롬프트: "로그인 세션 만료 버그를 고쳐줘"

 

AGENTS.md 없을 때

Codex 응답:
"auth.js의 세션 만료 로직을 수정했습니다.
토큰 갱신 타이밍을 조정하면 문제가 해결될 것입니다."

→ 코드만 수정하고 완료 보고
→ 어떤 테스트도 실행하지 않음
→ 개발자가 수동으로 확인해야 함

 

AGENTS.md 있을 때

# AGENTS.md (저장소 루트)
## 테스트 규칙
- 코드 수정 후 반드시 `npm test -- auth`를 실행한다
- 테스트가 실패하면 수정하지 않고 결과를 먼저 보고한다

Codex 응답:
"auth.js를 수정했습니다. AGENTS.md에 따라 npm test -- auth를 실행합니다.

결과: 3 passed, 0 failed
수정이 기존 테스트를 깨뜨리지 않음을 확인했습니다."

→ 수정 후 자동으로 인증 관련 테스트 실행
→ 테스트 통과 여부를 스스로 확인하고 보고

Karpathy의 "검증 가능한 목표" 원칙이다. AGENTS.md에 "수정 후 테스트를 실행한다"고 적어두면, 개발자가 매번 프롬프트에 "테스트도 돌려봐"를 적을 필요가 없다.

AGENTS.md 시작 템플릿: 처음 만든다면 아래 내용을 저장소 루트에 AGENTS.md로 저장하고 프로젝트에 맞게 채워가면 된다.

# AGENTS.md

## 테스트
- 코드 변경 후 [테스트 명령]을 실행한다

## 의존성
- 새 패키지를 추가하기 전에 반드시 물어봐라

## 코딩 규칙
- 불확실한 부분이 있으면 구현 전에 먼저 물어봐라
- 요청에 없는 파일은 건드리지 않는다

 

2.2 로컬 메모리 — ~/.codex/memories/

메모리 파일은 Codex 홈 디렉토리 아래에 저장된다. 기본 위치는 ~/.codex/memories/다.

공식 Memories 문서에 따르면, 이 파일에는 이전 대화의 요약, 오래 유지할 항목, 최근 입력, 그 내용을 뒷받침하는 증거가 들어간다.

메모리에 들어가기 좋은 내용은 안정적인 개인 선호, 반복되는 작업 흐름, 기술 스택, 프로젝트 관례, 자주 겪는 함정이다. 반대로 반드시 지켜야 하는 규칙은 AGENTS.md나 저장소 문서에 둬야 한다.

 

메모리는 모든 대화가 끝나는 즉시 만들어지는 기능이 아니다.

Codex는 활성 작업이나 너무 짧은 세션은 건너뛸 수 있고, 비밀값은 생성된 메모리 필드에서 가린다.

또한 스레드가 충분히 유휴 상태가 된 뒤 백그라운드에서 업데이트될 수 있으며, 남은 사용량이 낮으면 백그라운드 메모리 생성이 건너뛰어질 수 있다. 방금 끝낸 대화가 바로 메모리에 보이지 않아도 이상한 상황은 아니다.

 

중요한 점은 메모리 파일을 Codex가 만들어 둔 기록으로 봐야 한다는 것이다.

사람이 확인하거나 검토할 수는 있지만, 의도적인 동작 변경의 기본 수단으로 삼지는 않는다. 그런 변경은 설정, config, AGENTS.md 같은 명시적인 지침으로 관리하는 편이 안전하다.

Codex가 비밀값을 가리더라도, Codex 홈 디렉토리나 메모리 파일을 다른 사람에게 공유하기 전에는 민감한 내용이 없는지 직접 살펴보는 것이 좋다.

 

Codex 앱과 TUI에서는 /memories 명령으로 현재 스레드가 기존 메모리를 사용할지, 이 스레드를 앞으로의 메모리 생성에 사용할지 조절할 수 있다. 단, 이 설정은 현재 스레드 기준이고 전역 메모리 설정 자체를 바꾸는 것은 아니다.

 

ex) /memories를 사용하지 않고 기억해달라고 자연어로 해보았다. 

 - 이번 테스트에서는 AGENTS.md 에 저장하는 모습.  

 - /memories 입력 해보자. 다음과 같이 나올 것이다. 엔터 입력 >> 관련 설명은 이후 [ 2.3 ] 으로 바로 넘어 가자.

 - Yes > 엔터

 - 다음 대화 세션부터 적용된다는데 이럴때 팁은 일단 세션 종류 후, 다시 codex로 신규 대화 세션을 열고 기존 대화를 이어가면된다.

 

 - /exit 입력하여 완전히 빠져 나간후 codex 입력

 - 새로 코덱스창이 열리면 >> /resume 을 입력 한다.

  - 방금 하고있던 대화 내용을 확인하고 로드 하자.

 - 아까 AGENTS.md 에 저장하던 마지막 대화 내용이 그대로 로드 되는것을 볼 수 있다.

 - 기억해달라는 내용을 로컬 메모리에 저장하는 모습을 볼 수 있다.

 

2.3 메모리 활성화 방법과 주의사항

지역 제한 고지: 메모리 기능은 기본적으로 꺼져 있으며, 출시 시점 기준 유럽 경제 지역(EEA), 영국, 스위스에서는 사용할 수 없다.

활성화 방법은 두 가지다. 

위에서 보여드린대로 /memories 를 대화창에서 입력하여 Codex 설정에서 켜거나,

~/.codex/config.toml의 [features] 테이블에 아래와 같이 추가하면 된다.

[features]
memories = true

 

2.4 AGENTS.md vs 메모리 — 언제 무엇을 쓸까

공식 문서는 이 구분을 분명히 한다. 반드시 지켜야 하는 팀 규칙은 AGENTS.md 또는 버전 관리되는 문서에 보관한다. 메모리는 편리한 개인 기억으로 보고, 꼭 지켜야 하는 규칙의 유일한 근거로 쓰지 않는다.

 

실전 기준으로 정리하면 이렇다.

상황	사용할 도구
팀 전체가 따라야 하는 린트 규칙	AGENTS.md (저장소 루트)
PR 전 실행할 체크 명령	AGENTS.md (저장소 루트)
내가 선호하는 패키지 관리 방식	AGENTS.md (전역)
지난 스레드에서 배운 패턴	메모리 (자동 축적)
이번 작업에서만 참고할 특정 파일	프롬프트 경로, CLI /mention, IDE @파일명

예를 들어 팀에서 "PR 전에 npm run lint와 npm test를 반드시 실행한다"는 규칙은 AGENTS.md에 둔다.

이 규칙은 팀원이 바뀌어도 유지되어야 하기 때문이다. 반대로 "나는 설명을 한국어로 길게 듣는 편을 선호한다"처럼 개인 습관에 가까운 내용은 전역 AGENTS.md나 메모리로 충분하다.

"오늘 이 버그만은 API 응답 형식을 바꾸지 말라"처럼 일회성 제약은 프롬프트에 직접 쓰는 편이 가장 명확하다.

기억할 기준: 반복해서 지켜야 하는 팀 규칙은 AGENTS.md, 개인화된 작업 습관은 메모리, 이번 작업에만 적용되는 조건과 참고 파일은 프롬프트에 둔다. 명령 실행 정책처럼 더 구체적인 운영 규칙은 AGENTS.md · Rules 편에서 따로 다룬다.

 

3. 샌드박스(Sandboxing) — 3가지 권한 레벨 선택 가이드

Codex는 파일 접근과 명령 실행 권한을 샌드박스로 제어한다.

 

샌드박스는 말 그대로 안전 울타리다.

Codex가 내 컴퓨터 안에서 어디까지 읽고, 어디까지 수정하고, 어떤 명령을 실행할 수 있는지 정한다. 공식 Sandboxing 문서는 샌드박스의 목적을 "승인 피로 감소"로 설명한다. 여기서 승인 피로는 쉬운 명령마다 "허용할까요?"를 반복해서 묻는 바람에 사람이 지치는 상황을 말한다.

샌드박스는 위험이 낮은 작업은 정해진 울타리 안에서 진행하게 하고, 위험한 작업은 따로 막거나 확인받게 만든다.

 

여기서 자주 헷갈리는 부분이 있다. 샌드박스와 승인 정책은 같은 말이 아니다. 샌드박스는 Codex가 넘으면 안 되는 기술적인 경계이고, 승인 정책은 그 경계를 넘거나 특정 명령을 실행하려 할 때 사용자에게 물어볼지를 정하는 규칙이다. Codex가 git, 패키지 매니저, 테스트 러너 같은 명령을 실행할 때도 이 경계가 적용된다.

질문을 이렇게 바꿔 보자: "어떤 옵션이 있나?"보다 "이번 작업에서 Codex가 어디까지 해도 되나?"가 중요하다. 읽기만 시킬 작업, 파일을 고치게 할 작업, 패키지 설치까지 필요한 작업은 서로 다른 안전 울타리가 필요하다.

 

3.1 3가지 샌드박스 레벨

레벨	동작	기본 시작점	적합한 상황
read-only	파일을 읽어 분석하는 데 초점을 둔다. 수정이나 명령 실행은 제한된다	아님	코드 분석, 리뷰만 할 때
workspace-write	파일 읽기와 작업 폴더 안의 수정이 가능하다. 폴더 밖 작업이나 위험한 명령은 승인 정책을 따른다	권장 시작점	로컬 개발 일반 작업
danger-full-access	안전 울타리를 거의 푼다. 내 컴퓨터 파일과 네트워크 접근 제한이 크게 줄어든다	아님	Codex에 전체 접근 권한이 필요할 때만

한 줄로 요약하면: 처음에는 workspace-write + approval_policy = "on-request" 조합이 가장 무난하다.

프로젝트 폴더 안에서 고치는 일은 맡기되, 경계를 넘는 일은 물어보게 만드는 조합이기 때문이다.

danger-full-access는 정말 전체 권한이 필요할 때만 의도적으로 선택한다.

 

선택이 헷갈리면 아래 순서로 판단한다.

질문	권장 선택	이유
낯선 저장소를 읽기만 할 것인가?	read-only	수정 없이 구조만 파악하므로 울타리를 좁게 둔다.
현재 프로젝트 안에서만 파일을 고치면 되는가?	workspace-write + on-request	일반 개발 작업의 기본값이다. 폴더 밖 작업처럼 애매한 일만 따로 물어보게 한다.
다른 폴더도 일부 수정해야 하는가?	writable_roots	전체 권한을 열기보다 필요한 폴더만 추가로 연다.
사람 확인 없이 전체 권한 자동화가 필요한가?	전용 VM, 컨테이너, CI runner에서만 검토	로컬 작업 폴더에서 바로 쓰면 피해 범위가 커진다.

ex1) code --sandbox read-only

 - 수정자체가 불가능한건 아니다. 수정시 권한을 요청한다.

  - 권한 요청

ex2) code --sandbox workspace-write

 - 해당 프로젝트 내에서는 수정이 가능하다.

  - 별도의 권한 요청 없이 수정 완료 하였다.

 

3.2 승인 정책과의 조합

샌드박스 레벨은 승인 정책(approval_policy)과 함께 설정한다. 승인 정책은 Codex에게 언제 "물어보고 진행할지"를 정하는 옵션이다. 공식 문서에서 말하는 대표 정책은 untrusted, on-request, never다.

승인 정책	의미
untrusted	안전하다고 판단된 명령만 바로 실행하고, 나머지는 확인을 요청
on-request	샌드박스 안에서는 진행하고, 울타리 밖으로 나가려 할 때 확인을 요청
never	승인 질문을 하지 않는다. 실패하면 Codex가 그 결과를 보고 다음 방법을 찾는다

공식 문서에서 제시하는 두 가지 대표 조합은 다음과 같다.

 

완전 자동화 (주의 필요)

sandbox_mode = "danger-full-access"
approval_policy = "never"

 

저위험 로컬 자동화 (권장 시작점)

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

 

또는 CLI 플래그로 동일하게 설정할 수 있다.

codex --sandbox workspace-write --ask-for-approval on-request

작업 폴더 외의 다른 폴더도 함께 수정해야 한다면 무조건 danger-full-access로 올릴 필요는 없다.

 

공식 설정 문서 기준으로는 sandbox_workspace_write.writable_roots에 추가로 열어둘 폴더를 좁게 지정할 수 있다.

예를 들어 현재 프로젝트 밖의 공유 폴더 하나만 필요하다면, 전체 컴퓨터를 열기보다 그 폴더만 추가로 열어 주는 식이다.

초심자에게는 "필요한 폴더만 열어준다"는 감각이 중요하다.

 

3.3 config.toml 우선순위와 권한 프로필

샌드박스와 승인 정책은 대부분 config.toml에서 기본값으로 둔다.

개인 기본값은 ~/.codex/config.toml에 두고, 프로젝트별 예외는 저장소 안의 .codex/config.toml에 둘 수 있다. 단, 프로젝트 설정은 신뢰한 프로젝트에서만 로드된다.

 

우선순위도 알아두면 헷갈리지 않는다.

공식 문서 기준으로는 CLI 플래그와 --config가 가장 강하고, 그다음이 profile, 프로젝트 설정, 사용자 설정, 시스템 설정, 기본값 순서다. 즉, 오늘 한 번만 다르게 실행하려면 CLI 플래그를 쓰고, 계속 유지할 기본값은 config에 넣는 식으로 나누면 된다.

 

 

권한 설정을 매번 직접 조합하기 번거롭다면 default_permissions를 사용할 수 있다. 여기서 헷갈리기 쉬운 말이 permission profile이다. 쉽게 말해 permission profile은 여러 권한 설정을 묶어 놓은 프리셋에 가깝고, sandbox mode는 그중 "파일과 명령을 어디까지 허용할지"를 정하는 한 항목이다.

read-only, workspace-write, danger-full-access는 sandbox mode 이름이고, default_permissions = "workspace" 같은 값은 여러 설정을 묶어 고르는 예시로 읽으면 된다. 처음에는 제한이 있는 설정부터 시작한다.

주의: danger-full-access + approval_policy = "never" 조합은 Codex가 거의 모든 작업을 확인 없이 실행하게 만든다. 실험용 폴더처럼 충분히 통제된 환경에서만 쓰는 편이 안전하다.

 

4. 모델(Models) — 어떤 모델을 언제 쓸까

모델은 Codex 안에서 실제로 답을 만들고 판단하는 AI 엔진이다. 같은 Codex라도 어떤 모델을 쓰느냐에 따라 속도, 비용, 얼마나 깊게 따져 보는지가 달라진다. Codex가 사용하는 모델은 공식 Models 문서에서 확인한다. 2026년 5월 기준 Codex에서 주로 선택하는 모델은 다음과 같다.

 

4.1 모델 비교

모델	특성	적합한 상황
gpt-5.5	최신 고성능 모델, 복잡한 코딩·컴퓨터 사용·문서 작업·연구 흐름	대부분의 작업 — 시작점으로 권장
gpt-5.4	고성능 모델, 깊은 추론·도구 사용·에이전트 작업에 강함	전문성이 필요한 복잡한 작업
gpt-5.4-mini	빠르고 효율적인 미니 모델	빠른 코딩 반복, 작은 역할을 맡는 서브에이전트
gpt-5.3-codex	코딩에 특화된 모델, gpt-5.4의 코딩 능력을 뒷받침	복잡한 개발 작업
gpt-5.3-codex-spark	텍스트 중심의 빠른 리서치 프리뷰 모델	거의 즉각적인 코딩 반복. ChatGPT Pro 사용자 대상

한 줄로 요약하면: 일반 작업은 gpt-5.5로 시작하고, 가볍고 빠른 반복이 필요하면 gpt-5.4-mini를 선택한다. 단, 공식 문서는 gpt-5.5가 ChatGPT 로그인으로 사용할 때 제공되며, API 키 인증에서는 사용할 수 없다고 안내한다. 계정에 아직 보이지 않는다면 gpt-5.4를 쓰면 된다.

gpt-5.2는 깊은 디버깅을 포함한 코딩·에이전트 작업에 쓸 수 있는 이전 범용 모델이다. 지금 새로 시작하는 초심자라면 먼저 위 표의 추천 모델을 보고, 특별한 이유가 있을 때만 이전 모델을 선택하는 편이 단순하다.

 

ex) 가장 기본적인 변경 방법 

 - /model 입력 > 나오는 선택 화면에서 위아래로 움직여 모델을 선택한다.

 - effort 수준을 선택하는 화면인데 하기에 상세 내용은 작성해 두었다.

  - 선택된 모델 및 추론 레벨을 확인 가능하다.

 

모델 선택은 "가장 센 모델 하나만 고르면 끝"이 아니다. 작업의 성격이 다르면 적절한 모델도 달라진다.

작업	추천 방향	판단 이유
작은 파일 수정, 문구 변경, 빠른 탐색	gpt-5.4-mini	빠른 응답과 비용 효율이 더 중요하다.
여러 파일을 바꾸는 기능 구현	gpt-5.5 또는 gpt-5.4	맥락을 길게 유지하고 설계 판단이 필요하다.
원인 추적이 어려운 버그, 아키텍처 검토	강한 모델 + 높은 reasoning effort	속도보다 추론 깊이와 검증 계획이 중요하다.
여러 보조 에이전트에게 나눠 맡기는 반복 작업	가벼운 모델을 역할별로 사용	각 역할이 작고 독립적이면 빠른 모델이 효율적이다.

 

ex) 하나의 작업을 진행할때 여러가지 모델을 사용하여 작업하는 예시 

 - 메인 세션 : gpt 5.5 xhigh  

 - 작업을 수행하는 서브 에이전트 세션 예시

 

4.2 모델 지정과 reasoning effort

CLI에서는 시작할 때 --model로 모델을 지정한다. 공식 모델 예시에는 같은 뜻의 짧은 옵션인 -m도 함께 나온다. 플래그는 명령어 뒤에 붙여 동작을 바꾸는 옵션이다.

codex --model gpt-5.5 "이 모듈의 구조를 분석해라"

 

config.toml에 기본 모델을 설정할 수도 있다.

model = "gpt-5.5"

 

지원되는 모델에서는 생각의 깊이를 조절하는 model_reasoning_effort도 설정할 수 있다. 공식 Config Reference 기준 선택지는 minimal, low, medium, high, xhigh다. 단 xhigh는 모든 모델에서 되는 값이 아니라 모델 의존 옵션으로 안내되어 있다.

model_reasoning_effort = "high"

값	초심자용 의미	적합한 작업	주의점
minimal	생각을 거의 늘리지 않는 가장 가벼운 설정	짧은 요약, 단순 분류, 파일명 목록 정리	코드 수정이나 추론이 필요한 작업에는 부족할 수 있다
low	속도를 우선하는 낮은 추론	반복 수정, 간단한 리팩터링 후보 탐색	엣지 케이스를 놓칠 가능성이 있다
medium	속도와 판단 깊이의 균형	대부분의 일반 코딩, 문서화, 리뷰 초안	기본값으로 보기 좋지만 어려운 버그에는 올려볼 수 있다
high	가정을 더 많이 점검하는 깊은 추론	복잡한 버그, 설계 검토, 보안·권한 검토	응답이 느려지고 사용량도 커질 수 있다
xhigh	가능한 모델에서만 쓰는 더 깊은 추론	아키텍처 결정, 장기 리팩터링 계획, 원인 추적이 어려운 장애 분석	모델 의존 옵션이므로 안 되면 high로 낮춘다

클라우드 태스크 주의: 모델 선택과 사용 한도는 모델, 플랜, 그리고 로컬/클라우드 실행 여부에 따라 달라진다. 공식 Models 문서 기준으로, 클라우드 태스크의 기본 모델은 현재 사용자가 직접 바꾸지 못한다. 반면 로컬 CLI에서는 시작할 때 --model/-m으로 지정하고, 실행 중에는 /model로 바꿀 수 있다.

 

4.3 Fast mode와 Codex-Spark는 다르다

여기서 헷갈리기 쉬운 것이 Fast mode다.

Fast mode는 별도 모델명이 아니라, 지원 모델을 더 빠른 서비스 티어로 실행하는 속도 설정이다.

공식 Speed 문서 기준으로 Fast mode는 지원 모델 속도를 약 1.5배 높이고, 그 대신 크레딧을 더 빠르게 소모한다.

2026년 5월 기준 지원 모델과 배율은 다음처럼 공개되어 있다.

구분	공식 문서 기준	실전 해석
Fast mode	GPT-5.5와 GPT-5.4를 더 빠르게 실행. GPT-5.5는 표준 대비 2.5배, GPT-5.4는 2배 크레딧 소모	급하게 결과가 필요할 때만 켠다. 계속 켜두면 사용 한도가 빨리 줄어든다.
Codex-Spark	별도 빠른 모델. 연구 프리뷰이며 ChatGPT Pro 사용자 대상	Fast mode처럼 기존 모델을 가속하는 것이 아니라, 빠른 반복용 모델을 고르는 것이다.
설정 방법	/fast on, /fast off, service_tier = "fast"	작업 단위로 켜고 끄는 습관이 좋다. 기본값으로 고정하기 전에는 사용량을 먼저 본다.

service_tier = "fast"

[features]
fast_mode = true

API 키로 실행하는 경우에는 Fast mode 크레딧 체계가 아니라 표준 API 과금으로 처리된다는 점도 구분한다.

즉 "빠르게 하고 싶다"는 요구가 항상 Fast mode를 뜻하지 않는다.

단순 작업이면 먼저 작은 모델이나 낮은 reasoning effort를 쓰고, 그래도 지연이 문제일 때 Fast mode를 검토하는 순서가 낫다.

 

4.4 사용량과 비용은 모델명만으로 결정되지 않는다

요금과 사용량 제한은 모델명만으로 고정되지 않는다.

ChatGPT 플랜, API 키 사용, GitHub에서 실행되는 코드 리뷰, 클라우드 작업은 각각 사용량 계산 방식이 달라질 수 있다.

특히 플랜별 한도와 크레딧 정책은 바뀌기 쉬운 영역이므로 숫자를 외우기보다 공식 Pricing 페이지와 현재 계정의 사용량 화면을 확인하는 편이 안전하다.

실행 방식	공식 Pricing 문서 기준	관리 포인트
로컬 CLI / IDE 메시지	플랜별 5시간 단위 한도와 모델별 사용량 범위가 다르다	작은 반복은 작은 모델, 낮은 reasoning effort, 짧은 프롬프트로 처리한다
클라우드 태스크 / GitHub 코드 리뷰	공식 표 기준 GPT-5.3-Codex로 계산되는 항목이 따로 있다	로컬 모델 선택과 같은 방식으로 직접 바꿀 수 있다고 가정하지 않는다
API 키 사용	CLI, SDK, IDE 확장은 가능하지만 GitHub 코드 리뷰나 Slack 같은 클라우드 기능은 제공되지 않으며 API 토큰 요금이 적용된다	CI 자동화는 API key 비용과 로그 보관 정책을 따로 본다
Fast mode	지원 모델에서 더 높은 크레딧 비율을 쓴다	속도 병목이 확인된 작업에만 제한적으로 켠다

공식 Pricing 문서가 제시하는 절약 기준도 실용적이다.

프롬프트 크기를 줄이고, AGENTS.md를 작게 유지하고, 필요 없는 MCP 서버를 끄고, 반복 작업에는 더 작은 모델을 쓰면 한도를 더 오래 쓸 수 있다. 그래서 초심자에게 가장 좋은 기본 습관은 "강한 모델을 계속 켜두기"가 아니라, 작업 난이도에 맞춰 모델·reasoning effort·Fast mode·MCP 수를 함께 줄이는 것이다.

 

5. 정리: 4개 개념이 어떻게 연결되는가

지금까지 살펴본 4가지 개념은 따로 노는 기능이 아니다. Codex에게 일을 맡길 때 역할을 나눠 갖는 장치들이다. 공식 Customization 문서는 이 관계를 명확하게 설명한다.

모델(Models)
  └─ 작업 특성에 따라 선택 → 생각의 깊이와 속도 결정

프롬프트(Prompting)
  └─ 모델에 전달하는 지시 → 결과 품질을 크게 좌우

메모리(Memories) + AGENTS.md
  └─ 매번 프롬프트에 쓰지 않아도 Codex가 참고하는 배경 정보
     - AGENTS.md: 팀 규칙, 버전 관리, 공유
     - 메모리: 개인 작업 패턴, 이전 대화에서 배운 내용

샌드박스(Sandboxing)
  └─ 모델이 실제로 실행할 수 있는 범위를 제한
     → 반복 확인은 줄이고, 위험한 실행은 막음

예를 들어 gpt-5.5를 기본으로 쓰고, AGENTS.md에 린트·테스트 규칙을 박아두고, workspace-write로 실행한다. 그러면 매번 프롬프트에 "PR 전에 린트 돌려라"를 다시 쓸 필요가 없다. 메모리가 팀 코딩 습관을 기억해두면 다음번 프롬프트도 짧아진다.

 

4개가 제대로 맞으면 Codex에게 같은 말을 반복할 일이 줄어든다. 그게 전부다.

 

실제로는 아래처럼 연결해서 생각하면 된다.

상황	프롬프트	메모리/AGENTS.md	샌드박스/모델
낯선 저장소 분석	구조 요약, 위험 파일, 수정 전 확인 요청	팀 규칙은 아직 신뢰하지 말고 먼저 읽기	read-only + 강한 모델
작은 버그 수정	재현 단계, 수정 금지 범위, 테스트 명령	AGENTS.md의 테스트 규칙을 따르게 함	workspace-write + on-request
큰 리팩토링	먼저 계획 요청, 단계별 체크포인트, 회귀 테스트	반복 규칙은 AGENTS.md에, 임시 제약은 프롬프트에 둠	강한 모델 + 높은 reasoning effort

결국 좋은 프롬프트는 예쁜 문장이 아니라 작업 주문서다. 무엇을 고칠지, 어떤 규칙을 기억할지, 어떤 파일까지 건드려도 되는지, 어떤 모델로 처리할지를 함께 정해야 Codex가 덜 헤맨다.

 

6. Part 3 예고

다음 편은 Skills, MCP, Subagents다. Skills는 자주 쓰는 절차를 묶어두는 것이고, MCP는 Codex가 외부 도구로 나가는 통로다. Subagents는 큰 일을 역할별로 쪼개 돌리는 방식이다. 이 글이 "Codex에게 어떤 규칙을 줄 것인가"였다면, 다음 편은 "Codex가 어떤 도구를 쓸 수 있는가"에 가깝다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 (현재 글) Part 3: Subagents · Workflows (예정) Part 4: AGENTS.md · Rules (예정) Part 5: MCP · Plugins · Skills (예정) Part 6: 자동화 (예정) Part 7: 마이그레이션 (예정) Part 8: 병행 사용 패턴 (예정)

자주 묻는 질문

Codex에서 좋은 프롬프트는 무엇이 다른가?

좋은 프롬프트는 목표, 맥락, 제약, 완료 기준을 함께 준다. 이렇게 쓰면 Codex가 추측으로 범위를 넓히기보다 검증 가능한 작업 단위로 움직이기 쉽다.

 

Memories와 AGENTS.md는 같은 기능인가?

역할이 다르다. Memories는 개인 작업 패턴이나 이전 대화에서 배운 내용을 돕고, AGENTS.md는 저장소 안에서 팀 규칙과 작업 기준을 공유하는 지침 파일에 가깝다.

 

앞선 글에서 다룬 샌드박스를 왜 다시 다루는가?

앞선 글은 처음에 어떤 안전 설정으로 시작할지를 다뤘고, 이 글은 이번 작업을 Codex에게 어디까지 맡겨도 되는지 판단하는 법을 다룬다. 샌드박스는 외울 옵션 목록이 아니라, Codex가 읽기만 할지, 프로젝트 안에서 수정까지 할지, 더 넓은 권한이 필요한지를 정하는 안전 울타리다.

 

프롬프트, AGENTS.md, 메모리에는 각각 무엇을 넣어야 하나?

이번 작업에만 적용되는 조건은 프롬프트에 둔다. 팀이 반복해서 지켜야 하는 빌드, 테스트, 리뷰 규칙은 AGENTS.md에 둔다. 개인 작업 습관이나 이전 대화에서 배운 패턴은 메모리가 보조하도록 두는 편이 좋다.

 

처음에는 어떤 샌드박스와 승인 정책이 무난한가?

일반적인 로컬 개발 작업은 workspace-write와 on-request 조합이 무난하다. 낯선 저장소를 읽기만 할 때는 read-only로 시작하고, danger-full-access는 격리된 환경에서 정말 필요한 경우에만 쓴다.

 

모델은 항상 가장 강한 것을 고르면 되는가?

그렇지 않다. 큰 리팩토링, 복잡한 원인 분석, 넓은 코드 이해에는 강한 모델과 높은 reasoning effort가 유리하지만, 작은 반복 수정이나 단순 정리에는 더 가벼운 모델이 비용과 속도 면에서 낫다.

참고 자료

• Codex Prompting 공식 문서
• Codex Memories 공식 문서
• Codex Sandboxing 공식 문서
• Codex Models 공식 문서
• Codex Customization 공식 문서
• Codex AGENTS.md 가이드
• Codex Configuration Reference
• Codex CLI Slash commands
• Codex IDE Features
• Codex Workflows 공식 문서
• Codex Pricing
• Codex Config basics

작성일: 2026년 5월

분석 대상: OpenAI Codex CLI (2026년 5월 공식 문서 기준)

이 글은 2026년 5월 기준으로 작성되었다. 이후 변경될 수 있다.