Codex로 리팩터링하기

Claude Code나 Codex로 코드를 생성하다 보면, 어느 순간 한 파일 안에 너무 많은 코드가 몰려 있는 경우가 있다. 기능을 빠르게 구현하는 과정에서는 큰 문제처럼 보이지 않지만, 시간이 지나면 파일의 책임이 흐려지고 수정하기 어려운 구조가 된다.

Opus 4.6, GPT 5.3 때부터 활용해 만들었던 코드들이 프로젝트 안에 꾸준히 쌓이면서, 이제는 어느 정도 정리해야 할 시점이 왔다고 느꼈다. 그래서 기존 동작을 유지하면서도 안전하게 코드를 나눌 수 있는 리팩터링 전략을 고민해봤다.

최우선 목표는 기존 동작을 보존한 채, 변경 단위를 안전하게 격리하는 것이었다. 기능이 많아질수록 한 부분의 수정이 예상치 못한 영역에 영향을 줄 가능성도 커진다. 그래서 이번 리팩터링에서는 코드를 더 예쁘게 나누는 것보다, 기존 흐름을 깨지 않고 안전하게 구조를 정리하는 데 가장 큰 우선순위를 두었다.

이 파일에 너무 많은 코드가 있어. 정리해줘.

그래서 위와 같은 간단한 프롬프트만으로 리팩터링을 맡기기에는, 아무리 성능이 좋은 AI 모델이라도 불안할 수밖에 없다. 어떤 기준으로 코드를 나눌지, 반드시 보존해야 할 동작은 무엇인지, 그리고 어디까지를 리팩터링의 범위로 볼 것인지가 먼저 정리되어야 한다. 그래야 AI에게 작업을 맡기는 입장에서도, 기존 동작이 깨지지 않을 것이라는 최소한의 확신을 가질 수 있다.

이런 문제 역시 AI를 통해 어느 정도 해결할 수 있다. 곧바로 코드를 정리해달라고 지시하는 대신, 먼저 현재 프로젝트에서 정리가 필요한 모듈들을 어떤 기준으로 개선하면 좋을지 AI와 함께 토론해보는 것이다. 즉, AI에게 바로 수정 작업을 맡기기보다, 리팩터링의 기준과 경계부터 함께 정의하는 과정이 필요하다.

먼저, 내가 생각한 기준부터 던져줬다.

• 기존 동작이 깨지거나 변경되면 절대 안 된다.

• 안전하게 모듈화와 개선이 이루어져야 한다.

리팩터링을 맡기려면 아직 이것만으로는 부족하다. 이 기준을 출발점으로 삼아 GPT-5.5 모델과 대화를 이어갔다.

• 단순한 모듈화가 아니다. 기존 동작을 보존하고, 변경 단위를 안전하게 격리한다.

• 리팩터링과 기능 변경을 절대 섞지 않는다.

  • 더 좋은 코드가 목표가 아닌 동작은 그대로인데, 읽고 수정하기 쉬운 구조로 바꾸는 것이 목표.

  • 커밋 단위를 동작 고정 → 추출 → 이름 정리 → 중복 제거처럼 작게 나누어 작업한다.

• 변경되면 안 되는 동작 목록부터 정의한다.

• 파일을 나누는 기준은 대략 네 가지로 잡는다.

  • UI 표현, 상태와 이벤트 로직, 순수 계산 로직, 외부 의존 로직.

  • 순수한 것 → 표현적인 것 → 상태를 가진 것 → 외부 효과가 있는 것 순으로 적용한다.

• 가장 중요한 건 한 번에 하나만 옮기는 것이다.

훨씬 안전하고 정교한 기준을 정의하고, 점진적으로 리팩터링하는 운영 방식을 제시해줬다. 이를 바탕으로 프로젝트 전체에 참고할만한 지침을 만든 후, 정리가 필요한 파일에 세션별로 플랜모드를 활성화 시켜 다음과 같은 순서대로 리팩터링을 진행했다.

  
    
  
  
    
  

# 리팩터링 지침

이 프로젝트의 리팩터링 목표는 기존 동작을 변경하지 않고, 큰 파일의 책임을 안전하게 분리하는 것이다.

모든 변경은 동작 보존을 최우선으로 한다.
기능 추가, UI 변경, API 요청 방식 변경, 상태 구조 변경, 조건식 개선은 이번 리팩터링 범위에 포함하지 않는다.
한 번에 하나의 책임만 분리한다.
순수 함수 분리 → JSX 표현 컴포넌트 분리 → 상태 로직 분리 → 외부 효과 분리 순서로 진행한다.
동작 변경 가능성이 있는 수정은 먼저 제안만 하고, 바로 적용하지 않는다.

위 같은 내용으로 REFACTORING.md를 생성한 후, 프로젝트 범위의 리팩터링 지침을 정의해두었다.

그럼 이제 리팩터링할 파일을 @로 찾아 지정하고 플랜모드를 활성화한 후, 프롬프트를 실행한다.

  
    
  
  
    
  

리팩터링 문서를 참고하면서, 아래 플랜을 진행해줘.

---

CodeBlockSourceDialog.tsx 파일을 수정하지 말고 분석만 해줘.

목표는 기존 동작을 절대 바꾸지 않고 안전하게 모듈화하는 거야.
먼저 이 파일 안의 책임을 구분해줘.

분류 기준은 다음과 같아.

1. 순수 계산 로직
2. JSX 표현 로직
3. 이벤트 핸들러
4. React state / derived state
5. useEffect 또는 외부 side effect
6. API / router / storage / cookie 같은 외부 의존 로직

각 항목별로 분리 후보를 제안하되, 변경 위험도를 낮음 / 중간 / 높음으로 구분해줘.
그리고 가장 안전한 적용 순서를 제안해줘.
아직 코드는 수정하지 마.

코덱스는 자동으로 관련 지침도 함께 참고를 하는데, 여기서는 알아서 vercel의 react-best-practices도 함께 확인했다. 이후에는 요약, 책임별 분류, 가장 안전한 적용 순서, 테스트 계획 등의 섹션으로 나눠 플랜을 제시한다.

나는 보통 플랜 모드로 진행하면 몇 번 검토를 더 시킨다. 놓친 부분은 없는지 검토해달라고 하면 실제로 유의미한 결과를 내놓기도 했다.

확실히 해당 파일의 코드줄 수가 줄었고, 나쁘지 않게 모듈화를 진행한 모습이다. 실제로 동작이 깨지는 부분도 없었다. 이후에는 몇 번의 프롬프트를 더 하면서 동작 고정 → 추출 → 이름 정리 → 중복 제거 순서로 커밋을 진행하면 된다.

이렇게 Codex GPT 5.5(매우 높음)로 리팩터링을 해봤다. 앞으로의 코드 생성도 이와 같이 어느 정도의 규칙을 지켜주면 좋을 것 같아서 AGENTS.md 파일에 지침 몇 줄을 추가해줬다.

최근에는 클로드 코드까지 병행하면서, 내가 직접 코드를 작성하는 일이 거의 없어졌다. 대부분 검토에서 끝나거나 AI가 생성한 코드를 전적으로 믿는다. 그만큼 AI 모델의 코딩 성능이 너무나 좋아졌다. 직접 작성하는 코드라고 해봤자 프롬프트가 오히려 귀찮은 UI 작업이었다.