실패했을 때 복구하는 문제 해결 사전

실패는 끝이 아니라 복구 루틴의 시작이다

앱 개발을 하다 보면 Codex가 어느 날 갑자기 말을 듣지 않는 순간이 옵니다. 어제까지 잘 되던 로그인이 오늘은 실패하고, 분명 할 일 앱의 버튼만 고치라고 했는데 전혀 다른 파일까지 수정되어 있고, 빌드는 빨간 에러를 뿜어냅니다. 이때 초보자가 가장 많이 하는 실수는 곧바로 재설치하거나, 설정 폴더를 통째로 지우거나, Codex에게 "다 고쳐줘"라고 한 번에 맡기는 것입니다.

하지만 AI 도구를 잘 쓰는 사람은 실패하지 않는 사람이 아닙니다. 실패했을 때 빠르게 멈추고, 원인을 좁히고, 안전하게 되돌릴 줄 아는 사람입니다. 이번 장은 Codex 사용 중 자주 만나는 문제를 스스로 진단하는 "복구 사전"입니다. 설치, 인증, 컨텍스트, 실행, 빌드, 병합 오류를 유형별로 나누고, 당황했을 때 어떤 순서로 확인해야 하는지 익혀 보겠습니다.

복구의 첫 원칙: 재설치보다 관찰이 먼저다

문제가 생기면 제일 먼저 하고 싶은 일은 "처음부터 다시 깔기"입니다. 하지만 Codex 문제의 상당수는 설치 자체가 아니라 인증 만료, 네트워크, 사용량 제한, 설정 파일, 현재 작업 폴더 문제에서 발생합니다. Codex App과 Codex CLI는 같은 기반 에이전트와 설정을 사용하더라도, 시점에 따라 서로 다른 에이전트 버전이나 실험 기능을 사용할 수 있습니다.¹ 그래서 "앱에서는 되는데 CLI에서는 안 된다" 또는 그 반대 상황이 반드시 이상한 것은 아닙니다.

문제가 생겼다면 다음 순서로 원인을 좁히세요.

1. 현재 위치와 버전을 확인합니다.

2. 인증 상태와 계정 권한을 확인합니다.

3. 네트워크, VPN, 프록시, 서비스 상태를 확인합니다.

4. 설정 파일과 승인 모드를 확인합니다.

5. Git 상태를 확인해 작업물을 먼저 보호합니다.

6. 그다음에 업데이트나 재설치를 고려합니다.

실전에서는 터미널에서 다음 명령을 먼저 실행합니다.

pwd
git status
codex --version
node -v
npm -v

여기서 pwd는 현재 작업 폴더를 보여 줍니다. git status는 수정된 파일과 현재 브랜치를 보여 줍니다. codex --version은 내가 실제로 실행 중인 Codex CLI 버전을 알려 줍니다. 초보자에게는 이 다섯 줄이 의외로 강력합니다. "Codex가 이상하다"고 생각했는데 알고 보니 다른 폴더에서 실행 중이거나, 예전 브랜치에서 작업 중이거나, 시스템에 설치된 다른 Codex가 실행되는 경우가 많기 때문입니다.

Codex가 아예 작동하지 않을 때

Codex가 실행되지 않거나, 로그인 창만 반복해서 뜨거나, 아무 출력 없이 멈춘다면 원인을 넓게 보되 순서는 좁게 가져가야 합니다. 무작정 삭제하지 말고 인증, 사용량, 네트워크, 설정, 버전 순서로 봅니다.

인증 만료와 로그인 실패

가장 흔한 원인은 인증 정보가 만료되었거나 저장되지 않은 경우입니다. Codex는 ChatGPT 계정 로그인 또는 API 키 기반 사용 흐름을 제공하며, 일부 기능은 ChatGPT 계정 로그인과 연결될 수 있습니다.² 터미널에서 codex를 실행했을 때 매번 브라우저 로그인이 뜬다면, 설치보다 인증 저장 문제를 먼저 의심해야 합니다.

다음처럼 점검합니다.

codex
# 지원되는 버전이라면
codex login status

브라우저가 열리고 로그인을 요구한다면 정상적으로 다시 인증을 완료합니다. 비밀번호를 바꿨거나, 다른 기기에서 세션을 해제했거나, 회사 계정 정책이 바뀐 경우 기존 토큰이 더 이상 유효하지 않을 수 있습니다.

