42장. Codex로 코드 리뷰 받기

2026-04-24Views 473약 8분생성형 AI 활용

42장. Codex로 코드 리뷰 받기

코드를 만드는 일과 코드를 믿을 수 있게 만드는 일은 다릅니다. 초보자는 종종 이 둘을 같은 일처럼 느낍니다. 화면이 뜨고 버튼이 눌리면 끝난 것 같기 때문입니다. 하지만 실제 서비스는 그 다음부터가 진짜 시작입니다. 로그인은 안전한지, 글 수정 권한은 제대로 막았는지, 같은 로직을 여기저기 복붙하지는 않았는지, 나중에 내가 다시 읽어도 이해할 수 있는지가 더 중요해집니다.

바로 이 지점에서 Codex의 역할이 달라집니다. 이제 Codex를 단순한 코드 작성기가 아니라 리뷰어로 앉혀보는 것입니다. 한 발 떨어져서 내 코드를 읽게 만들면, 내가 못 본 틈이 보이기 시작합니다. 그리고 이 순간부터 결과물의 수준이 확 올라갑니다.

[8부] Codex로 코드 리뷰 받기

잘 돌아가는 코드와 잘 만든 코드는 다르다

처음 서비스를 만들 때는 일단 기능을 붙이는 데 집중하게 됩니다. 회원가입이 되고, 글이 저장되고, 검색이 되면 꽤 뿌듯합니다. 그런데 서비스는 기능만 붙는다고 완성되지 않습니다. 같은 기능이 여러 군데에서 중복되고, 에러 처리가 제각각이고, 권한 체크가 화면에만 있고 서버에는 빠져 있다면 언젠가 문제가 납니다.

특히 AI와 함께 빠르게 개발할 때는 이런 일이 더 자주 생깁니다. 속도는 빨라지지만, 코드의 결이 들쭉날쭉해질 수 있기 때문입니다. 어떤 파일은 친절하고 읽기 쉬운데, 어떤 파일은 급하게 이어 붙인 흔적이 남습니다. 이럴 때 Codex 리뷰는 말 그대로 두 번째 눈이 되어 줍니다.

Codex의 /review는 변경된 코드를 읽고 우선순위가 있는 피드백을 주는 기능입니다. 중요한 점은 이 리뷰가 읽기 전용으로 동작한다는 것입니다. 즉, 내 작업 파일을 멋대로 바꾸지 않고 문제를 짚어주는 쪽에 집중합니다.¹ 초보자 입장에서는 이 점이 꽤 든든합니다. 괜히 자동 수정 때문에 더 헷갈릴 일이 줄어들기 때문입니다.

Codex는 무엇을 리뷰해주는가

코드 리뷰라고 하면 문법 검사만 떠올리기 쉽지만, Codex가 유용한 이유는 더 넓게 본다는 데 있습니다. 특히 아래 항목에서 큰 도움을 줍니다.

구조: 한 파일이나 한 함수가 너무 많은 일을 하고 있지 않은가
중복: 비슷한 검증 로직, 데이터 가공 로직, UI 처리 로직이 여러 곳에 반복되지 않는가
가독성: 이름이 모호하지 않은가, 조건문이 너무 깊지 않은가, 의도가 한 번에 읽히는가
실수 가능성: null 처리, 권한 체크, 로딩과 실패 상태, 비동기 흐름에서 빠진 부분은 없는가

이 네 가지는 초보자가 가장 많이 놓치는 부분이기도 합니다. 코드는 실행되는데, 나중에 고치기 힘든 상태로 쌓이기 쉬운 지점들입니다.

예를 들어 글 작성 폼과 글 수정 폼에 비슷한 입력 검증이 두 번 들어가 있다면 당장은 괜찮아 보일 수 있습니다. 하지만 나중에 제목 길이 규칙이 바뀌면 두 군데를 모두 고쳐야 합니다. 한 곳만 바꾸면 버그가 생깁니다. 이런 문제는 지금은 작아 보여도 서비스가 커질수록 비용이 커집니다.

가장 쉬운 시작은 `/diff` 다음 `/review`

