제5강: 프로젝트 컨텍스트 이해

AI가 프로젝트 전체를 이해하는 방법과 활용법

난이도: 초급 예상 시간: 35분 카테고리: 기초

학습 목표

  • Cursor의 프로젝트 인덱싱 시스템 이해하기
  • 컨텍스트가 AI 제안에 미치는 영향 파악하기
  • 프로젝트 구조 최적화 방법 익히기
  • .cursorignore와 설정 파일 활용하기
  • 대규모 프로젝트에서 효율적으로 작업하기

프로젝트 컨텍스트란?

프로젝트 컨텍스트는 Cursor AI가 전체 코드베이스를 이해하는 방식입니다. 파일 구조, 의존성, 코드 패턴, 그리고 프로젝트의 전반적인 아키텍처를 파악하여 더 정확하고 일관된 코드 제안을 제공합니다.

컨텍스트의 구성 요소

파일 구조

프로젝트의 디렉토리 구조와 파일 조직

코드 내용

함수, 클래스, 변수 정의 및 사용 패턴

의존성

import/export 관계와 모듈 간 연결

설정 파일

package.json, tsconfig 등 프로젝트 설정

인덱싱 시스템의 작동 방식

Cursor의 스마트 인덱싱

1. 프로젝트 스캔

프로젝트를 열면 자동으로 모든 파일을 스캔

→

2. 인덱스 구축

코드 구조와 관계를 분석하여 인덱스 생성

→

3. 실시간 업데이트

파일 변경 시 자동으로 인덱스 갱신

인덱싱 상태 확인

Indexing project... (2,341/5,000 files)

하단 상태바에서 인덱싱 진행 상황을 확인할 수 있습니다

컨텍스트가 AI에 미치는 영향

컨텍스트 있을 때 vs 없을 때

✅ 풍부한 컨텍스트

my-app/
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Card.tsx
│   ├── hooks/
│   │   └── useAuth.ts
│   └── utils/
│       └── api.ts
└── package.json

새 컴포넌트 생성 시:

// AI가 프로젝트 스타일을 이해하고 제안
import React from 'react';
import { useAuth } from '../hooks/useAuth';
import Button from './Button';

interface UserProfileProps {
  userId: string;
}

const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
  const { user, isLoading } = useAuth();
  
  // 프로젝트의 API 패턴을 따름
  const handleUpdate = async () => {
    await api.updateUser(userId, data);
  };
  
  return (
    <Card>
      {/* 기존 컴포넌트 활용 */}
      <Button onClick={handleUpdate}>Update</Button>
    </Card>
  );
};

❌ 컨텍스트 부족

동일한 요청에 대한 일반적인 제안:

// 일반적인 React 컴포넌트
function UserProfile({ userId }) {
  return (
    <div>
      <h1>User Profile</h1>
      <p>User ID: {userId}</p>
      <button>Update</button>
    </div>
  );
}

프로젝트 구조 최적화

AI 친화적인 프로젝트 구조

1. 명확한 폴더 구조

src/
├── components/     # UI 컴포넌트
├── pages/         # 페이지 컴포넌트
├── hooks/         # 커스텀 훅
├── utils/         # 유틸리티 함수
├── services/      # API 서비스
├── types/         # TypeScript 타입
└── styles/        # 스타일 파일

일관된 구조는 AI가 파일의 역할을 쉽게 이해하도록 돕습니다

2. 의미 있는 파일명

✅ 좋은 예:

  • UserProfileCard.tsx
  • useAuthenticationHook.ts
  • formatCurrency.util.ts

❌ 피해야 할 예:

  • comp1.tsx
  • utils.ts
  • helper.js

3. 모듈화와 관심사 분리

// ✅ 각 파일이 단일 책임을 가짐
// services/auth.service.ts
export const authService = {
  login: async (credentials) => { /* ... */ },
  logout: async () => { /* ... */ },
  refreshToken: async () => { /* ... */ }
};

// hooks/useAuth.ts
export const useAuth = () => {
  const [user, setUser] = useState(null);
  // auth 로직만 포함
};

// components/LoginForm.tsx
export const LoginForm = () => {
  const { login } = useAuth();
  // UI 로직만 포함
};

.cursorignore 파일 활용

.cursorignore란?

.gitignore와 유사하게, AI가 무시해야 할 파일과 폴더를 지정하는 파일입니다.

효과적인 .cursorignore 예제

# 빌드 출력물
dist/
build/
out/
.next/

# 의존성
node_modules/
vendor/

# 환경 파일
.env
.env.local
.env.*.local

# 로그 파일
logs/
*.log
npm-debug.log*

# 테스트 커버리지
coverage/
.nyc_output/

# IDE 설정
.vscode/
.idea/
*.swp
*.swo

# 대용량 에셋
*.mp4
*.mov
*.zip
*.tar.gz

# 생성된 파일
*.min.js
*.min.css
generated/

장점

  • 🚀 인덱싱 속도 향상
  • 💾 메모리 사용량 감소
  • 🎯 더 정확한 컨텍스트
  • 🔒 민감한 정보 보호

프로젝트별 AI 설정

