Codex 사용법 가이드: 시작 방법, 5가지 팁, 실전 베스트 프랙티스
Codex는 단순 코드 자동완성 도구라기보다, 코드를 읽고 고치고 명령을 실행하고 결과를 리뷰까지 이어 가는 AI coding agent에 가깝습니다. 한국어 검색 의도에서 codex 사용법의 핵심도 설치 자체보다, 무엇을 Codex에 맡기고 어디서 사람이 검토할지를 이해하는 데 있습니다.
결론부터 말하면, Codex는 작고 명확한 작업으로 시작할 때 성능이 가장 안정적입니다. "이 저장소 전부 고쳐줘"처럼 넓게 던지기보다, 대상 파일, 목표, 제약, 완료 조건을 분명히 주는 편이 정확도와 리뷰 효율 모두 좋습니다.
AI coding 전체 맥락을 먼저 보고 싶다면 AI Coding 토픽 페이지, 2026년 베스트 Vibe Coding 툴 비교를 먼저 보는 편이 좋습니다. Codex와 Claude Code 차이가 궁금하면 Codex vs Claude Code Skills도 함께 보면 정리가 빠릅니다.
먼저 결론: Codex는 어떻게 쓰는 게 맞나
| 현재 상황 | 먼저 시작할 인터페이스 | 이유 |
|---|---|---|
| 터미널 중심으로 저장소를 다룸 | CLI | 지시, 수정, 테스트, 리뷰 흐름이 가장 직관적 |
| 여러 작업을 동시에 보며 diff를 확인해야 함 | App | review pane, worktree, handoff, automations에 강점 |
| 기존 에디터 흐름을 크게 바꾸고 싶지 않음 | IDE extension | 지금 쓰는 IDE 안에서 Codex를 붙이기 쉬움 |
시작 순서는 단순합니다.
- CLI 또는 App 중 하나만 먼저 시작
- 작은 태스크를 3회 정도 반복
AGENTS.md와 리뷰 루프를 익힘- 이후 skills, subagents로 확장
초기에는 "어디서 시작할지"가 가장 헷갈립니다. CLI는 가장 빠르게 검증하기 좋고, App은 리뷰와 worktree 운용이 강하며, IDE extension은 기존 개발 흐름을 덜 깨는 선택입니다.
Codex는 무엇인가
Codex는 OpenAI의 coding agent입니다. CLI에서는 로컬 디렉터리에서 코드를 읽고 수정하고 명령을 실행할 수 있습니다. App에서는 diff 리뷰, worktree 기반 병렬 작업, background task 관리까지 한 흐름에서 처리할 수 있습니다. IDE extension은 이 경험을 에디터 안으로 가져오는 역할입니다.
핵심은 Codex를 "코드를 대신 써주는 채팅"으로만 보면 가치의 절반만 쓰게 된다는 점입니다. 실제로는 아래 같은 작업에서 체감이 큽니다.
- 낯선 코드베이스 빠르게 파악
- 소규모~중규모 기능 수정
- 버그 원인 조사와 재현 경로 정리
- 테스트, lint, build까지 포함한 검증
- 코드 리뷰와 diff 정리
- 반복 작업의 skill화, automation화
즉 Codex는 단일 생성 모델이라기보다, 실무 워크플로에 들어오는 에이전트로 보는 편이 맞습니다.
Codex 시작 방법
1. CLI 설치 후 첫 세션 시작
OpenAI 공식 문서 기준으로 Codex CLI 최소 시작은 다음입니다.
npm i -g @openai/codex
codex첫 실행에서는 ChatGPT 계정 또는 API key로 인증합니다. 여기서 중요한 점은 설치 직후 큰 작업을 바로 던지지 않는 것입니다. 첫 턴은 환경 확인용의 작은 요청이 적절합니다.
예시는 다음처럼 시작하면 좋습니다.
이 리포지토리 구조를 요약하고, 핵심 디렉터리와 개발 흐름을 설명해 주세요.
아직 수정은 하지 말고 분석만 해 주세요.이 한 번으로 Codex가 저장소를 어떻게 읽는지, 설명의 깊이가 어느 정도인지 빠르게 확인할 수 있습니다.
2. 두 번째 요청에서 작은 수정 수행
다음에는 리뷰하기 쉬운 작은 변경을 맡깁니다.
이 컴포넌트의 문구만 수정해 주세요.
변경 대상은 1개 파일로 제한하고, 수정 후 diff를 요약해 주세요.이 단계의 포인트는 범위를 넓히지 않는 것입니다. Codex는 큰 요청도 처리하지만, 초반에는 "대상-목표-제약"을 좁히는 편이 안정적입니다.
3. 세 번째 요청에서 검증까지 포함
Codex는 수정만 시키는 것보다, 수정 후 확인까지 같이 시킬 때 가치가 커집니다.
이 테스트 실패를 고쳐 주세요.
수정 후 관련 테스트만 실행하고, 무엇을 바꿨는지 3줄로 요약해 주세요.이 "수정으로 끝내지 않는 습관"이 Codex 활용에서 매우 중요합니다.
Codex를 단순 생성 도구로 쓰지 않고 read -> plan -> edit -> test -> review 루프로 운용하면 정확도와 신뢰도가 동시에 올라갑니다. 중앙의 human check는 "diff를 그대로 받지 않고, 설명 가능한 변경만 채택한다"는 원칙을 의미합니다.
Codex 기본 사용법
먼저 이해시키고, 그다음 수정시켜라
Codex에 바로 구현을 시키기보다 먼저 설명을 받는 쪽이 성공률이 높습니다. 특히 기존 대형 저장소에서 효과가 큽니다.
이 모듈의 책임과 의존 관계를 요약해 주세요.
그다음 최소 수정안 2가지를 제시해 주세요.
아직 편집은 하지 마세요.이 방식이면 Codex의 이해 상태를 먼저 검증할 수 있습니다. 이해가 얕은 상태에서 바로 수정에 들어가는 것보다 한 턴 더 쓰는 편이 안전합니다.
완료 조건을 반드시 명시하라
Codex는 "무엇이 완료인지"가 명확할수록 결과가 안정됩니다.
나쁜 예:
이 페이지 개선해 주세요좋은 예:
이 페이지 도입부를 더 짧게 줄여 주세요.
첫 화면에서 "무엇인지"와 "왜 중요한지"가 바로 보이게 해 주세요.
기존 H2 구조는 유지하고 코드 블록은 늘리지 마세요.리뷰를 전제로 diff를 다뤄라
App의 review pane에서는 Codex가 만든 변경뿐 아니라, 저장소의 전체 미커밋 변경을 함께 보며 staged / unstaged를 조정할 수 있습니다. Inline comment로 특정 라인에 직접 피드백하면 "다시 고쳐줘"보다 훨씬 정밀하게 수정 루프를 돌릴 수 있습니다.
App 중심으로 쓴다면 병렬 코드 에이전트 가이드도 함께 읽는 편이 좋습니다. Codex의 worktree와 리뷰 설계를 한 번에 이해하기 쉽습니다.
5가지 팁
Tip 1: 구현부터 시키지 말고 계획부터 받기
첫 문장을 "구현해 줘" 대신 "먼저 계획을 제시해 줘"로 바꾸는 것만으로도 불필요한 왕복이 크게 줄어듭니다.
예시:
먼저 수정 계획을 3단계로 제시해 주세요.
그다음 구현으로 진행해 주세요.이 방식은 버그 수정, 리팩터링, 문서 개편 모두에 유효합니다.
Tip 2: 매번 범위와 금지 사항을 함께 적기
Codex는 강력하지만, 모호한 요청에는 범위가 쉽게 퍼집니다. 그래서 아래 3가지를 항상 함께 쓰는 것이 실무적으로 유리합니다.
- 어디를 수정하는지
- 무엇을 달성하는지
- 무엇을 건드리지 않는지
짧게 써도 충분합니다.
`components/header.tsx`만 수정해 주세요.
목표는 네비게이션 여백을 줄이는 것입니다.
로직 변경과 의존성 추가는 하지 마세요.Tip 3: 저장소 공통 규칙은 AGENTS.md로 분리
매 턴 동일한 규칙을 프롬프트에 붙이는 방식은 비효율적입니다. Codex 공식 best practices도 지속 규칙은 AGENTS.md에 두는 방식을 권장합니다.
AGENTS.md에는 최소한 다음을 넣어 두는 것이 좋습니다.
- 저장소 구조
- build / test / lint 명령
- 코딩 규약
- PR 기대 기준
- done 정의
CLI의 /init은 AGENTS.md 초안을 만드는 빠른 출발점으로 좋습니다. 다만 그대로 두지 말고 팀의 실제 build / test / review 흐름에 맞게 반드시 조정해야 합니다.
매 턴 지시는 prompt에, 저장소 공통 규칙은 AGENTS.md에, 반복 절차는 skills에, 주기 실행은 automations에 두면 지시 레이어가 섞이지 않고 유지보수가 쉬워집니다.
Tip 4: subagents 병렬 실행은 탐색과 리뷰를 크게 가속한다
여기는 2026년 3월 16일 기준 Codex에서 특히 중요한 지점입니다. 현재 Codex에서는 subagent workflows가 기본 활성화되어 있고, App과 CLI에서 흐름을 확인할 수 있습니다. Codex는 사용자가 명시적으로 요청했을 때만 전문화된 subagent를 여러 개 실행해 결과를 모아 반환합니다.
특히 잘 맞는 작업은 다음과 같습니다.
- 대규모 저장소 탐색
- PR 다각도 리뷰
- 복수 대안 비교
- 멀티스텝 구현 계획
예를 들어 PR 리뷰는 관점을 분리해 맡기면 효과가 큽니다.
이 브랜치를 main과 비교해서 리뷰해 주세요.
Security, bugs, test flakiness, maintainability를 각각 별도 subagent에 할당하고,
모든 결과가 모이면 통합 요약을 작성해 주세요.장점은 한 에이전트의 긴 사고 체인에 모든 것을 밀어 넣지 않아도 된다는 점입니다. 탐색, 검증, 요약을 분리하면 주 에이전트 컨텍스트가 덜 오염되고 복잡한 작업을 다루기 쉬워집니다.
subagents는 main agent가 security, bugs, tests, maintainability 같은 관점을 병렬로 분배하고, 마지막에 하나의 review summary로 통합하는 이미지로 이해하면 쉽습니다.
다만 subagents에는 주의점이 있습니다.
- 명시적으로 요청하지 않으면 실행되지 않음
- 각 subagent가 독립 model / tool을 쓰므로 token 비용 증가
- 강하게 결합된 단일 작업을 억지 분할하면 통합 비용이 오히려 증가
즉 병렬화는 만능이 아니며, 분할 가능한 작업에만 써야 효과가 납니다.
Tip 5: 변경 후에는 반드시 review 또는 test까지 수행
Codex의 가치는 "작성"보다 "수정 후 검증"까지 닫는 데 있습니다. 변경 뒤 아래 둘 중 하나만 꼭 지켜도 신뢰도가 크게 올라갑니다.
- 관련 테스트 실행
/review로 별도 관점 리뷰 실행
특히 App review pane은 inline comment로 diff에 직접 피드백할 수 있어 수정 루프를 짧게 가져가기 좋습니다.
Best Practices
1. 작은 태스크에서 시작
Codex best practice의 핵심은 간단합니다. 처음부터 너무 큰 작업을 던지지 않는 것입니다.
권장 순서는 다음과 같습니다.
- 분석만 요청
- 1개 파일 수정
- 작은 버그 수정
- 테스트 포함 수정
- 다중 파일 변경
- subagents/automation 확장
이 순서로 올리면 저장소별 제약과 규칙 부족 지점이 자연스럽게 드러납니다.
2. 초반에는 approval/sandbox를 보수적으로
OpenAI best practices에서도 초반에는 default permissions로 시작하고, 필요가 확인된 뒤 점진적으로 완화하는 방식을 권장합니다. 시작부터 권한을 넓게 주는 것보다 안전한 기본값에서 출발하는 편이 실패 비용이 낮습니다.
특히 공유 저장소나 프로덕션 근접 환경이라면, 자유 실행보다 review와 approval 단계를 끼우는 편이 맞습니다.
3. 지속 규칙은 prompt가 아니라 설정 레이어에 배치
매번 긴 규칙을 prompt에 넣으면 오히려 핵심 작업이 흐려집니다. 지속 규칙은 AGENTS.md, 반복 작업은 skills, 주기 작업은 automations로 분리하는 편이 운영 효율이 높습니다.
Codex skill은 SKILL.md를 중심으로 instructions, references, optional scripts를 묶는 구조라서, 리뷰 절차나 콘텐츠 점검처럼 재사용성이 높은 작업에 특히 적합합니다.
4. 같은 파일군을 병렬 스레드로 돌릴 때는 worktree 우선
같은 저장소에서 여러 스레드를 동시에 진행한다면 worktree를 빨리 도입하는 편이 안전합니다. Codex App의 worktree는 같은 프로젝트 안에서 병렬 작업을 하면서도 현재 로컬 환경을 덜 깨뜨리기 위한 장치입니다.
특히 다음 경우에 효과가 큽니다.
- 한쪽은 bugfix, 다른 쪽은 docs 업데이트를 병행
- background task를 돌리면서 현재 작업을 계속 진행
- main 작업 환경을 유지한 채 별도 task를 실험
worktree 없이 같은 파일을 live thread로 병렬 진행하면 리뷰와 병합 난도가 급격히 올라갑니다.
5. 변경을 "받아들이기"보다 "선별하기"
Codex가 만든 diff를 그대로 수용하기보다 stage, revert, inline comment로 선별하는 편이 결과 품질이 안정적입니다. 좋은 운용은 Codex를 오토파일럿으로 쓰는 것이 아니라, 빠른 초안+검증 파트너로 쓰는 것입니다.
어떤 사용자에게 어떻게 맞나
초보 개발자
처음에는 코드 생성보다 설명과 수정 중심으로 시작하는 것이 좋습니다.
- "이 함수가 무엇을 하는지 설명해 줘"
- "이 에러의 원인이 뭔지 정리해 줘"
- "최소 수정안만 제시해 줘"
이 접근은 학습과 실무를 함께 가져가기 쉽습니다.
1인 개발
Codex는 1인 개발과 궁합이 좋습니다. 요구 정리, 코드 수정, 테스트, 리뷰 루프를 한 흐름으로 묶기 쉽기 때문입니다. subagents는 탐색과 리뷰를 분리해야 하는 장면에서 특히 효율적입니다.
팀 개발
팀에서는 개인의 프롬프트 역량보다 AGENTS.md, 리뷰 규칙, worktree, skills 정비가 더 중요합니다. 사용자별 출력 편차를 줄이려면 저장소 단위의 working agreement를 먼저 고정하는 것이 효과가 큽니다.
맞지 않는 사용 방식
Codex는 강력하지만, 모호한 요청을 완전 자동으로 던져 놓고 결과만 받으려는 운영에는 맞지 않습니다. 지시를 명확히 하고, diff를 검토하고, 필요할 때 규칙을 계속 다듬는 팀/개인일수록 성과가 큽니다.
FAQ
Codex는 초보자도 쓸 수 있나요?
가능합니다. 다만 처음부터 대규모 구현에 쓰기보다, 코드 설명, 버그 원인 정리, 작은 수정부터 시작하는 편이 성공 확률이 높습니다.
Codex는 CLI와 App 중 무엇부터 시작해야 하나요?
터미널이 익숙하면 CLI, diff 리뷰와 병렬 작업 가시성이 중요하면 App이 적합합니다. 고민된다면 CLI로 기본 루프를 익힌 뒤 App으로 확장하는 순서가 무난합니다.
subagents는 언제 써야 하나요?
탐색, 리뷰, 비교처럼 관점 분리가 가능한 작업에 적합합니다. 반대로 강결합된 단일 변경을 억지로 분할하는 것은 비효율적입니다.
AGENTS.md와 skill은 어떻게 나눠 쓰나요?
AGENTS.md는 저장소 공통 규칙과 기대값, skill은 재사용 가능한 절차와 전문 작업에 적합합니다. 전자는 working agreement, 후자는 reusable workflow로 보면 명확합니다.
Codex가 만든 변경을 그대로 믿어도 되나요?
아니요. 관련 테스트와 diff 리뷰를 통과한 변경만 채택하는 것이 기본입니다. Codex는 빠르지만 최종 책임은 사람 리뷰어에게 있습니다.
Related Guides
- AI Coding 토픽 페이지
- 병렬 코드 에이전트 가이드
- Claude Code 스타일 에이전트 만들기
- 2026년 베스트 Vibe Coding 툴 비교
- Codex vs Claude Code Skills