최근 저는 리포지토리(repositories)가 Cursor 컨텍스트를 로드하는 방식을 재구성하는 데 시간을 보냈습니다. 기존 설정도 작동은 했지만, 무거웠습니다. 모든 에이전트(agent) 턴은 모델이 대부분의 작업에 필요하지 않은 대량의 규칙(rules), 중복된 가이드라인, 그리고 인벤토리(inventories)와 함께 시작되었습니다.

새로운 설정은 의도적으로 더 작게 만들었습니다. 에이전트는 여전히 필요한 것을 찾아내지만, 초기에 지불해야 하는 컨텍스트(context) 비용은 줄어듭니다. 이는 토큰 비용(token cost)이 낮아지고, 모델이 "상황을 파악(read the room)"하기 위해 기다리는 시간이 줄어들며, 제가 실제로 요청한 작업에 더 밀접하게 유지되는 답변을 얻을 수 있음을 의미합니다.

이미 저의 Cursor 설정을 갖추고 있다면, 이 포스트를 다음 단계로 생각하세요. 해당 포스트는 전체 툴킷(toolkit)을 다룹니다. 이 포스트는 작업이 시작되기 전에 컨텍스트 윈도우(context window)를 잡아먹지 않도록 툴킷을 배치하는 방법을 다룹니다.

빠른 답변

.cursor 디렉토리를 모든 프롬프트(prompt)에 붙여넣는 하나의 거대한 PDF처럼 취급하지 말고, 카드 카탈로그(card catalog)가 있는 도서관처럼 취급하세요. 가드레일(guardrails)을 위한 얇은 상시 활성화(always-on) 레이어는 유지하되, 그 외의 모든 것은 링크를 통해 라우팅(route)하고, 상세한 규칙은 적용되는 파일 유형에 범위를 제한하며, 기술(skills)은 필요할 때만 로드하세요. 에이전트는 작업에 필요할 때 언제든 더 많은 컨텍스트를 열 수 있지만, 기본값은 최소한의 유용한 기준선(baseline)이어야 합니다.

대상

• Cursor 규칙(rules), 기술(skills), 또는 AGENTS.md를 이미 사용 중이며 시간이 지남에 따라 에이전트가 느려지거나 노이즈가 심해지는 것을 느끼는 사람들
• .cursor 폴더가 자연스럽게 커지면서 이제 세 군데에서 동일한 지침을 반복하고 있는 팀
• 토큰 비용(token cost)을 신경 쓰며, 깊은 프로젝트 지식을 포기하지 않으면서도 더 깔끔한 첫 응답을 원하는 빌더(builders)

이것이 중요한 이유

컨텍스트(context)는 공짜가 아닙니다. 상시 활성화된 모든 규칙, AGENTS.md의 모든 문단, 그리고 시스템이 초기에 주입하는 모든 기술 설명은 에이전트가 유용한 한 줄을 쓰기도 전에 토큰을 소비합니다.

그 비용은 세 가지 측면에서 나타납니다:

• 비용 (money): 프롬프트가 커질수록 턴당 비용이 더 많이 발생하기 때문입니다.
• 지연 시간 (latency): 모델이 해당 작업에 필요하지 않을 수도 있는 컨텍스트를 흡수하는 데 시간을 소비하기 때문입니다.
• 집중력 (focus): 비대해진 베이스라인은 에이전트가 방황하거나, 말을 반복하거나,

무엇을 제외할 것인가:

• 전체 기술 테이블 (대신 카탈로그 링크를 사용하세요)
• 데이터 플랫폼의 모든 레이어에 대한 긴 산문 형태의 설명
• 단계별 워크플로우 (이는 기술 (skills)에 포함되어야 합니다)

레이어 2: 로컬 인덱스로서의 .cursor/README.md

이 파일은 Cursor 네이티브 자산의 지도입니다. 에세이가 아닌 표를 사용하여 훑어보기 쉽게 유지하세요.

포함할 내용:

• 어떤 규칙 (rules)이 존재하며 언제 적용되는지
• 어떤 기술 (skills)이 존재하며 언제 사용해야 하는지
• 어떤 서브 에이전트 (subagents)가 병렬 작업을 래핑 (wrap) 하는지
• 유지보수 문서가 어디에 있는지

