Chapter 04. 첫 작업 30분 안에 PR 받기

Codex는 설명을 오래 듣는 도구가 아니다. 한 번 직접 맡겨보고, 테스트가 돌고, 브랜치가 생기고, PR이 올라오는 장면을 보면 그제야 감이 온다. 그래서 첫 경험은 거창할 필요가 없다. 오히려 작고, 안전하고, 끝이 보이는 버그 하나가 좋다. 첫 PR은 대작보다 단편이 낫다.

이 장의 목표는 단순하다. GitHub를 연결하고, 저장소를 고르고, Ask와 Code 중 무엇을 써야 할지 판단하고, 실제 버그 하나를 수정해서 테스트를 통과시키고, PR까지 받아보는 것이다. Codex는 격리된 작업 환경에서 저장소를 읽고, 코드를 수정하고, 로그와 테스트 결과를 남기며 PR 생성까지 이어질 수 있다.¹

오늘은 "작은 버그 하나"만 고친다

처음부터 새 기능 전체를 맡기면 성공 경험보다 혼란이 먼저 온다. 첫 작업은 다음 조건을 만족하는 것이 좋다.

반대로 첫 작업으로 좋지 않은 것은 이런 종류다.

한국 개발자가 흔히 다루는 프로젝트로 생각해보면, Next.js + Supabase 앱의 로그인 폼 버그 같은 것이 딱 좋다. 재현도 쉽고, 수정 범위도 좁고, 테스트도 붙이기 좋다.

가장 빠른 시작은 GitHub 연결부터다

이미 앱이나 CLI 설치는 끝냈다고 가정하자. 이제 해야 할 일은 "Codex가 어디서 일할지"를 정해주는 것이다. 가장 빠른 경로는 ChatGPT의 Codex 화면이나 앱에서 GitHub를 연결하고, 첫 저장소 환경을 만드는 방식이다.²

여기서 중요한 건 저장소를 많이 연결하는 것이 아니라, 첫 저장소를 잘 고르는 것이다. 처음에는 회사의 핵심 결제 서비스보다 개인 프로젝트나 팀 내부의 비교적 안전한 서비스가 좋다. 브랜치 보호가 잘 되어 있고, 테스트 명령이 이미 잡혀 있는 저장소라면 더 좋다.

처음 연결할 때는 세 가지만 확인하자.

1. 기본 브랜치가 main인지 dev인지

2. 테스트 명령이 pnpm test, npm test, yarn test 중 무엇인지

3. PR을 올릴 대상 저장소가 맞는지

이 셋만 알아도 첫 작업에서 헤매는 시간이 확 줄어든다. Codex는 생각보다 성실하다. 문제는 가끔 성실하게 엉뚱한 저장소에서 일한다는 점이다. 그래서 첫 작업일수록 저장소 이름을 분명히 찍어주는 습관이 좋다.

Ask와 Code, 딱 이렇게 나누면 된다

처음 쓰는 사람은 여기서 많이 헷갈린다. Ask는 말 그대로 묻는 모드이고, Code는 실제로 손을 대는 모드다.³ 둘 다 똑똑하지만 역할이 다르다.

첫 PR을 가장 안정적으로 만드는 흐름은 이렇다. Ask로 3분 탐색하고, Code로 20분 실행한다.

예를 들어 Ask에는 이렇게 넣으면 좋다.

이 저장소에서 로그인 실패 시 에러 토스트가 보이지 않고,
버튼이 로딩 상태로 남는 버그를 고치고 싶어.
관련 파일 후보, 원인 추정, 필요한 테스트를 5줄 이내로 정리해줘.
아직 파일은 수정하지 마.

이 질문의 목적은 정답을 얻는 것이 아니라, Codex가 문제를 어디서 보고 있는지 확인하는 것이다. 관련 파일을 엉뚱하게 짚으면, 그때 바로 방향을 틀 수 있다.

첫 실전 예제: Next.js + Supabase 로그인 버그

이제 실제로 맡겨보자. 예제 상황은 이렇다.

Next.js 프런트엔드가 있고, Supabase 인증을 쓴다. 사용자가 비밀번호를 틀리면 로그인은 실패하지만, 화면에는 에러 토스트가 뜨지 않는다. 게다가 버튼이 loading 상태에서 풀리지 않는다. 사용자는 "눌렀는데 아무 일도 안 일어난다"고 느낀다. 이런 버그는 작지만 체감이 크다.

이때 Code 모드 프롬프트는 길어도 좋다. 대신 애매하면 안 된다. 좋은 첫 프롬프트는 보통 네 가지가 들어간다. 문제, 범위, 금지사항, 완료 조건이다.⁴