원격 서버, WSL, SSH 환경처럼 브라우저 콜백이 불안정한 곳에서는 장치 코드 로그인 같은 별도 인증 흐름을 지원하는 버전도 있습니다. 명령 이름은 버전에 따라 다를 수 있으므로 먼저 확인하세요.

codex login --help

도움말에 장치 인증 옵션이 있다면 그 안내를 따릅니다. 핵심은 "인증 명령은 현재 설치된 CLI 도움말을 기준으로 확인한다"는 점입니다.

사용량 제한과 느린 응답

오전에는 잘 되던 Codex가 오후부터 갑자기 느려지거나 429 Too Many Requests 같은 메시지를 낸다면, 사용량 제한에 걸렸을 수 있습니다. 이때는 계속 재시도하기보다 잠시 멈추는 것이 좋습니다. 자동화 스크립트, 반복 실행, 여러 Cloud 작업을 동시에 돌린 경우 제한에 빨리 도달할 수 있습니다.

Codex에게 같은 요청을 계속 보내는 대신 이렇게 정리합니다.

현재 429 오류가 발생했습니다.
반복 요청은 멈추고, 마지막으로 성공한 작업과 실패한 작업을 구분해 주세요.
재시도하기 전에 내가 확인해야 할 항목을 체크리스트로 정리해 주세요.

AI에게도 "계속 시도하지 말라"고 명시하는 습관이 필요합니다. 자동화와 Cloud 작업을 쓰는 단계에서는 특히 중요합니다.

네트워크, VPN, 프록시 문제

로그인, 모델 호출, Cloud 작업은 네트워크 영향을 받습니다. 회사 프록시, VPN, 방화벽, DNS 문제가 있으면 브라우저는 되는데 Codex App이나 CLI만 실패할 수 있습니다. 이때는 네트워크가 아예 막혀 있는지부터 확인합니다.

curl https://api.openai.com

응답 형태가 완벽하지 않아도 네트워크가 완전히 차단되었는지 확인하는 데 도움이 됩니다. 회사 환경에서는 프록시 설정이 터미널, VS Code, 브라우저마다 다르게 적용될 수 있습니다. 브라우저만 프록시를 타고, CLI는 직접 연결을 시도하는 경우도 있습니다.

다음 순서로 확인하세요.

• VPN을 잠시 끄고 다시 시도합니다.

• 회사 네트워크가 아닌 개인 핫스팟에서 시도합니다.

• 프록시 환경 변수 HTTP_PROXY, HTTPS_PROXY, NO_PROXY를 확인합니다.

• OpenAI 서비스 상태 페이지에서 장애 여부를 확인합니다.³

문제가 네트워크라면 재설치해도 거의 해결되지 않습니다. "다른 네트워크에서 되는가?"를 확인하는 편이 훨씬 빠릅니다.

설정 파일 오류와 모델 이름 문제

Codex 설정은 사용자 수준과 프로젝트 수준에 존재할 수 있습니다. 공식 설정 문서에서는 사용자 설정과 프로젝트 설정을 구분해 다룰 수 있으며, config.toml 같은 설정 파일을 통해 모델, 승인 모드 등을 관리할 수 있습니다.⁴ 설정 파일에 잘못된 모델 이름, 깨진 TOML 문법, 과하게 제한적인 샌드박스 설정이 들어가면 Codex가 이상하게 동작할 수 있습니다.

초보자는 설정 파일을 삭제하기보다 이름을 바꿔 백업한 뒤 기본값으로 실행해 보는 방식을 권장합니다.

mv ~/.codex/config.toml ~/.codex/config.toml.backup
codex

이렇게 하면 원래 설정을 보존하면서 "설정 때문인지"만 확인할 수 있습니다. 프로젝트 안에 .codex/config.toml이 있다면 사용자 설정이 아니라 프로젝트 설정이 문제일 수도 있습니다.

ls -la .codex
cat .codex/config.toml

설정 파일을 Codex에게 보여 줄 때는 API 키, 토큰, 개인 정보가 들어 있지 않은지 반드시 확인하세요.

Codex가 엉뚱한 파일을 수정했을 때

Codex가 요구사항을 오해하면 생각보다 넓은 범위를 수정할 수 있습니다. 예를 들어 "로그인 버튼 문구를 바꿔 줘"라고 했는데 레이아웃 파일, 테스트 파일, 라우터 파일까지 손댈 수 있습니다. 이때 중요한 것은 화를 내며 "왜 그랬어?"라고 묻는 것이 아니라, 먼저 diff를 보는 것입니다.

