[Codex] Codex 프롬프팅 가이드

Step 1. 프롬프트를 4레벨로 구분하기

Level 1 — 나쁜 프롬프트

로그인 버그 고쳐줘.

문제는 Codex가 판단해야 할 것이 너무 많다는 점이다.

어떤 버그인지, 어느 파일인지, 리팩토링까지 해도 되는지, 테스트는 해야 하는지 모두 불명확하다.

 

 

Level 2 — 보통 프롬프트

로그인 실패 시 에러 메시지가 제대로 표시되지 않아.

관련 코드를 찾아서 수정해줘.

조금 나아졌다.

Codex가 탐색해야 한다는 것은 알 수 있다.

하지만 변경 범위와 완료 조건이 여전히 애매하다.

 

 

Level 3 — 강한 프롬프트

로그인 실패 시 서버에서 반환한 에러 메시지가 UI에 표시되지 않는 문제를 수정해줘.

관련 로그인 흐름을 먼저 확인하고 원인을 찾아.

제약:
- 기존 API contract는 변경하지 마.
- 새로운 dependency는 추가하지 마.
- 관련 없는 코드는 리팩토링하지 마.

완료 조건:
- 원인을 설명할 수 있어야 함
- 버그 수정
- 관련 테스트 추가 또는 수정
- test와 lint 실행
- 마지막에 변경 내용을 요약

이 정도 수준부터 실무에서 매우 강력하다.

 

 

Level 4 — Agent형 프롬프트

로그인 실패 시 서버의 에러 메시지가 UI에 전달되지 않는 문제를 해결해줘.

먼저 관련 코드 경로와 기존 에러 처리 패턴을 조사해.
바로 수정하지 말고 원인과 수정 계획을 간단히 정리한 다음 구현해.

기존 구현 패턴을 우선 재사용하고,
문제 해결에 필요하지 않은 리팩터링은 하지 마.

성공 조건:
- 문제의 실제 원인이 제거되어야 함
- 기존 API와 타입 호환성이 유지되어야 함
- regression을 방지할 테스트가 있어야 함
- 관련 test / lint / typecheck를 통과해야 함

구현 후 diff를 스스로 리뷰해서
불필요한 변경, 누락된 edge case, 테스트 부족이 없는지 확인해.

마지막에는 다음만 알려줘:
1. 원인
2. 변경 사항
3. 검증 결과
4. 남아 있는 위험

여기서 Codex는 단순히 “코드 작성”을 하는 것이 아니라,

• 탐색(Explore) → 계획(Plan) → 구현(Implement) → 검증(Verify) → 리뷰(Review)

흐름으로 작업하게 된다.

이 패턴은 기억할 필요가 있다.

 

Step 2. 확장된 Codex 프롬프트 공식 (GCCDV)

G = Goal
C = Context
C = Constraints
D = Done when
V = Verify

예를 들면

[Goal]
사용자 검색 API의 응답 속도를 개선해줘.

[Context]
현재 /users/search 호출이 데이터가 많아지면 느려진다.
관련 repository와 query 코드를 확인해.

[Constraints]
API response shape은 변경하지 마.
dependency를 추가하지 마.
현재 DB abstraction을 유지해.

[Done]
동일한 검색 결과를 유지하면서 병목을 제거해.

[Verify]
관련 테스트를 실행하고,
가능하다면 개선 전후 query 동작도 확인해.

실제 사용에서는 [Goal] 같은 제목을 매번 쓸 필요는 없다.

더 자연스럽게 써도 된다.

사용자 검색 API가 데이터가 많을 때 느려져.

관련 query와 repository부터 확인해서 병목 원인을 찾아줘.

API response shape과 DB abstraction은 유지하고,
새 dependency는 추가하지 마.

수정 후 관련 테스트를 실행하고
어떤 병목을 어떻게 제거했는지 설명해줘.

Codex 입장에서는 사실상 동일한 구조이다.

 

Step 3. 실무에서 가장 많이 쓰는 프롬프트 10개

1. 코드베이스 탐색

이 기능이 어떻게 동작하는지 코드베이스에서 추적해줘.

관련 entry point부터 시작해서
호출되는 주요 함수와 데이터 흐름을 따라가.

아직 코드는 수정하지 마.

마지막에는 핵심 파일과 각각의 역할만 정리해줘.

가장 권장되는 시작 프롬프트이다.

 

2. 기능 구현

사용자가 자신의 프로필 이미지를 삭제할 수 있는 기능을 추가해줘.

먼저 기존 프로필 수정 흐름과 파일 삭제 패턴을 확인해.
기존 architecture와 naming convention을 따라가.

새로운 abstraction은 꼭 필요한 경우에만 만들어.

구현 후:
- 관련 테스트 추가
- test
- lint
- typecheck

를 실행하고 결과를 알려줘.

여기서 중요한 부분은

먼저 기존 패턴을 확인해.

이다.

 

