당신은 코덱스 프롬프트를 잘못 쓰고 있다. OpenAI 개발자에게 배우는 Codex 프롬프트 제대로 쓰는 법.

코덱스에게 “로그인 버그 고쳐줘”라고 말하면 언뜻 충분해 보인다. 그러나 어떤 재현 절차를 쓸지, 어느 파일까지 바꿔도 되는지, 기존 동작을 무엇으로 지킬지, 어떤 테스트가 통과하면 끝인지가 모두 비어 있다. 모델은 코딩보다 먼저 제품 판단을 추측해야 한다.

OpenAI 공식 가이드가 반복하는 핵심은 화려한 주문이 아니다. 저장소를 조사하고, 구현하고, 실제 도구로 검증하고, 필요한 경우 실패를 고쳐 완료까지 가도록 일의 경계와 증거를 주는 것이다. 좋은 Codex 프롬프트는 개발자에게 보내는 짧은 이슈 카드와 인수 기준을 합친 문서에 가깝다.

일반 챗봇 프롬프트와 Codex 프롬프트는 다르다

일반 챗봇은 답변을 생성하면 작업이 끝난다. Codex는 파일을 읽고, 명령을 실행하고, 패치를 적용하고, 테스트 결과를 관찰한 뒤 다시 수정한다. 따라서 “정답을 말해라”보다 “이 저장소에서 무엇을 바꾸고 어떤 증거로 확인하라”가 더 중요하다.

프롬프트에는 구현 방법을 모두 미리 지시할 필요가 없다. 오히려 코드베이스를 먼저 조사하고 기존 패턴을 따르게 하면 잘못된 가정을 줄일 수 있다. 반면 사용자만 아는 제품 요구, 금지 범위, 성공 기준은 생략하면 안 된다.

• 결과: 사용자가 보게 될 변화
• 범위: 바꿔도 되는 영역과 유지할 동작
• 증거: 테스트·빌드·스크린샷·벤치마크
• 중단 조건: 필요한 정보나 권한이 없을 때 보고할 내용

좋은 프롬프트의 7가지 구성요소

첫째는 결과다. “설정을 개선해라”가 아니라 “모바일에서 저장 버튼이 가려지지 않게 하고 기존 데스크톱 레이아웃은 유지하라”처럼 관찰 가능한 변화를 쓴다. 둘째는 재현·배경, 셋째는 변경 범위, 넷째는 보존해야 할 제약이다.

다섯째는 조사 규칙, 여섯째는 검증 명령, 일곱째는 완료 보고 형식이다. 모든 작업에 일곱 칸을 채울 필요는 없지만, 모델이 잘못 추측했을 때 비용이 큰 선택은 반드시 명시한다.

• 먼저 관련 파일과 기존 테스트를 읽기
• 사용자가 만든 변경과 무관한 코드를 되돌리지 않기
• 작업에 맞는 테스트를 실행하고 실패 원인까지 확인하기
• 완료 시 변경·검증·남은 위험을 짧게 보고하기

나쁜 요청을 실행 가능한 명세로 바꾸기

“검색이 느린데 최적화해줘. 끝까지 알아서 해”는 목표 수치도 정확성 제약도 없다. 모델이 캐시를 넣거나 결과 수를 줄여 빨라졌다고 보고해도 사용자가 원하는 개선인지 판단할 수 없다.

아래처럼 성능 목표, 측정 도구, 보존 조건, 허용 범위를 붙이면 Codex가 조사와 반복 실험을 스스로 선택하면서도 완료 여부는 객관적으로 판정할 수 있다.

목표: 상품 검색 API의 p95를 350ms 아래로 낮춰라.
범위: search 서비스와 관련 테스트만 수정한다. 공개 응답 스키마는 바꾸지 않는다.
조사: 먼저 현재 벤치마크와 느린 쿼리를 재현하고 병목의 근거를 남긴다.
검증: npm run benchmark:search와 관련 통합 테스트를 실행한다.
완료: 변경 이유, 전후 수치, 실행한 테스트, 남은 위험을 보고한다.

도구 사용과 자율성은 발동 조건으로 써라

“필요하면 검색해”보다 “현재 버전이나 공식 API 동작이 필요한 주장에는 공식 문서를 확인하라”가 낫다. “테스트해”보다 “변경한 패키지의 단위 테스트를 실행하고, 공용 타입을 바꾸면 전체 타입 검사를 추가하라”가 낫다. 도구 이름보다 언제 왜 써야 하는지를 알려주는 방식이다.

자율성을 원한다면 안전한 범위도 함께 준다. 로컬의 일회용 픽스처로만 도는 테스트는 자유롭게 반복해도 되지만 운영 데이터, 배포, 비용이 발생하는 외부 API는 별도 승인이 필요하다고 나눈다. 권한 확대와 완료 의지는 같은 문장이 아니다.

강한 모델일수록 지시를 덜 쌓아야 한다

OpenAI는 최신 Codex 모델로 옮길 때 예전 모델을 붙잡기 위해 추가했던 장황한 계획 지시, 반복 확인, 강제 보고 문구를 다시 검토하라고 권한다. 서로 다른 시대의 지침을 계속 누적하면 같은 상황에 “즉시 구현”과 “항상 계획부터 승인”이 동시에 걸리는 식의 충돌이 생긴다.

실패 사례를 발견했을 때마다 프롬프트에 문장을 추가하지 말고 위치를 고른다. 이번 작업만의 요구는 프롬프트, 저장소 전체의 규칙은 AGENTS.md, 반복 워크플로는 Skill, 여러 턴 지속될 완료 목표는 Goal에 둔다. 이것이 이 시리즈 여섯 글의 경계다.

복사해서 쓰는 Codex 작업 프롬프트

아래 템플릿은 모든 칸을 의무로 만들려는 것이 아니다. 한 줄 수정이면 결과와 검증만으로 충분하다. 영향 범위가 큰 기능일수록 재현·제약·완료 보고를 추가한다.

완료 조건을 “잘 작동함”으로 쓰지 말고 사용자가 확인할 표면을 지정한다. 테스트 이름, URL, 스크린샷 뷰포트, 성능 수치처럼 외부에서 확인 가능한 증거가 좋다.

[결과]
사용자가 보게 될 최종 변화를 한 문장으로 쓴다.

[배경·재현]
현재 동작, 오류, 관련 경로를 쓴다.

[범위·제약]
수정 가능한 영역과 반드시 유지할 동작을 쓴다.

[작업 방식]
관련 코드를 먼저 조사하고 기존 패턴을 따른다. 필요한 구현과 테스트까지 완료한다.

[검증]
실행할 테스트·빌드·수동 확인을 쓴다.

[완료 보고]
변경, 검증 결과, 남은 위험만 요약한다.

자주 묻는 질문