1. 규칙이 없을 때 생기는 스타일 혼란

AI 코딩 도구를 처음 쓸 때는 “잘 만들어주는지”에 집중하게 됩니다. 그런데 프로젝트가 조금만 커지면 다른 문제가 먼저 나타납니다. 같은 기능을 고치는데 어떤 파일에서는 함수형으로 작성하고, 다른 파일에서는 클래스형으로 작성합니다. 한 화면에서는 `fetch`를 직접 쓰고, 다른 화면에서는 별도 API 유틸을 만듭니다. 파일명도 `UserList.tsx`, `user-list.tsx`, `users.tsx`처럼 섞이기 시작합니다.

사람 개발자에게도 팀 규칙이 필요하듯, AI에게도 프로젝트 규칙이 필요합니다. 규칙이 없으면 AI는 현재 대화에서 보이는 코드 일부와 일반적인 관습을 바탕으로 판단합니다. 그 결과 “작동은 하지만 우리 프로젝트답지 않은 코드”가 만들어질 수 있습니다.

특히 바이브 코딩에서는 사용자가 매번 모든 구조를 설명하기 어렵습니다. 매 요청마다 “우리는 TypeScript를 쓰고, 컴포넌트는 이렇게 나누고, API 호출은 이 파일을 거치고, 스타일은 Tailwind로만 작성하고…”라고 반복하면 작업 속도도 느려지고 누락도 생깁니다. 이 반복 설명을 프로젝트 안에 규칙으로 남겨두는 방식이 Cursor Rules의 핵심입니다.

예를 들어 같은 버튼을 추가하더라도 규칙이 없으면 AI는 다음처럼 제각각 구현할 수 있습니다.

<button style={{ backgroundColor: "blue", color: "white" }}>
  저장
</button>

이미 프로젝트에 공통 버튼 컴포넌트가 있다면, 원하는 결과는 보통 이런 형태에 가깝습니다.

<Button variant="primary">
  저장
</Button>

차이는 작아 보이지만, 이런 선택이 누적되면 유지보수 난이도가 크게 달라집니다.

2. Cursor Rules란 무엇인가

Cursor Rules는 Cursor가 AI에게 코드를 작성하거나 수정하게 할 때 참고하도록 넣어두는 프로젝트 규칙입니다. 쉽게 말해 “이 프로젝트에서는 이런 방식으로 작업하라”는 지침서입니다.

Cursor에는 사용자 단위 규칙과 프로젝트 단위 규칙이 있습니다. 사용자 단위 규칙은 개인 환경 전체에 적용되는 성향에 가깝고, 프로젝트 단위 규칙은 특정 저장소 안에서만 적용되는 팀 규칙에 가깝습니다. 입문 단계에서 특히 중요한 것은 프로젝트 단위 규칙입니다. 프로젝트마다 기술 스택, 폴더 구조, 네이밍, 테스트 방식이 다르기 때문입니다.

Cursor의 프로젝트 규칙은 일반적으로 프로젝트 루트의 `.cursor/rules` 폴더에 작성하는 방식으로 알려져 있습니다. 규칙 파일은 `.mdc` 형식을 사용합니다. 예전에는 `.cursorrules` 파일을 사용하는 방식도 널리 쓰였지만, 현재는 `.cursor/rules` 기반의 Project Rules 방식이 주로 안내되는 흐름으로 알려져 있습니다.

기본 구조는 다음과 같습니다.

my-project/
  .cursor/
    rules/
      project-style.mdc
      api-rules.mdc
      ui-rules.mdc
  src/
  package.json

`.mdc` 파일에는 설명, 적용 범위, 항상 적용 여부 같은 메타정보와 실제 규칙 본문을 함께 적을 수 있습니다. Cursor의 세부 UI나 옵션 명칭은 버전에 따라 조금씩 달라질 수 있으므로, 실제 사용 시에는 Cursor 설정 화면의 Rules 관련 메뉴도 함께 확인하는 것이 좋습니다.

3. 프로젝트 규칙에 담을 내용

규칙은 많을수록 좋은 것이 아닙니다. AI가 작업할 때 실제로 판단에 도움이 되는 내용을 짧고 명확하게 적는 편이 좋습니다. 너무 긴 규칙은 오히려 중요한 내용이 묻히고, 서로 충돌하는 문장이 생길 수 있습니다.

