Cursor AI를 활용한 반자동화 코드 리뷰 시스템 가이드

1. 개요

기존 코드 리뷰는 GitHub PR 환경에서 코드 리뷰를 진행할 시 컨텍스트 전환의 부담, 팀원 부재 시 적시 피드백의 어려움 같은 불편함이 있었다. 그리고 Cursor의 Bugbot 같은 AI 리뷰 도구가 있지만 월 40달러의 비용이 부담스러웠다.

그래서 나는 Cursor v1.6의 Custom Slash Commands와 v1.7의 Plan Mode를 활용해 IDE에서 바로 쓸 수 있는 나만의 반자동 코드 리뷰 커맨드(/code-review)를 만들었다.

이 커스텀 커맨드는 몇 가지 질문에 답하면 AI가 Toss의 변경하기 쉬운 프론트엔드 코드를 위한 지침서를 기반으로 꽤나 괜찮은 퀄리티의 코드 리뷰를 자동으로 해주며, 토큰 소모량을 기준으로 산정해보았을 때 Bugbot보다 훨씬 저렴한 비용으로 이용할 수 있었고, 직접 써보니 퀄리티가 만족스러워 이 유용한 방법을 공유하고자 한다.

---

2. 기술적 배경: Cursor v1.6 & v1.7 업데이트

( Cursor Changelog 바로가기 )

이 자동화 시스템은 Cursor의 두 가지 핵심 기능 덕분에 가능했다.

2.1. Custom Slash Commands (v1.6)

• 기능: 사용자가 .cursor/commands/ 디렉토리에 Markdown 파일로 재사용 가능한 프롬프트를 정의할 수 있는 기능이다.
• 적용: /code-review는 이 기능을 사용하여 복잡한 코드 리뷰 로직을 하나의 실행 가능한 커맨드로 패키징한 것이다. 이를 통해 누구나 동일한 품질 기준으로 코드 리뷰를 요청할 수 있다.

2.2. Plan Mode (v1.7)

• 기능: 복잡하고 긴 작업을 수행하기 전에 AI가 스스로 상세한 실행 계획을 수립하고, 그 계획에 따라 체계적으로 작업을 진행하는 기능이다.
• 적용: 코드 리뷰 시, AI는 Plan Mode를 통해 단순히 코드를 읽는 것을 넘어, ①디렉토리 구조 분석 → ②리뷰 파일 선정 → ③Toss Rules 로드 → ④4대 원칙 기반 체계적 분석 → ⑤보고서 생성 이라는 다단계 프로세스를 안정적으로 수행한다. 이것이 바로 깊이 있는 분석이 가능한 이유다.

---

3. 핵심 도구: /code-review 커맨드 분석

/code-review 커맨드는 Toss Frontend Rules의 4대 원칙(가독성, 예측성, 응집도, 결합도)을 기준으로 코드를 체계적으로 분석하고 개선점을 제안합한다.

3.1. 4대 분석 기준

기준	중점 분석 항목
가독성 (Readability)	매직 넘버, 추상화 수준, 복잡한 조건문, 변수명
예측성 (Predictability)	반환 타입 일관성, 숨은 부작용(Side Effects), 함수명 명확성
응집도 (Cohesion)	파일/모듈 그룹화, 상수 위치, 연관 코드 분리 여부
결합도 (Coupling)	Props Drilling, 상태 관리 범위, 불필요한 추상화

3.2. Context Files

본 커맨드는 아래 룰 파일을 컨텍스트로 참조하여 리뷰를 진행한다.

• ㅎ@.cursor/rules/commons/toss-frontend-rules.mdc

  • ( Toss Frontend Rules 출처 )

---

4. 사용자 가이드: 단계별 실행 방법

4.1. 사전 준비

프로젝트 루트에 .cursor/commands/code-review.md 파일이 존재하는지 확인한다.

4.2. 커맨드 실행 및 파라미터 입력

Cursor 채팅창에서 /를 입력하여 code-review 커맨드를 선택하고 실행한다. AI가 순서대로 질문하는 내용에 답변한다.

1. 리뷰 대상 경로 입력 (targetPath)

🤖 "어떤 경로의 코드를 리뷰하시겠습니까? (예: /src/app/(logged-in)/example)"
👤 "/src/app/(logged-in)/example"

2. 리뷰 심층도 선택 (depth)

🤖 "리뷰 심층도를 선택하세요: shallow(구조만)/standard(주요 파일)/deep(종합적)"
👤 "standard"

• shallow: 전체적인 구조와 응집도를 빠르게 확인할 때 유용하다.
• standard: 주요 로직과 컴포넌트 중심으로 일반적인 리뷰 시 사용하다.
• deep: 모든 파일을 대상으로 한 가장 상세한 리뷰다.

3. 집중 분석 영역 선택 (focusArea) (선택 사항)