Next.js + Supabase 프로젝트다.

버그:
- 로그인 실패 시 에러 토스트가 보이지 않는다.
- 실패 후 submit 버튼이 loading/disabled 상태로 남는다.

수정 범위:
- app/(auth)/login/page.tsx
- components/auth/LoginForm.tsx
- 관련 테스트 파일만 수정해줘.

하지 말 것:
- Supabase 스키마 변경 금지
- 디자인 시스템 변경 금지
- 로그인 플로우 전체 리팩터링 금지

완료 조건:
- 잘못된 credentials 입력 시 한국어 에러 토스트가 표시될 것
- 실패 후 버튼 상태가 정상 복구될 것
- 가능한 경우 테스트를 추가하고 통과시킬 것
- 변경한 파일, 실행한 명령, 테스트 결과를 마지막에 요약할 것
- 준비가 되면 PR까지 만들어줘

이 프롬프트가 좋은 이유는 Codex가 "어디까지가 내 일인지"를 안다는 점이다. AI 코딩 도구는 종종 의욕이 너무 넘친다. 그래서 "이 파일만", "이건 하지 마", "완료는 여기까지"를 미리 못 박아두는 게 중요하다.

작업 중에는 무엇을 보면 되나

Codex가 움직이기 시작하면, 사용자는 손 놓고 있어도 되지만 눈은 열어둬야 한다. 보는 포인트는 세 가지면 충분하다.

첫째, 관련 파일을 제대로 찾았는지다. 로그인 버그인데 갑자기 전역 상태 관리, 공통 UI 라이브러리, Supabase 설정 파일까지 크게 뒤흔들기 시작하면 범위가 커진 것이다.

둘째, 테스트나 린트 명령을 실제로 돌렸는지다. Codex의 장점은 "수정했습니다"가 아니라 "수정하고 돌려봤습니다"에 있다. 로그와 테스트 결과가 없으면 아직 반쯤만 끝난 셈이다.

셋째, 실패 원인을 스스로 설명하는지다. 예를 들어 "테스트가 없어서 재현 기반으로 수정했고, 최소 단위 테스트를 추가했다"처럼 말해주면 신뢰도가 올라간다. 반대로 아무 설명 없이 파일만 툭 바꿔놓으면 꼭 diff를 더 꼼꼼히 봐야 한다.

테스트가 없으면, 테스트부터 조금 만들게 하자

실무에서 첫 버그 수정이 자주 막히는 이유는 의외로 간단하다. 테스트가 없다. 이럴 때는 Codex에게 억지로 완벽한 테스트 스위트를 만들게 할 필요는 없다. 첫 목표는 재현 가능한 최소 테스트 하나다.

예를 들어 이렇게 덧붙이면 된다.

기존 테스트가 부족하면,
이번 버그를 재현하는 최소 테스트만 추가해줘.
광범위한 테스트 리팩터링은 하지 마.

이 한 줄이 꽤 중요하다. 테스트가 없다고 하면 Codex는 때때로 갑자기 테스트 인프라 정비, 목 설정 통일, 폴더 구조 정리까지 하고 싶어 한다. 지금은 첫 PR을 받는 장면이 목표지, 테스트 철학을 완성하는 장면이 목표가 아니다.

PR 생성은 두 갈래로 생각하면 쉽다

Codex로 PR을 받는 길은 크게 두 가지다.

하나는 클라우드/앱 중심 흐름이다. Codex가 작업을 끝내면 변경 내역과 로그를 보여주고, 브랜치 생성과 PR 생성 단계까지 이어진다. 첫 경험으로는 이 길이 가장 쉽다.¹

다른 하나는 CLI + GitHub CLI 흐름이다. 이 경우 gh auth login으로 GitHub 인증을 해두면, Codex가 브랜치를 만들고 커밋하고 푸시한 뒤 gh pr create로 PR까지 올리는 루프를 만들 수 있다.⁵

CLI를 쓰는 사람이라면 이렇게 요청해도 된다.

수정이 끝나면 새 브랜치를 만들고,
테스트 통과 후 원격에 push하고,
base 브랜치가 dev라면 dev 대상으로 PR 초안을 만들어줘.
PR 제목과 본문은 한국어로 작성해줘.

중요한 건 main으로 보낼지 dev로 보낼지 미리 말하는 것이다. 이걸 빼먹으면 첫 PR이 기술적으로는 성공해도 팀 실무에서는 실패가 된다.

PR이 올라왔을 때, 제일 먼저 읽어야 하는 것

