작성일: 2026-05-26

목적: 「Cursor 공식 베스트 프랙티스(Best Practices) 완전 준수」라고 할 수 있는 수준에 도달하기 위한, Rules / Skills / AGENTS.md / MCP / 검증 / 재고 조사를 포함한 실무 템플릿.

주의: Cursor사의 공식 템플릿이 아님. 공식 문서의 현행 사양에 따라, 실무에서 파탄 나지 않도록 재설계한 것.

많은 프롬프트는, 입문용 자동 생성 프롬프트로서는 유용합니다.

하지만, 다음과 같은 이유로 「Cursor사의 공식 템플릿 완전 준수」라고 단정 지을 수는 없습니다.

.mdc

만을 전제로 하고 있어, .md / .mdc / AGENTS.md / Skills의 구분 사용이 약함. -
alwaysApply / description / globs의 적용 조건 설계가 부족함. - skills.md 일원화는 장기 운용 시 지견 로그(Knowledge Log)·규칙·설계 판단이 섞이기 쉬움. - 규칙의 증식, 중복, 진부화, 경합을 막는 재고 조사(Inventory) 플로우가 없음. -
생성 후에 「정말로 효과가 있는가」를 검증하는 테스트 절차가 없음. -
보안, 비밀 정보, 생성물, 외부 도구 연동, 승인 경계의 설계가 미흡함.

이 100점판에서는, Rules는 상시·조건부 행동 제어, Skills는 재사용 가능한 작업 절차, AGENTS.md는 경량 프로젝트 설명, MCP는 외부 데이터·도구 연결로 분리합니다.

Rules는, AI 에이전트(Agent)에게 매번 지키게 하고 싶은 행동 원칙·설계 규약·프로젝트 고유의 판단 기준입니다.

넣어도 좋은 것:

• 프로젝트 고유의 아키텍처(Architecture) 방침
• 기존 코드의 읽는 법
• 변경 전에 확인해야 할 파일
• 디렉터리별 책임
• 테스트 방침
• 생성물·의존 관계·비밀 정보를 건드리지 않는 규칙
• 반복적으로 발생하는 AI의 실수에 대한 대책

넣지 않는 것이 좋은 것:

• 너무 일반적인 코딩 관습
• linter / formatter / CI에서 기계적으로 담보할 수 있는 내용
• 장대한 설계서의 통째 복사
• 한 번만 사용하는 절차
• 드문 예외 조건의 나열
• 구현 커맨드(Command) 목록의 백과사전화

Skills는, Agent에게 「이 작업은 이렇게 진행한다」라고 가르치는 **재사용 가능한 워크플로우(Workflow)**입니다.

넣어야 할 것:

• ADR 작성
• 장애 조사
• 리팩터링(Refactoring) 계획
• DB 변경 리뷰
• Pull Request 셀프 리뷰
• 문서 업데이트
• 요구사항으로부터 설계서를 작성하는 작업
• 기존 코드로부터 사양을 역산하는 작업
• 스크립트나 템플릿을 동반하는 반복 작업

Rules에 작업 절차를 너무 많이 채워 넣으면, Agent의 상시 컨텍스트(Context)가 무거워집니다.

빈번하게 지켜야 할 판단 기준은 Rules, 필요할 때 호출하는 절차는 Skills로 나눕니다.

AGENTS.md는, Project Rules보다 경량화된 프로젝트 설명입니다.

적합한 내용:

• 프로젝트의 목적
• 최우선 디렉터리
• 실행·테스트·빌드(Build)의 대표 커맨드
• 팀 내에서의 기본 방침
• 신규 참여자를 위한 짧은 설명

