Cursor Rules 작성법: AI 코딩 도구에 팀 개발 규칙 적용하기

AI 코딩 도구를 팀에서 쓰기 시작하면 처음에는 생산성이 눈에 띄게 좋아지는 것처럼 느껴진다. 하지만 시간이 지나면 팀 규칙과 다른 코드 스타일, 테스트 누락, 디렉터리 구조 오해, 쓰지 않는 라이브러리 추천 같은 문제가 반복될 수 있다. 매번 채팅으로 팀의 방식을 설명하는 방식은 오래 유지하기 어렵고, 새로운 팀원이 합류할 때마다 같은 설명을 반복해야 한다.

Cursor Rules는 이런 반복 설명을 줄이기 위한 장치다. 프로젝트 안에 규칙을 문서로 남겨두면 AI가 코드베이스를 다룰 때 팀의 기본 원칙을 참고할 수 있다. 다만 규칙 파일을 길게 쓰기만 한다고 좋은 결과가 나오는 것은 아니다. AI가 실제 작업 중 읽고 따를 수 있는 형태로 짧고 구체적으로 작성해야 효과가 있다.

규칙은 팀의 반복 판단을 압축한 문서다

일반 개발 문서와 다른 목적

Cursor Rules는 일반 개발 문서와 목적이 조금 다르다. 사람에게 배경을 길게 설명하기보다, AI가 코드 작성이나 수정 중 즉시 참고할 수 있는 행동 기준을 제공하는 데 초점을 둔다. 예를 들어 컴포넌트는 작게 작성한다는 식의 원칙보다, 공유 UI는 특정 폴더에 두고 도메인 전용 컴포넌트는 해당 기능 폴더에 둔다는 식의 구체적인 지시가 더 도움이 된다. 좋은 규칙은 모호한 취향을 줄이고 반복되는 판단을 고정한다. 파일 위치, 네이밍, 테스트 명령, 금지된 패턴, 리뷰 기준처럼 매번 설명하기 귀찮은 항목이 우선순위가 된다.

너무 긴 규칙은 잘 지켜지지 않는다

규칙 파일에 모든 것을 넣고 싶어지지만, 길이가 늘어나면 정작 중요한 내용이 묻힌다. AI가 참고해야 할 핵심은 작업과 직접 연결되는 규칙이다. 회사 철학이나 긴 아키텍처 설명은 별도 문서로 두고, Cursor Rules에는 실제 수정 시 필요한 압축된 기준만 남기는 편이 좋다. 규칙이 많아질수록 서로 충돌할 가능성도 커진다. 예를 들어 항상 새 테스트를 추가하라는 규칙과 작은 변경에는 테스트를 생략해도 된다는 규칙이 함께 있으면 모델은 어느 쪽을 따라야 할지 애매해한다. 예외 조건까지 짧게 적어두는 것이 좋다.

예시는 규칙보다 강하게 작동한다

AI는 추상적인 문장보다 구체적인 예시를 더 잘 따르는 경향이 있다. 에러 처리는 일관되게 한다는 문장보다, 올바른 예시와 피해야 할 예시를 한두 개 보여주는 편이 효과적이다. 다만 예시가 너무 길면 오히려 그대로 복사되는 대상이 되어버릴 수 있으므로 최소한으로 유지하는 편이 안전하다.

실제 팁: 규칙 파일 작성 순서

프로젝트 구조부터 적기

가장 먼저 AI가 헷갈리기 쉬운 폴더 역할을 정리한다. 라우팅을 담당하는 폴더, 도메인 로직을 담는 폴더, 공통 유틸을 모아둔 폴더처럼 역할을 명시적으로 적어둔다. 파일을 새로 만들 때 어디에 둬야 하는지 알려주는 규칙은 실제 작업 품질에 바로 영향을 준다.

금지 패턴을 명확히 쓰기

팀에서 쓰지 않는 라이브러리, 직접 호출하면 안 되는 API, 더 이상 쓰지 않는 컴포넌트가 있다면 금지 항목으로 적는다. 가능하면 피한다는 표현보다 새 코드에서는 사용하지 않는다처럼 행동을 분명히 지시하는 편이 좋고, 필요하다면 대체할 패턴도 함께 적어둔다.

테스트와 검증 명령을 적기

AI가 변경 후 어떤 명령을 실행해야 하는지 모르면 검증 단계가 통째로 빠지기 쉽다. 자주 쓰는 테스트 명령이나 린트 명령을 적어두고, 전체 테스트가 오래 걸린다면 작은 변경에서 우선 실행할 범위도 함께 알려준다.

규칙을 작업 유형별로 나누기

프론트엔드 UI 수정, API 로직 수정, 데이터 마이그레이션처럼 작업 유형마다 중요한 기준이 다르다. 한 파일 안에서 짧은 섹션으로 나누면 AI가 필요한 부분을 빠르게 찾을 수 있다. 모든 작업에 같은 규칙을 강제하기보다 작업 유형별로 우선순위를 두는 편이 현실적이다.

주의사항

규칙 파일에 비밀 정보나 내부 토큰을 넣으면 안 된다. AI 도구가 참고하는 문서라는 점을 고려하면, 공개되어도 문제가 없는 개발 규칙만 담는 편이 안전하다. 민감한 배포 절차나 계정 정보는 별도 보안 문서와 권한 관리 체계로 다뤄야 한다.

또 하나의 문제는 규칙이 오래되어 실제 코드와 맞지 않는 경우다. 코드 구조가 바뀌었는데 규칙 파일이 예전 구조를 그대로 설명하면, AI는 낡은 방향으로 코드를 계속 만들어낼 수 있다. 큰 리팩터링이나 폴더 구조 변경 후에는 규칙 파일도 함께 점검하는 습관이 필요하다.

정리

Cursor Rules는 AI에게 팀의 개발 습관을 매번 다시 설명하지 않기 위한 실용적인 문서다. 핵심은 길이가 아니라 정확성이다. 파일 위치, 금지 패턴, 테스트 명령, 작업 유형별 기준처럼 실제 수정에 필요한 내용을 짧게 쓰고, 코드 구조가 바뀔 때 함께 업데이트하면 팀 전체의 AI 활용 품질을 안정적으로 유지할 수 있다.