Cursor @Codebase, @Docs, @Files 중 무엇을 써야 할까? 실전 상황별 선택 가이드

Cursor의 @ 기호 시스템은 겉보기에는 단순합니다. @Codebase, @Files, @Docs를 클릭하면 AI에 컨텍스트를 추가할 수 있습니다. 하지만 실제로 써 보면 많은 사람이 같은 지점에서 막힙니다. 어떤 코드를 찾아야 하는지는 알겠는데, 어떤 기호를 써야 할지 헷갈리는 것입니다.

기호를 잘못 고르면 AI는 관련 없는 내용을 잔뜩 넣거나, 정작 필요한 파일을 찾지 못합니다. 시간이 지나면 대화 기록에는 반복 조회가 쌓이고, Token은 많이 쓰는데 문제는 여전히 명확히 해결되지 않습니다.

이 글은 기능 정의를 나열하지 않습니다. 한 가지에 집중합니다. 구체적인 상황에서 어떤 @ 기호를 골라야 하는지 빠르게 판단하는 방법입니다. 읽고 나면 매번 망설이지 않고 결정할 수 있는 기준이 생길 것입니다.

1. @ 기호 시스템 핵심 비교: 6가지 기능 한눈에 보기

먼저 중요한 결론부터 말하겠습니다. BetterLink Blog의 실전 통계 기준으로 개발 시간의 80%는 파일을 직접 고르는 대신 @Codebase를 쓰는 편이 좋습니다. 숫자만 보면 과장처럼 들리지만, 이유는 단순합니다. @Codebase의 핵심 장점은 검색이 아니라, 내가 놓쳤을 수 있는 관련 코드를 AI가 발견해 주는 데 있습니다.

아래 6가지 기호를 사용 빈도가 높은 순서로 정리하면 다음과 같습니다.

@Codebase(60-80%): 전체 코드베이스 의미 검색입니다. 질문을 던지면 AI가 코드베이스에서 가장 관련 있는 파일, 함수, 타입 정의를 자동으로 찾습니다. 파일이 어디 있는지 알 필요도 없고 직접 선택할 필요도 없습니다. 프로젝트 아키텍처 이해, 코드 리팩터링, 여러 파일에 걸친 문제 추적에 적합합니다. 인덱스가 전체 코드베이스를 덮기 때문에 Token 소모는 비교적 큽니다.

@Docs(10-15%): 외부 문서를 참조합니다. React, Vue, Astro 같은 내장 프레임워크 문서를 바로 호출할 수 있고, URL로 사용자 지정 문서 소스를 추가할 수도 있습니다. 새로 출시된 라이브러리를 쓰거나, 최신 API 규칙을 확인하거나, 팀 지식 베이스를 연결할 때 적합합니다.

@Files(5-10%): 특정 파일의 전체 내용을 정확히 참조합니다. 파일명을 명확히 알고 있거나 vite.config.ts 같은 설정 파일을 수정할 때 사용합니다. 파일이 600줄을 넘는다면 @Files가 @Codebase보다 더 정확합니다. 대신 전체 파일 내용이 컨텍스트에 들어가므로 Token 소모가 큽니다.

@Code(5-10%): 정확한 코드 조각을 참조합니다. 선택한 부분만 넣고 전체 파일은 가져오지 않습니다. 로컬 코드 최적화, 작은 로직 디버깅, 파일 단위 컨텍스트 오염 방지에 적합합니다. Token 소모가 가장 낮습니다.

@Folders(5% 이하): 전체 디렉터리의 구조와 내용 개요를 참조합니다. 모듈 리팩터링, 새 컴포넌트 생성, 아키텍처 일관성 점검에 적합합니다. 여러 파일이 엮이므로 Token 소모가 큽니다.

@Repo(특정 상황): Repository context를 제공합니다. 여러 저장소가 얽힌 프로젝트, 버전 이력 분석, repo 간 문제 추적에 적합합니다. Token 소모는 중간 정도입니다.