Codex 리뷰를 부담 없이 시작하는 가장 좋은 방법은 순서를 고정하는 것입니다. 먼저 /diff로 무엇이 바뀌었는지 확인하고, 그다음 /review로 해석을 받습니다. /diff는 말 그대로 변경점 자체를 보여주고, /review는 그 변경점에서 위험하거나 어색한 부분을 짚어줍니다.²

/review에는 보통 네 가지 방식이 있습니다.¹

기준 브랜치와 비교하기
아직 커밋하지 않은 변경사항 보기
특정 커밋 리뷰하기
원하는 초점을 직접 적어서 맞춤 리뷰 받기

입문자에게 가장 추천하는 것은 두 가지입니다. PR을 올리기 전에는 기준 브랜치와 비교하는 방식, 커밋 직전에는 아직 커밋하지 않은 변경사항을 보는 방식입니다. 이 둘만 잘 써도 리뷰 습관이 금방 잡힙니다.

흐름은 단순합니다. 먼저 변경 범위를 확인하고, 리뷰를 돌리고, 중요한 지적부터 고치고, 다시 리뷰를 돌립니다. 리뷰 결과가 대화 기록에 차곡차곡 남기 때문에 이전에 지적받았던 문제가 사라졌는지도 비교하기 쉽습니다.²

우리 서비스에 바로 적용해보자

지금 만들고 있는 서비스로 예를 들어보겠습니다. 글 작성, 수정, 삭제 기능까지 붙였고, 이제 배포 전 품질을 끌어올리고 싶다고 해봅시다. 이럴 때는 글 수정 흐름 하나만 잡고 리뷰를 걸어보면 좋습니다.

가장 먼저 바뀐 범위를 봅니다.

/diff

변경 파일을 훑어보며 정말 이번 작업에 필요한 파일만 바뀌었는지 확인합니다. 여기서 이미 이상 신호가 보일 때가 많습니다. 예를 들어 글 수정 기능만 손봤는데 로그인 유틸 파일이나 공통 레이아웃까지 같이 바뀌어 있다면, 범위가 과하게 넓어진 것일 수 있습니다.

그다음 리뷰를 요청합니다.

/review

그리고 이런 식으로 초점을 주면 좋습니다.

현재 브랜치를 main과 비교해서 리뷰해줘.
중복된 검증 로직, 글 수정 권한 처리, 로딩과 에러 상태,
가독성이 떨어지는 부분을 우선적으로 봐줘.

이렇게 요청하면 Codex는 단순히 코드를 훑는 것이 아니라, 무엇을 중점적으로 봐야 하는지 알고 읽습니다. Codex는 명확한 목표와 검증 기준이 있을수록 더 좋은 결과를 내는 편입니다.³

실제로는 이런 피드백이 나올 수 있습니다.

글 수정 페이지와 글 작성 페이지에 제목 길이 검증이 따로 들어가 있어 규칙 변경 시 불일치 가능성이 있음
수정 버튼 비활성화는 화면에서 처리하지만 서버 쪽 작성자 확인이 부족해 우회 가능성이 있음
저장 실패 시 사용자에게 같은 메시지만 보여줘 원인 파악이 어려움
data, result, temp 같은 이름이 많아 흐름을 읽기 어려움

이런 피드백이 좋은 이유는 단순히 틀렸다고 말하지 않기 때문입니다. 왜 위험한지, 무엇을 고치면 좋아지는지를 함께 보여줍니다. 초보자에게는 이 설명 자체가 큰 공부가 됩니다.

좋은 리뷰 요청은 좋은 질문에서 나온다

Codex 리뷰 품질은 질문 품질에 크게 좌우됩니다. 그냥 문제 있나 봐줘라고 하면 너무 넓습니다. 반대로 초점을 잡아주면 더 실용적인 답을 얻을 수 있습니다.

아래처럼 요청해보면 좋습니다.

현재 변경사항에서 중복 로직과 함수 분리 후보를 찾아줘
이 API 라우트에서 인증과 권한 체크가 빠진 곳이 있는지 봐줘
이 폼에서 빈 값, 너무 긴 입력, 네트워크 실패 상황을 기준으로 리뷰해줘
이 페이지에서 로딩, 에러, 빈 목록 처리가 사용자 입장에서 어색하지 않은지 봐줘
성능보다 가독성과 유지보수성을 우선해서 개선 포인트를 짚어줘