Codex가 자기 스타일대로 새 구조를 발명하는 것을 줄여준다.

 

3. 버그 수정

다음 버그를 조사해서 수정해줘.

증상:
새로 가입한 사용자가 첫 로그인 후 /dashboard 대신 /login으로 돌아간다.

먼저 재현 가능한 코드 경로를 찾아서 root cause를 확인해.
증상만 우회하는 수정은 하지 마.

관련 테스트를 추가해서 regression을 막고,
수정 후 관련 테스트를 실행해.

Regression은 기존에 잘 작동하던 기능이 코드 수정(새 기능 추가, 버그 수정 등) 이후 갑자기 오작동하거나 멈추는 현상을 말한다. 쉽게 말해 "하나를 고쳤더니 다른 곳이 망가지는 증상"이다.

 

여기서 강력한 키워드는

root cause를 확인해.
증상만 우회하지 마.

이다.

 

발생한 문제의 근본적인 원인을 해결하는 쪽으로 수정하지 않고 눈에 보이는 표면적인 버그만 잡는 현상을 줄여준다.

 

4. 에러 메시지 기반 디버깅

터미널 에러를 그대로 붙이고

이 에러의 원인을 코드베이스에서 조사해줘.

<에러 로그>

가능성이 높은 원인부터 추적하되 추측으로 수정하지 마.
실제 코드와 설정을 확인해서 원인을 특정해.

원인이 확인되면 최소 변경으로 수정하고
같은 문제가 재발하지 않도록 검증해.

중요한 부분은

추측으로 수정하지 마.

이다.

 

5. 작은 리팩토링

이 함수가 너무 길어서 읽기 어려워.

behavior는 바꾸지 말고 readability를 개선해줘.

조건:
- public API 변경 금지
- 새로운 dependency 금지
- 과도하게 작은 함수로 쪼개지 마
- 기존 프로젝트 스타일 유지

관련 테스트가 있다면 실행해서 behavior가 유지되는지 확인해.

특히 리팩토링 후에도 기존의 동작이 유지되도록

behavior는 바꾸지 마.

가 중요하다.

 

6. 테스트 작성

이 모듈의 테스트를 보강해줘.

먼저 현재 테스트 구조와 testing convention을 파악해.

happy path만 추가하지 말고
실제 regression 가능성이 높은 edge case를 찾아서 테스트해.

production code는 테스트를 통과시키기 위한 목적으로 불필요하게 변경하지 마.

• Testing Convention: 테스트 코드를 작성할 때 개발자들 사이에 따르기로 한 공통의 약속, 규칙, 또는 모범 관례
• Production Code: 테스트 코드가 아닌, 실제 코드

여기서 마지막 문장 

production code는 테스트를 통과시키기 위한 목적으로 불필요하게 변경하지 마.

이 매우 중요하다.

Codex가 테스트 편의를 위해 실제 코드를 이상하게 바꾸는 것을 방지한다.

7. 코드 리뷰

구현을 끝낸 뒤 이렇게 한 번 더 시킨다.

현재 변경사항을 senior engineer 관점에서 리뷰해줘.

특히 확인해:
- bug 가능성
- edge case
- regression
- error handling
- 타입 안정성
- concurrency 문제
- security 문제
- 테스트 누락
- 불필요한 복잡성

문제가 없다면 억지로 문제를 만들지 마.

중요도 순으로 알려줘.

이 프롬프트는 굉장히 유용하다.

 

8. 구현 전 Plan

규모 큰 작업에서는 바로 코딩시키지 않는다.

이 기능을 구현해야 해.

아직 코드는 수정하지 마.

먼저 코드베이스를 조사해서:
- 관련 파일
- 현재 구조
- 변경이 필요한 지점
- 예상 영향 범위
- 테스트 전략

을 확인해.

그 다음 최소 변경으로 구현할 수 있는 계획을 작성해줘.

그리고 Codex가 제안한 계획이 괜찮으면

좋아. 그 계획대로 구현해.

구현하면서 예상과 다른 구조를 발견하면
기존 계획을 억지로 따르지 말고 실제 코드에 맞춰 조정해.

완료 후 테스트와 lint/typecheck까지 실행해.

이 Plan → Implement 흐름이 매우 중요하다.

 

9. 최소 변경

실제 서비스에 들어갈 코드를 Codex로 수정하거나 구현할 때 자주 쓰는 프롬프트이다.

이 문제를 해결하되 diff를 가능한 작게 유지해줘.

관련 없는 formatting, rename, cleanup, refactoring은 하지 말고
문제 해결에 필요한 코드만 변경해.

Codex는 범위 제약을 명확히 줄수록 불필요한 코드 변경을 하지 않는다. Codex 공식 가이드에서도 scope와 성공 조건을 명시하는 것을 권장한다.

 

10. 완전 자율형 작업

Codex에게 상당한 자율성을 주는 경우이다.

이 이슈를 end-to-end로 해결해줘.

