LeanX

실전: 작은 버그 수정을 처음부터 끝까지

실전 버그 수정은 브랜치 생성 → 버그 재현 확인 → 구체적 프롬프트로 코덱스에게 수정 위임 → 테스트와 diff 검토 → PR 생성 → 사람 리뷰 후 머지의 순서로 진행하며, 이 사이클을 그대로 반복하는 것이 코덱스 실무의 기본기입니다.

콘텐츠: LeanX · 최초 공개 2026.07.08 · 콘텐츠 기준일 2026.08.14

마지막 레슨입니다. 지금까지 배운 승인 모드, 프롬프트 작성법, PR 워크플로우, AGENTS.md를 전부 동원해서 작은 버그 하나를 처음부터 끝까지 고쳐 봅니다. 이 흐름이 손에 익으면, 나머지는 규모의 차이일 뿐입니다.

시나리오

가상의 상황: 우리 서비스의 회원가입 폼에서 이메일 끝에 공백이 붙으면 (예: "[email protected] ") 가입은 되는데 로그인이 안 된다는 제보가 들어왔습니다. 이 버그를 코덱스와 함께 고칩니다.

버그 수정 전체 흐름 (8단계)

  1. 1. 브랜치 만들기 — 터미널에서 git checkout -b fix/email-trim 으로 작업 전용 브랜치를 만듭니다. 본 코드를 지키는 안전벨트입니다.
  2. 2. 코덱스 실행 — 프로젝트 폴더에서 codex를 실행합니다. 승인 모드는 기본값 Auto면 충분합니다.
  3. 3. 버그 위치 찾기 (읽기 작업) — 먼저 원인 분석만 시킵니다: "회원가입 시 이메일 끝 공백이 제거되지 않는 것 같아. 이메일을 처리하는 코드가 어디인지 찾고, 원인을 설명해줘. 아직 고치지는 마."
  4. 4. 수정 위임 — 원인 설명이 맞는지 확인한 뒤 수정을 시킵니다. 목표 + 범위 + 완료 조건을 담아서요 (아래 프롬프트 참고).
  5. 5. 검증 — 코덱스가 돌린 테스트 결과를 확인하고, git diff로 바뀐 코드를 직접 읽습니다. 의도하지 않은 파일이 바뀌지 않았는지 꼭 보세요.
  6. 6. 커밋과 푸시 — 코덱스에게 "컨벤션에 맞는 커밋 메시지로 커밋해줘"라고 시키거나 직접 git commit 합니다. 그리고 git push -u origin fix/email-trim.
  7. 7. PR 생성 — 코덱스에게 PR 설명 초안을 부탁하면 변경 요약, 원인, 테스트 내역을 정리해 줍니다. GitHub에서 PR을 엽니다.
  8. 8. 리뷰와 머지 — 동료(또는 /review로 코덱스)에게 리뷰를 받고, 사람이 최종 확인 후 머지합니다. 끝!

4단계에서 쓰는 수정 프롬프트

원인 분석 고마워. 이제 고쳐줘.

목표: 회원가입과 로그인 양쪽에서 이메일 앞뒤 공백을 제거(trim)하고
소문자로 정규화한 뒤 처리하도록 수정.

범위: src/auth/ 폴더 안의 파일만 수정할 것.
다른 폴더는 건드리지 마.

완료 조건:
1) "[email protected] " 처럼 공백이 붙은 입력도 정상 처리되는 테스트 추가
2) npm test 전체 통과
3) 변경한 파일과 이유를 요약해서 보고

3단계에서 "아직 고치지 마"라고 못 박은 것에 주목하세요. 진단과 수술을 분리하는 겁니다. 코덱스가 엉뚱한 원인을 짚었는데 그대로 수정까지 해 버리면, 되돌리는 비용이 더 큽니다. 분석 → 사람 확인 → 수정 순서가 안전합니다.

같은 작업을 클라우드로 한다면?

이 정도로 명확한 버그라면 클라우드 위임과도 궁합이 좋습니다. GitHub 이슈에 버그 내용을 정리하고 @codex를 멘션하면, 3~7단계를 코덱스가 클라우드에서 알아서 하고 PR만 올려 줍니다. 여러분은 8단계(리뷰와 머지)만 하면 되죠. 로컬 방식은 과정을 지켜보며 배우기 좋고, 클라우드 방식은 시간을 아끼기 좋습니다.

이번 레슨에서 쓴 git 명령 모음

git checkout -b fix/email-trim   # 작업 브랜치 생성
git diff                          # 바뀐 내용 확인
git add -A && git commit -m "fix: 이메일 앞뒤 공백 제거 및 소문자 정규화"
git push -u origin fix/email-trim # 원격에 브랜치 푸시

버그를 고칠 때마다 "코덱스가 헤맸던 지점"을 AGENTS.md에 한 줄씩 추가하세요. 예를 들어 이번에 코덱스가 테스트 명령어를 헷갈렸다면 "테스트는 npm test로 실행"을 추가하는 식입니다. 이렇게 하면 다음 작업부터 같은 실수가 사라지고, 여러분의 코덱스는 점점 우리 팀에 최적화된 팀원이 됩니다.

첫 실전 대상으로는 "고장 나도 복구 쉬운" 작업을 고르세요. 오타 수정, 문구 변경, 작은 UI 버그가 좋습니다. 결제 로직이나 DB 마이그레이션 같은 고위험 작업은 코덱스와 충분히 손발을 맞춘 뒤에 맡기세요.

축하합니다! 설치부터 실전 버그 수정까지, 코덱스 활용의 한 사이클을 완주했습니다. 이제 남은 것은 반복입니다. 작은 작업부터 위임하고, 결과를 검토하고, 규칙을 다듬는 사이클을 돌리다 보면 어느새 코덱스 없이 일하던 시절이 낯설게 느껴질 거예요.