무거운 항목들을 로드하지 말아야 할 때를 에이전트에게 명시적으로 알려주세요. "자산을 유지보수하거나 사용자가 인벤토리를 요청하지 않는 한 전체 카탈로그를 열지 마십시오"와 같은 한 줄은 반복적으로 토큰을 절약해 줍니다.

레이어 3: 상시 적용 규칙 (always-on rules)과 작업 범위 규칙 (task-scoped rules)의 분리

이것은 제가 수행한 가장 영향력 있는 (highest-leverage) 변화입니다.

**상시 적용 (always-on)**은 "저장소의 모든 컨벤션 (convention)"이 아니라 "행동 및 안전 (behavior and safety)"을 의미해야 합니다.

저의 상시 적용 행동 규칙은 다음을 다룹니다:

• 가정하기 전에 질문하기
• 범위 드리프트 (scope drift) 방지
• git을 사용자 제어 상태로 유지
• 위험도에 맞춘 검증
• 짧은 섹션 하나로 구성된 문서화 철학
• 몇 줄로 요약된 아키텍처 불변량 (architecture invariants)

상세한 컨벤션은 glob 범위 규칙 (glob-scoped rules)으로 이동합니다:

---
description: "sql and model conventions"
globs: "**/*.sql"
...

그리고:

---
description: "yaml metadata conventions"
globs: "**/*.yml"
...

이제 마크다운 (markdown) 편집 시에는 SQL 규칙을 로드하지 않습니다. YAML 편집 시에는 원고 규칙을 로드하지 않습니다. 에이전트는 모든 차선을 한꺼번에 읽지 않고도 올바른 차선으로 진입합니다.

콘텐츠 비중이 높은 저장소의 경우, 동일한 아이디어가 구역 (zones) 전체에 적용됩니다. 하나는 웹사이트 포스트에 범위를 지정하고, 다른 하나는 도서 챕터에 범위를 지정하며, 각각 고유한 glob 패턴을 가집니다. 에이전트는 실제로 다루고 있는 파일에 대한 말투와 문장 부호 규칙을 로드합니다.

레이어 4: 온디맨드 런북 (on-demand runbooks)으로서의 기술 (skills)

기술 (skills)이 강력한 이유는 그것이 **절차적 (procedural)**이고 **작업에 종속 (task-bound)**되어 있기 때문입니다. 하지만 이를 상시 적용되는 정책처럼 취급하면 비용이 많이 들게 됩니다.

각 기술의 초점을 유지하세요:

• 언제 사용할지 명시하는 frontmatter description (설명)
• 필수 입력값 (required inputs)
• 순서가 지정된 단계 (ordered steps)
• 완료 기준 (done criteria)
• 내용을 직접 복사하는 대신 공식 참조 문서 (canonical reference docs)로 연결

에이전트는 설명을 통해 기술 (skills)을 발견하고, 작업이 일치할 때 해당 파일을 로드합니다. 사용자가 인사를 건네기도 전에 모든 기술의 전체 텍스트를 로드할 필요는 없습니다.

기술 구조를 강화하기 위한 템플릿이 필요하다면, starter templates for ai rules, skills, and commands를 참조하세요.

레이어 5: 인벤토리 및 계약을 위한 참조 파일 (reference files)

일부 자료는 인라인 (inline)으로 넣기에는 너무 길지만 여전히 가치가 있습니다. 이를 .cursor/reference/에 넣고 링크로 연결하세요.

적합한 대상:

• 전체 기술 (skill) 및 서브 에이전트 (subagent) 카탈로그
• 모델 또는 스키마 계약 (schema contracts)
• 자산 유지 관리 런북 (maintaining-assets runbooks)
• 여러 규칙에서 공통으로 사용하는 공유 산문 계약 (shared prose contracts)

각 참조 파일의 상단에는 언제 이 파일을 로드해야 하는지 명시해야 합니다. 특히 카탈로그의 경우, 모든 작업마다 파일을 열지 않도록 주의를 주어야 합니다.

중복은 조용한 토큰 세금입니다

가장 빠르게 수행할 수 있는 감사는 중복 확인 (duplication pass)입니다.

다음 항목들 사이에서 반복되는 동일한 아이디어를 찾아보세요:

• AGENTS.md
• 상시 적용 규칙 (always-on rules)
• 기술 (skills)
• .cursor/ 내부의 README 파일들

흔한 중복 사례:

