Codex로 기존 레포 리팩토링 실제 써본 후기
3년 묵은 사이드 프로젝트 레포를 오랜만에 열었는데, 파일 하나가 1,200줄이 넘더라고요. 어디부터 손대야 할지 감이 안 와서 그냥 탭을 닫아버린 게 벌써 몇 번째인지 모릅니다. 이번엔 OpenAI Codex한테 리팩토링을 맡겨봤어요.
같은 레포, 같은 코드인데 결과가 완전히 달랐습니다. 예전엔 손도 못 대던 파일이 반나절 만에 정리됐거든요. 차이는 딱 하나였어요. "한 번에 다 고치기"를 포기한 거요. 오늘은 제가 직접 돌려본 과정과, 망하지 않으려면 뭘 조심해야 하는지를 솔직하게 풀어볼게요.
▲ 손대기 무서운 레거시 레포, 이번엔 Codex와 함께 정리해봤어요
📋 이 글에서 다루는 내용
핵심 요약
1. Codex는 큰 파일을 한 번에 갈아엎지 않고 '작은 패스'로 쪼개 고칠 때 가장 안정적이에요.
2. /plan으로 계획을 먼저 뽑고, 죽은 코드 삭제 → 중복 정리 → 헬퍼 추출 순서로 나눠 돌리는 게 핵심입니다.
3. 테스트가 없는 레포라면 리팩토링보다 '테스트 먼저 짜달라'가 먼저예요. 검증 없이 맡기면 조용히 망가집니다.
1. 손대기 무서운 레거시 레포, 왜 자꾸 미루게 될까요?
▲ 어디서부터 손대야 할지 모르는 순간, 우리는 탭을 닫습니다
혹시 이런 경험 있으신가요? 함수 하나가 화면을 세 번 스크롤해야 끝나고, 변수 이름은 temp2, dataFinal 같은 거 투성이. 주석은 2년 전 자신이 남긴 "일단 이렇게" 한 줄이 전부죠.
문제는 그 코드가 지금도 잘 돌아간다는 거예요. 그래서 더 무섭습니다. 건드렸다가 어디가 터질지 모르니까요. 이걸 개발자들은 '기술 부채'라고 부르는데, 쉽게 말하면 나중에 이자까지 붙여서 터지는 폭탄이에요. 지금 안 갚으면 언젠가 훨씬 크게 갚아야 합니다.
그동안 저도 리팩토링을 몇 번씩 시도했어요. 그런데 매번 30분쯤 코드를 노려보다가 "이건 주말에 날 잡고 하자"며 미뤘습니다. 그 주말은 오지 않았고요. 생각보다 많은 분이 바로 이 지점에서 막혀요. 시작할 엄두가 안 나는 거죠.
2. AI한테 맡기면 코드가 다 망가진다던데, 진짜일까요?
▲ "AI가 코드를 다 뒤엎어버린다"는 걱정, 절반만 맞아요
주변 개발자들한테 "AI로 리팩토링 해봤어?"라고 물으면 열에 아홉은 이렇게 답해요. "그거 코드 다 갈아엎어서 오히려 더 망가져." 저도 처음엔 그런 줄 알았어요.
근데 그 얘기를 자세히 들어보면 공통점이 있더라고요. 다들 "이 파일 전체 깔끔하게 리팩토링해줘" 한 문장을 던졌던 거예요. 그러면 AI는 정말로 파일 전체를 새로 씁니다. 변수명 바꾸고, 구조 바꾸고, 로직까지 살짝 손대면서요. 그중 하나만 어긋나도 전부 의심스러워지죠.
하지만 Codex를 조금 써보니 이건 도구 탓이 아니라 시키는 방식의 문제였어요. 실제로 OpenAI 공식 문서에서도 리팩토링은 "죽은 코드 삭제, 제어 흐름 단순화, 헬퍼 추출 같은 작고 검토 가능한 단위로 쪼개서" 진행하라고 안내합니다. 한 방에 끝내는 게 아니라 작은 걸음을 여러 번 밟는 거죠. 이 얘기, 다음 섹션에서 제 실패담이랑 같이 풀어볼게요.
3. 제가 계속 실패했던 진짜 이유는 '한 번에'였어요
▲ "전체 리팩토링해줘" = 뒤엉킨 결과
▲ 작은 패스로 나누면 = 검토 가능한 결과
첫 시도 때 저도 똑같이 "이 레포 전체를 최신 컨벤션에 맞게 리팩토링해줘"라고 던졌어요. 결과는요? Codex가 파일 12개를 한꺼번에 바꾼 diff를 내밀었는데, 무려 +900줄, -700줄이었습니다. 이걸 어떻게 리뷰하나요. 그냥 통째로 믿거나, 통째로 버리거나 둘 중 하나였어요. 결국 버렸습니다.
진짜 원인은 도구가 아니라 제 요청의 크기였어요. 사람도 "집 전체 대청소해"라고 하면 어디부터 할지 막막하잖아요. "일단 책상 위 서류만 버려"라고 하면 바로 움직이고요. Codex도 똑같더라고요.
그래서 방식을 바꿨어요. 먼저 /plan으로 "이 레포에서 뭐부터 손봐야 할지 계획만 세워줘"라고 시켰습니다. 그랬더니 죽은 코드, 중복 로직, 너무 커진 모듈을 순서대로 정리한 목록을 주더라고요. 그다음부터는 그 목록을 하나씩, 커밋 하나에 한 가지 변경만 담기게 돌렸어요. 이게 전부였습니다.
| 요청 방식 | diff 크기 | 리뷰 가능 여부 | 결과 |
|---|---|---|---|
| "파일 전체 리팩토링해줘" | +900 / -700줄 | 사실상 불가 | 통째로 폐기 |
| "죽은 코드만 삭제해줘" | +5 / -80줄 | 1분 안에 확인 | 바로 커밋 |
| "이 함수 3개로 쪼개줘" | +60 / -40줄 | 차분히 검토 가능 | 수정 후 커밋 |
4. Codex로 리팩토링, 실제로 이렇게 돌렸어요
▲ 터미널에서 Codex를 띄우고 작은 단위로 하나씩 시켰어요
제가 실제로 밟은 순서를 그대로 적어볼게요. 특별한 세팅은 없었어요. 레포 루트에서 codex를 실행하고, 진지한 작업이라 모델은 gpt-5.5로 뒀습니다. OpenAI도 무거운 Codex 작업엔 GPT-5.5를 우선 권장하더라고요.
1) AGENTS.md로 우리 레포 규칙부터 알려주기
가장 효과 컸던 건 이거예요. 레포 루트에 AGENTS.md 파일을 만들어서 "우리는 이런 코딩 컨벤션을 쓴다, 이 폴더는 건드리지 마라, 테스트는 이 명령으로 돌린다"를 적어뒀어요. 이걸 읽고 나니까 Codex가 뜬금없는 라이브러리를 새로 끌어오는 일이 확 줄었습니다.
2) /plan으로 계획만 먼저
바로 코드를 고치게 하지 않고 "지금 이 레포에서 가장 급한 리팩토링 순서를 계획으로만 뽑아줘"라고 했어요. 죽은 코드 → 중복 로직 → 거대 함수 순서로 목록이 나왔고, 저는 이 중에서 오늘 할 것 3개만 골랐습니다.
3) 작은 패스로 하나씩, 매번 테스트
"쓰지 않는 import랑 함수만 지워줘"처럼 딱 한 가지만 시키고, 변경이 끝나면 바로 테스트를 돌렸어요. 통과하면 커밋, 아니면 되돌리기. 실제로 써보면 이 리듬이 생각보다 빨라요. 한 패스가 5분이면 끝나거든요. GPT-5.5 기준으로는 이런 작업을 몇 시간씩 이어서 맡겨도 흐름이 끊기지 않더라고요.
5. 직접 써보고 정리한 리팩토링 체크리스트
▲ 반나절 삽질 끝에 정리한, 저만의 안전장치들이에요
며칠 굴려보면서 "이건 꼭 지켜야겠다" 싶은 것들만 추렸어요. 그대로 따라 하셔도 대부분 통할 거예요.
✅ 테스트가 없다면? 리팩토링보다 "이 함수 테스트부터 짜줘"가 먼저예요. 안전망 없이 맡기면 조용히 망가집니다.
✅ 한 커밋에 한 가지 변경만. diff가 화면을 넘기면 이미 너무 큰 요청이에요.
✅ /plan → 확인 → 실행 순서 고정. 계획 없이 바로 고치게 하지 않기.
✅ AGENTS.md에 "건드리면 안 되는 폴더"를 명시. DB 마이그레이션, 결제 로직은 특히요.
✅ 변경마다 테스트 실행. 통과 못 하면 무조건 되돌리기.
그리고 처음 시작할 때 복사해서 쓰기 좋은 프롬프트도 하나 남겨둘게요. 저는 이 틀을 조금씩 바꿔가며 계속 썼어요.
복사해서 쓰는 리팩토링 요청 템플릿
"[파일 경로]에서 [한 가지 작업: 예 - 사용하지 않는 import 제거]만 해줘. 로직은 바꾸지 말고, 끝나면 [테스트 명령]으로 검증까지 해줘. diff는 최대한 작게."
💰 지금 열기 무서운 레포, 하나쯤 있으시죠?
"주말에 날 잡고 하자"며 미뤄둔 그 레포, 사실 그 주말은 안 옵니다. 오늘 딱 '죽은 코드 삭제' 한 패스만 돌려보세요. 시작이 반이 아니라, 시작이 거의 전부예요.
👉 Codex 공식 리팩토링 가이드 보기자주 묻는 질문 (FAQ)
Q1. Codex 리팩토링은 별도 요금을 내야 하나요?
Codex는 별도 구독 상품이 아니라 ChatGPT 유료 플랜에 포함돼 있어요. Plus나 Pro 요금제를 쓰고 있다면 추가 결제 없이 바로 사용할 수 있습니다. 다만 플랜별로 사용량 한도가 있어서, 큰 레포를 오래 돌리면 한도에 걸릴 수 있어요.
Q2. 테스트 코드가 하나도 없는 레포도 Codex로 리팩토링할 수 있나요?
할 수는 있지만 순서를 바꿔야 해요. 리팩토링을 시키기 전에 "이 함수의 동작을 확인하는 테스트부터 만들어줘"라고 먼저 시키는 걸 강하게 권합니다. 검증할 방법이 없으면 코드가 미묘하게 바뀌어도 눈치채기 어렵거든요.
Q3. 리팩토링 도중에 Codex가 엉뚱한 파일을 건드리면 어떻게 하나요?
레포 루트의 AGENTS.md에 "이 폴더나 파일은 수정 금지"라고 명시해두면 대부분 막을 수 있어요. 그래도 변경은 항상 커밋 단위로 작게 유지하고, 이상하면 git으로 바로 되돌리면 됩니다.
Q4. Codex 리팩토링과 Claude Code 중에 뭐가 더 낫나요?
둘 다 작은 단위로 나눠 시키면 좋은 결과를 줘요. Codex는 ChatGPT 플랜에 묶여 있어 이미 구독 중이면 진입이 쉽고, 터미널 기반 워크플로우가 깔끔합니다. 팀 컨벤션이 확실할수록(AGENTS.md 활용) 만족도가 올라가요.
한 걸음 더: 이렇게 확장해보세요
리팩토링에 손이 익었다면, 이제 같은 방식으로 개발 워크플로우 전체를 자동화하는 쪽으로 넓혀볼 수 있어요. 리팩토링은 시작점일 뿐이거든요.
✅ 반복 작업(파일 정리, 포맷 통일)은 Zapier나 Make 같은 노코드 자동화 도구와 엮으면 손이 훨씬 덜 갑니다.
✅ PR 리뷰 자동화: Codex에게 /review를 붙여 커밋마다 자체 코드 리뷰를 받게 하면 리뷰어 부담이 줄어요.
✅ 팀 협업툴(Slack, Linear 등)과 연동해 "이슈 → 리팩토링 → PR"까지 이어지는 흐름을 만들면 생산성이 한 단계 올라갑니다.
마무리
직접 써보고 내린 결론은 간단해요. Codex가 리팩토링을 잘하냐 못하냐의 문제가 아니라, 우리가 얼마나 작게 쪼개서 시키느냐의 문제였습니다. "전체 다 고쳐줘"는 실패하고, "이거 하나만"은 거의 항상 성공했어요.
지금 열기 겁나는 레포가 하나 떠오르셨다면, 오늘은 딱 한 패스만 돌려보세요. 죽은 코드 몇 줄 지우는 것부터요. 그 작은 성공 한 번이 미뤄둔 폭탄의 심지를 자르는 시작이 됩니다. 저도 계속 써보면서 새로 알게 되는 팁은 이 글에 업데이트할게요.
🎯 오늘 딱 한 패스, 시작해볼까요?
미뤄둔 레포를 열고 "쓰지 않는 코드만 지워줘" 한 줄부터. 완벽한 리팩토링이 아니라, 멈춰 있던 걸 움직이게 만드는 게 목표예요.
💰 Codex 시작하러 가기 →📌 출처
• OpenAI, "Refactor your codebase" 공식 유스케이스 문서 (developers.openai.com/codex)
• OpenAI Codex 공식 페이지 및 Codex CLI 가이드 (openai.com/codex)
• OpenAI Codex Changelog, GPT-5.5/5.6 모델 지원 (2026)
댓글