Cursor가 프로젝트 파일 구조를 기억하도록 만드는 방법 (2026)

트리 일부가 의도적으로 인덱싱에서 제외됨

이것은 가장 먼저 확인해야 할 사항이자, 아무런 알림도 없기 때문에 사람들이 가장 놀라는 부분입니다.

Cursor는 ignore 파일을 준수합니다. 공식 문서에 따르면 "Cursor는 자동으로 .gitignore 패턴을 준수합니다. git에 의해 무시되는 파일은 Cursor의 인덱싱에서도 무시됩니다." 여기에 더해 .cursorignore는 ".gitignore가 다루는 범위 이상의 추가 제외 사항"을 더하며, Cursor는 "기본적으로 .env 파일, .git/, lock 파일을 이미 무시하고 있습니다."

그 결과는 단호합니다. "무시된 파일은 인덱싱 및 Agent에서 차단됩니다." 따라서 생성된 API 클라이언트, 벤더링된 SDK 또는 빌드 출력 디렉토리가 gitignore에 등록되어 있다면(보통 그렇듯이), Agent는 해당 구조의 일부를 전혀 볼 수 없습니다. 파일이 어디에 있는지 잊어버린 것이 아니라, 애초에 보여준 적이 없는 것입니다.

여기에 정말 혼란스러운 동작을 설명해 주는 미묘한 차이가 있습니다. "터미널 명령과 MCP 도구는 Cursor의 파일 액세스 제어 외부에서 실행되므로 무시된 파일을 계속 읽을 수 있습니다." 따라서 동일한 Agent가 ls를 실행한 후에는 디렉토리가 존재한다는 것을 알면서도, 검색을 통해서는 그 안에서 아무것도 찾지 못할 수 있습니다. 이러한 불일치는 마치 건망증처럼 느껴집니다.

저장된 맵이 없음 — 구조는 매번 다시 탐색됨

@ 언급에 대한 Cursor의 가이드는 보기보다 많은 것을 시사합니다. 관련 파일이 무엇인지 알고 있을 때만 사용하고, "어떤 파일이 중요한지 확실하지 않다면 건너뛰십시오. Agent가 자체 검색을 통해 관련 파일을 찾습니다"라고 안내합니다.

이것이 설계 방식입니다. Agent는 메시지 간에 프로젝트 맵을 유지하는 대신 요청당 필요한 것을 찾아냅니다. 규칙이 배치하거나 사용자가 직접 첨부하지 않는 한, 턴 간에 레이아웃에 대한 정보는 유지되지 않습니다. 그리고 Cursor는 왜 무언가가 유지되어야 하는지에 대해 직접적으로 설명합니다. "대형 언어 모델은 완료(completion) 간에 메모리를 유지하지 않습니다. 규칙은 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공합니다."

따라서 "내 파일 구조 기억하기"는 여러분이 찾지 못한 메모리 설정이 아닙니다. 무엇을 어떻게 지속되도록 만들었는가의 문제입니다.

구조에 대해 작성한 규칙이 로드되지 않음

만약 배치 규칙을 작성했는데도 무시되고 있다면, 거의 항상 다음 네 가지 중 하나에 해당하며, Cursor의 FAQ에서 처음 두 가지를 언급하고 있습니다. "규칙 유형을 확인하십시오. Apply Intelligently인 경우 설명(description)이 정의되어 있는지 확인하십시오. Apply to Specific Files인 경우 파일 패턴이 참조된 파일과 일치하는지 확인하십시오."

프런트매터(frontmatter) 테이블을 숙지해 둘 가치가 있습니다. 필드가 설정되지 않은 규칙은 손상된 규칙이 아니라 수동 규칙이기 때문입니다. alwaysApply: true인 경우 "항상 포함됩니다. Glob 및 설명은 무시됩니다." alwaysApply: false와 glob이 있는 경우 "일치하는 파일이 컨텍스트에 있을 때 자동 첨부됩니다." 설명이 있고 glob이 없는 경우 "Agent가 설명을 읽고 관련이 있을 때 규칙을 가져옵니다." 둘 다 없는 경우 "채팅에서 규칙을 @로 언급할 때만 포함됩니다."

그다음은 확장자 함정입니다. ".cursor/rules에 있는 일반 .md 파일은 description, globs, alwaysApply를 지정할 프런트매터가 없기 때문에 규칙 시스템에서 무시됩니다. 일반 마크다운을 선호한다면 대신 AGENTS.md를 사용하십시오."

