Gemini로 코드 리뷰와 리팩토링하는 방법: AI 기반 코드 품질 개선

Gemini가 코드 리뷰에 적합한 이유

코드 리뷰 도구로서 Gemini의 가장 큰 강점은 1M token context window다. 이것이 왜 중요한가? 코드 리뷰는 단일 파일을 보는 것이 아니라 시스템 전체의 맥락 안에서 개별 변경을 판단하는 행위다.

일반적인 AI 도구에 코드 리뷰를 요청하면, 파일 하나 또는 diff 하나를 올리게 된다. 도구는 해당 코드만 보고 “변수명이 좋지 않다”, “null check가 없다” 같은 피상적 피드백을 준다. 그 코드가 전체 시스템에서 어떤 역할을 하는지, 기존 코드와 어떤 패턴을 따르는지, 팀의 코딩 규칙은 무엇인지 모르기 때문이다.

Gemini의 1M token context는 다르다. 프로젝트의 주요 파일 수십 개를 한 번에 올릴 수 있다. 아키텍처 문서, 코딩 컨벤션 문서, 기존 코드, 그리고 리뷰 대상 코드를 모두 같은 context에 넣을 수 있다. 이렇게 하면 AI가 “이 프로젝트에서는 에러를 이런 방식으로 처리하는데, 이 새 코드는 다른 방식을 쓰고 있다”는 수준의 리뷰를 할 수 있게 된다.

context가 풍부한 프롬프트 구성법

기본 구조

효과적인 코드 리뷰 프롬프트는 세 가지 레이어로 구성된다.

레이어 1: 프로젝트 맥락
"이 프로젝트는 [기술 스택]을 사용하는 [서비스 종류]이다.
아키텍처는 [패턴]을 따르며, [주요 제약 조건]이 있다."

레이어 2: 코딩 규칙
"우리 팀의 코딩 규칙:
- 에러 처리는 custom error class를 사용
- 모든 public 함수에 JSDoc 주석 필수
- 데이터베이스 접근은 repository 패턴
- 비즈니스 로직은 service layer에 집중"

레이어 3: 리뷰 대상과 관점
"아래 코드를 리뷰해 달라. 특히 [관점]에 집중해 달라.
[파일 내용]"

레이어 1과 2가 있고 없고의 차이는 크다. 맥락 없이 코드만 올리면 “일반적으로 좋은 코드인가”를 판단하지만, 맥락이 있으면 “이 프로젝트에 맞는 코드인가”를 판단한다.

관련 파일 함께 올리기

리뷰 대상 파일만 올리지 말고, 관련 파일을 함께 올려야 한다.

"다음 파일들을 참고하면서 마지막에 첨부된 파일을 리뷰해 달라.

[참고 1: src/errors/AppError.ts - 프로젝트의 에러 처리 패턴]
[참고 2: src/services/UserService.ts - 기존 서비스의 구현 패턴]
[참고 3: src/repositories/UserRepository.ts - 기존 레포지토리 패턴]
[참고 4: docs/CODING_CONVENTIONS.md - 코딩 규칙 문서]

[리뷰 대상: src/services/OrderService.ts - 새로 작성한 코드]"

이렇게 하면 Gemini는 기존 코드의 패턴을 학습하고, 새 코드가 그 패턴을 따르는지 비교 리뷰할 수 있다.

6가지 차원의 코드 품질 분석

체계적인 코드 리뷰를 위해 6가지 품질 차원을 정의하고 각 차원에 대해 평가를 요청한다.

"아래 코드를 다음 6가지 차원으로 분석해 달라.
각 차원에 대해 [1-5점] 평가와 구체적 근거를 제시해 달라.

1. 가독성 (Readability)
   - 변수/함수 이름이 의도를 명확히 전달하는가
   - 코드 흐름이 자연스럽게 읽히는가
   - 주석이 적절한가 (과도하거나 부족하지 않은가)
   - 함수 길이와 복잡도가 적절한가

2. 유지보수성 (Maintainability)
   - 단일 책임 원칙을 따르는가
   - 의존성이 명확하고 느슨한가
   - 변경이 필요할 때 영향 범위가 제한적인가
   - 매직 넘버/하드코딩된 값이 없는가