이 6가지 기호는 서로 배타적이지 않습니다. 같은 대화 안에서 조합할 수 있습니다. 예를 들어 먼저 @Codebase로 전체 정보를 얻고, @Files로 핵심 파일을 고정한 뒤, 마지막에 @Docs로 공식 문서 근거를 보강할 수 있습니다. 중요한 것은 문제 유형에 맞춰 선택하는 것이지, 무작정 쌓아 올리는 것이 아닙니다.

2. 의사결정 트리: 문제 유형에서 @ 기호 선택까지

기호 선택의 핵심 논리는 질문 하나로 요약됩니다. 코드가 어디에 있는지 알고 있나요?

모른다면 @Codebase를 씁니다. 안다면 @Files 또는 @Code를 씁니다. 문서 설명이 더 필요하면 @Docs를 추가합니다.

조금 더 구체적으로 살펴보겠습니다.

상황 1: 파일 위치를 모를 때
예를 들어 Next.js 프로젝트를 리팩터링하다가 어떤 API의 반환 형식을 바꾸고 싶어졌다고 해 보겠습니다. 그런데 타입 정의가 어디 있는지 확실하지 않습니다. types/에 있을 수도 있고, components/에 있을 수도 있고, 어떤 utils.ts 파일에 임시로 정의되어 있을 수도 있습니다.

이럴 때는 @Codebase를 씁니다. Chat에 바로 이렇게 적으면 됩니다. “ApiResponse 타입 정의를 찾아 반환 형식을 수정해 줘.” AI는 전체 코드베이스를 스캔해 이 타입을 참조하는 모든 위치를 찾아냅니다. 내가 놓쳤을 수 있는 utils.ts까지 포함해서 말입니다.

상황 2: 파일명을 명확히 알 때
예를 들어 vite.config.ts의 프록시 설정을 바꾸거나, src/utils/auth.ts의 특정 함수를 리팩터링한다고 해 보겠습니다. 파일 경로가 명확하고, 내용도 꽤 깁니다. 600줄을 넘을 수도 있습니다.

이럴 때는 @Files를 씁니다. @Files를 클릭하고 대상 파일을 선택하면 AI가 전체 내용을 가져옵니다. @Codebase보다 더 정확하며, AI가 “관련 있지만 중요하지 않은” 파일을 잔뜩 반환하는 일을 피할 수 있습니다.

상황 3: 최신 문서를 확인해야 할 때
방금 출시된 라이브러리를 사용하거나, 프레임워크의 최신 API 사용법을 확인해야 할 때가 있습니다. AI의 훈련 데이터가 아직 그 내용을 포함하지 못했을 가능성이 있습니다.

이럴 때는 @Docs를 씁니다. @Docs를 입력해 내장 프레임워크 문서를 선택하거나 URL을 붙여 새 문서 소스를 추가합니다. 핵심은 prompt에 “문서의 최신 사용법을 기준으로 작성해 달라”고 강조하는 것입니다. 그렇지 않으면 AI가 기억 속의 오래된 API를 사용할 수 있습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

상황 4: 특정 코드 조각만 볼 때
어떤 함수의 로직을 디버깅 중이고, 몇 줄만 최적화하면 됩니다. 전체 파일을 컨텍스트에 넣고 싶지 않습니다.

이럴 때는 @Code를 씁니다. 해당 코드 조각을 선택하고 Cmd+K로 인라인 편집을 실행하거나, Chat에서 @Code로 참조합니다. Token 소모가 가장 낮고 컨텍스트도 가장 깔끔합니다.

상황 5: 모듈 리팩터링 또는 새 컴포넌트 생성
components/ 디렉터리 전체를 리팩터링하거나 새 features/ 모듈을 만들어야 하고, 기존 아키텍처와의 일관성을 지켜야 한다고 해 보겠습니다.

이럴 때는 @Folders를 씁니다. 디렉터리 구조 개요와 핵심 파일 내용을 가져오므로, AI가 모듈의 조직 방식을 이해하고 기존 스타일에 맞는 코드를 만들 수 있습니다.