🤖 "특정 영역에 집중하시겠습니까? readability(가독성)/predictability(예측성)/cohesion(응집도)/coupling(결합도)/all(전체)"
👤 "readability"

• 특정 코드 품질(예: 가독성)을 집중 개선하고 싶을 때 사용한다. 입력하지 않으면 all로 처리된다.

4.3. 리뷰 기준 커스터마이징

이 코드 리뷰 커맨드의 핵심 장점 중 하나는 리뷰 기준의 모듈성이다. 현재는 Toss Frontend Rules를 기본으로 사용하지만, 팀의 필요에 따라 언제든지 다른 코드 리뷰 규칙(예: Google Frontend Style Guide, Airbnb Style Guide 등)으로 교체할 수 있다.

리뷰 기준을 변경하려면 .cursor/commands/code-review.md 파일의 두 부분을 수정해야 한다.

단계 1: 새로운 룰 파일 준비

먼저, 적용하고 싶은 새로운 코드 리뷰 규칙을 담은 Markdown 파일을 .cursor/rules/ 디렉토리 내에 준비한다. 예를 들어, B_Rules.mdc 파일을 생성했다고 가정하겠다.

단계 2: code-review.md 파일 수정

code-review.md 파일을 열고 아래 두 영역을 수정한다.

1. Instructions > Initial Analysis 섹션 수정

AI에게 어떤 규칙을 읽고 이해해야 하는지 알려주는 지침 부분이다.

 

수정 전:

### 1. Initial Analysis
...
3. **Read Rules:** Load and understand the A_Rules from `.cursor/rules/commons/A_Rules.mdc`
...

수정 후 (예시):

### 1. Initial Analysis
...
3. **Read Rules:** Load and understand the B_Rules from `.cursor/rules/commons/B_Rules.mdc`
...

 

2. Context Files 섹션 수정

AI가 리뷰 시 실제로 참조할 컨텍스트 파일을 지정하는 부분이다.

 

수정 전:

## Context Files
- @.cursor/rules/commons/A_Rules.mdc

수정 후 (예시):

## Context Files
- @.cursor/rules/commons/B_Rules.mdc

위와 같이 두 부분의 파일 경로만 새로운 룰 파일로 변경하면, 다음 실행부터 /code-review 커맨드는 완전히 새로운 기준에 따라 코드 리뷰를 수행하게 된다.

---

5. 활용 시나리오

시나리오 1: 새로운 기능 브랜치 표준 리뷰

• 목표: 머지 전 코드 품질을 종합적으로 검토
• 입력: targetPath: /src/app/(logged-in)/new-feature, depth: standard, focusArea: all

시나리오 2: 레거시 코드 가독성 개선

• 목표: 오래된 코드의 가독성을 집중적으로 분석하고 리팩토링 포인트를 도출
• 입력: targetPath: /src/modules/legacy, depth: deep, focusArea: readability

시나리오 3: 프로젝트 구조 검토

• 목표: 파일과 모듈이 응집도 높게 구성되었는지 빠른 확인
• 입력: targetPath: /src/domains, depth: shallow, focusArea: cohesion

---

6. 리뷰 결과 해석 및 후속 조치

AI는 분석 후 우선순위에 따라 정리된 보고서를 제공한다.

6.1. 이슈 우선순위

심볼	우선순위	설명	권장 조치
🔴	High	버그 유발 가능성, 심각한 성능 저하, 보안 문제	즉시 수정 필요
🟠	Medium	유지보수성 저하, 잠재적 버그, 비효율적인 구조	다음 스프린트 내 수정 권장
🟢	Low	코드 스타일, 네이밍 등 가독성 향상을 위한 제안	선택적으로 개선

6.2. 상세 이슈 포맷

각 이슈는 아래와 같은 형식으로 제공되어 문제점과 해결 방안을 명확히 파악할 수 있다.

---

 

* Current State

 // 현재 문제가 되는 코드 스니펫

 

* Issue

• 문제점에 대한 명확한 설명
• 위반된 Rule
• 코드베이스에 미치는 영향

* Improvement Suggestion

// 개선된 코드 예시

 

* Priority: 🔴/🟠/🟢

---

7. 첨부 파일 (Appendix)

7.1. 코드 리뷰 커맨드 정의서: .cursor/commands/code-review.md

/code-review 커맨드의 실제 정의 파일이다. 이 파일은 AI가 코드 리뷰를 수행하는 방식, 파라미터, 분석 기준, 결과 포맷 등 모든 지침을 담고 있다.
(toss-frontend-rules.mdc과 꽤 높은 결합도를 가지고있는 커맨드이다. 수정 필요 시 커스텀 커맨드의 일부 항목을 직접 수정해야 한다.

code-review.md

0.01MB

7.2. 코드 리뷰 실행 결과 예시: example.md

/code-review 커맨드를 입력하였던 경로에 대해 실행했을 때 생성된 실제 코드 리뷰 보고서 예시다.

example.md

2.8 kB