복잡한 적용 조건이 필요한 경우에는, AGENTS.md가 아니라 .cursor/rules/*.mdc로 나눕니다.

MCP는, Cursor에 외부 도구나 외부 데이터를 연결하기 위한 메커니즘입니다. Rules나 Skills에 Jira, Notion, GitHub, Redmine, Google Drive, DB 등의 정보를 장문으로 복사하는 것은 악수(Bad practice)입니다.

MCP에 적합한 대상:

• Jira / Redmine / GitHub Issue
• Notion / Google Drive / 사내 문서
• DB 스키마(Schema) 참조
• 브라우저·Figma·모니터링 도구
• 사내 API

단, MCP는 외부 도구나 로컬 커맨드를 실행할 수 있기 때문에, 비밀 정보·권한·승인 플로우의 설계가 필수적입니다.

project-root/
├─ AGENTS.md
├─ .cursor/
...

Cursor Rules는 alwaysApply, /, description, /, globs의 조합에 따라 읽어오는 방식이 달라집니다.

100점판에서는 다음 기준으로 분류합니다.

적용 대상:

• 보안
• 비밀 정보 취급
• 변경 전의 확인 자세
• 생성물·vendor·의존 관계를 부주의하게 편집하지 않는 방침
• 불분명한 점이 있을 경우 관련 파일을 읽는 방침

예시:

---
alwaysApply: true
---

적용 대상:

• 아키텍처 판단
• 설계 리뷰
• ADR 작성
• 대규모 리팩터링 (Refactoring)
• 구현 방침 상담

예시:

---
description: "백엔드의 서비스 계층, 도메인 계층, API 경계를 변경할 때의 설계 판단 규칙"
alwaysApply: false
...

적용 대상:

• React / Vue / C# / SQL / Python / Terraform 등, 파일 유형에 강하게 의존하는 규약
• 테스트 파일
• DB 마이그레이션 (Migration)
• 문서

예시:

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

적용 대상:

• 가끔 사용하는 감사
• 대규모 정리
• 릴리스 전 체크
• 이행 계획

예시:

---
alwaysApply: false
---

채팅에서 @90-rule-maintenance와 같이 명시하여 호출합니다.

이하 내용을 setup-cursor-rules-100.md로 저장하고, Cursor Agent에게 @setup-cursor-rules-100.md 를 실행해줘라고 요청합니다.

setup-cursor-rules-100.md

당신은 시니어 아키텍트 (Senior Architect), Cursor Rules Engineer, AI 개발 운영 설계자입니다.
이 리포지토리를 분석하여, Cursor Agent가 안전하고 고정밀도로 개발 지원을 할 수 있도록 Rules / Skills / AGENTS.md / 운영 로그의 구성을 생성 및 업데이트하십시오.
...

AGENTS.md
.cursor/rules/00-core.mdc
.cursor/rules/10-architecture.mdc
.cursor/rules/20-frontend.mdc
.cursor/rules/21-backend.mdc
.cursor/rules/22-database.mdc
.cursor/rules/30-testing.mdc
.cursor/rules/40-documentation.mdc
.cursor/rules/50-security-and-secrets.mdc
.cursor/rules/90-rule-maintenance.mdc
.cursor/skills/capture-learning/SKILL.md
.cursor/skills/create-adr/SKILL.md
.cursor/skills/audit-rules/SKILL.md
.cursor/skills/pr-self-review/SKILL.md
docs/ai/learnings/.gitkeep
docs/ai/rule-audits/.gitkeep
docs/adr/.gitkeep

단, 프로젝트에 존재하지 않는 영역의 Rules는 억지로 만들지 마십시오. 예를 들어 프론트엔드가 존재하지 않는다면 20-frontend.mdc는 생성할 필요가 없습니다.

3. Rules 작성 기준

3.1 00-core.mdc

...

---
alwaysApply: true
---

3.2 10-architecture.mdc

• description을 사용하는 Apply Intelligently 방식으로 설정하십시오.
• 레이어링 (Layering), 의존 방향 (Dependency Direction), 도메인 경계 (Domain Boundary), 기존 설계 읽는 법을 기술하십시오.
  ...

---
description: "설계 변경, 레이어링, 책임 분할, 의존 방향, 아키텍처 판단에 관한 규칙"
alwaysApply: false
---

3.3 파일 유형별 Rules

파일 유형이 명확한 Rules는 globs를 사용하십시오.
예:

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

Rules 본문에는 대상 파일에서 준수해야 할 프로젝트 고유 규칙만을 작성하십시오.

3.4 90-rule-maintenance.mdc

• 원칙적으로 alwaysApply: false인 수동 호출 방식으로 설정하십시오.
  ...

---
name: capture-learning
description: "복잡한 버그 해결, 설계 판단, 새로운 라이브러리 도입, 반복적으로 발생하는 AI의 실수로부터 재사용 가능한 지식을 정리한다"
---

4.2 create-adr

목적:

• 중요한 설계 판단을 docs/adr/ADR-YYYYMMDD-title.md에 기록한다.
  ...

AGENTS.md

Project Overview

이 프로젝트는 <프로젝트의 목적을 1~3문장으로 기술>한다.
...

alwaysApply: true

...

description: "설계 변경, 책임 분할, 의존 방향, 아키텍처 판단, 리팩터링 (Refactoring) 계획에 관한 규칙"
alwaysApply: false
...

alwaysApply: true

...

name: capture-learning
description: "복잡한 버그 해결, 설계 판단, 신규 라이브러리 도입, 반복적으로 발생하는 AI의 실수로부터 재사용 가능한 지식을 정리한다"
...

---
name: audit-rules
description: "Cursor Rules, Skills, AGENTS.md, AI 지견(知見) 로그를 전수 조사하여 중복, 모순, 노후화, 과잉 적용을 정리한다"
...

---

- `alwaysApply: true`가 너무 많지 않다. - 보안 관련 사항 외에 상시 적용(alwaysApply)을 너무 남발하지 않는다.
- 파일 유형 Rules에는 `globs`가 있다. - Apply Intelligently 방식의 Rules에는 명확한 `description`이 있다. - 수동 호출(manual) Rules는 상시 로드할 필요가 없는 내용으로 구성되어 있다.
- 각 Rule은 500행 미만이다.
- 방대한 설계서를 그대로 복사해 넣지 않았다.
- 기존 코드와 모순되지 않는다.
- linter / formatter로 보장할 수 있는 내용을 Rules에 너무 많이 적지 않았다.
- 부정형뿐만 아니라, 바람직한 행동이 명시되어 있다.

- 각 Skill은 `.cursor/skills/<name>/SKILL.md`에 있다. - `name`은 부모 폴더명과 일치한다. - `description`이 구체적이며, 사용하는 타이밍을 알 수 있다. - 상시 읽게 할 필요가 없는 작업 절차는 Skills로 분리되어 있다.
- 커맨드처럼 사용하는 Skill에는 `disable-model-invocation: true` 설정을 검토한다. - 스크립트를 포함하는 경우, 권한·부작용(side effect)·에러 발생 시의 처리 방식이 명시되어 있다.

- `docs/ai/learnings/`에 일시적인 지견(learnings)을 쌓아두는 장소가 있다. - `docs/adr/`에 설계 판단(Architecture Decision Records)을 남기는 장소가 있다. - 월 단위 또는 특정 시점마다 Rules를 정리(audit)하는 절차가 있다.
- 규칙 업데이트 전에 인간의 리뷰를 거친다.
- MCP나 외부 도구 연결 권한을 최소화한다.
- 비밀 정보를 Rules / Skills / AGENTS.md에 작성하지 않는다.

| 관점 | 원문 기사의 약점 | 100점판의 개선 |
|---|---|---|
| `.mdc` 전제 | `.mdc`에 고정된 형태에 가까움 | `.md` / `.mdc` / AGENTS.md / Skills를 구분하여 사용 |
| 적용 조건 | `globs` 중심 | `alwaysApply` / `description` / `globs` / manual을 명확화 |
| Skills | `skills.md` 하나로 통합 | `.cursor/skills/<name>/SKILL.md`로 분리 |
| 지견 축적 | `skills.md`에 축적 | learnings → audit → Rules/Skills/ADR 승격 |
| 승인 | Accept 전제가 모호함 | 변경 전 계획 제시, 승인 후 편집을 명시 |
| 정리 (Audit) | 취약함 | `audit-rules` Skill을 표준화 |
| 보안 | 제외 대상 중심 | 비밀 정보, MCP, 외부 부작용까지 명시 |
| 검증 | 없음 | 적용 시뮬레이션과 체크리스트를 추가 |
| 장기 운용 | 규칙이 늘어나는 것을 전제로 함 | 분할·통합·폐지·이관을 포함 |

이 템플릿을 사용한다고 해서 생성된 Rules가 자동으로 100점이 되는 것은 아닙니다.

100점에 가깝게 만들기 위해서는 생성 후 다음 항목으로 채점합니다.

| 평가 축 | 배점 | 확인 포인트 |
|---|---|---|
| 공식 사양과의 정합성 | 20 | Rules / Skills / AGENTS.md의 형식과 역할이 올바른가 |
| ... | |

합격선은 80점입니다.

팀 표준으로 삼으려면 90점 이상이어야 합니다.

"완전 준수"라고 정의할 경우, 공식 사양과의 차이점, 대상 버전, 검증 결과, 한계를 명시하는 것이 중요합니다.

- Cursor Rules: https://cursor.com/docs/rules.md
- Cursor Agent Skills: https://cursor.com/docs/skills.md
- Cursor MCP: https://cursor.com/docs/mcp.md