Cursor .cursor/agents와 rules는 역할을 어떻게 나누나?

Cursor에서 .cursor/agents/ 와 .cursor/rules/ 는 둘 다 에이전트 행동을 바꾸지만, 계층이 다릅니다. Rules는 적용되면 모델 컨텍스트 앞에 실리는 지속 지침이고, Agents(커스텀 서브에이전트) 는 부모 Agent가 위임하면 자체 컨텍스트 창에서 일하는 전문 자식입니다. Skills(다단계 절차 패키지) 비교(cursor-skills-vs-rules)와 각도를 분리해, 이 글은 agents에 넣을 것 · rules에 넣을 것 · 겹치면 무엇이 깨지나만 다룹니다.

요금·플랜·토큰 한도·제휴·창작 후기는 없습니다. 근거는 Cursor 공식 Subagents·Rules의 동작·경로·적용 방식뿐입니다.

agents에 넣을 것은?

한 줄 답: 역할이 분명한 전문 작업을 넣습니다. 긴 탐색·독립 검증·병렬 워크스트림처럼 컨텍스트 격리가 필요할 때 .cursor/agents/*.md(또는 사용자 ~/.cursor/agents/)에 YAML 프론트매터 + 본문 프롬프트로 둡니다.

넣을 것	이유(문서 동작)
verifier·debugger·security-auditor 같은 단일 책임 역할	서브에이전트는 자체 컨텍스트에서 일하고 최종 메시지만 부모에게 반환
위임 신호가 되는 `description`	Agent가 Task 힌트·설명을 보고 자동 위임 여부를 판단. `/name`·자연어로도 명시 호출
`readonly`·`model`·`is_background`	쓰기 제한, 부모와 다른 모델, 백그라운드(부모 비차단) 등 실행 모드
팀 공유 역할 정의	프로젝트 `.cursor/agents/`는 VCS로 공유. 이름 충돌 시 프로젝트 > 사용자, 동일 프로젝트에선 `.cursor/` > `.claude/`/`.codex/`

문서상 커스텀 서브에이전트 필드(요약):

필드	기본	역할
`name`	파일명	표시·식별(소문자·하이픈)
`description`	—	위임 판단용 짧은 설명
`model`	`inherit`	부모와 동일, 또는 특정 모델 ID
`readonly`	`false`	`true`면 편집·상태 변경 셸 제한
`is_background`	`false`	`true`면 부모를 막지 않음

최소 예(검증 전용):

---
name: verifier
description: Validates completed work. Use after tasks are marked done.
model: inherit
readonly: true
---

You are a skeptical validator. Verify claimed work actually works.
Run relevant checks. Report passed vs incomplete.

넣지 말 것(agents 쪽): “항상 모든 채팅에 실릴 짧은 코딩 규범”만 agents에 두면, 위임되지 않는 한 부모 세션에는 안 실립니다. 한 방이면 끝나는 단순 절차는 문서도 Skills 쪽을 권합니다(이 글은 Skills 본편이 아님). 모호한 “helps with coding” description은 위임 신호가 되지 않습니다.

repo/
  .cursor/
    agents/
      verifier.md      ← 전문 자식 (격리 컨텍스트)
      debugger.md
    rules/
      api-conventions.mdc  ← 지속 지침 (적용 시 컨텍스트에 주입)

rules에 넣을 것은?

한 줄 답: 짧고 반복되는 제약·규범·아키텍처 결정을 넣습니다. 프로젝트 규칙은 .cursor/rules/*.mdc이고, 적용되면 프롬프트 레벨에 포함되어 코드 생성·편집 해석에 일관된 안내를 줍니다. plain .md만 rules 폴더에 두면 무시됩니다(프론트매터 없음). 단순 대안은 루트·하위 AGENTS.md(메타데이터 없는 마크다운)입니다 — 이는 .cursor/agents/와 다른 것입니다.

규칙 타입	동작
Always Apply (`alwaysApply: true`)	매 채팅에 포함. globs·description 무시
Apply to Specific Files (`globs`)	매칭 파일이 컨텍스트에 있을 때 자동 첨부
Apply Intelligently (`description`)	Agent가 관련성으로 끌어옴
Apply Manually	`@rule`로만 포함

문서의 frontmatter 조합:

`alwaysApply`	`description`	`globs`	동작
`true`	—	—	항상 포함
`false`	—	있음	매칭 파일 시 자동 첨부
`false`	있음	없음	관련 시 Agent가 포함
`false`	없음	없음	`@` 수동만

실무로 rules에 둘 예:

생성물 디렉터리(dist/·build/) 수정 금지, 시크릿 하드코드 금지 — 짧게 alwaysApply: true.
src/components/**/*.tsx 네이밍·export 규칙 — globs + alwaysApply: false.
백엔드 RPC 컨벤션처럼 가끔 관련 — description만(Intelligent).
일회성 긴 체크리스트 — Rule이 아니라 Skill·명시 @ 파일·필요 시 agents 쪽으로 분리(Skills 본편과 겹치지 않게 “길면 Rule이 아님”만 기억).