• 세 곳에 명시된 git 정책
• 모든 규칙에 복사된 아키텍처 개요 (architecture overview)
• 기술 (skill)과 규칙 모두에 나열된 검증 명령 (validation commands)
• 프롬프트에 붙여넣은 전체 디렉토리 트리

각 주제에 대해 하나의 공식적인 위치 (canonical home)를 정하세요. 그 외의 모든 곳에서는 복사본 대신 링크로 대체하세요.

이렇게 하면 유지보수도 쉬워집니다. 검증 방식이 변경될 때, 에이전트가 여전히 믿고 있을지도 모르는 오래된 복사본들을 찾아다니는 대신 파일 하나만 업데이트하면 됩니다.

인덱싱 위생 (indexing hygiene)도 여전히 중요합니다

토큰 효율성은 규칙과 기술에 관한 것만이 아닙니다. Cursor가 저장소 (repo)에서 무엇을 인덱싱 (index)하는지에 관한 것이기도 합니다.

다음 항목들을 계속 사용하세요:

• 생성된 출력물 및 의존성 (dependencies)을 위한 .gitignore
• 빌드 아티팩트 (build artifacts), 압축된 번들 (minified bundles), 로컬 비밀 정보 (local secrets)와 같은 추가 제외 항목을 위한 .cursorignore

인덱스(index) 내의 불필요한 정보(junk)가 적을수록 시맨틱 검색 (semantic search) 과정에서 무관한 자료가 줄어들고, 잘못된 파일로 우회하는 경우도 줄어듭니다.

저는 저의 cursor 설정의 컨텍스트 위생 (context hygiene) 섹션에서 기초적인 내용을 다루었습니다. .cursor 디렉토리 최적화와 인덱싱 (indexing) 최적화는 함께 작동합니다.

에이전트가 가져오게 하되, 가져오는 행위를 의도적으로 만드세요

가벼운 베이스라인 (baseline)이 에이전트의 무지를 의미하지는 않습니다. 이는 에이전트가 집중된 상태로 시작하여 의도적으로 범위를 확장함을 의미합니다.

효과적인 패턴:

• 정답이 어디에 있는지 이미 알고 있을 때 사용하는 @Files 및 @Folders
• 에이전트가 일치하는 파일을 편집할 때 자동으로 부착되는 작업 범위 규칙 (task-scoped rules)
• 작업 설명이 해당 스킬의 description과 일치할 때 에이전트가 여는 스킬 (skills)
• 유지보수, 인벤토리 질문, 또는 모호한 워크플로 선택을 위해 여는 참조 카탈로그 (reference catalogs)

토큰을 낭비하는 패턴:

• 항상 켜져 있는 지침 (always-on instructions)에 디렉토리 전체를 붙여넣는 것
• 규칙에 "무엇을 하기 전에 모든 문서를 읽으세요"라고 작성하는 것
• 어떤 것이 표준인지 결정하지 못해 항상 켜져 있는 규칙을 5개나 만드는 것

모델은 지도를 제공했을 때 검색 (retrieval)을 잘 수행합니다. 백과사전 전체를 주고 1페이지를 찾아보라고 할 때는 성능이 떨어집니다.

실질적인 마이그레이션 경로

주말 내내 새로 작성할 필요는 없습니다. 저에게 효과적이었던 순서는 다음과 같습니다:

1) 매 턴마다 로드되는 항목 목록 작성

목록:

• alwaysApply: true가 설정된 규칙들
• AGENTS.md의 큰 섹션들
• 항상 켜져 있는 파일 내에 인라인(inlined)으로 포함된 모든 스킬 (skill) 또는 서브 에이전트 (subagent) 목록

각 항목에 대해 스스로 물어보세요: "어제 풀 리퀘스트 (pull request)에 대한 일반적인 질문을 할 때도 이것이 필요했는가?"

2) AGENTS.md를 라우터 (router)로 재작성

엄격한 제약 조건과 작업별 경로 테이블 (route-by-task table)만 유지하세요. 그 외의 모든 것은 링크 뒤로 옮기세요.

3) 항상 켜져 있는 동작을 하나의 얇은 규칙으로 통합

중복되는 가드레일 (guardrails)을 병합하세요. 협업 선호도나 행동 스킬을 복사하는 대신 링크로 연결하세요.

4) 글로브 (globs) 패턴을 사용하여 작업 범위 규칙 (task-scoped rules) 추출

