AI Native Notes
GPT Codex로 돌아가기
GPT Codex입문14분 소요

Codex 시작하기 — 설치, 첫 작업, 체크포인트까지

Codex 앱·CLI·IDE에서 시작하고, 첫 프롬프트·Git 체크포인트·핵심 명령으로 빠르게 감을 잡는 입문 가이드

시작하기온보딩workflow기본기

공식 참고 자료: Quickstart · CLI Slash Commands · Best Practices · Review

커리큘럼 흐름

  1. Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프 ← 현재 문서
  2. Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
  3. Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
  4. Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
  5. Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
  6. Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
  7. Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
  8. Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
  9. Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
  10. Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
  11. Codex 검증 루프 — 머지 전에 동작을 증명하기
  12. Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
  13. Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
  14. Codex 팀 딜리버리 플레이북 — 중급 레인 운영
  15. Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
  16. Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
  17. Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
  18. Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
  19. Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
  20. Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
  21. Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기

이 문서에서 참고한 공식 문서

  • 앱/CLI/IDE로 시작하는 기본 진입 흐름과 로그인 방식 — Quickstart
  • /status, /init, /review, /mcp, /plan, /compact 같은 핵심 세션 명령 — CLI Slash Commands
  • 처음엔 default permissions와 작은 작업으로 감을 잡으라는 원칙 — Best Practices
  • 로컬 변경을 다시 읽는 review 범위와 습관 — Review

먼저 알아둘 것: 기능보다 성공 루프가 먼저다

Codex를 잘 시작하는 핵심은 모든 설정을 외우는 것이 아닙니다. 작고 안전한 작업을 한 번 끝까지 성공시키는 것이 훨씬 중요합니다.

처음에는 아래 네 가지만 정하면 됩니다.

  • 어떤 클라이언트에서 시작할지
  • 어떤 저장소를 열지
  • 첫 작업을 얼마나 작게 자를지
  • 마음에 안 들면 어떻게 되돌릴지

이 네 가지가 잡히면 그 다음부터는 명령, 설정, 자동화가 붙기 쉬워집니다.

어디서 시작할까

Quickstart 기준으로 Codex는 앱, CLI, IDE 확장, cloud 흐름으로 시작할 수 있습니다.

Codex 앱

가장 무난한 입문 경로입니다. 리뷰, worktree, 자동화, 세션 흐름을 한 UI에서 보기 쉬워서 “지금 무슨 일이 일어나고 있나”를 파악하기 좋습니다.

CLI

터미널 중심 개발자에게 가장 직관적입니다. 프롬프트, 실행 명령, diff, 검증 루프를 텍스트로 정확히 확인할 수 있어 학습 속도가 빠릅니다.

IDE 확장

에디터 안에서 컨텍스트를 유지하고 싶다면 좋습니다. 다만 첫 몇 번은 앱이나 CLI가 더 설명적이라, 입문 감각을 잡기 쉽습니다.

Cloud

처음부터 여기서 시작할 필요는 없습니다. 로컬에서 한두 번 성공 패턴을 만든 뒤 cloud로 옮기는 편이 훨씬 덜 헷갈립니다.

시작 전 5분 준비

첫 작업 전에 아래만 준비해도 체감이 꽤 달라집니다.

  1. 작업할 저장소를 정한다
    • 샘플 repo나 개인 프로젝트처럼 되돌리기 쉬운 곳이 좋습니다.
  2. 검증 명령 하나를 정한다
    • 예: npm test, pnpm lint, pytest -q
  3. 롤백 수단을 만든다
    • 최소한 git status를 보고 checkpoint를 남길 준비를 합니다.
  4. 숨은 의존성을 확인한다
    • 필요한 env, 테스트 데이터, 설치 상태를 먼저 봅니다.

초반 실패의 상당수는 프롬프트 문제가 아니라 잘못된 작업 디렉터리, 빠진 쓰기 권한, 숨은 환경 의존성에서 옵니다.