먼저 관련 코드와 테스트를 조사하고
root cause를 확인한 뒤 필요한 변경을 구현해.

기존 architecture와 convention을 우선 재사용해.

완료 기준:
- 요구사항 충족
- regression test 포함
- 관련 tests 통과
- lint/typecheck 통과
- diff 자체 리뷰 완료

중간에 사소한 구현 선택이 필요하면
프로젝트의 기존 패턴을 기준으로 합리적으로 판단해서 계속 진행해.

다만 다음 상황에서는 임의로 결정하지 마:
- public API 변경
- DB schema 변경
- 새로운 dependency 도입
- 보안 정책 변경

마지막에는 변경 사항과 검증 결과만 간결하게 알려줘.

Codex를 개발자처럼 일을 맡기는 방식이다.

 

Step 4. Ask와 Do를 구분하기

Codex에는 두 종류의 프롬프트가 있다.

 

Ask

이 인증 구조가 어떻게 동작하는지 설명해줘.

이 버그의 원인을 조사해줘.
아직 수정하지 마.

 

Do

원인을 확인했으니 수정해줘.

관련 테스트까지 추가하고 검증해.

 

초보자는 둘을 한 번에 섞는다.

이게 왜 안 되는지 알려주고 아무튼 고쳐줘.

숙련자는 조사[Ask] → 확인 → 수정[Do] 과정을 구분한다.

특히 복잡하거나 원인이 불명확한 작업에는 이러한 방식이 좋다.

다만 항상 분리해야 하는 것은 아니다.

예를 들어, 변수명을 변경하는 것과 같이 위험도도 낮고 명확한 작업은 Ask 없이 바로 Do해도 된다.

Step 5. 방법보다 결과를 지정하라

자주 쓰이는 프롬프트로 다음과 같은 프롬프트가 있다.

UserService를 수정하고
Repository를 수정하고
Controller를 수정하고
테스트를 추가해.

그런데 이것은 미리 구현 방법을 정해버린 것이다.

 

더 좋은 프롬프트는

회원 탈퇴 시 사용자의 활성 세션이 모두 무효화되도록 해줘.

현재 logout/session 처리 구조를 먼저 조사하고
기존 architecture에 가장 자연스럽게 맞는 방식으로 구현해.

기존 API contract는 유지해.

이다.

 

Codex가 코드베이스를 조사해서 더 나은 구현 경로를 선택할 수 있는 여지를 준다.

현재 OpenAI 공식 가이드도 이를 outcome-first prompting이라고 설명하며, 결과와 성공 기준은 명확히 하되 꼭 필요한 경우가 아니면 작업 절차를 지나치게 고정하지 않는 방식을 권장한다.

 

Step 6. 실습

이제 VS Code에서 본인의 아무 프로젝트나 열고 Codex에 아래 프롬프트를 넣어보자.

현재 프로젝트에서 핵심적인 기능 하나를 골라줘.

아직 코드는 수정하지 마.

그 기능이 동작하는 전체 흐름을 코드에서 추적해서 설명해줘.

다음을 반드시 포함해:
- entry point
- 주요 함수/클래스
- 데이터 흐름
- 외부 dependency
- error handling
- 관련 테스트

추측하지 말고 실제 코드 기준으로 확인해.

마지막에는
“이 기능을 안전하게 수정하려면 꼭 알아야 하는 것”
5개를 정리해줘.

 

Codex 답변을 확인한 다음 두 번째 프롬프트를 보낸다.

좋아.

이 기능에 작은 개선을 하나 제안해줘.

조건:
- 기존 architecture를 유지
- 새로운 dependency 없음
- 30분 이내 수준의 작은 변경
- 테스트 가능한 변경

아직 구현하지 말고,
변경 목적 / 수정할 파일 / 구현 계획 / 테스트 계획만 작성해줘.

 

그리고 마지막 세 번째 프롬프트를 보낸다.

좋아. 그 계획대로 구현해.

관련 없는 코드는 수정하지 말고
최소한의 diff를 유지해.

구현 후 관련 테스트를 실행하고
현재 변경사항을 스스로 리뷰해.

마지막에는:
1. 변경 파일
2. 변경 이유
3. 테스트 결과
4. 남은 위험

만 알려줘.

이 3번의 대화를 통해 바로

• 탐색(Explore) → 계획(Plan) → 구현(Implement) → 검증(Verify) → 리뷰(Review)

를 경험하게 된다.

 

Step 7. 기억해야하는 프롬프트 문장 5가지

앞으로 Codex를 쓰면서 거의 매일 쓰게 될 것이다.

먼저 관련 코드를 조사해.

아직 코드는 수정하지 마.

기존 패턴을 우선 재사용해.

관련 없는 코드는 변경하지 마.

구현 후 테스트하고 diff를 스스로 리뷰해.

이 다섯 문장만 습관화해도 Codex 사용 품질이 상당히 높아진다.