git status
git diff --stat
git diff

git diff --stat은 어떤 파일이 얼마나 바뀌었는지 한눈에 보여 줍니다. 수정 범위가 넓다면 바로 추가 지시를 내리지 말고 다음 세 가지를 판단합니다.

• 의도한 파일 안에서만 작은 오해가 있었는가?

• 관련 없는 파일이 섞였지만 수정 의도는 대체로 맞는가?

• 요구사항 자체를 크게 오해했는가?

첫 번째라면 같은 채팅에서 작은 수정 지시로 회복하면 됩니다.

방금 변경 중 `src/components/LoginButton.tsx`의 문구 수정은 유지하세요.
하지만 `src/app/layout.tsx`와 `src/routes.ts` 변경은 이번 요청 범위가 아닙니다.
두 파일의 변경을 되돌리고, LoginButton 관련 diff만 남겨 주세요.
작업 후 변경 파일 목록을 보여 주세요.

두 번째라면 Codex에게 되돌릴 파일을 명확히 지정합니다.

현재 diff를 기준으로 이번 작업의 목표와 무관한 파일을 찾아 주세요.
단, 직접 되돌리기 전에 목록과 이유를 먼저 제안하세요.
내가 승인한 파일만 원래 상태로 되돌리세요.

세 번째라면 새 채팅을 여는 편이 낫습니다. 대화 맥락에 잘못된 전제가 쌓이면 Codex가 계속 그 방향으로 밀고 갈 수 있기 때문입니다. 새 채팅에서는 목표, 제약, 관련 파일, 완료 기준을 다시 짧게 제공합니다.

목표: 로그인 버튼의 표시 문구만 바꾼다.
관련 파일: src/components/LoginButton.tsx
수정 금지: 라우팅, 인증 로직, 레이아웃, 패키지 의존성
완료 기준: 버튼 텍스트가 "시작하기"로 바뀌고 기존 테스트가 통과한다.
먼저 파일을 읽고 수정 계획을 3줄로 설명한 뒤 진행해 주세요.

여기서 핵심은 Codex에게 "관련 파일"뿐 아니라 "수정 금지"를 알려 주는 것입니다. 초보자는 목표만 말하는데, 실제 협업에서는 경계가 더 중요할 때가 많습니다.

컨텍스트가 길어져 품질이 떨어질 때

긴 대화를 이어 가다 보면 Codex가 예전 지시와 최신 지시를 섞기 시작합니다. 처음에는 Tailwind를 쓰라고 했고, 중간에는 CSS Module을 쓰라고 했고, 나중에는 shadcn/ui 컴포넌트로 바꾸라고 했을 수 있습니다. 사람도 헷갈리는데 AI도 헷갈립니다.

이때는 세 가지 방법을 씁니다.

첫째, 지원되는 경우 대화 압축 기능을 사용합니다. 일부 CLI와 앱 환경에서는 /compact 같은 명령이 제공될 수 있습니다. 명령 이름은 버전에 따라 다를 수 있으므로 현재 도움말을 확인하세요. 압축은 대화 내용을 마법처럼 정리하는 기능이 아닙니다. 잘못된 결정까지 요약될 수 있으므로, 압축 직후에는 요약 내용을 읽고 틀린 부분을 바로 고쳐야 합니다.

대화를 압축한다면 다음 항목만 남겨 주세요.
1. 현재 목표
2. 이미 결정된 기술 스택
3. 수정 금지 파일
4. 마지막으로 실패한 명령과 에러
5. 다음에 해야 할 한 가지 작업

둘째, 새 채팅을 열고 현재 상태를 짧게 재현합니다. 새 채팅을 열 때는 "이전 대화 참고"가 아니라 "현재 사실"을 줘야 합니다.

현재 상태 요약:
- Next.js 앱이며 로그인 페이지를 수정 중입니다.
- 브랜치: feature/login-copy
- 마지막 변경: LoginButton 문구 수정
- 실패 명령: npm run build
- 핵심 에러: Type error in src/components/LoginButton.tsx line 18
- 원하지 않는 작업: 인증 구조 변경, 패키지 추가

먼저 에러 원인 후보를 3개 이하로 좁히고, 가장 작은 수정부터 제안해 주세요.

