Cursor @폴더 범위 — 언제 디렉터리를 넣나?

Cursor 채팅에서 @를 치면 파일·폴더를 컨텍스트에 붙일 수 있습니다. 문제는 “폴더를 넣으면 더 똑똑해진다”는 착각입니다. 범위가 넓을수록 Agent가 형제 패키지·레거시·생성물까지 끌어와 수정·환각 비용이 커집니다.

이 글의 축은 셋입니다. 파일 vs 폴더는 언제? · 너무 넓으면 생기는 증상은? · 모노레포에서 최소 범위는? 요금·플랜·토큰 한도·제휴·창작 후기는 없습니다.

근거는 Cursor 공식 도움말 @ mentions and context입니다. @auth.ts처럼 파일, @src/components/처럼 폴더를 붙이고, 폴더 선택 뒤 /로 더 깊게 들어갈 수 있으며, 관련 파일을 알면 @로 명시하고 모르면 생략해 Agent 검색에 맡기라고 안내합니다. 여러 항목은 @를 반복해 붙입니다.

파일 vs 폴더는 언제?

한 줄 답: 고칠 파일이 이미 보이면 @파일, 그 기능이 한 디렉터리 안에 흩어져 있고 경로를 아직 못 꼽으면 @폴더(가능하면 하위까지 /로 좁히기) 입니다. “레포 루트 폴더 전체”는 기본값이 아닙니다.

상황권장 @이유
버그 스택·심볼이 특정 파일@path/to/auth.ts정확한 본문을 바로 붙임
컴포넌트 + 테스트 쌍@Comp.tsx + @Comp.test.tsx문서 예시처럼 관련 파일을 알 때 둘 다
“이 feature는 apps/web/src/billing/ 안”@apps/web/src/billing/폴더는 구역 힌트; /로 더 깊게
경로를 전혀 모름@ 생략Agent가 codebase search로 찾음
워크스페이스 설치·루트 CI만루트 파일만 @ 또는 생략폴더 전체보다 해당 파일

실무 순서:

  1. 티켓·스택트레이스에서 후보 파일 1~3개를 먼저 적습니다.
  2. 후보가 있으면 @파일을 붙이고, 부속(테스트·타입·스키마)만 추가 @합니다.
  3. 후보가 “디렉터리 단위”일 때만 @폴더를 쓰고, 메뉴에서 /로 한 단계 더 좁힙니다.
  4. 그래도 넓으면 채팅에 “이 폴더 밖은 수정하지 말 것”을 한 줄 고정합니다.
# Prefer — known files
@apps/web/src/billing/InvoiceForm.tsx
@apps/web/src/billing/InvoiceForm.test.tsx

# Prefer — narrow folder, then deepen with /
@apps/web/src/billing/

# Avoid as default
@/          (repo tip as a folder)
@apps/      (whole apps tree)
@packages/  (all packages)

공식 문서도 “관련 파일을 알면 @로 붙이고, 모르면 생략”이라고 말합니다. 폴더는 “모르겠다”의 대체재가 아니라 이미 구역을 아는 경우의 중간 정밀도입니다.

너무 넓으면 생기는 증상은?

한 줄 답: 범위가 넓으면 Agent가 잘못된 형제·레거시·생성물을 읽고, 불필요 diff·경로 환각·테스트 엇갈림이 납니다. 모델이 갑자기 멍청해진 것처럼 보이지만 대개 컨텍스트 오염입니다.

증상흔한 원인조치
형제 패키지까지 대규모 diff@apps/·@packages/ 과다@를 소유 패키지·하위 폴더로 재첨부
import/경로 환각팁 트리·여러 앱을 한 앱으로 해석파일 @로 되돌리기
테스트는 초록·버그 그대로다른 패키지 테스트만 컨텍스트대상 테스트 파일을 @
생성물·락·벤더 언급dist/·node_modules가 폴더에 포함.cursorignore + 더 좁은 @
규칙(AGENTS.md)과 충돌넓은 폴더 + 중첩 규칙 혼선규칙 경로를 별도 @로 명시
“관련 파일 찾아줘”가 느리고 산만폴더를 대체 검색으로 남용@ 빼고 Agent 검색에 맡김

체크리스트(증상이 보이면):

  1. 현재 붙은 @ 목록을 채팅에서 확인합니다.
  2. 레포 팁·apps/·packages/ 단위면 즉시 제거합니다.
  3. 티켓의 소유 경로 한 줄만 남기고 파일 @로 재시작합니다.
  4. 그래도 필요하면 한 개의 하위 폴더만 @합니다.
  5. 모델을 바꾸기 전에 범위를 먼저 고칩니다.