마지막으로 위치입니다. 규칙은 열려 있는 폴더의 .cursor/rules에 저장됩니다. 모노레포의 하위 디렉토리를 프로젝트로 열면 규칙의 범위가 해당 하위 디렉토리로 제한됩니다.

붙여넣은 트리는 일주일만 지나도 틀려집니다

규칙이 로드되더라도 부패하기 마련입니다. 디렉토리 목록은 항상 켜져 있는 파일에 넣을 수 있는 것 중 가장 빠르게 낡아버리는 요소이며, 오래된 트리는 없는 것보다 못합니다. 이동된 경로로 Agent를 적극적으로 잘못 안내하기 때문입니다. 이것이 바로 Cursor가 규칙이 "코드가 변경됨에 따라 오래된다"고 말하는 의미이며, 복사하기보다 참조하라고 조언하는 이유입니다.

항상 켜져 있는 규칙에 tree -L 3 출력을 붙여넣기. 로드는 되고 며칠 동안은 정확하지만, 곧 잘못된 방향으로 안내하기 시작합니다. 규칙 내용은 "모델 컨텍스트의 시작 부분에 포함"되므로 매 메시지마다 비용을 지불해야 합니다.

"프로젝트는 기능별로 구성되어 있습니다"라고만 적고 끝내기. 사실이지만 실행 불가능합니다. Agent에게 새 파일이 어디로 가야 하는지 알려주지 못합니다.

매 채팅마다 폴더를 수동으로 다시 첨부하기. 작동은 하지만, how to stop re-explaining context to AI에서 설명한 비효율적인 반복 작업입니다.

Cursor가 볼 수 있도록 디렉토리 무시 해제하기. 가끔은 맞을 수 있지만 대부분은 아닙니다. 문서에는 "대용량 생성 파일은 인덱싱을 느리게 만든다", "비밀번호 및 자격 증명은 AI 컨텍스트에서 제외하는 것이 안전하다" 등 무시해야 하는 이유가 나열되어 있습니다.

구조 규칙을 Apply Intelligently로 설정하기. 그럴듯하게 들리지만, 5초 만에 작성한 설명에 결정을 맡기게 됩니다. 설명이 모호하면 규칙이 적용되지 않습니다.

매 세션마다 Agent에게 코드베이스를 다시 스캔하도록 요청하기. 비용이 많이 들고 반복적이며, how to stop Claude Code re-reading your codebase에서도 동일한 패턴이 나타납니다.

이 문제를 해결 가능한 수준으로 재정의하자면, Cursor가 파일이 어디에 있는지 외우기를 바라는 것이 아닙니다. 새 파일이 어디로 가야 하는지, 그리고 그 이유가 무엇인지 알기를 바라는 것입니다. 전자는 유추할 수 있고 낡아버리지만, 후자는 컨벤션(관례)이며 유지됩니다.

Cursor의 자체 문서가 이를 은연중에 보여줍니다. globs: src/components/**/*.tsx로 범위가 지정된 자동 첨부 규칙의 예시에는 "컴포넌트 바로 옆의 모듈 CSS 파일에 스타일을 함께 배치하십시오", "컴포넌트를 200줄 미만으로 유지하십시오. 파일이 그 이상으로 커지면 하위 컴포넌트를 동일한 디렉토리로 추출하십시오"와 같은 줄이 포함되어 있습니다. 이것이 바로 배치 규칙입니다. 예시에는 트리가 없습니다.

네 가지 단계입니다.

무엇이든 작성하기 전에 ignore 파일을 감사하십시오. Agent가 계속해서 잘못 파악하는 디렉토리를 기준으로 .gitignore와 .cursorignore를 확인하십시오. 체크인된 스키마 디렉토리나 커밋하는 생성된 클라이언트처럼 폴더가 실제로 보여야 하는 경우, 이는 어떤 규칙으로도 대체할 수 없는 한 줄짜리 해결책입니다.

glob으로 범위를 지정하여 배치 컨벤션을 작성하십시오. 영역당 하나의 규칙을 패턴별로 첨부하여 해당 영역에서 작업할 때 로드되도록 하십시오. 문서화된 glob 형식을 사용하십시오. src/ 아래의 모든 항목은 src/**, 컴포넌트는 src/**/*.tsx, 두 개가 필요한 경우 docs/**/*.md, docs/**/*.mdx와 같이 쉼표로 구분된 패턴을 사용합니다. 현재 존재하는 것이 아니라 파일이 어디로 가야 하고 이름은 어떻게 지어야 하는지 명시하십시오.