상황 6: 여러 저장소 또는 버전 이력 분석
프로젝트가 여러 Git 저장소에 의존하거나, 특정 commit의 영향 범위를 분석해야 할 때가 있습니다.

이럴 때는 @Repo를 씁니다. 버전 이력과 저장소 간 의존 관계를 포함한 Repository context를 제공합니다.

간단히 말해 의사결정 트리의 핵심은 한 문장입니다. 위치가 불확실하면 @Codebase, 위치를 알면 @Files/@Code, 문서가 부족하면 @Docs입니다. 나머지 두 기호인 @Folders와 @Repo는 특정 상황을 보완하는 선택지입니다.

3. @Codebase vs @Files: 핵심 차이와 실전 사례

이 두 기호는 가장 헷갈리기 쉽습니다. 차이는 하나입니다. AI가 찾아 주게 할 것인가, 내가 직접 가리킬 것인가입니다.

@Codebase의 가치는 “검색”이 아니라 “발견”입니다. 질문 하나를 던지면 AI가 전체 코드베이스에서 의미 기반 매칭을 수행하고 가장 관련 있는 파일, 함수, 타입 정의를 반환합니다. 중요한 점은 내가 생각하지 못한 파일까지 반환할 수 있다는 것입니다. 예를 들어 “API 반환 형식을 어떻게 바꾸나요?”라고 물으면 AI는 다음과 같은 파일을 반환할 수 있습니다.

• API handler 파일, 즉 내가 예상한 파일
• 타입 정의 파일, 아마 알고 있었을 파일
• 어떤 utils.ts 안에 임시로 정의된 타입 별칭, 놓쳤을 수 있는 파일
• 테스트 파일 안의 mock 데이터, 전혀 신경 쓰지 않았을 수 있는 파일

이것이 @Codebase의 핵심 장점입니다. AI가 내가 놓쳤을 가능성이 있는 관련 코드를 발견해 줍니다.

@Files의 가치는 “정확성”입니다. 파일을 명확히 지정하면 AI는 전체 내용을 가져오고 해석에 모호성이 없습니다. 대신 파일이 어디 있는지 알아야 하며, 전체 파일 내용이 컨텍스트에 들어가므로 더 많은 Token을 감수해야 합니다.

실전 사례 1: API 반환 형식 수정(@Codebase가 더 적합)

상황은 이렇습니다. Next.js API가 있고 반환 형식은 다음과 같습니다.

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

반환 형식을 { users, count }로 바꾸고 싶지만 타입 정의가 어디 있는지 확실하지 않습니다.

@Files를 쓴다면 관련 파일을 직접 찾아야 합니다. route.ts, 어딘가 있을 types.ts, 이 API를 호출하는 프론트엔드 컴포넌트까지 말입니다. 이 과정에서는 파일을 놓치기 쉽습니다.

@Codebase를 쓰면 Chat에 바로 이렇게 적으면 됩니다.

@Codebase
사용자 API의 반환 형식을 { data, total }에서 { users, count }로 바꿔 줘.
관련 타입 정의와 프론트엔드 호출 코드도 함께 수정해야 해.

AI는 다음처럼 반환합니다.

다음 관련 파일을 찾았습니다.
1. src/app/api/users/route.ts - API handler
2. src/types/api.ts - ApiResponse 타입 정의
3. src/components/UserList.tsx - 프론트엔드 컴포넌트(API 호출)
4. src/utils/mock.ts - 테스트 mock 데이터, 같은 형식 사용

이때 mock.ts도 같은 형식을 사용한다는 것을 한눈에 알 수 있습니다. 이전에는 전혀 신경 쓰지 않았던 파일일 수 있습니다.

실전 사례 2: vite.config.ts 설정 최적화(@Files가 더 적합)

상황은 이렇습니다. Vite의 프록시 설정을 수정하려고 합니다. 파일 경로는 명확합니다. vite.config.ts입니다.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

