Codex로 기존 코드 수정 맡길 때, 실패를 줄이는 요청 방식 5가지

기존 프로젝트의 코드 수정을 Codex에 맡기면 빠르게 진도가 나갑니다. 하지만 “이 기능 좀 고쳐줘”처럼 넓게 요청하면, 원하지 않은 파일까지 바꾸거나 기존 동작을 깨뜨리는 일이 생길 수 있습니다. 특히 이미 운영 중인 프로젝트라면, 코드를 잘 쓰는 것보다 수정 범위와 완료 기준을 먼저 정하는 것이 중요합니다.

제가 기존 코드를 수정할 때 실패를 줄이기 위해 쓰는 요청 방식 5가지를 정리했습니다. 핵심은 단순합니다. Codex가 추측할 부분을 줄이고, 사람이 마지막에 확인할 지점을 분명하게 만드는 것입니다.

 

코드 에디터와 AI 작업 창, 기존 코드 수정 요청 체크리스트

 

먼저 기억할 원칙: 한 번에 수정부터 맡기지 않아도 됩니다

처음 보는 코드베이스라면 바로 “수정해줘”라고 하기보다, 먼저 원인과 영향 범위를 분석하게 하는 편이 안전합니다. 분석 결과를 보고 방향이 맞는지 확인한 다음 실제 변경을 요청하면, 대화가 한 번 더 늘어나더라도 되돌리는 시간을 크게 줄일 수 있습니다.

공식 OpenAI 문서도 작업 목표, 관련 맥락, 제약 조건, 성공 기준, 결과 형식을 구체적으로 주는 방식을 권장합니다. 로컬 코드 수정처럼 범위가 있는 일일수록 이 원칙이 잘 맞습니다.

1. 수정할 파일과 건드리지 말아야 할 범위를 함께 적습니다

가장 흔한 실패는 기능은 고쳤는데 관련 없어 보이던 공통 코드나 설정까지 바뀌는 경우입니다. 작업 대상이 명확하다면 파일·함수·컴포넌트 단위로 지정하세요. 반대로 수정하면 안 되는 영역도 함께 적는 것이 좋습니다.

나쁜 요청은 이런 식입니다.

로그인 오류를 고쳐줘.

이 요청만으로는 로그인 화면, API, 인증 미들웨어, 데이터베이스 설정 중 어디를 봐야 하는지 알기 어렵습니다. Codex가 넓게 탐색하면서 예상보다 큰 변경을 할 수 있습니다.

아래처럼 바꾸면 훨씬 안전합니다.

`src/pages/Login.tsx`의 로그인 버튼 클릭 시 오류를 수정해줘. API 응답 처리 부분만 수정하고, 인증 API 경로와 전역 상태 관리 코드는 변경하지 마. 수정 전 원인부터 짧게 설명해줘.

이 방식의 장점은 검토할 diff도 작아진다는 점입니다. 원하는 변경이 한두 파일에 모이면, 사람이 빠뜨린 부작용을 찾기도 쉬워집니다.

2. 첫 요청은 ‘분석만’ 하게 합니다

오류 원인이 확실하지 않을 때는 수정과 분석을 한 번에 시키지 않는 편이 좋습니다. 먼저 아래 네 가지를 확인해 달라고 요청합니다.

• 원인으로 보이는 지점
• 영향을 받는 파일과 기능
• 가능한 해결 방법
• 실제 수정 전에 확인할 위험 요소

예시는 다음과 같습니다.

결제 완료 후 주문 상태가 갱신되지 않는 원인을 분석해줘. 아직 코드는 수정하지 말고, 관련 파일과 데이터 흐름을 확인한 뒤 원인 후보와 권장 수정 방향만 알려줘.

분석 결과가 나오면 “주문 상태 갱신 로직만 수정해줘”처럼 다음 요청을 이어갑니다. 이 과정에서 원인이 프런트엔드가 아니라 API 응답 형식이나 캐시 정책에 있다는 사실을 발견하기도 합니다.

한 번에 해결책을 받는 것보다 느려 보일 수 있습니다. 하지만 애매한 문제를 잘못된 방향으로 고친 뒤 복구하는 시간까지 생각하면, 대부분은 이 편이 더 빠릅니다.

3. ‘완료’의 기준을 테스트 가능한 문장으로 적습니다

“작동하게 해줘”는 사람에게도 모호한 말입니다. 완료 기준을 사용자의 행동과 결과로 바꾸면 Codex가 구현 방향을 잡기 쉬워지고, 나중에 검증도 간단해집니다.

