Codex 첫 요청은 이렇게 쓰세요: 코딩 프롬프트 실전 예시

요약: “알아서 잘 만들어 줘”보다 “이 입력에서 이 결과가 나오게 해 줘”가 작업 기준을 세우기 쉽습니다. 첫 요청에는 해결할 문제와 확인 방법을 함께 넣으세요.

1. 요청하기 전에 완료 장면을 정하기

코딩 작업을 맡기기 전, 사용자가 어떤 화면에서 무엇을 할 수 있어야 하는지 한 문장으로 적어 보세요. “검색 개선”은 방향이고, “검색 결과가 없으면 빈 화면 대신 안내 문구를 보여 준다”는 확인 가능한 동작입니다. 후자의 문장이 있으면 코드를 수정한 뒤 결과를 비교할 수 있습니다.

OpenAI의 Codex 프롬프트 안내도 원하는 동작, 관련 코드나 재현 단계, 유지할 조건, 검증 방법을 강조합니다. 여기서 제안하는 예시는 이 원칙을 가상의 블로그 검색 기능에 적용한 자체 작성 예시입니다. 모든 항목을 형식적으로 채우기보다 결과를 바꿀 수 있는 정보를 넣는 데 집중하세요.

2. 네 가지 정보를 짧게 전달하기

문제: 무엇이 불편하고 언제 발생하는지 적습니다. 위치: 관련 화면이나 파일을 알려 줍니다. 조건: 바꾸면 안 되는 기능을 지정합니다. 검증: 무엇을 확인하면 완료라고 볼지 적습니다. 이 네 가지면 작은 작업을 시작하기에 충분한 경우가 많습니다.

예를 들어 “모바일 검색이 이상하다”만으로는 입력창 크기, 검색 속도, 결과 표시 중 어느 문제인지 알기 어렵습니다. “휴대전화 너비에서 검색 버튼이 줄바꿈되고 입력창과 겹친다”처럼 관찰 내용을 적으세요. 원인을 확신하지 못했다면 “CSS 문제다”라고 단정할 필요가 없습니다. 증상과 원인 추측을 구분하면 조사할 여지가 생깁니다.

3. 복사해서 고쳐 쓸 첫 요청 예시

블로그 검색 화면에서 결과가 0개일 때 안내가 없습니다.
검색어가 입력되어 있고 결과가 없으면
'검색 결과가 없습니다. 다른 검색어를 입력해 보세요.'를 보여 주세요.
검색어가 비어 있으면 기존 화면을 유지해 주세요.
대상은 src/search 폴더이며, API 응답 형식은 바꾸지 마세요.
기존 테스트 방식에 맞춰 필요한 검증을 수행해 주세요.
완료 후 변경 파일, 확인한 동작, 실행 명령과 결과를 알려 주세요.
직접 확인하지 못한 사항은 별도로 표시해 주세요.

이 예시에서 중요한 것은 안내 문구의 길이가 아니라 빈 검색어와 검색 결과 0개를 구분한 점입니다. 조건을 놓치면 처음 페이지를 열었을 때부터 “결과가 없다”는 메시지가 보일 수 있습니다. 이런 경계 사례를 한두 개 넣으면 사용자 의도를 더 정확히 전달할 수 있습니다.

4. 후속 요청은 관찰한 차이만 전달하기

첫 결과가 기대와 다르면 같은 요청 전체를 다시 붙여 넣기보다 다른 점을 말해 주세요. “검색 중에도 결과 없음 메시지가 잠깐 보입니다. 로딩 중에는 표시하지 말고, 응답이 끝난 뒤에만 보여 주세요”처럼 새로 관찰한 상황을 전달하면 다음 수정의 기준이 분명해집니다.

직접 파일을 수정했다면 그 사실도 알리는 것이 좋습니다. “안내 문구는 제가 바꿨습니다. 그 문구는 유지하고 표시 조건만 수정해 주세요”처럼 현재 상태를 기준으로 요청하세요. 이전 대화에서 정한 모습보다 실제 파일이 우선입니다. 수정 직후에는 브라우저 캐시나 실행 중인 서버 상태 때문에 이전 화면을 보고 있지 않은지도 확인할 필요가 있습니다.

5. 작업이 어긋났을 때 확인하는 체크리스트

• 범위가 커졌는가? 검색 화면 외에 수정된 파일의 필요성을 설명하도록 요청합니다.
• 실행과 제안을 섞었는가? 실제 실행한 명령과 실행 방법 안내를 분리해 달라고 합니다.
• 환경에서 막혔는가? 필요한 도구, 접근할 수 없는 경로, 실패한 설치 단계 중 무엇인지 확인합니다.
• 성공 기준이 모호한가? 정상 검색, 결과 0개, 로딩 중처럼 비교할 사례를 구체화합니다.