목표는 개발, 테스트, 프로덕션 등 여러 환경을 지원하도록 프록시를 바꾸는 것입니다.

이 경우에는 @Files가 더 적합합니다. 이유는 세 가지입니다.

1. 파일 위치가 명확합니다.
2. 내용이 길지 않습니다. 보통 50-200줄입니다.
3. 여러 파일을 넘나들며 찾을 필요가 없습니다.

Chat에는 이렇게 적으면 됩니다.

@Files vite.config.ts
프록시 설정을 개발, 테스트, 프로덕션 여러 환경을 지원하도록 수정해 줘.
환경 설정은 .env.development, .env.test, .env.production에서 읽어 와.

AI는 전체 vite.config.ts를 가져와 바로 수정안을 제시합니다.

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

정리하면 이렇습니다. 위치를 모르거나 숨은 관련 코드를 발견해야 한다면 @Codebase, 위치를 알고 있거나 긴 파일을 완전히 이해해야 한다면 @Files를 쓰면 됩니다.

4. @Docs: 새 라이브러리 사용과 문서 통합

@Docs가 해결하는 문제는 분명합니다. AI의 훈련 데이터가 문서 업데이트를 따라가지 못한다는 것입니다.

예를 들어 지난주에 출시된 라이브러리를 쓰거나, 어떤 프레임워크가 API 사용법을 바꾼 경우가 있습니다. React 19의 새 hooks, Next.js 15의 Turbopack 같은 예입니다. AI의 훈련 데이터가 몇 달 전 상태에 머물러 있다면 코드를 생성할 때 오래된 API를 사용할 수 있습니다.

@Docs의 원리는 이렇습니다. 지정한 문서를 실시간으로 검색하고 내용을 파싱한 뒤 컨텍스트에 넣습니다. AI는 코드를 생성할 때 문서 안의 최신 규칙을 우선 참고합니다.

사용 방법

사용법은 간단합니다.

1. Chat에 @Docs를 입력합니다.
2. React, Vue, Astro, Tailwind, Next.js 같은 내장 프레임워크 문서를 선택합니다.
3. 또는 URL을 붙여 넣어 사용자 지정 문서 소스를 추가합니다.

사용자 지정 문서 소스는 꽤 실용적입니다. 예를 들어 팀 내부 지식 베이스가 Feishu 문서나 GitHub Wiki에 있다면 URL을 추가할 수 있습니다. 그러면 AI가 팀 규칙을 참고해 코드를 생성할 수 있습니다.

실전 사례: React 19 새 hooks

React 19의 useOptimistic hook을 쓰고 싶은데 최신 사용법이 확실하지 않다고 해 보겠습니다.

Chat에 바로 이렇게 씁니다.

@Docs React
React 19의 useOptimistic hook으로 optimistic update 기능을 구현해 줘.
상황: 좋아요 버튼을 클릭하면 즉시 +1을 표시하고, 서버 확인을 기다린다.

AI는 먼저 React 공식 문서를 검색해 최신 useOptimistic API 설명을 가져온 뒤, 규칙에 맞는 코드를 생성합니다.

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // 즉시 +1 표시
    await onSubmit();     // 서버 확인 대기
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

주의할 점: 훈련 데이터가 @Docs를 덮을 수 있음

주의해야 할 함정이 하나 있습니다. AI는 훈련 데이터와 @Docs를 동시에 참고할 수 있습니다. 훈련 데이터의 오래된 사용법이 더 강하게 남아 있으면 새 API와 오래된 API를 섞어 이상한 코드를 만들 수 있습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

해결책은 prompt에 “문서의 최신 사용법을 기준으로 작성해 달라”고 강조하는 것입니다.

예를 들면 다음과 같습니다.

@Docs React
문서의 최신 사용법, 즉 React 19 기준으로 작성해 줘.
훈련 데이터에 있는 오래된 API는 사용하지 마.

이렇게 쓰면 AI가 @Docs 내용을 우선 참고하고, 오래된 버전의 영향을 줄일 수 있습니다.