셋째, 반복되는 규칙은 AGENTS.md로 옮깁니다. 매번 "패키지 추가하지 마", "한글 파일명 쓰지 마", "테스트 먼저 실행해"라고 말하고 있다면 대화가 아니라 프로젝트 지침으로 관리해야 합니다.

## Troubleshooting Rules

- 오류가 발생하면 재설치 전에 `git status`, 실패 명령, 핵심 에러를 먼저 확인한다.
- 패키지 추가가 필요하면 먼저 이유와 대안을 제안하고 승인 후 진행한다.
- 수정 범위가 넓어질 경우 작업을 멈추고 변경 파일 목록을 보고한다.
- 한글 파일명은 새로 만들지 않는다. 기존 한글 파일명은 변경 전 사용자에게 확인한다.

컨텍스트 관리는 대화 정리가 아니라 품질 관리입니다. Codex가 똑똑해 보여도, 오래된 지시와 최신 지시가 충돌하면 결과는 흔들립니다.

설치와 실행 오류 사전

설치와 실행 오류는 메시지가 무섭게 보이지만 대부분 유형이 정해져 있습니다. 다음 문제들은 초보자가 가장 자주 만나는 것들입니다.

command not found: codex

Codex가 설치되지 않았거나, 설치된 경로가 PATH에 들어 있지 않은 상태입니다. npm으로 설치했다면 Node.js와 npm 버전부터 확인합니다. Codex CLI를 npm으로 설치하는 경우 Node.js 버전 요구사항과 설치 방식의 영향을 받을 수 있으므로, 공식 CLI 문서와 설치 안내를 함께 확인하는 것이 좋습니다.⁵

node -v
npm -v
npm list -g @openai/codex --depth=0
which codex

Windows에서는 PowerShell, Git Bash, WSL이 서로 다른 환경입니다. PowerShell에 설치했는데 WSL에서 codex를 실행하면 당연히 못 찾을 수 있습니다. 반대로 WSL에 설치했는데 Windows 터미널에서 실행해도 안 됩니다. "어디에 설치했고, 어디에서 실행하는지"를 맞추세요.

npm 설치가 권한 문제로 실패한다

EACCES: permission denied가 보이면 전역 npm 설치 경로 권한 문제일 가능성이 큽니다. 초보자가 자주 하는 실수는 sudo npm install -g로 밀어붙이는 것입니다. 당장은 설치될 수 있지만 나중에 업데이트와 권한 문제가 더 꼬일 수 있습니다.

가능하면 nvm 같은 Node 버전 관리자를 사용해 사용자 홈 디렉터리 안에 Node와 글로벌 패키지를 설치하세요.

nvm install --lts
nvm use --lts
npm install -g @openai/codex
codex --version

포트 충돌로 앱이 실행되지 않는다

Next.js, Vite, Express 앱을 Codex와 함께 실행하다 보면 EADDRINUSE 또는 "port already in use"가 나올 수 있습니다. 이미 같은 포트를 쓰는 개발 서버가 떠 있는 상태입니다.

macOS와 Linux에서는 다음처럼 확인합니다.

lsof -i :3000
kill -9 <PID>

Windows PowerShell에서는 다음처럼 확인할 수 있습니다.

netstat -ano | findstr :3000
taskkill /PID <PID> /F

Codex에게는 이렇게 요청합니다.

개발 서버 실행 중 포트 충돌이 발생했습니다.
현재 에러 메시지는 `EADDRINUSE: port 3000`입니다.
프로세스를 무조건 종료하지 말고, 어떤 프로세스가 포트를 쓰는지 확인하는 명령과 안전한 대안을 알려 주세요.

Node 버전이 맞지 않는다

빌드 오류처럼 보이지만 실제로는 Node 버전 문제인 경우가 많습니다. 예를 들어 로컬은 Node 18인데 프로젝트는 Node 22 기준으로 만들어졌을 수 있습니다.

node -v
cat package.json
cat .nvmrc

package.json의 engines, .nvmrc, README의 요구 버전을 확인하세요. Codex에게도 반드시 Node 버전을 알려 주는 것이 좋습니다.

현재 Node 버전은 v18.19.0이고, 프로젝트는 .nvmrc에 22가 적혀 있습니다.
nvm으로 버전을 맞춘 뒤 의존성을 재설치하는 안전한 순서를 알려 주세요.
기존 변경 파일은 건드리지 마세요.