먼저 담아야 할 내용은 기술 스택입니다. React인지 Next.js인지, JavaScript인지 TypeScript인지, 스타일링은 Tailwind CSS인지 CSS Modules인지, 상태 관리는 무엇을 쓰는지 적어야 합니다. AI는 프로젝트 파일을 보고 어느 정도 추론할 수 있지만, 규칙으로 명시하면 일관성이 좋아집니다.

다음은 폴더 구조와 책임 분리입니다. 예를 들어 `components`에는 재사용 UI만 두고, 페이지 전용 로직은 `app` 또는 `pages` 아래에 둔다는 식입니다. API 호출은 컴포넌트 안에서 직접 하지 않고 `lib/api` 또는 `services`를 통해 처리한다는 규칙도 자주 쓰입니다.

네이밍 규칙도 중요합니다. 컴포넌트 파일명은 PascalCase로 할지, 라우트 파일은 kebab-case로 할지, 커스텀 훅은 `use`로 시작하게 할지 등을 정합니다. 작은 규칙처럼 보이지만 AI가 새 파일을 만들 때 큰 영향을 줍니다.

검수와 안전 관련 규칙도 포함할 수 있습니다. 예를 들어 기존 공개 API를 함부로 바꾸지 말 것, 타입 오류를 무시하지 말 것, 임시 데이터를 실제 로직처럼 남기지 말 것, 환경변수 이름을 임의로 만들지 말 것 같은 내용입니다.

프로젝트 규칙에 자주 들어가는 항목은 다음과 같습니다.

- 사용 기술 스택
- 폴더 구조와 파일 위치 기준
- 컴포넌트 작성 방식
- API 호출 방식
- 상태 관리 방식
- 스타일링 규칙
- 네이밍 규칙
- 타입 작성 기준
- 에러 처리 방식
- 테스트 또는 검증 기준
- 금지 사항

이 중에서 모든 항목을 처음부터 채울 필요는 없습니다. 현재 프로젝트에서 자주 흔들리는 부분부터 규칙으로 만드는 편이 실용적입니다.

4. 좋은 규칙 작성 예시

좋은 규칙은 “추상적인 선호”보다 “구체적인 행동 기준”에 가깝습니다. “깔끔하게 작성해줘”는 규칙으로서 약합니다. 반면 “새 API 호출 함수는 `src/lib/api`에 작성하고, 컴포넌트에서 `fetch`를 직접 호출하지 않는다”는 AI가 바로 적용할 수 있습니다.

아래는 React와 TypeScript 기반 프로젝트에서 사용할 수 있는 예시입니다. 실제 프로젝트에 그대로 복사하기보다는 폴더명과 도구명을 현재 프로젝트에 맞게 바꾸는 것이 좋습니다.

---
description: General project coding rules
globs: ["**/*"]
alwaysApply: true
---

- Use TypeScript for all new source files.
- Do not use `any` unless there is a clear reason. Prefer explicit types or inferred types.
- Keep components small and focused on one responsibility.
- Reuse existing components before creating new ones.
- Do not change public function names or exported interfaces without checking related usages.
- Do not introduce a new library unless it is already listed in `package.json` or explicitly requested.
- Follow the existing folder structure instead of creating new top-level folders.

UI 관련 규칙은 별도 파일로 분리할 수 있습니다. 이렇게 나누면 규칙을 관리하기 쉽고, 특정 파일 범위에만 적용하기도 편합니다.

---
description: UI component rules
globs: ["src/components/**/*", "src/app/**/*"]
alwaysApply: false
---

- Use existing shared components from `src/components` when possible.
- Do not write inline styles unless there is a specific exception.
- Keep display logic in components, but move reusable business logic into hooks or utilities.
- Component names should use PascalCase.
- Custom hooks should start with `use`.

API 규칙도 프로젝트 품질에 큰 영향을 줍니다.

---
description: API and data fetching rules
globs: ["src/**/*"]
alwaysApply: false
---

- Do not call external APIs directly inside UI components.
- Place reusable API functions in `src/lib/api` or the existing API utility folder.
- Handle loading and error states when adding data fetching logic.
- Do not hard-code secrets, tokens, or private URLs in source files.
- Use environment variables for configurable values.