최소 glob Rule 예:

---
description: API route validation and typed errors
globs: src/routes/api/**/*.ts
alwaysApply: false
---

- Validate inputs at the route boundary.
- Return the existing typed error shape.
- Update the nearest unit test before claiming done.

문서 권장: 500줄 미만·초점 유지, 모호한 가이드 지양, 스타일 가이드 통째 복사 대신 린터·정규 예제 @ 참조. User Rules는 Customize → Rules의 전역 선호(응답 스타일 등)이고 Agent(Chat)에 쓰이며 Inline Edit(Cmd/Ctrl+K)에는 적용되지 않습니다. Team Rules는 대시보드로 관리되며, 충돌 시 문서상 우선순위는 Team → Project → User입니다.

겹치면 무엇이 깨지나?

한 줄 답: 같은 문장을 “항상 주입되는 Rule”과 “위임될 때만 사는 Agent 프롬프트”에 동시에 두면, 적용 시점·컨텍스트가 어긋나 놓침·중복·상충이 납니다.

겹침 패턴	깨지는 것
긴 다단계 절차를 `alwaysApply` Rule에 통째로	매 채팅 컨텍스트가 비대해짐. 문서는 초점·길이·예시를 권함. 절차성 작업은 agents/skills 축으로 분리
레포 전역 규범을 agents에만 두고 Rule에 없음	서브에이전트가 위임되지 않으면 부모 세션에 규범이 안 실림. “항상 지키게”가 실패
동일 금지 조항을 Rule과 agent 본문에 다른 문구로 복제	부모는 Rule을 보고, 자식은 깨끗한 컨텍스트 + 부모이 넘긴 프롬프트 + 자기 본문만 봄. 버전이 갈라지면 한쪽만 갱신되어 상충
Intelligent Rule `description`과 agent `description`이 둘 다 모호	잘못된 시점 포함·잘못된 위임. 둘 다 “언제” 신호가 약함
`AGENTS.md`와 `.cursor/agents/`를 같은 폴더로 착각	`AGENTS.md`는 Rules의 단순 대안(지침 마크다운). `.cursor/agents/`는 서브에이전트 정의. 경로·역할이 다름
agents를 “설정만 하면 항상 켜짐”으로 기대	커스텀 서브에이전트는 자동 위임·`/name`·자연어 요청으로 기동. Rules의 Always Apply와 다름

안전한 분리 체크리스트:

매 세션에 짧게 실려야 하면 → .cursor/rules (또는 단순하면 AGENTS.md).
격리된 전문 작업·검증·병렬이면 → .cursor/agents/.
한 규범을 자식에도 강제하려면 Rule만 믿지 말고, 위임 프롬프트에 요약을 넘기거나 readonly verifier처럼 검증 역할을 agents에 둡니다. 서브에이전트는 이전 대화 이력을 기본으로 공유하지 않습니다.
Skills 비교(cursor-skills-vs-rules)와 섞지 마십시오. 규범=Rules, 전문 자식=Agents, 다단계 절차 패키지=Skills.

팁: 커스텀 서브에이전트 “어디에 정의하나”(cursor-custom-subagents)는 파일 위치·위임 시점 본편입니다. 이 글은 Rules와의 책임 경계만 고정합니다.

자주 묻는 질문

Q. .cursor/agents와 AGENTS.md는 같나요?
아닙니다. AGENTS.md는 Project Rules의 단순 마크다운 대안이고, .cursor/agents/*.md는 커스텀 서브에이전트 정의입니다.

Q. Rule을 서브에이전트에도 자동으로 전부 물려주나요?
문서는 서브에이전트가 깨끗한 컨텍스트로 시작하며, 부모가 필요한 정보를 프롬프트에 넣는다고 설명합니다. “항상 주입”은 Rules 축의 이야기입니다. 자식에도 같은 제약이 필요하면 위임 시 요약하거나, 검증용 agent 본문에 명시하십시오.

Q. Skills랑 뭐가 다른가요?
Skills는 다단계 절차 패키지 축입니다. 이 글은 agents(격리된 전문 자식) vs rules(지속 지침) 만 다룹니다. Skills 선택 기준은 cursor-skills-vs-rules를 보세요.

무엇을 기억하면 되나?

Cursor agents rules 경계는 한 문장입니다. 지속·짧게 실릴 규범은 .cursor/rules(·AGENTS.md), 격리된 전문 역할은 .cursor/agents/. 겹치면 컨텍스트 비대화·미적용·상충이 납니다. Skills 각도와 섞지 말고, 공식 Subagents·Rules 동작만 기준으로 나누시면 됩니다.