권한 문제로 명령을 실행하지 못한 경우에는 코드가 틀렸다고 즉시 결론 내리지 마세요. 반대로 명령이 실행되었다는 것만으로 원하는 동작이 검증된 것도 아닙니다. “어떤 사례를 확인했고 무엇이 남았는지”를 답변에서 읽을 수 있어야 합니다. 작업 결과를 판단하기 어려우면 각 변경이 원래 요청의 어느 조건을 해결하는지 연결해 달라고 요청하세요.

6. 검색 화면의 상태를 표로 정리해 요청하기

화면 기능에서는 정상 결과만 설명하면 중요한 상태가 빠집니다. 검색 화면이라면 처음 열었을 때, 입력만 했을 때, 응답을 기다릴 때, 결과가 없을 때, 서버가 실패했을 때가 서로 다릅니다. “검색 결과 없음” 문구를 추가하려는 작은 작업도 이 상태를 나누어야 검색 중에 잘못된 문구가 나타나는 일을 줄일 수 있습니다. 아래 표는 가상 블로그의 요구사항 예시이며 실제 제품의 정책에 맞춰 바꾸어야 합니다.

상태	화면에 보여 줄 내용	피해야 할 결과
검색 전	기존 안내 화면	처음부터 결과 없음 표시
요청 중	기존 로딩 표시	빈 결과 안내가 먼저 나타남
성공·결과 있음	검색 결과 목록	오래된 결과와 새 결과 혼합
성공·결과 0개	결과 없음 안내	오류인 것처럼 표시
요청 실패	실패 안내와 재시도 방법	정상적인 빈 결과로 오해

표를 만든 뒤에는 기준이 불명확한 칸만 결정하면 됩니다. 예를 들어 검색어가 공백뿐이면 요청하지 않을지, 이전 검색 결과를 유지할지 정하세요. 입력할 때마다 검색하는 화면과 검색 버튼을 눌러야 요청하는 화면도 다릅니다. 기존 방식이 있다면 그 방식을 유지하도록 적으면 됩니다. 사용자 관점의 상태표는 구현 코드를 미리 지정하지 않으면서도 원하는 동작을 정확하게 전달하는 방법입니다.

7. 작은 작업용과 큰 작업용 요청을 다르게 구성하기

바로 구현하기 적합한 작은 요청

검색 결과 없음 안내를 구현해 주세요.
완료된 응답이 성공이고 결과 배열이 비었을 때만 표시합니다.
요청 중·요청 실패·아직 검색하지 않은 상태에서는 표시하지 않습니다.
기존 로딩과 오류 안내, API 형식, 검색 실행 시점은 유지하세요.
프로젝트의 기존 스타일과 테스트 도구를 사용하세요.
새 라이브러리 추가가 필요한지 먼저 현재 코드에서 판단하세요.
변경 내용과 상태별 검증 근거를 정리해 주세요.

이 요청은 원하는 행동과 유지할 조건을 분리합니다. “새 라이브러리를 쓰지 말라”는 제한만 강하게 적으면 기존 코드로 불가능한 문제에서도 억지로 구현할 수 있습니다. 현재 구조에서 가능한지 판단하게 하고, 불필요한 의존성 추가를 피하는 이유를 설명하는 편이 낫습니다. 구현 선택을 모두 지정하기보다 제품에서 중요한 결과를 먼저 적으세요.

선택지가 있는 작업은 조사부터 시작하기

검색어 자동 완성 기능을 추가하려고 합니다.
현재 검색 실행 방식, 데이터 크기, 관련 화면 구조를 조사해 주세요.
클라이언트 검색과 서버 검색 중 현재 프로젝트에 맞는 선택지를 비교하세요.
선택지마다 수정 범위, 필요한 데이터, 검증 방법을 설명하세요.
사용자 입력 전송 방식이나 API 변경이 필요한 결정은 분명히 표시하세요.
아직 구현하지 말고 현재 자료로 판단할 수 없는 조건을 남겨 주세요.

자동 완성처럼 설계가 달라질 수 있는 작업에서는 데이터 위치와 크기를 모른 채 구현부터 시작하면 나중에 범위가 커집니다. 먼저 선택지를 검토하고 방향을 정한 뒤 구현 요청으로 넘어가세요. 반대로 문구 한 줄 수정은 긴 설계 문서가 필요하지 않습니다. 작업의 어려움보다 “결정하지 않은 조건이 얼마나 많은가”를 기준으로 조사 단계를 둘지 선택할 수 있습니다.

8. 결과가 틀릴 때 사용할 후속 요청 네 가지

첫 결과가 기대와 다르면 불만의 표현보다 관찰된 차이를 보내세요. 화면, 입력, 동작 순서를 함께 적으면 재현하기 쉽습니다. 예를 들어 “안 됩니다”는 저장 여부와 메시지 문제를 구분할 수 없지만 “검색 버튼을 누른 직후 결과 없음 문구가 나타나고, 응답이 오면 목록으로 바뀝니다”는 표시 조건을 조사할 단서를 줍니다.

