컨텍스트는 AI의 작업 환경이다
Cursor에서 같은 모델을 써도 결과가 크게 달라지는 이유가 있다. 모델의 지능만으로 일하지 않기 때문이다. Agent는 지금 대화에 들어온 파일, 문서, 규칙, 검색 결과, 이전 결정, 브랜치 변경 사항을 바탕으로 판단한다. 이 전체가 컨텍스트다.
컨텍스트 관리는 "AI에게 많이 알려 주는 기술"이 아니다. 지금 작업에 필요한 것만 정확히 보여 주는 기술이다. 사람이 동료에게 일을 맡길 때도 마찬가지다. 결제 버그를 고쳐 달라고 하면서 전체 저장소와 6개월 전 회의록을 던져 주면 좋은 위임이 아니다. 반대로 결제 API 파일, 최근 에러 로그, 기대 동작, 수정하면 안 되는 파일을 함께 주면 훨씬 안전하다.
Cursor의 컨텍스트 참조는 작업 목적에 따라 다르게 써야 한다. 특정 파일을 정확히 고칠 때는 @file, 폴더 전체의 구조와 패턴을 봐야 할 때는 @folder, 특정 함수나 클래스만 다룰 때는 @code, 위치를 모를 때는 @codebase, 외부 라이브러리 지식이 필요할 때는 @docs나 @web을 우선 사용한다.1 이전 대화의 결정이 중요하면 @Past Chats, 현재 브랜치에서 무엇이 바뀌었는지 확인해야 하면 @Branch를 붙인다.
핵심은 하나다. Agent가 추측으로 빈칸을 채우지 않게 해야 한다.
AI 생성 이미지
참조 방식은 작업 크기에 맞춘다
작은 수정에는 작은 컨텍스트가 좋다. 예를 들어 버튼 컴포넌트의 disabled 스타일만 고치고 싶다면 전체 src 폴더를 줄 필요가 없다.
@src/components/Button.tsx에서 disabled 상태의 스타일만 수정해 줘.
기존 variant 구조는 바꾸지 말고, className 조합 방식도 유지해.
수정 후 변경 이유를 3줄로 요약해 줘.이 요청은 목표, 파일, 제약, 출력 형식이 분명하다. Agent는 다른 컴포넌트를 뒤질 필요가 없다.
반대로 인증 미들웨어가 API 라우트 전반에 빠진 곳을 찾아야 한다면 파일 하나로는 부족하다.
@src/app/api 폴더를 검토해서 인증 미들웨어가 누락된 라우트를 찾아줘.
아직 코드는 수정하지 말고, 파일별 위험도와 수정 계획만 Markdown 표로 정리해 줘.이때는 @folder가 적절하다. 폴더 안의 반복 패턴을 봐야 하기 때문이다.
특정 훅이나 함수만 바꾸는 경우에는 @code가 더 낫다.
@useUserData 훅만 리팩터링해 줘.
외부 API 호출 방식은 유지하고, 로딩·에러 상태 이름은 기존 컴포넌트와 호환되게 둬.구현 위치를 모를 때는 직접 파일을 찍지 말고 먼저 @codebase로 찾게 한다.
@codebase에서 사용자 플랜 제한을 계산하는 위치를 찾아줘.
바로 수정하지 말고, 관련 파일과 데이터 흐름을 먼저 설명해 줘.이 방식은 특히 오래된 프로젝트에서 유용하다. 다만 @codebase 검색은 만능이 아니다. Cursor가 의미 기반 검색으로 관련 조각을 가져오더라도, 큰 파일의 세부 구현이나 파일 간 타입 관계를 놓칠 수 있다.2 그래서 처음에는 넓게 찾고, 다음 단계에서는 찾은 파일을 @file로 좁혀야 한다.
외부 지식은 @docs와 @web로 분리한다
프레임워크나 외부 API를 다룰 때는 코드베이스만으로 부족하다. Next.js, React Router, Stripe, Supabase처럼 버전별 동작이 중요한 도구는 공식 문서 맥락을 함께 줘야 한다.
@docs는 반복적으로 참고할 문서에 적합하다. 예를 들어 프로젝트가 특정 UI 라이브러리를 계속 쓴다면 문서를 Cursor에 등록해 두고, 컴포넌트 구현 때마다 참조하게 할 수 있다. 문서가 오래되었거나 답변이 이상하면 다시 인덱싱해야 한다.3
@web은 최신 오류 메시지, 릴리스 변경, 특정 이슈 검색에 적합하다. 단, 웹에서 찾은 내용은 그대로 적용하지 않는다. Agent에게 항상 현재 프로젝트와 비교하게 해야 한다.
@web에서 이 오류 메시지의 원인 후보를 찾아줘.
그다음 우리 프로젝트의 @package.json과 @src/lib/auth.ts 기준으로 실제 적용 가능한 해결책만 추려줘.
바로 수정하지 말고 먼저 판단 근거를 설명해.외부 지식은 참고 자료일 뿐이다. 최종 기준은 현재 코드, 현재 버전, 현재 제품 정책이다.
많이 주면 똑똑해지는 것이 아니다
초보자가 자주 하는 실수는 "혹시 모르니 전부 넣기"다. 전체 폴더, 긴 과거 대화, 오래된 문서, 관련 없는 로그를 한꺼번에 넣는다. 그러면 Agent는 더 똑똑해지기보다 더 산만해진다.
좋은 요청에는 다음 네 가지가 들어간다.
목표: 무엇을 바꾸려는가
관련 컨텍스트: 어떤 파일, 폴더, 문서, 대화를 참고해야 하는가
수정 범위: 어디까지 바꿔도 되는가
제외 범위: 무엇은 건드리면 안 되는가
예를 들어 나쁜 요청은 이렇다.
설정 화면 좀 정리해 줘.좋은 요청은 이렇다.
@src/app/settings/page.tsx와 @src/components/settings 폴더를 기준으로 설정 화면의 빈 상태 UI를 개선해 줘.
기존 API 호출과 저장 로직은 수정하지 마.
새 패키지는 설치하지 마.
모바일 375px에서 overflow가 없어야 해.
변경 후 테스트 방법과 확인해야 할 UI 상태를 목록으로 알려줘.이렇게 쓰면 Agent의 자유도가 줄어든다. 자유도가 줄어든다는 것은 창의성이 줄어든다는 뜻이 아니다. 제품 코드에서는 불필요한 창의성이 버그가 되는 경우가 많다.
컨텍스트 창은 생각보다 작게 느껴진다
모델 설명에는 매우 큰 컨텍스트 길이가 적혀 있을 수 있다. 하지만 Cursor에서 실제로 사용자가 체감하는 공간은 그보다 작다. 시스템 프롬프트, 코드 검색 결과, 자동으로 포함된 파일, 대화 기록, 도구 호출 정보가 모두 같은 예산을 사용하기 때문이다. 모드와 모델에 따라 체감 가능한 컨텍스트 양도 달라진다.2
그래서 Tab 자동완성, Chat, Agent를 같은 방식으로 다루면 안 된다.
Tab은 현재 파일과 주변 코드 흐름에 강하다. 짧은 반복 코드, 바로 확인 가능한 제안에 적합하다. Chat은 설명, 비교, 설계 질문에 좋다. Agent는 여러 파일 수정과 명령 실행까지 할 수 있지만, 그만큼 컨텍스트를 빠르게 소비한다.
대규모 변경일수록 한 번에 모든 것을 맡기지 말아야 한다. 다음처럼 나눈다.
@codebase로 관련 위치를 찾게 한다.찾은 파일 목록을 검토한다.
핵심 파일만
@file로 다시 제공한다.Plan Mode로 수정 순서를 세운다.
한 단계씩 구현한다.
각 단계 후 diff와 테스트 결과를 요약하게 한다.
컨텍스트는 무한한 창고가 아니라 작업대다. 작업대 위에는 지금 쓰는 도구만 올려야 한다.
같은 대화를 이어갈 때와 새로 시작할 때
대화는 길어질수록 편해 보인다. 앞에서 말한 내용을 다시 설명하지 않아도 되기 때문이다. 하지만 긴 대화에는 비용이 있다. 초기 지시가 흐려지고, 실패한 시도와 오래된 가정이 남고, Agent가 이전 맥락과 현재 목표를 섞기 시작한다. 여러 가이드에서도 긴 대화가 이어질수록 품질 저하와 비용 증가가 발생할 수 있다고 설명한다.3
같은 대화를 이어가도 되는 경우는 다음과 같다.
같은 기능의 구현과 검증을 계속하고 있다.
앞에서 합의한 결정이 아직 유효하다.
Agent가 파일과 목표를 정확히 기억하고 있다.
남은 작업이 앞 단계의 자연스러운 후속 작업이다.
새 대화를 여는 것이 좋은 경우는 다음과 같다.
기능이나 주제가 바뀌었다.
Agent가 같은 실수를 반복한다.
실패한 접근이 대화에 많이 쌓였다.
"아까 말한 것"을 Agent가 엉뚱하게 해석한다.
한 논리적 작업 단위가 끝났다.
새 대화를 열 때는 그냥 버리지 말고 요약을 남긴다.
지금까지의 결정, 수정한 파일, 남은 TODO, 주의해야 할 제약을
다음 채팅에 붙여 넣을 수 있게 15줄 이내로 요약해 줘.그 요약을 .cursor/plans/나 작업 문서에 저장해 두면 다음 Agent에게 재사용할 수 있다. 필요하면 @Past Chats와 함께 관련 파일을 다시 붙인다. 중요한 것은 긴 대화를 계속 끌고 가는 것이 아니라, 유효한 결정만 압축해 옮기는 것이다.
대형 코드베이스에서는 컨텍스트도 운영 자원이다
프로젝트가 커질수록 Agent에게 "알아서 찾아봐"라고 말하는 비용이 커진다. 빌드 산출물, 로그, 대용량 JSON, 오래된 레거시 폴더, 생성된 타입 파일이 검색 공간에 섞이면 필요한 코드가 묻힌다.
먼저 .cursorignore를 정리한다. 보통 다음 항목은 제외 후보가 된다.
node_modules/
.next/
dist/
build/
coverage/
*.log
*.lock
large-fixtures/
legacy-unused/락파일은 상황에 따라 다르다. 의존성 문제를 자주 다루는 프로젝트라면 필요할 수 있다. 하지만 일반 기능 구현에서 매번 거대한 락파일이 컨텍스트에 끼어드는 것은 낭비다.
반대로 인덱싱되어야 하는 문서는 잘 관리해야 한다.
README.mddocs/architecture.mddocs/api.mddocs/design-system.mddocs/product-decisions.md주요 모듈의
README.md
대형 코드베이스에서는 문서가 Agent의 지도 역할을 한다. 코드 전체를 매번 읽히는 대신, "이 기능은 어느 모듈에 있고 어떤 규칙을 따른다"는 안내판을 제공하는 것이다.
작업 패키지를 만들어라
실전에서는 컨텍스트를 하나의 작업 패키지로 묶어 주는 것이 가장 안정적이다. 작업 패키지는 Agent가 일을 시작하기 전에 받아야 할 최소 자료 묶음이다.
기능 구현이라면 다음을 포함한다.
PRD 또는 미니 요구사항
Plan Mode에서 만든 구현 계획
수정 대상 파일 목록
참고할 기존 패턴 파일
적용해야 할 Rules 또는 Skills
외부 문서 링크나
@docs현재 브랜치의 변경 요약
제외 범위와 완료 기준
예시는 이렇다.
작업 패키지:
- 요구사항: @docs/prd/invite-flow.md
- 구현 계획: @.cursor/plans/invite-flow-plan.md
- 주요 수정 파일: @src/app/invite/page.tsx, @src/server/invite.ts
- 참고 패턴: @src/app/settings/page.tsx
- 현재 변경 맥락: @Branch
요청:
플랜의 2단계인 초대 링크 만료 상태 UI만 구현해 줘.
API 스키마와 DB 마이그레이션은 수정하지 마.
완료 후 변경 파일, 테스트 방법, 남은 리스크를 요약해 줘.이런 요청은 Agent에게 "무엇을 왜 바꾸는지"를 알려 준다. 단순히 파일을 고치는 것이 아니라 제품 의도, 구현 경계, 검증 기준을 함께 전달한다.
작업이 끝나면 마지막에 다시 요약을 남긴다.
이번 단계에서 바뀐 점, 확인한 테스트, 아직 결정하지 않은 사항,
다음 Agent가 이어받을 때 필요한 컨텍스트를 짧게 정리해 줘.이 요약이 다음 작업의 출발점이 된다. 컨텍스트 관리는 한 번 잘 붙이는 기술이 아니라, 작업이 진행될수록 불필요한 것은 버리고 중요한 것은 압축하는 습관이다.
컨텍스트 관리 체크리스트
작업을 시작하기 전에 다음을 확인하자.
수정 위치를 알고 있다면
@file이나@code를 먼저 썼는가?위치를 모른다면 바로 구현하지 말고
@codebase로 탐색하게 했는가?외부 라이브러리 동작은
@docs나@web으로 확인했는가?이전 결정이 필요하면
@Past Chats나 저장된 플랜을 붙였는가?현재 브랜치 변경이 중요하면
@Branch를 확인하게 했는가?수정 범위와 제외 범위를 명시했는가?
오래된 대화가 작업을 방해하고 있지는 않은가?
.cursorignore가 검색 공간을 깨끗하게 유지하고 있는가?단계가 끝날 때 다음 작업용 요약을 남겼는가?
AI 성능의 절반은 모델에서 오고, 나머지 절반은 컨텍스트에서 온다. Cursor를 잘 쓰는 사람은 프롬프트를 길게 쓰는 사람이 아니다. Agent가 지금 봐야 할 것과 보지 말아야 할 것을 구분하는 사람이다.
참고
1Mastering Context Management in Cursor
2Cursor Context Window: Limits, Workarounds, and Better Alternatives (2026)
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.