커서 룰(Cursor Rule), 팀 문서 퀄리티 자동으로 챙기는 꿀팁

최근 회사에서 커서를 구매해줘서 써봤는데, 인생이 달라졌습니다.. 지금까진 뗀석기로 개발한 기분인데요 

 

아무튼 cursor를 쓰면서, 내가 원하는 스크립트를 미리 입력하는 방법을 찾고 있었는데

"rule" 이라는 방법을 찾아서 간단히 공유하고, 제가 실제로 어떻게 쓰는지 몇가지 케이스를 공유해볼려고 합니다.

 

Cursor AI IDE의 룰(Rule), 이렇게 활용합니다

 

Cursor AI IDE의 룰(Rule)은 개발자가 원하는 코딩 원칙과 팀 규칙을 AI에게 전달하는 일종의 “가이드라인 문서”입니다.

보통 코드 스타일이나 문법 규칙은 ESLint, Prettier 같은 도구가 처리합니다. 하지만 Cursor 룰은 그보다 상위 개념으로, AI가 코드를 생성하는 순간부터 개발자 또는 팀의 철학과 컨벤션을 반영할 수 있게 해주는 것이 특징입니다.

즉, 룰을 정의해두면 AI는 단순히 문법적으로 맞는 코드를 제안하는 것이 아니라,

 

• 팀의 아키텍처 구조를 지키고,
• 특정 라이브러리 사용을 강제하거나 금지하며,
• 에러 처리 방식이나 테스트 작성 원칙까지 고려한 코드

를 처음부터 작성해줍니다. 이로써 코드 리뷰에서 반복되는 지적을 줄이고, 개발자가 진짜 중요한 로직과 설계에 집중할 수 있도록 도와줍니다.

 

Cursor 룰은 어떻게 구성되어 있을까?

Cursor IDE에서 룰은 보통 프로젝트 루트에 .cursor/rules/ 폴더 형태로 관리됩니다. 이 안에 마크다운(.mdc) 파일을 작성해 규칙을 기술하게 되며, 각 파일은 하나의 주제를 담당할 수 있습니다.

예를 들어:

• architecture.mdc → 폴더 간 의존성 규칙
• performance.mdc → 성능 관련 제안
• security.mdc → 보안 체크리스트
• testing.mdc → 테스트 작성 가이드

이처럼 여러 개의 룰 파일을 만들어두면, Cursor가 코드 생성 시 해당 규칙들을 참고해 반영합니다.

 

룰 파일은 기본적으로 Markdown(.mdc) 문서지만, 맨 위에는 아래와 같은 frontmatter 블록을 가집니다.

---
description: 대시보드 UI 접근성 가이드
globs: ["app/(dashboard)/**", "**/*.tsx"]
alwaysApply: false
---
# 규칙
- 데이터 테이블에는 캡션/헤더 스코프를 명시합니다.
- 대용량 리스트는 가상화 시 aria-rowcount/aria-rowindex 검토.

 

이 영역이 바로 룰의 동작 방식과 적용 범위를 제어하는 옵션입니다.

 

.mdc 파일 상단의 --- 구간(프런트매터)으로 적용 범위와 방식을 제어합니다.

• description: 룰의 요약/설명(Agent가 룰을 선택·요약할 때 사용)
• globs: 이 패턴에 매칭되는 파일이 대화/작업에 등장할 때 자동 첨부
  • 예) ["app/(dashboard)/**", "**/*.tsx", "!**/*.test.ts"]
• alwaysApply: true면 항상 컨텍스트에 포함
  이 3개가 룰 동작의 핵심입니다. (Cursor UI의 “Rule Type” 드롭다운도 내부적으로 이 속성 조합을 바꿔줍니다.)

 

어떻게 활용할 수 있을까?

 

1. 팀 컨벤션 문서화
   기존에는 Notion이나 Wiki에만 적어두던 “팀 규칙”을 Cursor 룰로 옮겨 AI에게 직접 인식시킬 수 있습니다.
2. 예: “새 페이지는 반드시 app/(dashboard)/ 구조를 따를 것”,
   “데이터 패칭에는 TanStack Query를 활용할 것”
3. AI 코드 생성 품질 향상
   단순한 함수 작성 요청에도 AI가 미리 정의한 룰을 참고해 구조적이고 일관성 있는 코드를 제안합니다.