여기서 중요한 점은 규칙이 실제 프로젝트 구조와 맞아야 한다는 것입니다. 예를 들어 프로젝트에 `src/lib/api` 폴더가 없는데 “반드시 `src/lib/api`를 사용하라”고 적으면 AI가 폴더를 새로 만들거나 기존 구조와 다른 방향으로 작업할 수 있습니다. 기존 프로젝트를 다루는 경우에는 6강에서 다룬 것처럼 먼저 구조를 파악한 뒤 규칙을 작성하는 흐름이 안전합니다.

규칙 문장은 짧게 쓰는 편이 좋습니다. 한 문장 안에 조건이 너무 많으면 AI가 일부만 반영할 수 있습니다.

나쁜 예시는 다음과 같습니다.

코드는 최대한 깔끔하고 좋은 구조로 작성하고, 상황에 따라 적절히 판단해서 기존 코드도 참고하고, 필요하면 파일도 나누고, 성능도 고려해서 만들어줘.

좋은 예시는 이렇습니다.

- Before creating a new component, search for an existing reusable component.
- Put reusable formatting functions in `src/lib`.
- Keep page components responsible for routing and layout only.
- Do not mix API fetching logic with presentational components.

짧고 명확한 규칙일수록 AI가 안정적으로 따르기 쉽습니다.

5. 규칙 유지·업데이트

규칙은 한 번 작성하고 끝나는 문서가 아닙니다. 프로젝트가 바뀌면 규칙도 같이 바뀌어야 합니다. 처음에는 Tailwind CSS를 쓰다가 디자인 시스템 컴포넌트를 도입할 수도 있고, API 호출 위치가 `services`에서 `lib/api`로 바뀔 수도 있습니다. 규칙이 오래된 상태로 남아 있으면 AI는 최신 코드보다 낡은 문서를 따르려고 할 수 있습니다.

작업 중 AI가 반복해서 같은 실수를 한다면, 그때가 규칙을 추가할 시점입니다. 예를 들어 매번 컴포넌트 안에 API 호출을 직접 작성한다면 “컴포넌트에서 직접 fetch를 호출하지 않는다”는 규칙을 넣습니다. 새 라이브러리를 자꾸 설치하려 한다면 “명시 요청 없이 새 라이브러리를 추가하지 않는다”는 규칙을 넣습니다.

다만 실수 하나마다 규칙을 무조건 늘리면 규칙 파일이 금방 복잡해집니다. 반복되는 문제인지, 프로젝트 전체에 적용할 만한 기준인지 확인한 뒤 추가하는 편이 좋습니다.

규칙을 관리할 때는 다음 흐름이 실용적입니다.

1. AI가 반복해서 어긋나는 부분을 기록한다.
2. 기존 규칙으로 해결 가능한지 확인한다.
3. 해결이 어렵다면 짧은 규칙을 추가한다.
4. 이후 작업에서 실제로 잘 지켜지는지 확인한다.
5. 프로젝트 구조가 바뀌면 관련 규칙도 함께 수정한다.

팀 프로젝트라면 규칙 변경도 코드 변경처럼 다루는 것이 좋습니다. `.cursor/rules` 폴더를 Git에 포함하면 팀원들이 같은 기준으로 AI를 사용할 수 있습니다. 혼자 작업하는 바이브 코딩 프로젝트에서도 Git에 포함해두면 나중에 환경을 옮기거나 프로젝트를 다시 열었을 때 같은 규칙을 유지할 수 있습니다.

커밋 대상에 포함되는 구조는 보통 다음과 같습니다.

.cursor/
  rules/
    project-style.mdc
    ui-rules.mdc
    api-rules.mdc

반대로 개인 취향에 가까운 규칙은 프로젝트 규칙보다 사용자 규칙에 두는 편이 낫습니다. 예를 들어 “답변은 한국어로 받기”, “설명은 짧게 받기” 같은 선호는 프로젝트 품질 기준이라기보다 개인 작업 방식에 가깝습니다. 프로젝트 규칙에는 팀원이나 미래의 자신이 봐도 납득할 수 있는 기준을 남기는 것이 좋습니다.

Cursor Rules의 목적은 AI를 더 강하게 통제하는 데 있지 않습니다. 매번 반복해서 설명하던 기준을 프로젝트 안에 저장해두고, AI가 그 맥락 위에서 코드를 작성하게 만드는 데 있습니다. 바이브 코딩에서 속도만큼 중요한 것이 일관성입니다. 규칙을 잘 만들어두면 AI가 빠르게 작업하면서도 프로젝트의 스타일, 구조, 금지사항을 놓치지 않게 됩니다.