구조적 범위 지정을 위해 중첩된 AGENTS.md를 사용하십시오. 하위 디렉토리에 배치하면 "해당 디렉토리 또는 그 하위 디렉토리의 파일로 작업할 때 자동으로 적용"되며, 지침은 "상위 디렉토리와 결합되고 더 구체적인 지침이 우선 적용"됩니다. 프런트매터도 없고 glob 유지 관리도 필요 없으며, 설명하는 코드 바로 옆에 파일이 위치하므로 레이아웃이 변경될 때 업데이트될 가능성이 더 높습니다.

특정 요청에 대해 폴더를 명시적으로 첨부하십시오. 영역을 알고 있다면 @를 사용하십시오. "파일이나 폴더를 포함하려면 @auth.ts 또는 @src/components/를 입력하십시오(폴더를 선택한 후 /를 입력하면 더 깊이 탐색할 수 있습니다)." 이는 당장의 요청을 위한 것이지 컨벤션을 대체하는 것은 아닙니다.

이것으로 로딩과 범위 지정은 해결됩니다. 하지만 이 중 어느 것도 레이아웃을 이해하기 쉽게 만드는 부분, 즉 경계가 왜 그곳에 있는지, 어떤 재구성을 시도했다가 되돌렸는지, 퇴화한 것처럼 보이지만 그렇지 않은 디렉토리는 무엇인지에 대한 정보를 담지 못합니다. 규칙은 권장 500줄로 제한되어 있으며 복제하기보다는 가리키도록 설계되었기 때문에, 구조 뒤에 숨겨진 논리가 머무를 곳이 없습니다.

바로 이 부분을 MemoryLake가 해결합니다. 도구가 읽을 수 있는 레이어에 프로젝트의 지속적인 지식을 보관하므로 규칙은 짧게 유지되고 추론 근거는 계속 사용할 수 있습니다. 설정은 세 단계로 진행됩니다.

1단계: API 키 생성

MemoryLake에 로그인하고 API 키를 생성합니다. 연결하는 도구 전체에서 하나의 자격 증명만 사용하면 됩니다.

2단계: 첫 번째 메모리 업로드

각각 하나의 주장만 담긴 짧은 항목들입니다. 특히 구조에 대해 작성해야 할 내용은 다음과 같습니다.

각각의 새로운 항목이 어디로 가는지와 그 이유. "라우터가 해당 디렉토리를 glob하므로 새 API 핸들러는 경로당 하나의 파일로 src/api/handlers/에 들어갑니다." 규칙은 위치를 명시하지만, 그 이유는 다음 달에 그럴듯한 대안이 나와도 흔들리지 않게 잡아줍니다.

임의적인 것처럼 보이지만 그렇지 않은 경계. 다른 모듈에서 가져올 수 없는 모듈, 프레임워크가 없어야 하는 디렉토리 등입니다. 트리 구조 자체는 제약 조건을 전달하지 못합니다.

이미 거부한 재구성 방식. 시도해 보았던 평평한 구조, 의도적으로 만들지 않은 utils/ 등입니다. 새로운 에이전트가 올 때마다 이를 다시 제안하지만, 레포지토리의 그 어디에도 이 결정이 기록되어 있지 않습니다.

인덱싱에서 제외된 디렉토리와 그 안의 내용. generated/가 gitignore에 등록되어 있다면, 40,000개의 파일의 무시를 해제하는 것보다 그 안에 무엇이 있고 어떻게 생성되는지에 대한 한 줄짜리 메모가 훨씬 더 유용합니다.

3단계: AI 및 에이전트 연결

사용하는 도구를 연결합니다. MemoryLake는 MCP 및 API를 통해 액세스할 수 있으므로, Claude Code, Codex, OpenClaw를 포함한 MCP 네이티브 에이전트는 MCP 서버를 가리켜 연결하고, 다른 어시스턴트는 API를 통해 동일한 메모리를 읽습니다. 한 번 작성한 배치 컨벤션을 레포지토리에서 작업하는 모든 에이전트가 동일하게 읽게 됩니다.

세 가지 명확한 한계가 있습니다. MemoryLake는 코드베이스를 인덱싱하지 않으며 Cursor 규칙을 작성하지 않습니다 — 파일은 Cursor 자체 인덱싱이 찾고, 규칙은 Agent를 가이드하는 방법입니다. MemoryLake는 사용자나 에이전트가 입력한 내용만 보관하므로 2단계는 수동으로 진행됩니다. 또한 이는 강제가 아닌 컨텍스트 제공입니다. 배치 규칙이 반드시 준수되어야 한다면 린트(lint) 규칙이나 CI 검사가 확실한 보증 수단입니다.