Too-wide red flags:
- Attached: @apps/ or @packages/ or repo tip folder
- Diff touches sibling package not in the ticket
- Agent cites files under dist/, .next/, build/
- Answer mixes two apps' route names

Recovery:
1. Clear broad folder @ mentions
2. Re-attach 1–3 concrete files
3. Optional: one leaf folder under the owning package
4. Re-state: do not edit outside <path>

넓은 @폴더는 “안전망”이 아닙니다. 검색을 Agent에 맡기는 편이 더 좁은 결과를 내는 경우가 많습니다(공식 가이드의 “모르면 생략”).

모노레포에서 최소 범위는?

한 줄 답: 모노레포에서는 소유 패키지(또는 그 안의 feature 디렉터리) 가 @폴더의 천장입니다. 크로스 패키지가 필요하면 파일을 골라 @를 여러 번 붙이고, 워크스페이스 루트 폴더 전체를 붙이지 않습니다.

최소 범위 규칙:

작업@ 최소올리지 말 것
단일 앱 UI 버그@apps/web/src/… 파일 또는 그 feature 폴더@apps/, 레포 팁
공유 패키지 타입@packages/ui/… 해당 파일 + 소비처 파일@packages/ 전체
API + 웹 동시각 쪽 파일 @ 2~4개@apps/ + @packages/
루트 CI·락파일@pnpm-workspace.yaml 등 루트 파일만팁을 폴더로 @
레거시 금지Do not touch 경로를 브리프에 명시@packages/legacy/

모노레포 브리프 조각 예:

Context for this Cursor session:
- Touch: apps/web/src/billing/**
- Do not touch: apps/admin/**, packages/legacy/**, firmware/**
- Prefer @ files under Touch; if folder, only @apps/web/src/billing/
- Never @ repo tip, @apps/, or @packages/ as a whole
- Cross-package: name exact files with @, do not widen to parent

폴더 트리에서 “한 칸만” 고르는 감각:

repo/
  apps/
    web/src/billing/   ← OK ceiling for billing work
    web/src/           ← usually too wide
    web/               ← too wide
    admin/             ← out of scope
  packages/
    api/               ← only if ticket lists it (prefer files)
    legacy/            ← never as @ folder for unrelated tasks

최소 범위는 에디터에서 연 루트(cwd) 와 다릅니다. cwd가 팁이어도 @는 좁게 유지할 수 있습니다. 반대로 패키지 폴더로 열었어도 @apps/를 붙이면 다시 넓어집니다. 루트 선택 howto는 인접 글(monorepo agent root)을, 이 글은 @ 첨부 범위만 다룹니다.

자주 묻는 질문

폴더를 붙이면 안의 모든 파일이 통째로 들어가나요?
공식 도움말은 폴더를 “include files or folders”로 안내하고, 선택 후 /로 더 깊게 들어가라고 합니다. 구현·설정·크기 한도에 따라 전량 덤프가 아닐 수 있습니다. 실무에서는 전량이라고 가정하지 말고, 필요한 파일은 @파일로 명시하는 편이 안전합니다.

관련 파일을 모를 때도 @폴더를 먼저 써야 하나요?
아니요. 문서는 모르면 생략하고 Agent 검색에 맡기라고 합니다. 폴더는 “구역을 이미 알 때”의 도구입니다.

여러 폴더를 한꺼번에 붙여도 되나요?
@를 여러 번 쓸 수 있습니다. 다만 모노레포에서는 소유 구역 밖 폴더를 더할수록 증상 표의 실패 모드에 가까워집니다. 필요할 때마다 파일 단위로 늘리는 쪽을 권합니다.

.cursorignore와 @폴더의 관계는?
ignore된 경로는 @·인덱싱에서 빠질 수 있습니다. 시크릿·벤더·생성물은 deny로 막고, @는 업무 코드의 최소 구역에만 씁니다.

무엇을 기억하면 되나?

파일 @가 기본, 폴더 @는 구역을 알 때의 중간 정밀도, 모노레포 천장은 소유 패키지·feature 디렉터리입니다. 너무 넓으면 모델을 바꾸기 전에 @ 목록을 줄입니다. 근거: Cursor @ mentions and context. 요금·제휴 없음.

공식 문서는 어디인가?