드디어 PR이 생겼다. 여기서부터가 진짜 시작이다. Codex가 PR을 만들었다고 해서 끝난 것이 아니다. 이제 사람의 일이 시작된다.

첫 검토는 아래 순서가 좋다.

1. PR 제목과 설명이 실제 변경 내용을 반영하는지 본다.

2. 변경 파일 수가 예상보다 커지지 않았는지 본다.

3. 테스트 결과와 실행 명령이 적혀 있는지 본다.

4. 의도하지 않은 포맷팅 변경이나 리네임이 없는지 본다.

5. 내가 요청하지 않은 리팩터링이 끼어들지 않았는지 본다.

특히 첫 PR에서는 변경 파일 수를 꼭 보자. 로그인 토스트 버그 하나인데 파일이 열다섯 개 바뀌었다면, 뭔가 너무 열심히 한 것이다.

diff를 읽는 습관이 실력을 만든다

Codex 시대에도 결국 개발자를 지켜주는 것은 diff 읽는 습관이다. AI가 코드를 써주는 시대라서 더 그렇다. 좋은 사용자는 프롬프트를 길게 쓰는 사람이 아니라, 이 변경이 왜 들어갔는지 묻는 사람이다.

리뷰할 때는 이런 질문을 던져보자.

• 에러 토스트가 왜 이제서야 뜨는가?

• 버튼 상태 복구는 finally에서 처리했는가?

• 에러 메시지 문구는 사용자 친화적인가?

• 실패 케이스 테스트가 실제로 이 버그를 막아주는가?

CLI를 쓰고 있다면 /review를 활용해 현재 변경분을 읽기 전용으로 다시 검토할 수 있다. 이 기능은 워킹 트리를 건드리지 않고 브랜치 차이, 미커밋 변경, 특정 커밋 등을 점검하는 데 유용하다.⁶ GitHub 쪽에서는 PR에 @codex review 댓글을 달아 리뷰를 추가로 받을 수도 있다.⁷ 다만 이 단계의 핵심은 "사람 리뷰를 없애는 것"이 아니라 "사람이 더 중요한 판단에 집중하게 만드는 것"이다.⁸

첫 PR이 잘 안 나올 때의 흔한 원인

처음부터 한 번에 예쁘게 끝나면 좋겠지만, 실제로는 자주 미끄러진다. 그럴 때는 대개 아래 넷 중 하나다.

범위가 너무 컸다

"로그인 관련 이슈 전부 정리해줘"는 멋있어 보이지만 실패하기 쉽다. 첫 작업은 한 줄짜리 완료 기준이 있는 것이 낫다.

저장소나 브랜치가 헷갈렸다

모놀리포에서는 특히 흔하다. 프런트 문제인데 백엔드 패키지를 뒤지고 있을 수 있다. Ask 단계에서 관련 파일 후보를 먼저 확인하는 이유가 여기에 있다.

테스트 명령이 불분명했다

Codex는 성실하지만, 프로젝트마다 pnpm test, pnpm lint, pnpm typecheck, npm run test:e2e가 다르다. 팀이 쓰는 기본 검증 명령은 사용자가 알려주는 편이 빠르다.

설명 없이 Code부터 눌렀다

작은 버그라도 Ask 한 번 없이 바로 Code로 들어가면, 잘못된 가정 위에서 빠르게 달릴 수 있다. 첫 작업일수록 3분 탐색이 30분 수습을 막아준다.

첫 성공 이후에 생기는 감각

한 번 PR을 받아보면, 이후 장들의 내용이 훨씬 현실적으로 읽힌다. AGENTS.md가 왜 필요한지, Skills가 왜 강력한지, Automations가 왜 무서우면서도 매력적인지 몸으로 이해된다. 그 전까지 Codex는 "신기한 도구"지만, 첫 PR 이후부터는 "일을 맡길 수 있는 동료"가 된다.

처음에는 버그 하나면 충분하다. 로그인 실패 토스트든, 버튼 상태 복구든, 테스트 한 줄 추가든 상관없다. 중요한 것은 설명에서 체험으로 넘어가는 순간이다. 그 순간부터 Codex는 기능 목록이 아니라 워크플로우가 된다.

참고

¹Codex 실전 예제와 PR 생성 흐름

²ChatGPT 플랜에서 Codex 사용하기

³Codex가 드디어 ChatGPT Plus에도: 사용법부터 사례까지

⁴Codex로 버그 수정과 테스트 자동화

⁵codex를 이용한 GitHub 이슈, PR 생성 자동화

⁶Codex CLI Automatic Code Review

⁷Use Codex in GitHub

⁸GitHub PR 리뷰 자동화 - Codex와 협업하는 개발 워크플로