3. 성능 (Performance)
   - 불필요한 연산이나 메모리 할당이 있는가
   - N+1 쿼리 같은 데이터베이스 비효율이 있는가
   - 적절한 캐싱이나 메모이제이션이 있는가
   - 루프 내 비효율적 패턴이 있는가

4. 보안 (Security)
   - 입력값 검증이 충분한가
   - SQL injection, XSS 등의 취약점이 있는가
   - 민감 정보가 노출될 가능성이 있는가
   - 인증/인가 로직이 적절한가

5. 테스트 가능성 (Testability)
   - 함수가 테스트하기 쉬운 구조인가
   - 외부 의존성이 주입 가능한가
   - 부수 효과가 격리되어 있는가
   - 경계 조건이 명확한가

6. 에러 처리 (Error Handling)
   - 에러가 적절히 잡히고 처리되는가
   - 에러 메시지가 디버깅에 유용한가
   - 에러가 삼켜지거나 무시되는 곳이 없는가
   - 복구 가능한 에러와 치명적 에러를 구분하는가

각 차원에서 점수가 3점 이하인 항목에 대해 구체적 개선 코드를 제시해 달라."

6가지 차원을 모두 적용할 필요는 없다. 상황에 따라 집중해야 할 차원이 다르다. 보안이 중요한 인증 모듈이라면 보안과 에러 처리에 가중치를 두고, 성능이 중요한 데이터 처리 파이프라인이라면 성능 차원에 집중한다.

보안 전용 리뷰

보안 리뷰는 일반 코드 리뷰와 분리하여 수행하는 것이 효과적이다. 관점을 보안에 한정하면 더 깊이 있는 분석이 나온다.

"아래 코드를 보안 관점에서만 리뷰해 달라.
OWASP Top 10 (2021) 기준으로 검토하되, 다음에 특히 주의해 달라:

A01 - Broken Access Control:
- 인가 체크가 누락된 엔드포인트가 있는가
- 수평적/수직적 권한 상승이 가능한 경로가 있는가

A02 - Cryptographic Failures:
- 민감 데이터가 평문으로 저장/전송되는가
- 약한 암호화 알고리즘이 사용되는가

A03 - Injection:
- SQL, NoSQL, OS command, LDAP injection 가능성
- 사용자 입력이 검증 없이 쿼리에 포함되는 곳

A07 - Identification and Authentication Failures:
- 세션 관리 취약점
- 비밀번호 정책 미흡

각 발견에 대해:
- 심각도: [Critical/High/Medium/Low]
- 취약한 코드 위치 (파일명, 라인 범위)
- 공격 시나리오: 이 취약점을 어떻게 악용할 수 있는가
- 수정 코드: 취약점을 해결하는 구체적 코드"

보안 리뷰에서 Gemini가 특히 잘 잡아내는 것은 “의도치 않은 정보 노출”이다. 에러 메시지에 스택 트레이스가 포함되거나, API 응답에 불필요한 내부 필드가 노출되는 경우를 잘 감지한다. 반면, 비즈니스 로직 수준의 권한 우회(예: “관리자만 접근 가능한 기능을 일반 사용자가 특정 순서로 API를 호출하면 우회할 수 있는 경우”)는 비즈니스 규칙을 완전히 이해해야 하므로 한계가 있다.

코드 설명 요청

기존 코드베이스를 이해해야 할 때, Gemini에게 코드 설명을 요청하는 것이 효과적이다. 특히 레거시 코드나 다른 사람이 작성한 코드를 인수인계 받을 때 유용하다.

"아래 코드를 다음 수준으로 설명해 달라:

1. 높은 수준 요약: 이 파일/모듈이 전체 시스템에서 어떤 역할을 하는가 (2-3문장)

2. 핵심 흐름: 메인 함수의 실행 흐름을 단계별로 설명
   - 각 단계에서 어떤 데이터가 들어오고 나가는가
   - 분기 조건과 그 의미

3. 설계 결정: 코드에서 드러나는 설계 결정과 그 이유
   - 왜 이 패턴을 선택했을까
   - 대안은 무엇이 있었을까

4. 숨겨진 복잡성: 코드를 처음 보는 사람이 놓치기 쉬운 부분
   - 암묵적 의존성
   - 실행 순서에 의존하는 로직
   - 에지 케이스 처리

5. 위험 지점: 이 코드를 수정할 때 주의해야 할 부분
   - 수정 시 다른 곳에 영향을 줄 수 있는 연결점
   - 테스트가 없어서 회귀를 놓칠 수 있는 부분"