핵심은 리뷰의 관점을 미리 정해주는 것입니다. 보안, 구조, 중복, UI 상태, 테스트 누락처럼 주제를 좁힐수록 리뷰가 또렷해집니다.

리뷰 결과를 읽는 올바른 순서

Codex가 지적했다고 해서 전부 바로 반영할 필요는 없습니다. 좋은 리뷰어를 쓰는 것과 리뷰 결과를 맹신하는 것은 전혀 다른 이야기입니다. 리뷰 결과는 다음 순서로 읽으면 훨씬 안정적입니다.

첫째, 사실 여부를 확인합니다. 정말 그 지적이 현재 코드에 해당하는가를 봅니다. 가끔은 맥락을 넓게 해석해서 나온 의견일 수도 있습니다.

둘째, 영향도를 판단합니다. 보안, 데이터 손상, 권한 누락처럼 위험도가 높은 문제는 바로 처리해야 합니다. 반면 이름이 조금 아쉽다거나 함수 분리 방식의 취향 차이는 나중으로 미뤄도 됩니다.

셋째, 작은 수정으로 반영합니다. 리뷰 하나를 고치겠다고 파일 절반을 다시 쓰기 시작하면 오히려 새 문제가 들어올 수 있습니다. 특히 초보자일수록 한 번에 크게 고치기보다, 작은 단위로 고치고 다시 리뷰받는 편이 안전합니다.

넷째, 꼭 실행해봅니다. 리뷰는 생각의 품질을 높여주지만, 최종 검증은 여전히 실행과 테스트입니다. 버튼을 눌러보고, 로그인해보고, 수정과 삭제를 실제로 해보는 단계는 건너뛰면 안 됩니다.

AGENTS.md로 리뷰 기준을 고정하자

혼자 작업하더라도 기준 문서를 하나 두면 리뷰 품질이 더 안정적입니다. Codex는 저장소의 AGENTS.md를 참고해 팀이나 프로젝트의 규칙에 맞춰 리뷰할 수 있습니다.⁴

예를 들어 우리 서비스라면 이런 규칙을 적어둘 수 있습니다.

## Review guidelines

- 로그인한 사용자만 글 작성, 수정, 삭제를 할 수 있어야 한다
- 권한 검사는 화면뿐 아니라 서버에서도 확인해야 한다
- 사용자 입력 검증은 공통 함수나 스키마로 모을 수 있으면 모은다
- 같은 로직이 두 번 이상 반복되면 추출 후보로 본다
- 실패 메시지는 사용자용 문장과 개발자용 로그를 구분한다

이 문서가 있으면 Codex는 그냥 일반적인 좋은 코드만 찾는 것이 아니라, 우리 서비스에서 특히 중요하게 보는 포인트를 더 잘 짚어줍니다. 즉, 리뷰가 프로젝트 맞춤형으로 바뀝니다.

중복 코드와 읽기 어려운 코드는 왜 위험할까

중복 코드는 대표적인 코드 냄새입니다. 비슷한 코드가 여러 군데 있으면 한 곳을 고칠 때 다른 곳을 놓치기 쉽고, 결국 유지보수 비용이 커집니다.⁵ 특히 초보자가 AI와 함께 빠르게 개발할 때는 비슷한 기능을 새 파일에 그대로 다시 만들어버리는 일이 흔합니다. 글 작성 폼, 글 수정 폼, 관리자 수정 폼이 조금씩 다른 얼굴로 같은 코드를 품고 있는 식입니다.

이럴 때 Codex 리뷰는 중복을 찾아내는 데 꽤 강합니다. 어디가 비슷한 역할을 하는지, 함수로 추출할 수 있는지, 공통 컴포넌트나 유틸로 묶을 수 있는지를 잘 제안합니다. 다만 정리할 때는 욕심을 줄이는 것이 중요합니다. 큰 갈아엎기보다 작은 단위로, 리뷰 가능한 범위 안에서 정리하는 편이 안전합니다.⁶

가독성도 마찬가지입니다. 지금의 나는 코드를 기억하고 있지만, 일주일 뒤의 나는 거의 남입니다. 그 남이 다시 읽어도 이해되는 코드가 좋은 코드입니다. Codex가 변수 이름, 함수 길이, 조건문 깊이, 역할 분리를 자주 지적하는 이유가 여기에 있습니다.