Windows 실행 정책과 WSL 경로 문제

Windows PowerShell에서 "스크립트를 실행할 수 없습니다"라는 메시지가 나오면 실행 정책 문제일 수 있습니다. 이 경우 현재 사용자 범위에서 실행 정책을 조정하거나, Git Bash 또는 WSL을 사용하는 방법이 있습니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

WSL을 사용할 때는 경로 문제가 자주 생깁니다. /mnt/c/Users/... 아래의 Windows 파일을 WSL에서 작업하면 파일 감시, 권한, 줄바꿈, 성능 문제가 섞일 수 있습니다. 안정성을 우선한다면 프로젝트를 WSL의 Linux 홈 디렉터리 아래에 두는 편이 좋습니다.

cd ~
git clone <repository-url>
cd <project>
code .

샌드박스가 파일을 찾지 못한다

Codex Cloud나 샌드박스 환경에서 FileNotFoundError가 발생하면 실제로 파일이 없는 것이 아니라, 샌드박스에 업로드되지 않았거나 Git이 추적하지 않는 파일일 수 있습니다. .env, 로컬 DB 파일, 대용량 바이너리, .gitignore에 포함된 파일은 Codex가 보지 못할 수 있습니다.

확인 명령은 간단합니다.

git status --ignored
git ls-files | grep "파일명"

환경 변수 파일은 Git에 커밋하면 안 되는 경우가 많습니다. 대신 .env.example을 만들고, 실제 값은 Codex 설정이나 배포 플랫폼 환경 변수로 전달해야 합니다.

테스트와 빌드가 계속 실패할 때

테스트나 빌드 실패는 Codex에게 맡기기 좋은 작업입니다. 다만 긴 로그를 그대로 던지면 Codex도 핵심을 놓칠 수 있습니다. 실패 명령을 최소 재현 형태로 줄이는 것이 먼저입니다.

예를 들어 전체 빌드가 실패했다면 다음 순서로 줄입니다.

npm run build
npm run typecheck
npm test
npm test -- LoginButton

전체 실패에서 단일 테스트 실패로 줄어들면 원인 찾기가 쉬워집니다. Codex에게 전달할 때도 전체 로그 1,000줄이 아니라 핵심 에러와 직전 변경사항을 줍니다.

실패 명령:
`npm run build`

핵심 에러:
`Type 'string | undefined' is not assignable to type 'string'`
파일: `src/lib/auth.ts:42`

직전 변경사항:
- 로그인 성공 후 redirectTo 파라미터를 추가함
- auth.ts와 LoginForm.tsx를 수정함

요청:
1. 원인 후보를 3개 이하로 좁혀 주세요.
2. 가장 작은 수정안을 먼저 제안해 주세요.
3. 수정 후 실행할 검증 명령을 알려 주세요.

원인이 애매하면 이전 커밋과 비교합니다.

git log --oneline -5
git diff HEAD~1..HEAD

특정 파일만 이전 커밋 상태로 되돌려 실험할 수도 있지만, 실행 전에는 반드시 현재 변경을 커밋하거나 stash로 보호하세요.

git status
git stash push -m "before build troubleshooting"

Codex에게는 "한 번에 다 고치라"고 하지 말고 원인 후보를 하나씩 검증하게 합니다.

빌드 실패 원인을 한 번에 고치려 하지 마세요.
가설을 하나씩 세우고, 각 가설마다 확인 명령 또는 최소 수정안을 제안해 주세요.
첫 번째 가설만 적용한 뒤 결과를 보고 다음 단계로 진행하겠습니다.

이 방식은 느려 보이지만 실제로는 가장 빠릅니다. 한 번에 여러 파일을 고치면 빌드가 통과해도 무엇이 원인이었는지 모르게 됩니다.

Cloud 작업과 로컬 변경이 충돌했을 때

Codex Cloud로 PR을 만들고, 동시에 로컬에서도 같은 파일을 수정하면 충돌이 발생할 수 있습니다. 이때 가장 먼저 할 일은 병합이 아니라 보호입니다. 현재 로컬 작업물을 잃지 않게 커밋하거나 stash로 보관해야 합니다.

git status
git branch --show-current
git diff --stat

아직 커밋하기 애매한 작업이라면 stash를 사용합니다.

git stash push -m "local work before pulling codex cloud changes"