이 5단계 설명을 요청하면, 코드의 표면적 기능뿐만 아니라 설계 의도와 숨겨진 복잡성까지 파악할 수 있다. 새로운 팀원의 온보딩 시간을 크게 줄여준다.

리팩토링 기회 식별

코드 냄새 감지

"아래 코드에서 리팩토링이 필요한 '코드 냄새(code smell)'를 식별해 달라.
Martin Fowler의 리팩토링 카탈로그 기준으로 분류하고,
각 냄새에 대해 적용할 수 있는 구체적 리팩토링 기법을 제안해 달라.

우선순위를 다음 기준으로 정해 달라:
1. 현재 버그를 유발하고 있는가
2. 향후 변경 시 버그를 유발할 가능성이 높은가
3. 코드 이해를 방해하는가
4. 성능에 영향을 주는가

| 코드 냄새 | 위치 | 리팩토링 기법 | 우선순위 | 예상 노력 |
|-----------|------|---------------|----------|-----------|"

자주 발견되는 코드 냄새 패턴과 Gemini의 리팩토링 제안은 다음과 같다.

Long Method는 Extract Method로 해결한다. 하나의 함수가 50줄 이상이면 논리적 단위로 분리한다. Gemini는 분리 지점을 제안하고 분리된 함수의 이름까지 추천한다.

Duplicated Code는 Extract Function 또는 Template Method 패턴으로 해결한다. 여러 곳에 비슷한 코드가 반복되면, 공통 부분을 추출하고 변하는 부분만 파라미터로 받는다.

Feature Envy는 Move Method로 해결한다. 한 클래스의 메서드가 다른 클래스의 데이터에 과도하게 접근하면, 그 메서드를 데이터가 있는 클래스로 옮긴다.

Primitive Obsession은 Value Object 도입으로 해결한다. 이메일, 전화번호, 금액 같은 값을 string이나 number로 다루는 대신 전용 타입을 만든다.

리팩토링 코드 생성

코드 냄새를 식별한 후, 구체적인 리팩토링 코드를 요청한다.

"위에서 식별한 코드 냄새 중 우선순위 1번에 대해
리팩토링된 코드를 생성해 달라.

요구사항:
- 외부에서 관찰 가능한 동작이 변하면 안 된다
- 기존 테스트가 모두 통과해야 한다
- 변경 전후의 diff를 보여 달라
- 새로 추가해야 할 테스트가 있다면 함께 제시해 달라

리팩토링 전:
[기존 코드]

리팩토링 후:
[변경된 코드를 여기에 생성]"

“외부에서 관찰 가능한 동작이 변하면 안 된다”는 조건이 핵심이다. 리팩토링의 정의 자체가 “동작을 보존하면서 구조를 개선하는 것”이기 때문이다. 이 조건을 명시하면 Gemini가 동작 변경과 구조 변경을 구분하여 작업한다.

검증 전략

Gemini가 제안한 리팩토링을 바로 적용하면 안 된다. 검증 단계가 필수다.

1단계: 동작 보존 확인

"리팩토링 전 코드와 리팩토링 후 코드를 비교하여,
외부에서 관찰 가능한 동작이 달라진 부분이 있는지 확인해 달라.

확인 항목:
- 같은 입력에 대해 같은 출력이 나오는가
- 부수 효과(side effect)가 동일한가
- 예외 발생 조건이 동일한가
- 호출하는 외부 의존성이 동일한가

동작이 달라진 부분이 있으면 의도적 변경인지 실수인지 판단해 달라."

2단계: 테스트 커버리지 확인

"리팩토링된 코드에 대해 다음을 확인해 달라:

1. 기존 테스트가 커버하는 경로
2. 리팩토링으로 새로 생긴 코드 경로 중 테스트가 없는 부분
3. 추가해야 할 테스트 케이스와 구체적 테스트 코드"

3단계: 점진적 적용

대규모 리팩토링은 한 번에 적용하지 말고 단계적으로 수행한다.

"이 리팩토링을 3단계로 나누어 수행하고 싶다.
각 단계가 독립적으로 커밋 가능하고, 각 단계 후에 모든 테스트가 통과하도록
단계를 나눠 달라.