사람 리뷰와 Codex 리뷰를 나눠서 생각하자

Codex가 잘 보는 것과 사람이 더 잘 보는 것은 다릅니다. 둘을 섞어 생각하면 오히려 기대가 어긋납니다.

리뷰 주체	잘 보는 것
Codex	중복, 빠진 예외 처리, 권한 체크 누락, 가독성, 위험한 패턴
사람	서비스 의도, 사용자 경험, 비즈니스 규칙, 출시 판단

예를 들어 Codex는 이 함수가 너무 길고, 에러 처리가 빠졌고, 인증 확인이 약하다는 점을 잘 짚습니다. 하지만 이 기능이 우리 사용자에게 정말 필요한지, 검색 결과를 카드형으로 보여주는 것이 목록형보다 나은지, 무료 플랜에서 이 흐름이 맞는지는 사람이 판단해야 합니다.

그래서 가장 좋은 조합은 이렇습니다. 먼저 Codex로 셀프 리뷰를 해서 기계적으로 잡을 수 있는 문제를 미리 줄입니다. 그다음 사람 리뷰어에게는 더 중요한 질문, 즉 제품과 흐름과 우선순위에 대한 판단을 맡깁니다. GitHub PR에서는 @codex review 같은 방식으로 팀에 보이는 리뷰를 요청할 수 있고,⁷ 반대로 조용히 내 터미널에서만 먼저 셀프 리뷰를 하고 싶다면 로컬 CLI 리뷰를 쓰면 됩니다.⁸

초보자에게 특히 좋은 셀프 리뷰 루틴

처음에는 리뷰가 귀찮게 느껴질 수 있습니다. 하지만 루틴으로 고정하면 훨씬 편해집니다.

기능 하나를 너무 크게 만들지 말고 작은 단위로 끝낸다.
/diff로 변경 범위를 먼저 확인한다.
/review로 기준 브랜치와 비교해 큰 문제를 찾는다.
중요한 지적부터 고친다.
다시 /review로 아직 커밋하지 않은 변경사항을 확인한다.
직접 실행하고 테스트한 뒤 커밋한다.
PR을 열고 필요하면 팀에 보이는 리뷰를 추가로 요청한다.

이 루틴의 장점은 간단합니다. 문제가 커지기 전에 잡습니다. 초보자에게 가장 무서운 것은 큰 사고보다 작은 실수가 쌓이는 것입니다. 리뷰는 그 누적을 막아줍니다.

초보자가 자주 하는 실수

Codex 리뷰를 쓰면서 많이 하는 실수도 있습니다.

변경 범위를 확인하지 않고 곧바로 리뷰부터 돌린다
한 번에 너무 많은 파일을 바꾼 뒤 리뷰 결과가 흐려진다
문제 있나 봐줘처럼 너무 넓은 요청만 던진다
AI 제안을 전부 정답처럼 받아들인다
리뷰를 반영하고도 실제 실행은 해보지 않는다

이 다섯 가지만 피해도 리뷰 효율이 꽤 올라갑니다. 특히 마지막이 중요합니다. 리뷰는 사고를 돕는 도구이지, 최종 실행 결과를 대신 보증하는 마법은 아닙니다.

리뷰어로 Codex를 쓰는 순간 실력이 달라진다

AI에게 코드를 쓰게만 하면, 나는 결과를 받는 사람에 머물기 쉽습니다. 하지만 AI에게 리뷰를 맡기기 시작하면 이야기가 달라집니다. 무엇이 좋은 구조인지, 어떤 중복이 위험한지, 어디서 실수가 나는지 계속 비교하며 보게 되기 때문입니다. 즉, 코드를 생산하는 사람에서 코드를 판단하는 사람으로 한 단계 올라서게 됩니다.

처음 풀스택 서비스를 만드는 과정에서 가장 값진 변화는 문법을 많이 아는 것이 아닙니다. 스스로 품질을 점검하는 눈이 생기는 것입니다. Codex를 리뷰어로 세워두면, 그 눈을 훨씬 빨리 기를 수 있습니다.

돌아가는 코드에 만족하지 말고, 다시 읽어도 믿을 수 있는 코드까지 가보자. 바로 그 한 걸음을 Codex 리뷰가 도와줍니다.