첫 10분 흐름

Quickstart 기준의 최소 흐름은 단순합니다.

  1. Codex 앱 또는 CLI 설치
  2. ChatGPT 계정 또는 OpenAI API key로 로그인
  3. 프로젝트 폴더 선택
  4. 첫 작업 전송

여기서 기억할 포인트:

  • API key로도 로그인할 수 있다
  • 다만 공식 문서는 ChatGPT 구독이 최신 모델/기능과 더 자연스럽게 맞는 경우가 있다고 안내한다
  • 입문자는 로컬 프로젝트 + 일반 계정 로그인 조합이 가장 단순하다

즉, 첫 목표는 “모든 기능 사용”이 아니라 한 저장소에서 한 작업을 무리 없이 끝내는 것입니다.

첫 작업은 작을수록 좋다

초반에는 야심찬 기능 개발보다 탐색 가능하고 되돌리기 쉬운 작업을 고르는 편이 낫습니다.

좋은 첫 작업 예시:

  • “이 저장소 구조를 5줄로 설명해줘.”
  • “이 에러와 가장 관련 있는 파일부터 찾아줘.”
  • “이 폴더의 dead code 후보를 조사만 해줘.”
  • “행동을 바꾸지 않는 작은 리팩토링만 해줘.”

피하고 싶은 첫 작업:

  • 앱 전체를 modernize 해줘
  • auth, billing, onboarding을 한 번에 정리해줘
  • 설계 판단이 큰 기능을 바로 구현해줘
  • 배포까지 한 번에 끝내줘

첫 작업의 목적은 생산성 과시가 아니라 신뢰 형성입니다.

첫 작업 크기를 고르는 감각

작업은 “기능 단위”보다 검증 루프 하나로 끝낼 수 있는 크기가 좋습니다.

크기 감각 좋은 예 아직 이른 예
아주 작음 조사만 하기, 한 문단 문서 수정, 작은 에러 재현 도메인 세 군데가 동시에 걸린 변경
적당함 컴포넌트 하나 수정 + 관련 테스트 API 계약과 DB 스키마 동시 변경
큼 기능 한 묶음 이상, 여러 팀 경계 포함 첫 세션에서 하기엔 과함

한 번의 lint/test/review로 “잘 됐는지” 판단하기 어렵다면 대개 너무 큽니다.

첫 프롬프트는 소원이 아니라 작업 지시여야 한다

Best Practices 쪽 흐름과도 맞는 가장 무난한 형태는 아래입니다.

Goal:
무엇을 바꾸고 싶은가
 
Context:
어떤 파일, 로그, 기존 패턴이 중요한가
 
Constraints:
무엇을 건드리면 안 되는가
 
Done when:
무엇이 완료 기준인가

예를 들면:

Goal:
`src/lib/` 안에서 사용되지 않는 유틸 후보를 찾아줘.
 
Context:
- 조사 범위는 `src/lib/`
- 관련 사용처는 import 기준으로 함께 보여줘
 
Constraints:
- 파일 수정은 하지 말 것
- 결과는 우선순위가 높은 후보부터 정리할 것
 
Done when:
- 후보 3개와 근거를 정리할 것

이 정도만 되어도 Codex는 훨씬 덜 추측합니다.

처음 익히면 좋은 핵심 명령 6개

Slash Commands 문서 기준으로 초반에는 아래 여섯 개면 충분합니다.

/status

현재 모델, approval policy, writable roots, context 상태를 확인합니다. “왜 예상과 다르게 행동하지?” 싶을 때 제일 먼저 보는 명령입니다.

/init

현재 디렉터리에 AGENTS.md 초안을 만듭니다. 저장소 규칙을 반복 설명하기 싫어질 때 가장 먼저 익히면 좋습니다.

/review