1단계: [가장 안전한 변경]
2단계: [1단계에 의존하는 변경]
3단계: [최종 정리]

각 단계의 커밋 메시지도 제안해 달라."

실무 워크플로 정리

일상적 코드 리뷰에서 Gemini를 활용하는 워크플로를 정리하면 다음과 같다.

PR 생성 시 변경 파일과 함께 관련 파일(기존 패턴 참고용)을 Gemini에 올린다. 6가지 차원 중 해당 PR에 관련된 차원을 선택하여 리뷰를 요청한다. 보안 민감 코드의 경우 별도의 보안 전용 리뷰를 추가로 수행한다.

리팩토링 계획 수립 시 대상 코드와 관련 코드를 함께 올려 코드 냄새를 식별한다. 우선순위 매트릭스를 기반으로 실행 순서를 정한다. 각 리팩토링을 독립적 단계로 나누어 점진적으로 실행한다.

레거시 코드 인수인계 시 5단계 코드 설명을 요청하여 코드의 전체 그림을 파악한다. 숨겨진 복잡성과 위험 지점을 문서화한다. 향후 리팩토링 계획의 기초 자료로 활용한다.

주의할 점은, Gemini의 코드 리뷰를 사람의 리뷰를 대체하는 것으로 보면 안 된다는 것이다. AI 리뷰는 사람이 놓치기 쉬운 패턴 불일치, 보안 취약점, 성능 비효율을 잡아내는 보완 도구다. 비즈니스 로직의 정확성, 설계 방향의 적절성, 팀 문화에 맞는 코드 스타일 같은 판단은 여전히 사람의 몫이다. AI와 사람의 리뷰를 결합하면 어느 한쪽만으로는 달성할 수 없는 리뷰 품질을 얻을 수 있다.

대규모 코드베이스에서의 활용 전략

점진적 context 확장

프로젝트 전체를 한 번에 올릴 수 없는 경우, 점진적으로 context를 확장하는 전략을 사용한다.

1회차: 리뷰 대상 파일과 직접 의존하는 파일만 올려서 기본 리뷰를 수행한다. 2회차: 1회차에서 발견된 문제와 관련된 추가 파일(예: 에러 처리 패턴 불일치가 발견되면 프로젝트의 에러 처리 모듈)을 올려서 심화 리뷰를 수행한다. 3회차: 유사한 역할을 하는 기존 코드를 올려서 일관성 리뷰를 수행한다.

이 방식은 한 번에 모든 것을 올리는 것보다 각 회차의 분석 깊이가 깊어지는 장점이 있다.

리뷰 결과의 추적과 학습

Gemini가 반복적으로 지적하는 패턴이 있다면, 그것을 팀의 코딩 규칙에 반영하여 사전에 방지하는 것이 장기적으로 효과적이다. 예를 들어 Gemini가 매번 “이 함수에서 에러가 삼켜지고 있다”를 지적한다면, ESLint 규칙이나 코딩 컨벤션 문서에 “모든 catch 블록은 최소한 로깅을 포함해야 한다”를 추가하는 것이 근본적 해결이다.

리뷰 결과를 축적하면 팀의 코드 품질 추이를 파악할 수 있다. 월별로 Gemini 리뷰에서 발견된 문제 유형과 빈도를 기록하면, 어떤 영역의 품질이 개선되고 있고 어떤 영역이 지속적으로 문제인지 가시화된다. 이 데이터는 팀 교육의 우선순위를 결정하는 근거가 된다.

Gemini 코드 리뷰의 한계

Gemini의 코드 리뷰가 잡아내지 못하는 영역을 인식하는 것도 중요하다. 비즈니스 요구사항과의 일치 여부는 판단하기 어렵다. 코드가 기술적으로 완벽해도 비즈니스 규칙을 잘못 구현했다면, Gemini는 이를 감지하지 못한다. 또한 시스템 수준의 아키텍처 적합성도 제한적이다. 개별 파일은 깔끔하지만 전체 아키텍처에서 잘못된 레이어에 위치하는 코드를 판단하기 어렵다. 마지막으로 팀의 암묵적 규칙도 알 수 없다. 문서화되지 않은 “우리 팀에서는 이렇게 한다”는 관습은 Gemini가 참고할 수 없다. 이런 규칙은 코딩 컨벤션 문서에 명시하여 context로 제공해야 한다.