sql, yaml, typescript, website markdown, book markdown, ci workflows. 가이드라인이 단순하지 않다면 각 항목은 고유한 범위 규칙 (scoped rule)을 갖게 됩니다.

5) 인벤토리(inventories)를 참조 파일로 이동

카탈로그 (catalogs), 계약 (contracts), 유지보수 가이드 (maintenance guides)는 .cursor/reference/ 아래에 위치합니다. 상단에 "언제 로드해야 하는지 (when to load)"에 대한 노트를 추가하세요.

6) 중복 제거 및 삭제

두 파일이 동일한 내용을 말하고 있다면, 하나를 선택하고 나머지는 삭제하세요. 오래된 중복 파일은 권위 있어 보이기 때문에 문서가 누락된 것보다 더 해롭습니다.

7) 세 가지 프롬프트로 테스트

리팩터링 후에 다음을 실행하세요:

• 전문 규칙 범위를 벗어난 일반적인 작업 (빠르고 집중된 상태를 유지해야 함)
• 특정 파일 유형에 특화된 작업 (사용자가 언급하지 않아도 적절한 범위 규칙을 가져와야 함)
• "새로운 기술 추가"와 같은 유지보수 작업 (카탈로그나 유지보수 문서로 라우팅되어야 함)

리팩터링 후 개선된 점

차이점은 턴(turn)마다 미묘하지만 빠르게 누적됩니다:

• 첫 응답이 서론(preamble)이 적고 정책 인용이 반복되지 않은 채 도착합니다.
• SQL 작업이 마크다운 어조 규칙을 상속받는 일이 중단되며, 그 반대의 경우도 마찬가지입니다.
• 베이스라인이 축소되었기 때문에 일상적인 편집에 소모되는 토큰 (token) 비용이 감소했습니다.
• 에이전트가 범위를 확장할 때는 저장소(repo) 때문에 강제되는 것이 아니라, 실제로 작업에 더 많은 컨텍스트 (context)가 필요하기 때문인 경우가 대부분입니다.

이는 cursor automations for housekeeping and hygiene의 철학과 동일합니다. 저장소에 이미 플레이북 (playbook)이 포함되어 있기 때문에 자동화 프롬프트가 짧게 유지됩니다. 효율적인 .cursor 레이아웃은 대화형 에이전트와 백그라운드 자동화 모두를 더 저렴하게 실행할 수 있게 합니다.

마치며

첫날부터 완벽한 .cursor 디렉토리를 가질 필요는 없습니다. 중복된 권위가 쌓이지 않으면서 성장할 수 있는 디렉토리가 필요할 뿐입니다.

작게 시작하고, 공격적으로 라우팅(routing)하며, 규칙의 범위를 해당 규칙이 관리하는 파일로 제한하고, 카탈로그(catalogs)는 기본 컨텍스트(default context)가 아닌 참조 자료(reference material)로 취급하세요. 에이전트는 필요할 때 여전히 찾아볼 것입니다. 그것이 핵심입니다. 당신은 단지 에이전트가 모든 대화에 도서관 전체를 들고 들어가는 것을 막고 있는 것뿐입니다.

FAQ

항상 켜져 있는 레이어(always-on layer)는 얼마나 작아야 하나요?

1분 이내에 읽을 수 있으면서도 안전성과 범위(scope)에 대해 에이전트를 신뢰할 수 있을 정도로 작아야 합니다. 만약 항상 켜져 있는 자료가 스크롤을 필요로 한다면, 세부 사항을 glob 범위 지정 규칙(glob-scoped rules)이나 스킬(skills)로 옮기세요.

컨텍스트를 가볍게 유지하면 에이전트가 프로젝트 컨벤션(project conventions)을 놓치게 될까요?

표준 소스(canonical source)를 완전히 제거했을 경우에만 그렇습니다. 라우팅(routing)이 그 문제를 해결합니다. 컨벤션은 여전히 존재하며, 단지 관련이 있을 때만 로드될 뿐입니다. 만약 에이전트가 놓치는 부분이 보인다면, 스킬의 description을 강화하거나, glob 패턴을 조정하거나, AGENTS.md에 표준 문서(canonical doc)를 가리키는 한 줄을 추가하세요.

토큰을 최적화해야 할까요, 아니면 "에이전트가 항상 모든 것을 알게" 최적화해야 할까요?