4. 예: “API 호출 시 반드시 Result<T, E> 타입으로 감싸고, 실패 시 로깅 + 사용자 메시지 제공”
   
   
5. 리뷰 비용 절감
   코드 리뷰 단계에서 발생하는 반복적인 스타일 및 규칙 지적이 줄어들어, 리뷰어는 아키텍처 적합성이나 로직 검증에 집중할 수 있습니다.
   
   
6. 지속적인 팀 학습 도구
   신입 개발자나 새로운 팀원이 투입될 경우, 룰에 의해 생성되는 코드만 보더라도 팀이 어떤 방식을 선호하는지 자연스럽게 익힐 수 있습니다.

 

실제로 어떻게 활용하고 있는지?

 

1. PR 리뷰

---
description: "실무형 PR 템플릿"
alwaysApply: false
---

# 📑 실무형 PR 템플릿

## 목적

- PR 문서를 일관된 구조와 충분한 근거로 작성한다.
- 변경 이유(Why) → 설계(How) → 검증(Proof) 흐름을 따른다.
- 문서는 **마크다운** 형식으로 작성한다.

---

## 🟢 필수 섹션

### Description

- 변경 범위를 한 줄로 요약한다.
- 핵심 키워드를 포함한다.

### 배경

- 기존 동작의 한계나 문제점을 설명한다.
- 개선이 필요한 이유를 명확히 기술한다.

### 주요 변경사항

- 개선된 동작 방식을 요약한다.
- 데이터 구조, 처리 방식, 정책 등 변경된 규칙을 나열한다.

### 테스트

- 주요 시나리오 목록을 항목으로 나열한다.
- 실행 방법을 간단히 명시한다.
- 현재 테스트 결과를 요약한다.

### 성능 분석 (필수)

- **시간복잡도**와 **공간복잡도**를 명시한다.
- 계산 결과가 `O(n^2)` 이상일 경우, **주의가 필요하다는 경고 문구**를 반드시 포함한다.
  - 예: `이 PR은 최악의 경우 O(n^2) 복잡도를 가질 수 있으므로, 대규모 데이터 환경에서는 성능 저하에 유의해야 함.`

---

## 🟡 선택 섹션 (대규모/구조 변경 PR 시 작성)

### 타입/구조 변경

- 변경 전/후 구조를 항목으로 정리한다.
- 호환성 영향과 범위를 명확히 기술한다.

### 동작 규칙

- 포함/제외 조건을 단계별로 기술한다.
- 결과 반영 조건과 불변성 원칙을 기록한다.

### 구현 파일

- 변경된 파일 경로를 나열한다.
- 각 파일의 역할과 변경 이유를 요약한다.

### 검증 방법

- 테스트 통과 확인 절차를 적는다.
- 샘플 데이터나 실제 UI 확인 절차를 체크리스트로 작성한다.

### 변경 파일 요약

- 파일별 변경 의도를 불릿 형태로 정리한다.

---

## 작성 규칙 (Do/Don’t)

- **Do**

  - 필수 섹션은 항상 작성한다.
  - 선택 섹션은 변경 규모·영향에 따라 추가한다.
  - 구조 변경은 호환성 영향까지 반드시 기록한다.
  - 불변성 원칙은 필요 시 명시한다.
  - 시간·공간복잡도는 항상 기록하고, `O(n^2)` 이상일 경우 반드시 경고 문구를 추가한다.

- **Don’t**
  - 근거 없는 성능 수치를 기재하지 않는다.
  - 불필요하게 긴 코드 조각을 문서에 직접 삽입하지 않는다(파일 경로나 링크로 대체).

---

## 리뷰어 체크리스트

- [ ] 필수 섹션이 모두 포함되었는가?
- [ ] 변경 이유와 개선 방법이 명확하게 연결되는가?
- [ ] 구조 변경 시 영향 범위가 기술되었는가?
- [ ] 테스트 시나리오가 주요 변경사항을 커버하는가?
- [ ] 시간/공간복잡도가 기록되었는가?
- [ ] 복잡도가 `O(n^2)` 이상일 경우, 경고 문구가 포함되었는가?
- [ ] 성능 및 추후 과제가 현실적으로 기술되었는가?

 

AI가 가장 강력한 부분이죠. 분석엔 강력하지만 상대적으로 창조엔 약합니다. 가장 만족스러운 부분인데

cursor는 문서화에 큰 강점이 있습니다.

 