커밋해도 되는 작업이라면 작은 커밋으로 남깁니다.

git add .
git commit -m "Save local work before merging Codex changes"

그다음 원격 변경을 가져옵니다.

git fetch origin
git status
git pull

충돌이 발생하면 git status로 충돌 파일을 확인합니다. GitHub 공식 문서에서도 병합 충돌 해결의 기본 흐름은 충돌 파일 확인, 충돌 표식 제거, 원하는 최종 내용 선택, git add, git commit으로 이어집니다.⁶

충돌 파일 안에는 보통 이런 표식이 보입니다.

<<<<<<< HEAD
현재 브랜치의 내용
=======
병합하려는 브랜치의 내용
>>>>>>> feature/codex-change

초보자는 <<<<<<<, =======, >>>>>>>를 그대로 남겨 둔 채 커밋하는 실수를 자주 합니다. 이 표식은 최종 코드에 남아 있으면 안 됩니다. 둘 중 하나를 선택하거나, 둘을 합쳐 새로운 최종 내용을 만든 뒤 표식을 삭제해야 합니다.

VS Code를 사용한다면 충돌 영역 위에 다음 선택지가 표시될 수 있습니다.

• Accept Current Change: 현재 브랜치 내용을 유지합니다.

• Accept Incoming Change: 들어오는 브랜치 내용을 사용합니다.

• Accept Both Changes: 양쪽 내용을 모두 남깁니다.

• Compare Changes: 양쪽 차이를 비교합니다.

선택 후에는 반드시 테스트를 실행합니다.

git add .
git commit -m "Resolve merge conflict"
npm test
npm run build

Codex에게 충돌 해결을 맡길 수도 있지만, 최종 판단은 사람이 해야 합니다. 특히 인증, 결제, 데이터베이스 마이그레이션, 권한 로직이 섞인 충돌은 "양쪽 다 반영"이 항상 정답이 아닙니다.

Codex에게는 이렇게 맡기세요.

현재 병합 충돌을 해결하려고 합니다.
먼저 충돌 파일 목록을 확인하고, 각 파일에서 양쪽 변경 의도를 요약해 주세요.
직접 수정하기 전에 파일별 해결 전략을 제안하세요.
인증 로직과 데이터베이스 마이그레이션은 임의로 합치지 말고 내 승인을 기다리세요.

이미 병합하다가 너무 꼬였다면 중단할 수 있습니다.

git merge --abort

단, 이 명령은 진행 중인 merge를 취소합니다. 이미 충돌 해결 중 수정한 내용이 있다면 사라질 수 있으므로 실행 전 상태를 확인하세요.

git status
git diff

원격 PR의 변경 자체가 잘못되었다면 병합보다 revert가 나을 수 있습니다.

git revert <commit-hash>

revert는 이전 커밋을 삭제하는 것이 아니라 "그 변경을 취소하는 새 커밋"을 만듭니다. 팀 작업에서는 기록을 안전하게 남길 수 있어 유용합니다.

문제 상황별 빠른 처방표

아래 표는 막혔을 때 빠르게 펼쳐 보는 사전입니다. 중요한 것은 "증상 → 원인 후보 → 첫 행동"의 순서입니다.

이 표를 외울 필요는 없습니다. 대신 문제가 생겼을 때 "지금 내가 어느 줄에 있는가?"를 찾으면 됩니다.

Codex에게 문제 해결을 맡기는 좋은 프롬프트

문제 해결 프롬프트는 일반 개발 프롬프트와 다릅니다. "기능을 만들어 줘"가 아니라 "원인을 좁혀 줘"가 핵심입니다. 다음 템플릿을 복사해 두고 쓰면 좋습니다.

문제 상황:

실패 명령:

핵심 에러 메시지:

최근 변경사항:

현재 환경:
- OS:
- Node:
- 패키지 매니저:
- 브랜치:

제약 조건:
- 패키지 추가 금지 / 허용
- 수정 가능한 파일:
- 수정 금지 파일:

요청:
1. 원인 후보를 가능성 높은 순서로 정리해 주세요.
2. 가장 작은 확인 명령부터 제안해 주세요.
3. 직접 수정 전 변경 계획을 보여 주세요.
4. 수정 후 검증 명령을 알려 주세요.

실제 예시는 이렇습니다.

문제 상황:
Next.js 앱에서 `npm run build`가 실패합니다.