예를 들어 비밀번호 재설정 기능이라면 이렇게 적을 수 있습니다.

완료 기준은 세 가지야. ① 등록된 이메일이면 재설정 안내 메시지가 표시돼야 해. ② 없는 이메일이면 계정 존재 여부를 노출하지 않는 동일한 안내 문구를 보여줘. ③ 요청 중에는 버튼을 비활성화하고 중복 요청이 나가지 않아야 해.

여기에 브라우저, 기기, 예외 상황까지 필요한 만큼만 추가합니다. “모바일에서도 깨지지 않게”보다는 “가로 375px 화면에서 버튼이 화면 밖으로 넘치지 않아야 해”가 더 확인하기 좋은 기준입니다.

4. 실행할 테스트와 확인 방법을 요청에 넣습니다

코드가 문법적으로 맞아도 기능이 정상이라는 뜻은 아닙니다. 프로젝트에 이미 테스트 명령이 있다면, 수정 요청에 같이 적어두는 것이 좋습니다.

수정 후 `npm test -- Login`을 실행해줘. 테스트가 없거나 실행할 수 없으면 그 사실을 말하고, 대신 수동 확인 절차를 3단계 이내로 정리해줘.

테스트 명령을 모른다면 먼저 물어봐도 됩니다.

이 프로젝트에서 로그인 변경 후 실행해야 할 테스트나 린트 명령을 찾아줘. 아직 코드는 수정하지 마.

중요한 것은 “테스트를 통과시켜줘”만 적고 끝내지 않는 것입니다. 어떤 테스트를 돌렸는지, 실패했다면 원인이 무엇인지 함께 받으면 결과를 신뢰하기 쉬워집니다. 테스트가 없는 오래된 프로젝트라면 최소한 재현 절차와 수동 확인 항목을 남겨두세요.

5. 마지막에는 변경 요약과 diff 검토를 요청합니다

수정이 끝났다고 해서 바로 배포하지는 않습니다. 저는 마지막에 변경 파일 목록, 파일별 수정 이유, 테스트 결과를 짧게 정리해 달라고 요청합니다.

수정 내용을 마무리해줘. 변경한 파일 목록과 각 파일에서 바꾼 이유를 표로 정리하고, 실행한 테스트와 결과를 알려줘. 의도하지 않은 변경 가능성이 있는 부분도 하나라도 있으면 함께 표시해줘.

이 답변을 보고 실제 diff를 열어보면 됩니다. 특히 다음 세 가지는 꼭 확인하세요.

• 환경 변수, 권한, 배포 설정이 불필요하게 바뀌지 않았는지
• 의존성 버전이나 lock 파일이 의도 없이 변경되지 않았는지
• 오류 처리와 기존 사용자 흐름이 사라지지 않았는지

Codex는 수정 작업을 빠르게 도와주지만, 최종 책임까지 대신 지지는 않습니다. 작은 변경이라도 사람이 diff와 테스트 결과를 확인하는 습관이 가장 확실한 안전장치입니다.

바로 복사해 쓸 수 있는 요청 템플릿

아래 틀에 필요한 내용만 채워서 쓰면 됩니다.

목표: [무엇을 고칠지]

수정 범위: [파일 / 함수 / 컴포넌트]
수정하지 말 것: [건드리면 안 되는 기능, 설정, 파일]

먼저 할 일: 코드를 수정하기 전에 원인과 영향 범위를 짧게 분석해줘.

완료 기준:
1. [사용자가 확인할 수 있는 결과]
2. [예외 상황에서의 결과]
3. [성능·디자인·호환성 등 추가 조건]

검증: [실행할 테스트 명령]. 실행할 수 없으면 이유와 수동 확인 방법을 알려줘.

마무리: 변경한 파일, 변경 이유, 테스트 결과, 남은 주의사항을 간단히 정리해줘.

정리

Codex에 기존 코드 수정을 맡길 때는 긴 프롬프트가 꼭 필요한 것은 아닙니다. 대신 범위, 분석 단계, 완료 기준, 검증 방법, 변경 요약 이 다섯 가지를 빠뜨리지 않으면 됩니다.

처음에는 조금 번거롭게 느껴져도, 이 구조가 익숙해지면 요청은 짧아지고 검토 시간도 줄어듭니다. AI에게 일을 맡기는 실력은 멋진 문장을 쓰는 능력보다, 내가 원하는 결과를 확인 가능한 조건으로 바꾸는 데서 시작됩니다.

 

참고: [OpenAI 공식 문서 — Model guidance](https://developers.openai.com/api/docs/guides/latest-model)