Cursor rules 설정 가이드: 적용 범위부터 TypeScript 예제까지

기대할 수 있는 효과는 코드 리뷰에서 정리할 일이 줄어드는 것입니다. 시간을 가정해 계산해 보겠습니다. 개발자 네 명이 매주 세 번씩, 한 번에 5분을 같은 문제를 고치는 데 쓴다면 이미 정한 규약을 반복해서 맞추는 데 60분이 듭니다. 그만큼 절약된다고 보장하는 수치는 아닙니다. 설정 후 어떤 수정 작업이 사라졌는지 세고, 규칙을 유지보수하는 데 든 시간을 빼야 합니다. 구독 비용은 별개이며, Cursor 요금 안내에서 다룹니다.

Cursor rules는 어디에 작성해야 할까요?

팀이 공유하는 코딩 규약은 코드와 함께 두고, 개인적인 답변 취향은 개인 설정으로 관리합니다.

하위 디렉터리의 AGENTS.md 지침은 상위 지침과 함께 해당 디렉터리 및 그 아래에 적용되며, 더 구체적인 지침이 우선합니다. Team Rules, Project Rules, User Rules가 충돌할 때의 우선순위는 공식 문서에 Team → Project → User로 명시되어 있습니다. Cursor 규칙 공식 문서

저는 소규모 팀이라면 프로젝트 규칙을 기본으로 사용합니다. “기존 폼 컴포넌트를 사용한다”는 저장소에 둘 지침입니다. “최종 답변은 짧게 한다”는 개인 취향입니다. 둘을 구분해야 개인의 선호가 뜻하지 않게 팀 전체의 정책이 되는 일을 막을 수 있습니다.

각 규칙을 언제 불러올지 정합니다

규칙 본문 위에 있는 짧은 설정 블록인 프런트매터가 규칙을 컨텍스트에 불러오는 조건을 결정합니다.

에이전트가 판단해 적용한다는 것은 규칙의 설명을 보고 에이전트가 해당 규칙을 선택한다는 뜻입니다. glob은 파일 경로 패턴을 말합니다. 규칙을 불러오는 방식과 문법

작업 지시서를 알맞은 작업대에 전달한다고 생각하면 이해하기 쉽습니다. 아무리 잘 쓴 지침이라도 필요한 작업에 전달되지 않으면 소용이 없습니다. 기본 보안 규칙은 항상 적용하고, 스타일 지침은 관련 파일에만 적용합니다. 작업에 따라 관련성이 달라지는 지침은 에이전트가 판단해 선택하도록 둡니다.

TypeScript 웹 앱에 바로 쓸 수 있는 규칙 세 가지

저장소에 다음 파일을 만듭니다. Cursor 공식 문서의 프런트매터 필드와 패턴 문법을 사용한 팀 내부 규약 예시입니다. 파일 안의 지침은 상황에 맞게 바꿔 쓸 출발점이며, Cursor가 정한 코딩 표준은 아닙니다.

스타일 규칙: TypeScript 파일에 적용합니다

.cursor/rules/style.mdc로 저장합니다.

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

- Follow the nearest existing module's naming and import conventions.
- Prefer named exports unless the framework requires a default export.
- Reuse existing UI components and utilities before adding alternatives.
- Keep formatting in the repository's formatter and linter configuration.

이 예시는 애플리케이션 코드가 src/ 아래에 있다고 가정합니다. 저장소 구조에 맞게 경로를 조정합니다. 규칙은 포매터가 결정할 수 없는 선택에 초점을 맞췄습니다. 앱에 이미 적절한 버튼이나 날짜 처리 헬퍼가 있는지가 그런 선택입니다. 팀에서 다른 방식을 정했다면 export 방식에 대한 지침도 바꿉니다. 규칙은 저장소의 실제 방식을 설명해야 하며, 은근히 설계를 바꾸는 수단이 되어서는 안 됩니다.

테스트 규칙: 어떤 작업에 필요한지 설명합니다

.cursor/rules/tests.mdc로 저장합니다.

---
description: Testing requirements when adding features, fixing bugs, or changing TypeScript behavior
alwaysApply: false
---

