좋은 .cursorrules 파일에는 실제로 무엇이 들어있을까? 10개를 직접 만들어보며 배운 점들

description: 대부분의 .cursorrules 파일은 도움이 되기에는 너무 모호하거나, 유용하기에는 너무 경직되어 있습니다. 10개의 서로 다른 스택(stack)을 위해 규칙을 만든 후, 실제로 효과가 있었던 것들을 정리했습니다.
tags: cursor,ai,webdev,productivity

저는 다른 사람들의 .cursorrules 파일을 읽는 데 많은 시간을 보냈습니다. 어떤 것들은 환상적이지만, 대부분은 그렇지 않습니다.

작성자가 노력을 기울이지 않아서가 아닙니다. '좋은 지침처럼 느껴지는 것'과 '실제로 Cursor의 동작을 변화시키는 것' 사이에 간극이 있기 때문입니다. 서로 다른 스택을 위해 10개의 규칙 파일을 처음부터 직접 만들어본 후, 제가 배운 점들을 공유하고자 합니다.

.cursorrules 파일이란 무엇이며, 왜 중요한가?

아직 사용해 본 적이 없다면: .cursorrules 파일은 프로젝트 루트(root)에 위치하며 Cursor에 일련의 지속적인 지침을 제공합니다. AI가 코드를 생성할 때마다 이 규칙들을 컨텍스트(context)로 사용합니다.

이를 브리핑 문서라고 생각하세요. 매 프롬프트마다 "TypeScript 엄격 모드(strict mode)를 사용해줘", "기본 내보내기(default exports)를 사용하지 마", "일반 CSS가 아니라 Tailwind를 사용해"와 같이 선호 사항을 다시 설명하는 대신, 한 번만 작성해 두면 자동으로 적용됩니다.

잘 만들어진 파일은 Cursor가 첫 번째 제안부터 사용자의 프로젝트에 딱 맞는 코드를 생성하게 해줍니다. 잘못 만들어진 파일은 아무런 역할도 못 하거나 오히려 방해가 됩니다.

나쁜 규칙의 예시

자주 등장하는 규칙의 실제 예시는 다음과 같습니다:

항상 깨끗하고, 읽기 쉬우며, 유지보수 가능한 코드를 작성하세요.
최선의 관행(best practices)을 따르세요.
의미 있는 변수 이름을 사용하세요.

이것은 쓸모가 없습니다. 틀린 말은 아니지만, 단지 쓸모가 없을 뿐입니다. "깨끗한 코드를 작성하라"는 지침이 아닙니다. Cursor는 이미 깨끗한 코드를 작성하려고 노력하고 있습니다. 당신은 Cursor가 이미 알고 있는 것 외에 아무것도 말해주지 않았습니다.

조금 더 낫지만 여전히 약한 버전은 다음과 같습니다:

TypeScript를 사용하세요.
복잡한 함수에는 주석을 추가하세요.
콜백(callback)보다 async/await를 선호하세요.

이것들은 실제 선호 사항이지만, 여전히 너무 일반적입니다. 모든 현대적인 TypeScript 프로젝트는 async/await를 사용합니다. 여기에 이를 언급하는 것은 아무런 신호(signal)를 더해주지 못합니다.

두 예시 모두의 문제는 그것들이 _스택에 무관(stack-agnostic)_하다는 점입니다. 이 규칙들은 어떤 프로젝트에도 동일하게 적용될 것이므로, Cursor가 당신의 프로젝트를 이해하는 데 실제로 도움을 주지 못합니다.

좋은 규칙의 모습

좋은 규칙은 스택에 특화되어 있고 프로젝트의 컨벤션(conventions)에 특화되어 있습니다. 다음은 Next.js 프로젝트의 전/후 비교입니다:

취약한 규칙:

Next.js의 베스트 프랙티스(best practices)를 따르세요.
컴포넌트를 적절하게 구조화하세요.
에러를 적절하게 처리하세요.

강력한 규칙:

이 프로젝트는 App Router를 사용하는 Next.js 14를 사용합니다. /app 디렉토리의 모든 컴포넌트는 기본적으로 서버 컴포넌트(Server Components)입니다.
컴포넌트에 상호작용(이벤트 핸들러, useState, useEffect)이 필요한 경우에만 'use client'를 추가하세요.
getServerSideProps나 getStaticProps를 사용하지 마세요. 이는 Pages Router 패턴입니다.
...

차이점을 주목하세요. 두 번째 버전은 Cursor가 그렇지 않으면 알 수 없는 정보, 즉 이것이 Pages Router가 아닌 App Router라는 점과 해당 환경의 규칙이 무엇인지를 알려줍니다. 또한 흔히 발생하는 실수인 Pages Router의 데이터 페칭(data-fetching) 패턴을 명시적으로 지적합니다. 왜냐하면 그것이 바로 AI 모델들이 App Router 프로젝트에서 자주 틀리는 부분이기 때문입니다.

이번에는 FastAPI를 위한 또 다른 예시입니다:

취약한 규칙:

FastAPI 컨벤션(conventions)을 따르세요.
검증을 위해 Pydantic을 사용하세요.

강력한 규칙:

이 프로젝트는 Pydantic v2를 사용하는 FastAPI를 사용합니다. model_validator와 field_validator를 사용하세요 (Pydantic v1 방식인 @validator는 사용하지 마세요).
응답 모델(Response models)은 class Config가 아닌 model_config = ConfigDict(from_attributes=True)를 사용합니다.
모든 데이터베이스 액세스는 SQLAlchemy 비동기 세션(async sessions)을 통해 이루어집니다. 동기 세션 패턴을 절대 사용하지 마세요.
...

취약한 버전은 Cursor가 절반 정도의 확률로 Pydantic v1 문법을 기본값으로 사용하게 만들 것입니다. 왜냐하면 그것이 모델의 학습 데이터에서 가장 흔하기 때문입니다. 강력한 버전은

1. 도구뿐만 아니라 버전을 명시하세요

"React를 사용하세요"도 괜찮습니다. 하지만 "적절한 경우 동시성 기능(concurrent features)을 포함한 React 18을 사용하세요"가 더 좋습니다. 버전의 구체성은 매우 중요합니다. 왜냐하면 AI 모델은 매우 다양한 버전 패턴을 학습했으며, 현재 최신 버전이 아닐 수도 있는 가장 흔한 패턴을 기본값으로 선택할 것이기 때문입니다.

2. 무엇을 해야 하는지뿐만 아니라 무엇을 피해야 하는지도 설명하세요

"Y를 사용하세요"라고 말하는 것보다 "X를 사용하지 마세요"라고 말하는 것이 더 유용할 때가 많습니다. Cursor가 잘못된 경로가 어떤 모습인지 알게 되면, 사용자가 직접 찾아내어 수정해야 하는 '그럴듯하지만 틀린(plausible-but-wrong)' 코드를 생성하는 것을 방지할 수 있습니다. 예를 들어, Go 프로젝트의 경우 "상태 관리를 위해 전역 변수를 사용하지 말고 의존성 주입(dependency injection)을 사용하세요"라고 지정하면, 소규모 규모에서는 작동하지만 운영 환경(production)에서는 문제를 일으키는 흔한 패턴을 잡아낼 수 있습니다.

3. 프로젝트 구조를 기술하세요

프로젝트가 모노레포(monorepo), 특정 폴더 레이아웃, 도메인(domain)과 인프라스트럭처(infrastructure) 계층의 분리 등 명확하지 않은 구조를 가지고 있다면 이를 규칙에 포함시키세요. Cursor는 파일 트리(file tree)를 컨텍스트로 사용하지만, _무엇이 어디에 왜 있는지_에 대한 짧은 설명은 새로운 코드를 어디에 배치할지에 대해 더 나은 결정을 내리는 데 도움이 됩니다.

규칙 파일에서 피해야 할 사항

집중력을 유지하세요. 500줄에 달하는 .cursorrules 파일은 문제입니다. 중요한 지침이 노이즈와 섞여 희석되기 때문입니다. 모든 것이 강조되면, 아무것도 강조되지 않는 것과 같습니다.

단순히 철학적인 지침은 피하세요: "코드를 작성하기 전에 신중하게 생각하세요." "예외 케이스(edge cases)를 고려하세요." 이러한 지침은 동작을 변화시키지 않습니다.

그리고 모순을 피하세요. 만약 "항상 JSDoc 주석을 추가하세요"라고 말하면서 동시에 "코드를 간결하게 유지하세요"라고 한다면, 이 두 목표가 충돌하기 때문에 일관성 없는 결과를 얻게 될 것입니다.

보상

규칙 파일이 제 역할을 수행할 때, 여러분은 (좋은 의미로) 그 파일의 존재를 의식하지 않게 됩니다. Cursor는 그저 딱 맞는 코드를 생성할 뿐입니다. 똑같은 실수를 반복해서 수정할 필요가 없습니다. 매 세션마다 여러분의 컨벤션(convention)을 다시 설명할 필요도 없습니다. 제안되는 코드들이 여러분이 실제로 작성할 코드와 일치하게 됩니다.

그러한 복리 효과 (compounding effect)는 실제로 존재합니다. 하루의 코딩 과정에서는 아마 몇 번의 좌절을 피하고 몇 분을 절약하는 정도일 것입니다. 하지만 한 달이 지나면 그것은 의미 있는 차이를 만들어냅니다.

Next.js, React, FastAPI, Django, Node.js, Go, Vue 3, Svelte, React Native, 그리고 Full-Stack SaaS까지 10가지의 서로 다른 스택 (stack)을 대상으로 이 과정을 거친 후, 처음부터 구축하는 대신 시작점으로 삼을 수 있도록 결과물인 규칙 파일들을 하나의 팩 (pack)으로 묶었습니다. 각 파일은 단순히 일반적인 조언이 아니라, 여기서 설명한 각 스택별 컨벤션 (convention)과 주의사항 (gotchas)을 반영하고 있습니다.

해당 팩은 여기에서 찾을 수 있습니다: Stackdrop Cursor Rules Pack

여러분의 .cursorrules 파일에서 실제로 차이를 만든다고 느낀 규칙은 무엇인가요? 다른 분들은 무엇을 알아냈는지 궁금합니다. 특히 제가 다루지 않은 스택에 대해서라면 더욱 그렇습니다. 여러분의 최고의 규칙들을 댓글로 남겨주세요.