언제 @Docs를 써야 할까?

간단한 판단 기준은 이렇습니다. 라이브러리나 프레임워크 출시 시점이 AI 훈련 마감일보다 늦거나, API가 크게 업데이트되었다면 @Docs를 쓰세요.

예를 들면 다음과 같습니다.

• React 19: 2024년 말 출시, 주요 API 업데이트
• Next.js 15: 2024년 말, Turbopack 기본 활성화
• Supabase 최신 기능: 문서가 계속 실시간으로 바뀜
• 팀 내부 규칙: AI 훈련 데이터에는 있을 수 없음

반대로 라이브러리가 안정적이라면, 예를 들어 React 18, Vue 3, Tailwind 3처럼 훈련 데이터가 잘 덮고 있는 경우에는 @Docs의 필요성이 크지 않습니다.

5. 컨텍스트 관리 모범 사례

@ 기호를 잘 쓰는 것은 첫 단계일 뿐입니다. 두 번째 단계는 컨텍스트를 잘 관리하는 것입니다. 많은 사람이 이 함정에 빠집니다. 대화 기록이 길어질수록 AI의 이해가 흐려지고, 마지막에는 원래 의도와 전혀 다른 코드가 생성됩니다.

핵심 원칙: 대화는 짧게, 기능은 나눠서

기능 하나를 끝냈다면 대화를 새로 시작하세요. “API 리팩터링”, “Bug 수정”, “새 기능 추가”를 한 대화에 섞지 않는 편이 좋습니다.

왜 그럴까요? 기능마다 필요한 컨텍스트가 다르기 때문입니다. API를 리팩터링할 때 AI가 필요한 것은 타입 정의, API handler, 프론트엔드 호출 코드입니다. Bug를 고칠 때 필요한 것은 오류 로그, 관련 코드 조각, 테스트 케이스입니다. 이것들을 섞으면 컨텍스트가 점점 복잡해지고, AI의 이해는 점점 흐려집니다.

간단한 방법은 Chat 패널 오른쪽 위의 “Clear Chat”을 누르거나 단축키로 새 대화를 여는 것입니다.

작은 수정 vs 복잡한 작업

두 상황에는 서로 다른 방식을 사용합니다.

작은 수정, 예를 들어 코드 한 줄을 바꾸거나 매개변수 하나를 조정하는 경우: 인라인 편집(Cmd+K)을 씁니다. 대상 코드를 선택하고 Cmd+K를 누른 뒤 수정 지시를 입력합니다. 현재 파일과 선택한 내용이 자동으로 컨텍스트가 되므로 추가 설정이 필요 없습니다.

복잡한 작업, 예를 들어 모듈 리팩터링이나 새 컴포넌트 생성: Chat과 @-mentions를 함께 씁니다. 먼저 @Codebase로 전체 정보를 얻고, 다시 @Files로 핵심 파일을 고정한 뒤, 작업 설명을 명확히 적습니다. 이렇게 하면 컨텍스트가 더 완전해지고 AI의 이해도 더 정확해집니다.

인덱스 최적화: .cursorignore로 방해 파일 제외하기

@Codebase의 인덱스는 전체 코드베이스를 덮지만, 모든 파일을 AI가 볼 필요는 없습니다.

예를 들어 다음과 같은 파일은 제외하는 편이 좋습니다.

• node_modules/: 의존성 라이브러리라 AI가 볼 필요가 없습니다.
• dist/, build/: 빌드 산출물입니다.
• .env, .env.local: 민감한 설정입니다.
• 대형 정적 자원: 이미지와 동영상입니다.

이런 디렉터리는 .cursorignore 파일로 제외합니다. .gitignore와는 별도로 관리하고, 기준은 단순합니다. AI가 이 파일을 볼 필요가 있는가?

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

이렇게 하면 @Codebase의 인덱스 범위가 더 정확해지고, 조회 속도도 빨라집니다. 5-10초 걸리던 조회가 2-3초로 줄어들고, 반환 결과도 더 관련성이 높아집니다.