표시 조건 보완:
검색 버튼을 누른 직후 빈 결과 문구가 먼저 나타납니다.
요청 중에는 기존 로딩만 보이도록 표시 조건을 조정하세요.
이미 바뀐 안내 문구와 정상 결과 목록은 유지하세요.

범위 보완:
검색 화면 수정 외에 공통 레이아웃도 바뀌었습니다.
공통 변경이 이번 요구사항에 필요한 이유를 설명하세요.
필요하지 않은 변경만 분리해 되돌리는 방안을 제시하세요.
다른 사람이 만든 변경은 보존하세요.

검증 보완:
테스트 통과라고 보고했지만 실행 명령이 없습니다.
실제로 실행한 명령과 결과를 알려 주세요.
실행하지 않았다면 미실행으로 정정하고 가능한 검증을 수행하세요.

현재 파일 보완:
안내 문구는 제가 방금 수정했습니다.
현재 파일의 문구를 기준으로 표시 조건만 보완하세요.
이전 답변의 문구로 덮어쓰지 마세요.

각 후속 요청은 하나의 차이에 집중합니다. 문구, 상태 처리, 디자인, 데이터 형식을 한꺼번에 다시 요청하면 이전 수정 중 무엇이 잘못됐는지 추적하기 어렵습니다. 먼저 동작 문제를 해결하고, 이후 문구와 화면 정리를 별도 단계로 맡기는 방식도 좋습니다. 되돌리기 요청은 전체 파일을 원래대로 돌리는 대신 관련 없는 변경만 구분하게 해야 현재 작업을 보존할 수 있습니다.

9. 실제 완료 보고를 읽고 다음 행동 결정하기

좋은 결과 보고에는 요구사항과 근거의 연결이 있어야 합니다. “세 파일 수정”이라는 목록만으로는 검색 전 상태가 유지되는지 알 수 없습니다. 상태별로 어떤 코드와 검증이 대응하는지 요약하도록 요청하세요. 아래 형식을 복사하면 시행한 일과 남은 일을 구분하기 쉽습니다.

결과를 다음 표 형식으로 정리해 주세요.
요구사항 | 대응 파일 또는 로직 | 실제 확인한 근거 | 남은 확인
검색 전 화면 유지
요청 중 빈 결과 문구 숨김
성공 응답의 결과 0개 안내
요청 실패 시 기존 오류 안내 유지
정상 검색 결과 유지
검증 명령은 실제 실행한 것만 적고, 실패와 미실행을 구분하세요.

실제 명령이 실패했다면 로그의 첫 원인을 보고 다음 요청을 정합니다. “명령을 찾을 수 없음”은 실행 환경이나 도구 문제이고, “기대 문구와 실제 문구가 다름”은 동작 또는 테스트 기대값 문제일 수 있습니다. 두 종류를 같은 “테스트 실패”로 처리하지 마세요. 코드 차이를 읽기 어려우면 변경된 각 조건을 쉬운 문장과 입력 예시로 설명하도록 요청할 수 있습니다.

화면 기능은 자동 검증과 직접 사용 확인이 함께 필요할 수 있습니다. 직접 확인할 때는 페이지를 열고, 검색 전 상태를 보고, 결과가 있는 검색어와 없는 검색어를 차례로 입력합니다. 요청 실패 상태는 프로젝트가 제공하는 테스트나 개발용 모의 응답 방식으로 확인하는 것이 좋습니다. 실제 서비스의 네트워크나 운영 데이터를 임의로 바꾸는 방법을 기본 절차로 삼을 필요는 없습니다.

마지막으로 이번 작업에서 새로 알게 된 사실만 다음 요청에 이어 주세요. 관련 파일 위치와 검증 명령이 확인되었다면 다시 긴 배경을 설명할 필요가 없습니다. 매 작업의 조건을 모두 영구 규칙으로 만들지도 마세요. 여러 작업에 반복되는 프로젝트 약속은 AGENTS.md로, 특정 기능의 요구사항은 해당 요청이나 작업 기록으로 나누면 프롬프트가 더 간결해집니다.

10. 자주 묻는 질문

프롬프트를 길게 써야 하나요? 길이보다 결과를 바꾸는 정보가 중요합니다. 작은 수정은 몇 문장으로 시작하고, 필요한 맥락을 후속으로 보완해도 됩니다.

모든 파일을 지정해야 하나요? 알고 있는 관련 위치부터 알려 주세요. 정확한 파일을 모르면 화면 이름과 재현 단계를 주고 조사하도록 요청할 수 있습니다.

매번 계획부터 받아야 하나요? 변경 범위가 크거나 선택해야 할 설계가 있을 때 계획이 도움이 됩니다. 단순한 문구 수정까지 긴 계획을 요구할 필요는 없습니다. 다만 설명만 원하는지 실제 수정을 원하는지는 항상 분명히 해 두는 편이 좋습니다.

공식 출처 및 확인일: OpenAI 공식 문서: Prompting. 2026년 10월 3일 확인. 예시의 경로와 명령은 자신의 프로젝트에 맞게 조정하세요.