"파일이 잘못된 위치에 생성되었습니다"라는 문제는 두 단계의 확인으로 좁혀집니다. 디렉토리가 무시되었는가? 규칙의 유형과 패턴이 올바른가? 거의 항상 이 두 가지 중 하나가 원인입니다.

폴더를 추가할 때마다 규칙을 업데이트할 필요가 없어집니다. 컨벤션은 리팩토링 후에도 살아남지만, 디렉토리 목록은 그렇지 못합니다.

새로운 기여자가 에이전트와 동일한 답변을 얻게 됩니다. 문서화된 배치 컨벤션은 모델을 가이드하는 동시에 훌륭한 온보딩 문서가 됩니다.

인덱싱 제외가 더 이상 버그처럼 보이지 않습니다. .gitignore가 Agent의 접근 범위에서 파일을 제거한다는 사실을 알게 되면, "dist/에서 아무것도 찾을 수 없다"는 보고가 더 이상 미스터리하게 느껴지지 않습니다.

레이아웃 결정이 도구의 한계를 넘어 유지됩니다. Cursor, Claude Code, Codex 중 무엇이 읽든 추론 근거는 동일합니다. 이는 what persistent memory actually means에서 다룬 형태입니다.

.gitignore와 .cursorignore를 먼저 확인하십시오. git에 의해 무시되는 파일은 Cursor의 인덱싱에서도 무시되며, 어떤 규칙으로도 이를 우회할 수 없습니다.

항상 켜져 있는 규칙에 디렉토리 트리를 절대 붙여넣지 마십시오. 유추 가능하고 일주일 안에 낡아버리며, 두 개발사 모두 권장하지 않습니다.

glob으로 구조 규칙의 범위를 지정하십시오. 컴포넌트에 대한 규칙은 매 메시지가 아니라 컴포넌트를 열었을 때 첨부되어야 합니다.

디렉토리별 컨벤션에는 중첩된 AGENTS.md를 권장합니다. 더 구체적인 지침이 우선 적용되고, 유지 관리할 프런트매터가 없으며, 설명하는 대상 바로 옆에 파일이 위치합니다.

.cursor/rules 내부에서는 일반 .md가 아닌 .mdc를 사용하십시오. 그곳의 .md 파일은 아무런 경고 없이 무시됩니다.

파일 목록이 아닌 명명 규칙(naming convention)을 작성하십시오. "경로당 하나의 파일, 경로 이름을 딴 파일명"이 handlers/ 스냅샷보다 훨씬 오래 유지됩니다.

당장의 작업을 위해 @로 폴더를 첨부하십시오. 검색이 올바른 영역을 찾아내기를 바라는 것보다 정밀하게 지정하는 것이 좋습니다.

추론 근거는 규칙 외부에 보관하십시오. 경계가 존재하는 이유를 알아야 에이전트가 컨벤션에서 예상하지 못한 상황을 처리할 수 있습니다. 이는 why agents ignore the instruction files you wrote에서 다룬 일반적인 문제입니다.

Cursor는 메시지 간에 프로젝트 맵을 유지하지 않으며, 그렇게 하도록 설계되지도 않았습니다. Agent는 매번 자체 검색을 통해 관련 파일을 찾고, 규칙은 유지되어야 하는 모든 것을 위한 문서화된 메커니즘입니다. 따라서 파일이 잘못된 위치에 생성될 때는 다음 세 가지를 순서대로 확인해야 합니다. 디렉토리가 .gitignore 또는 .cursorignore에 의해 제외되었는지, 규칙의 유형과 glob 패턴이 실제로 로드되도록 설정되었는지, 그리고 규칙이 파일이 어디로 가야 하는지를 말하는지 아니면 단순히 어디에 있는지를 설명하는지입니다.

마지막 항목이 실질적인 해결책이며, 이는 Cursor와 Claude Code의 문서가 독립적으로 지적하는 부분이기도 합니다. 도구가 유추할 수 있는 콘텐츠에 항상 켜져 있는 컨텍스트를 낭비하지 말고, 오래될 수 있는 내용을 복사하지 마십시오. 배치 컨벤션을 작성하고, 이를 관리하는 디렉토리에 범위를 지정하고, 레이아웃 뒤에 숨겨진 추론 근거를 모든 도구가 쿼리할 수 있는 곳에 보관하십시오. 그러면 트리의 스냅샷이 우연히 정확하게 유지되어서가 아니라, 컨벤션이 명확하기 때문에 새 파일이 올바른 위치에 생성될 것입니다.