README.md를 정기적으로 업데이트하기

쉽게 놓치는 습관이 하나 있습니다. README.md에 프로젝트 상태와 구조를 기록하는 것입니다.

왜 중요할까요? README.md는 @Codebase 인덱스의 핵심 파일 중 하나입니다. AI가 프로젝트 아키텍처를 이해할 때 README를 우선 참고하는 경우가 많습니다. README에 다음 내용이 명확히 적혀 있다면 도움이 됩니다.

• 프로젝트 구조: 디렉터리별 설명
• 핵심 모듈: 어떤 파일이 어떤 기능을 담당하는지
• 최근 변경 사항: 새 기능, 리팩터링 계획

AI는 복잡한 작업을 처리할 때 전체 구조를 더 빨리 이해하고, 반복 조회를 줄일 수 있습니다.

Pro 사용자의 장점: 더 넓은 인덱스 범위

Cursor Pro 사용자는 전체 코드베이스의 의미 정보를 인덱싱할 수 있습니다. Free 사용자는 인덱스 범위에 제한이 있습니다. 프로젝트가 500개 파일을 넘는다면 Pro 버전의 @Codebase 효과가 확실히 더 좋아질 수 있습니다.

그렇다고 Free 사용자가 활용할 방법이 없는 것은 아닙니다. 핵심은 여전히 같습니다. 컨텍스트를 관리하고, 올바른 기호를 쓰고, 방해 파일을 제외하는 것입니다. Pro는 있으면 좋은 강화 요소이지, 반드시 있어야 하는 전제는 아닙니다.

6. 자주 묻는 질문과 해결책 FAQ

문제 1: @Codebase 결과가 실제 코드베이스와 다름

증상은 이렇습니다. 방금 어떤 파일을 수정했는데 @Codebase가 여전히 예전 내용을 반환합니다. 또는 분명히 존재하는 파일을 @Codebase가 찾지 못합니다.

원인은 인덱스가 아직 동기화되지 않았기 때문입니다.

해결 방법은 다음과 같습니다.

1. Cursor Settings -> “Reindex Codebase”를 눌러 강제로 다시 인덱싱합니다.
2. 또는 프로젝트 폴더를 제거한 뒤 다시 추가합니다. 이 방법이 더 확실합니다.

이 작업은 1-2분 정도 기다려야 합니다. 인덱싱이 끝나면 문제가 사라집니다.

문제 2: @Codebase가 잘못된 파일을 매칭함

증상은 이렇습니다. “UserService를 어떻게 수정하나요?”라고 물었는데, AI가 예상한 services/UserService.ts가 아니라 utils/user.ts를 반환합니다.

원인은 의미 기반 매칭의 모호성입니다. AI가 관련성을 잘못 판단했을 수 있습니다.

해결 방법은 다음과 같습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

1. @Files로 올바른 파일을 명확히 지정합니다.
2. 또는 prompt에 파일 경로를 적습니다. 예: “src/services/UserService.ts를 수정해 줘.”

@Codebase의 장점은 자동 발견이지만, 그 대가로 오차가 있을 수 있습니다. 정밀한 작업에는 @Files가 더 적합합니다.

문제 3: @Docs를 붙였는데 AI가 오래된 API를 사용함

증상은 이렇습니다. @Docs React를 추가했는데 AI가 여전히 React 18 방식의 코드를 생성합니다.

원인은 훈련 데이터의 기존 인상이 너무 강해 @Docs 내용을 덮었기 때문입니다.

해결 방법은 prompt에 다음처럼 강조하는 것입니다.

@Docs React
문서의 최신 사용법, 즉 React 19 기준으로 작성해 줘.
훈련 데이터에 있는 오래된 API는 사용하지 마.

이 문장을 추가하면 AI가 @Docs를 우선 참고합니다.

문제 4: @Codebase 조회가 너무 느림(5-10초)