- Cover changed behavior with a focused regression test.
- Use the existing test runner, fixtures, and file naming conventions.
- Read package.json for the relevant test script; do not invent a command.
- Report the command and actual result, or explain why tests were not run.

목표는 쓸모 있는 테스트와 사실에 맞는 결과 보고입니다. 버그를 수정했다면 원래의 오류를 테스트로 검증했다는 근거가 남아야 합니다. 리팩터링했다면 관련 동작이 유지되어야 합니다. 어느 쪽이든 테스트 프레임워크를 하나 더 도입할 필요는 없으며, “테스트를 작성했다”와 “테스트를 통과했다”를 혼동한 보고도 필요하지 않습니다.

이 체크리스트를 명시적으로 적용할 작업에는 요청에 @tests를 넣습니다. 팀에서 모든 작업에 적용하려면 적용 방식을 Always Apply로 바꿉니다. 이는 의식적으로 결정할 정책입니다. 설명만 작성해 두면 규칙의 선택은 에이전트에 맡기게 됩니다.

보안 규칙: 기본 원칙은 짧게 유지합니다

.cursor/rules/security.mdc로 저장합니다.

---
alwaysApply: true
---

- Never put secrets in source code, test fixtures, or application logs.
- Use existing server-side authentication and authorization helpers.
- Validate untrusted input at server boundaries with the existing schemas.
- Do not remove permission checks to make a feature or test pass.

저장소에서 사용하는 모듈 경로를 알고 있다면 “기존 헬퍼”라는 표현을 실제 경로로 바꿉니다. 평범한 기능 개발 중에도 바로 이해할 수 있을 만큼 기본 원칙을 명확하게 유지합니다. “안전하게 만든다”는 말만으로는 리뷰어가 확인할 것이 많지 않습니다. “권한 검사를 유지한다”는 확인 가능한 요구사항을 제시합니다.

이 파일은 지침이며, 보안을 강제하는 경계는 아닙니다. 접근 권한 검사는 계속 코드로 강제하고, 민감한 변경 사항은 리뷰해야 합니다. Cursor 역시 AI 지침을 유일한 보안 통제 수단으로 삼지 말라고 주의를 줍니다. Team Rules 안내

실제 코드 변경으로 설정을 확인합니다

이전에 같은 수정 요청을 반복하게 만들었던 작은 작업을 골라 봅니다. 폼 유효성 검사 변경이 좋은 예입니다. 컴포넌트를 수정하고, 동작을 바꾸며, 사용자 입력도 다루기 때문입니다.

1. 기대하는 결과를 적습니다. 재사용할 기존 컴포넌트, 테스트할 동작, 유지해야 할 입력 검증 경계를 구체적으로 정합니다.
2. 세 파일을 저장하고 상태를 확인합니다. Cursor의 Customize → Rules에서 규칙을 볼 수 있으며, Agent에서는 /create-rule도 사용할 수 있습니다. 규칙 만들기
3. 관련 파일을 컨텍스트에 넣고 변경을 요청합니다. 평소와 같은 수준으로 요청합니다. 요청에 모든 규칙을 다시 적으면 설정 자체가 도움이 되었는지 알 수 없습니다.
4. diff와 보고된 검증 결과를 리뷰합니다. 규칙을 지켰다는 말 대신 실제 코드에 규약이 반영되었는지 확인합니다. 이번 확인에서 테스트 체크리스트가 중요하다면 @tests를 명시적으로 요청합니다.
5. 유용한 규칙을 코드 변경과 함께 커밋합니다. 팀이 리뷰할 수 있는 출발점을 만듭니다. 파일을 더 추가하기 전에 모호한 문장부터 고칩니다.

규약이 지켜지지 않았다면 두 경우를 구분합니다. 규칙이 해당 작업에 전달되지 않았거나, 전달되었지만 지침이 효과를 내지 못한 경우입니다. 전자는 적용 조건을 고쳐야 합니다. 후자는 지침을 더 명확하게 쓰거나, 예제를 넣거나, 자동 검사를 마련해야 합니다.

어떤 규약을 남길 가치가 있을까요?

반복되는 실수 중 팀에 가장 큰 비용을 만드는 것부터 시작합니다. 다음은 줄일 수 있는 리뷰 부담을 기준으로 우선순위를 매긴 활용 사례입니다.