실패 명령:
`npm run build`

핵심 에러 메시지:
`Module not found: Can't resolve '@/components/ui/button'`

최근 변경사항:
Codex가 pricing 페이지 UI를 개선하면서 Button 컴포넌트를 import했습니다.

현재 환경:
- OS: Windows 11 + WSL Ubuntu
- Node: v22.3.0
- 패키지 매니저: npm
- 브랜치: feature/pricing-redesign

제약 조건:
- 새 UI 라이브러리 추가 금지
- 수정 가능 파일: app/pricing/page.tsx, components 내부
- 수정 금지 파일: 인증, 결제, DB 관련 파일

요청:
원인 후보를 먼저 정리하고, 가장 작은 수정으로 빌드를 통과시키는 방법을 제안해 주세요.
직접 수정하기 전에 어떤 파일을 바꿀지 알려 주세요.

이렇게 주면 Codex가 로그 전체를 추측으로 해석하는 대신, 현재 상황 안에서 원인을 좁힐 가능성이 높아집니다.

그래도 안 될 때: 좋은 도움 요청 만들기

어떤 문제는 혼자 해결하기 어렵습니다. 이때도 "안 돼요"라고만 쓰면 도움을 받기 어렵습니다. 좋은 질문에는 재현 가능한 정보가 들어 있습니다.

도움을 요청할 때는 다음 정보를 준비합니다.

• Codex App 또는 CLI 버전

• OS와 실행 환경: macOS, Linux, Windows, WSL, Remote SSH 등

• 실행한 명령과 전체 에러 중 핵심 부분

• 문제가 항상 발생하는지, 가끔 발생하는지

• 마지막으로 성공했던 시점과 그 이후 바뀐 것

• 이미 시도한 해결 방법

• 민감 정보를 제거한 설정 일부

절대 공유하면 안 되는 것도 있습니다.

• API 키와 토큰

• auth.json 원본

• .env 실제 값

• 세션 쿠키와 인증 헤더

• 고객 데이터와 개인정보가 포함된 로그

로그를 공유해야 한다면 핵심 에러 주변 몇십 줄만 추려서 올리세요. 전체 로그를 붙여 넣는 것은 읽는 사람에게도 부담이고, 민감 정보 유출 위험도 큽니다.

초보자를 위한 최종 복구 루틴

마지막으로, 문제가 생겼을 때 그대로 따라 할 수 있는 루틴을 정리해 보겠습니다.

# 1. 현재 위치와 Git 상태 확인
pwd
git status
git diff --stat

# 2. 작업물 보호
# 커밋 가능한 상태라면
git add . && git commit -m "Save work before troubleshooting"

# 커밋하기 애매하다면
git stash push -m "before troubleshooting"

# 3. 버전과 환경 확인
codex --version
node -v
npm -v

# 4. 실패 명령을 다시 한 번만 실행하고 핵심 에러 확보
npm run build

# 5. Codex에게 원인 좁히기 요청

여기서 중요한 부분은 2번입니다. 작업물을 보호하지 않고 문제 해결을 시작하면, 원래 문제보다 "내가 어디까지 바꿨는지 모르겠다"는 문제가 더 커집니다.

Codex와 함께 앱을 만들다 보면 실패는 계속 생깁니다. 로그인도 풀리고, 빌드도 깨지고, 테스트도 실패하고, 병합 충돌도 납니다. 하지만 이제 실패는 막다른 길이 아닙니다. 오류 메시지는 단서이고, diff는 지도이며, Git은 안전망입니다. Codex는 그 길을 함께 추적하는 동료입니다.

다음 장에서는 이 개인적인 복구 습관을 팀 운영으로 확장합니다. 혼자서는 git status와 AGENTS.md만 잘 관리해도 충분하지만, 팀에서는 권한, 리뷰, 브랜치 전략, 비용 관리, 공통 프롬프트 규칙까지 함께 맞춰야 합니다. 이제 Codex를 "내 도구"에서 "팀의 개발 시스템"으로 다루는 방법을 살펴보겠습니다.

참고

¹Troubleshooting - Codex app | OpenAI Developers

²Quickstart - Codex | OpenAI Developers

³OpenAI Status

⁴Config basics - Codex | OpenAI Developers

⁵CLI - Codex | OpenAI Developers

⁶명령줄을 사용하여 병합 충돌 해결 | GitHub Docs