.cursor/settings.json

프로젝트별 AI 동작을 커스터마이징할 수 있습니다:

{
  "ai": {
    "model": "gpt-4",
    "temperature": 0.7,
    "contextWindow": 8192
  },
  "features": {
    "tabAutocomplete": {
      "enabled": true,
      "delay": 200,
      "maxSuggestionLength": 500
    },
    "chat": {
      "defaultContext": ["*.ts", "*.tsx", "README.md"],
      "excludePatterns": ["*.test.ts", "*.spec.ts"]
    }
  },
  "codebase": {
    "language": "typescript",
    "framework": "react",
    "style": {
      "quotes": "single",
      "semicolons": true,
      "indentation": 2
    }
  }
}

커스텀 컨텍스트 규칙

.cursorrules 파일

# 프로젝트 규칙
- 모든 컴포넌트는 함수형으로 작성
- TypeScript 엄격 모드 사용
- 상태 관리는 Zustand 사용
- API 호출은 반드시 try-catch로 감싸기
- 모든 함수에 JSDoc 주석 추가

# 코딩 스타일
- camelCase for 변수와 함수
- PascalCase for 컴포넌트와 타입
- UPPER_SNAKE_CASE for 상수

# 금지 사항
- var 키워드 사용 금지
- any 타입 사용 최소화
- console.log는 개발 중에만

대규모 프로젝트 최적화

성능 최적화 전략

1. 선택적 인덱싱

작업 중인 모듈만 집중적으로 인덱싱:

# .cursorignore에 추가
# 현재 작업하지 않는 모듈
legacy/
archived/
experiments/

2. 워크스페이스 분리

모노레포의 경우 개별 워크스페이스로 작업:

// 각 패키지를 별도로 열기
cursor packages/frontend
cursor packages/backend
cursor packages/shared

3. 심볼릭 링크 활용

자주 참조하는 파일들을 가까이 배치:

# 중요한 참조 파일 링크
ln -s ../../shared/types ./src/types
ln -s ../../shared/utils ./src/utils

실습: 프로젝트 컨텍스트 최적화

React 프로젝트 설정하기

AI가 최대한 효과적으로 도와줄 수 있도록 프로젝트를 구성해봅시다.

Step 1: 프로젝트 구조 생성

mkdir my-react-app && cd my-react-app
npx create-react-app . --template typescript
cursor .

Step 2: .cursorignore 생성

# .cursorignore
node_modules/
build/
coverage/
.env
*.log

# React 관련 무시 파일
public/
src/serviceWorker.ts
src/setupTests.ts
src/logo.svg

Step 3: .cursorrules 작성

# React 프로젝트 규칙
- React 18+ 기능 활용
- 함수형 컴포넌트와 Hooks 사용
- TypeScript strict 모드
- CSS Modules 또는 styled-components

# 폴더 구조
- components/: 재사용 가능한 UI 컴포넌트
- pages/: 라우트별 페이지 컴포넌트
- hooks/: 커스텀 React Hooks
- utils/: 유틸리티 함수
- services/: API 통신 로직

# 네이밍 컨벤션
- 컴포넌트: PascalCase (예: UserProfile.tsx)
- 훅: camelCase with 'use' prefix (예: useAuth.ts)
- 유틸: camelCase (예: formatDate.ts)

Step 4: 컨텍스트 테스트

AI Chat을 열고 다음을 질문해보세요:

"이 프로젝트의 구조를 설명해줘"

"Button 컴포넌트를 프로젝트 스타일에 맞게 만들어줘"

"현재 프로젝트에서 사용 중인 의존성 목록을 보여줘"

문제 해결

인덱싱이 너무 오래 걸려요

  • 불필요한 파일을 .cursorignore에 추가
  • node_modules나 dist 폴더가 포함되지 않았는지 확인
  • 프로젝트를 더 작은 워크스페이스로 분리

AI가 프로젝트 스타일을 따르지 않아요

  • .cursorrules 파일 생성 및 규칙 명시
  • 예제 코드를 충분히 작성하여 패턴 학습
  • 일관된 코딩 스타일 유지

특정 파일이 인덱싱되지 않아요

  • .cursorignore에 해당 파일이 포함되지 않았는지 확인
  • 파일 크기가 너무 크지 않은지 확인 (10MB 이상)
  • 파일 인코딩이 UTF-8인지 확인

핵심 정리

프로젝트 전체 이해

Cursor는 단순히 현재 파일만이 아닌 전체 프로젝트의 구조와 패턴을 이해합니다.

컨텍스트가 품질을 결정

풍부한 컨텍스트는 더 정확하고 프로젝트에 맞는 코드 제안으로 이어집니다.

최적화는 필수

.cursorignore와 프로젝트 구조 최적화로 성능과 정확도를 크게 향상시킬 수 있습니다.

커스터마이징 가능

프로젝트별 설정과 규칙으로 AI의 동작을 세밀하게 조정할 수 있습니다.

다음 강의 예고

다음 강의에서는 GPT-4, Claude 등 다양한 AI 모델을 선택하고 활용하는 방법을 배웁니다.

다음 강의로 이동
5/30 완료