이 표를 보고 파일 다섯 개를 더 만들어야 한다고 받아들일 필요는 없습니다. 아직 겪지 않은 문제는 넣지 않습니다. 기계가 요구사항을 정확하게 검사할 수 있다면 그 검사를 우선합니다. 유용한 규칙은 작업 요청과 저장소의 기존 툴 사이에 남은 빈틈을 메웁니다.

예전 .cursorrules 파일은 어떻게 해야 할까요?

현재 문서에 안내된 프로젝트 설정에는 .cursor/rules/*.mdc를 사용합니다. 2026년 10월 11일 기준, 규칙 문서에는 .cursorrules가 언급되어 있지 않으므로 기존 파일이 여전히 작동하는지는 해당 문서로 확인할 수 없습니다. 현재 공식 문서

저장소에 예전 파일이 남아 있다면 유용한 지침을 목적별 프로젝트 규칙으로 옮기는 것을 권합니다. 위의 세 파일을 출발점으로 삼을 수 있습니다. 각 규칙의 적용 조건을 정하고 실제 작업으로 확인한 뒤 기존 파일을 제거합니다. 이미 적혀 있다는 이유만으로 낡은 규약까지 유지할 필요는 없습니다.

CLAUDE.md, AGENTS.md와는 어떤 관계일까요?

공통된 개념은 프로젝트에서 계속 참고할 지침을 두는 것입니다. Claude Code에는 CLAUDE.md가 있고, Codex는 AGENTS.md의 작업 규약을 읽습니다. Cursor의 일반 Markdown 방식도 이런 단순한 용도에 맞으며, .mdc 파일을 사용하면 규칙을 불러오는 조건까지 선택할 수 있습니다. 기본 규약은 일관되게 유지하되, 각 툴이 지침을 읽는 방식은 의식적으로 설정해야 합니다. 문장을 복사하는 것과 설정을 복사하는 것은 다릅니다. 여러 에이전트를 쓰는 팀이라면 공통 규약의 담당자를 한 명 정해 파일마다 서로 다른 기준이 생기지 않게 합니다.

설정을 마친 뒤 만들어 볼 만한 작은 툴 두 가지

엔지니어링 리드에게는 저장소 규칙 검사기가 더 유망한 기회입니다. 파일 확장자와 지원되는 프런트매터 필드를 확인하고, 버전 관리 중인 어떤 파일과도 일치하지 않는 패턴을 찾아내는 툴입니다. 최소한의 유용한 형태는 리뷰 중 로컬에서 실행하는 보고서입니다. 수요 신호는 크지 않습니다. 이 글을 위한 조사에서 DataForSEO는 “cursor rules examples”의 월간 추정 검색량을 140건으로 반환했습니다. 관련 주제에 관심이 있다는 뜻이지, 사람들이 돈을 낼 것이라는 근거는 아닙니다. 한계도 분명합니다. 구조가 올바른 규칙이라도 지침의 내용은 부실할 수 있습니다. 지표 정의

팀 규약 검토 자료를 만드는 툴은 여러 저장소를 관리하는 리드에게 도움이 될 수 있습니다. 반복되는 리뷰 의견과 승인된 예제를 규칙 변경 제안 diff로 정리하고, 변경마다 리뷰어를 지정합니다. DataForSEO가 반환한 “cursor team rules”의 월간 추정 검색량은 70건입니다. 내부 유틸리티로 시작하는 편이 좋습니다. 기본 제공되는 Team Rules가 이미 배포를 처리하므로, 규칙을 저장하는 대시보드를 하나 더 만드는 것만으로는 제품 경쟁력이 약합니다. 가치 있는 작업은 무엇을 상시 지침으로 남길지 판단하는 데 있습니다. 지표 정의

설정할 때 자주 묻는 질문

다음 주에는 반복되는 수정 작업 하나를 골라 해당 규칙을 명확하게 다듬고, 다음번 평소와 같은 풀 리퀘스트에서 시험합니다. 제품 선택까지 검토하고 있다면 Cursor 리뷰나 추천 Cursor 대안을 참고합니다.

이 방식을 팀의 개발 워크플로에 연결하는 작업은 AI 프로덕션 시스템 구축에서 다룹니다.