증상은 이렇습니다. @Codebase를 쓸 때마다 오래 기다려야 합니다.

원인은 인덱스 범위가 너무 넓기 때문입니다. 예를 들어 node_modules나 dist 같은 디렉터리가 포함되어 있을 수 있습니다.

해결 방법은 .cursorignore 설정을 확인하고 불필요한 파일을 제외하는 것입니다.

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

제외 후 인덱스 범위가 줄어들면 조회 속도는 2-3초 수준으로 내려갑니다.

문제 5: 대화 기록이 너무 길어 AI 이해가 흐트러짐

증상은 이렇습니다. 한 대화 안에서 이미 서너 가지 기능을 논의했고, AI의 답변이 점점 원래 의도에서 벗어납니다.

원인은 컨텍스트 오염입니다. 각 기능의 컨텍스트가 한꺼번에 섞인 것입니다.

해결 방법은 대화를 새로 시작하는 것입니다. Chat 패널 오른쪽 위의 “Clear Chat”을 눌러 새 대화를 엽니다. 기능마다 따로 처리하면 컨텍스트가 더 깔끔해집니다.

문제 6: Token 소모가 너무 높아 예산을 초과함

증상은 이렇습니다. 대화할 때마다 많은 Token을 쓰고, Pro 한도가 빠르게 줄어듭니다.

원인은 기호 선택이 부적절해서 관련 없는 내용이 너무 많이 들어갔기 때문입니다.

해결 방법은 다음과 같습니다.

1. 작은 수정은 Cmd+K 인라인 편집을 사용합니다. @-mentions를 트리거하지 않습니다.
2. 정밀한 작업은 @Files/@Code를 사용해 @Codebase가 “관련 있어 보이지만 실제로는 불필요한” 파일을 많이 반환하지 않게 합니다.
3. .cursorignore로 node_modules, dist 같은 큰 파일을 제외합니다.

Token 소모 관리의 핵심 원칙은 정확히 참조하고 전체 코드베이스 검색을 피하는 것입니다.

마무리

Cursor의 @ 기호 시스템에서 핵심 논리는 한 문장입니다. 위치가 불확실하면 @Codebase, 위치를 알면 @Files/@Code, 문서가 부족하면 @Docs입니다.

개발 시간의 80%는 @Codebase를 쓰는 편이 좋습니다. 과장이 아닙니다. @Codebase의 진짜 가치는 “발견”에 있습니다. AI는 내가 놓쳤을 가능성이 있는 관련 코드를 찾아냅니다. 예를 들어 utils.ts에 임시로 정의된 타입 별칭이나 테스트 파일 안의 mock 데이터 같은 것들입니다.

하지만 @Codebase가 만능은 아닙니다. 파일이 600줄을 넘거나 위치를 명확히 알고 있다면 @Files가 더 정확합니다. 작은 코드 조각을 디버깅할 때는 @Code가 가장 Token을 아낍니다. 새 라이브러리나 최신 API를 쓸 때는 @Docs를 추가해 규칙의 정확성을 확보해야 합니다.

컨텍스트 관리도 중요합니다. 대화는 짧게 유지하고 기능은 나누세요. 작업 하나를 끝낸 뒤에는 새 대화를 시작해 기록이 점점 복잡해지지 않게 합니다. .cursorignore로 방해 파일을 제외하고 README.md를 정기적으로 업데이트하면 AI의 이해가 더 정확해집니다.

다음에 개발할 때는 먼저 스스로에게 물어보세요. 파일 위치를 알고 있는가, 아니면 AI가 관련 코드를 찾아야 하는가? 확실하지 않다면 먼저 @Codebase를 쓰세요. AI가 숨은 관련성을 찾아 줄 것입니다. 확실하다면 정확히 참조해 컨텍스트 오염을 피하세요.

이 기호 체계를 제대로 쓰면 Cursor는 단순히 많은 내용을 반환하는 검색 도구가 아니라, 실제로 함께 코딩하는 파트너가 될 수 있습니다.