기획 문서 내용과 "지금까지 작업한 내용을 main 브랜치와 지금 브랜치의 차이를 기반으로 분석해서 PR 문서를 마크다운으로 만들어줘" 라고 위 룰과 함께 명령을 내리면,  작업 컨택스트가 없는 리뷰어도 손쉽게 맥락 파악이 가능해집니다.

 

그리고 리뷰어 혹은 개발자가 성능 병목사항을 일일히 짚어내기 어려운데, 시간복잡도 공간복잡도 측면에서 코드를 분석해주니 

코드 품질도 높일 수 있고 주니어/신입 개발자에게는 어떻게 개발해야하는지 피드백을 AI한테 받아서 개발이 가능해집니다. 

 

2. Test 코드 작성

---
description: Documentation and testing guidelines, available on demand
alwaysApply: false
---

## Documentation

- After defining any function, method, or component:
  - Write a JSDoc comment explaining its purpose, parameters, and return value.
  - Keep it concise but informative.

## Testing

- Test code with various inputs, including edge cases.
- use **vitest** for testing, not jest
- Include both positive and negative scenarios.
- Use a clear "as is → when → to be/should" structure:
  - `describe('<Unit>')`
    - `describe('as is: <current state>')`
      - `describe('when <condition>')`
        - `it('to be: <expected>, should <assertions>')`
- Avoid testing implementation details — focus on public behavior.

 

AI가 가장 강력한 부분 2죠.

잘개 쪼개져서 격리된 모듈과 순수함수로 코드를 구현하고, 작은 context 토큰 범위와 기획 문서를 제공한다면 비교적 정확한 테스트케이스를 뽑아낼 수 있습니다.

 

3. 컨벤션 강제 

 

---
description: Always apply modularization and abstraction principles for maintainable frontend architecture
alwaysApply: true
---

## Core Principles

### 1. Side Effect Isolation

- Treat code that depends on environment (time, network, browser API) as **side effects**.
- Isolate side effects into separate modules or inject them as parameters.
- In tests, mock side-effect modules to avoid flaky results.
- Keep core functions as pure as possible.

### 2. Component Layer Separation

- Split each component into the following logical layers:
  1. **UI (Render)** – Pure presentational JSX, no business logic.
  2. **State** – State management hooks, selectors, store.
  3. **Domain Logic** – Business rules and computations.
  4. **Network (API)** – Data fetching/mutations, isolated into API modules.
- Ensure that these layers communicate via explicit interfaces.

### 3. Strategy Pattern & Dependency Injection

- For business policies or algorithms that may change (e.g., payment calculation, discount rules):
  - Define them as strategy interfaces.
  - Implement strategies separately.
  - Inject the strategy into components/hooks instead of hardcoding.
- Components should depend only on the interface, not concrete implementations.

### 4. Domain Policy Ownership

- Avoid embedding business policy data directly in frontend code.
- Fetch policies from backend whenever possible.
- Frontend focuses on **how** to display/use the data, backend controls **what** policy applies.

 

기존 코드들이 규칙대로 잘 짜여졌다면 더욱 강력해집니다.

코드를 짤때, 팀이 원하는 스타일 및 컨밴션으로 코드를 구현하도록 권장합니다. 

AI가 마구잡이로 코드를 짜는걸 방지해주죠

 

 

마무리

 

정리하자면, Cursor 룰은 “AI에게 우리 팀의 개발 문화를 주입하는 장치"라고 볼 수 있습니다.
단순한 스타일 교정이 아니라, 아키텍처, 성능, 보안, 접근성, 테스트 등 다양한 영역의 원칙을 미리 정의해두고 이를 코드 생성 단계에 반영할 수 있다는 점이 큰 장점입니다.

덕분에 개발팀은 규칙을 반복적으로 확인하거나 리뷰에서 같은 지적을 주고받을 필요가 줄어들고, 진짜 중요한 설계와 문제 해결에 집중할 수 있습니다.

 

개인적으론 문서화가 제일 마음에 드네요. 코드 리뷰 전 코드 품질을 높이기 위한 하나의 셀프 피드백 단계를 추가한 느낌입니다.

그리고 클로드 코드도 대단하다는데 거기까진 못써봤네요

다만 오픈소스에서 클로드코드로 나온 결과물 코드를 몇개 봤는데 장난 아닌듯 싶습니다..