작업 후 로컬 변경을 다시 읽습니다. 방금 수정한 diff를 한 번 더 보수적으로 검토할 때 가장 먼저 익히면 좋습니다.

/mcp

연결된 MCP 도구를 확인합니다. repo 밖 문서나 티켓이 필요할 때 지금 실제로 접근 가능한 표면을 확인하는 데 유용합니다.

/plan

바로 구현하지 말고 계획부터 세우게 합니다. 파일/도메인이 여러 군데 걸리는 작업에서는 첫 세션부터 큰 도움이 됩니다.

/compact

대화가 길어졌을 때 핵심만 남기고 압축합니다. 긴 세션에서 문맥을 잃지 않게 도와줍니다.

나머지 명령은 필요가 생길 때 익혀도 됩니다. 처음에는 /status, /review, /init 세 개만 익혀도 체감이 크게 올라갑니다.

Git checkpoint를 습관으로

Codex는 빠르게 많이 바꿀 수 있습니다. 그래서 초반에는 “잘 고친다”보다 쉽게 되돌릴 수 있다가 더 중요합니다.

가장 단순한 루프는 이렇습니다.

git status
git add -A && git commit -m "checkpoint: before codex task"

작업 결과가 마음에 들면 이후에도 checkpoint를 남기면 됩니다. 이 습관만 있어도 “좋아 보이는데 어디가 바뀌었는지 모르겠다”는 불안을 많이 줄일 수 있습니다.

review를 초반 루틴에 붙여라

Review 문서 기준으로 review는 단순 코드 품평이 아니라, 지금 실제로 머지하거나 유지할 변경만 다시 보는 장치입니다.

초반 추천 루프는 아래와 같습니다.

  1. 작은 작업 요청
  2. 관련 lint/test 실행
  3. /review로 로컬 변경 다시 보기
  4. scope가 맞는지 확인
  5. 마음에 들면 checkpoint 또는 commit

이 루틴이 잡히면 이후에 automation이나 cloud로 올라가도 흔들림이 줄어듭니다.

첫 주 진행 순서

처음 일주일은 아래 순서가 무난합니다.

  1. 로컬에서 read-only 또는 조사성 작업
  2. 작은 수정 + 검증 명령 실행
  3. /review로 변경 다시 보기
  4. 저장소 규칙을 AGENTS.md로 정리하기
  5. 반복되는 작업이 생기면 skills나 automation 검토

건강한 순서는 작업 → 검토 → 규칙화 → 자동화입니다. 처음부터 모든 기능을 켜는 순서가 아닙니다.

초반에 자주 막히는 이유

증상 흔한 원인 먼저 할 일
아무 것도 못 하는 것 같다 잘못된 작업 디렉터리, 너무 넓은 요청 범위를 줄이고 /status 확인
계속 되묻는다 Goal/Constraints가 모호함 프롬프트를 이슈 형태로 다시 씀
이상한 파일까지 건드린다 scope와 writable roots가 불명확 파일 앵커를 더 구체적으로 줌
결과가 불안하다 review/checkpoint 없이 바로 수용 /review와 Git checkpoint 루틴 추가
cloud에서만 실패한다 로컬 숨은 상태에 의존 로컬 성공 루프를 먼저 만든 뒤 setup을 명시

빠른 시작 체크리스트

  • 앱 또는 CLI 중 하나를 정했다
  • 로컬 프로젝트 하나를 골랐다
  • 첫 작업을 작고 되돌리기 쉽게 잘랐다
  • 검증 명령 하나를 정했다
  • 작업 전후로 git status를 볼 준비가 됐다
  • /review, /status의 용도를 이해했다

한 줄 요약

처음엔 작은 로컬 성공 루프를 만드는 데 집중하세요. 클라이언트 선택, 작업 크기, rollback, review 습관만 잡혀도 Codex는 훨씬 덜 불안하고 훨씬 더 유용해집니다.

연결된 가이드