AI 코딩 도구의 컨텍스트를 잘 쓰는 법

AI 코딩 도구를 처음 쓸 때 가장 흔한 불만이 "맥락을 모른다"는 거다. 우리 프로젝트의 컨벤션, 사용하는 라이브러리, 선호하는 패턴 — 이런 걸 모르니까 매번 다른 스타일의 코드를 만들어낸다. 한 파일에서는 axios를 쓰고 다른 파일에서는 fetch를 쓰는 식이다.

이 문제를 해결하는 게 프로젝트 컨텍스트 파일이다. Cursor에서는 .cursorrules, Claude Code에서는 CLAUDE.md. 이름은 다르지만 역할은 같다. AI에게 "이 프로젝트에서는 이렇게 해"라고 알려주는 설명서다.

왜 필요한가#

AI는 프롬프트에 없는 것은 모른다. "Server Actions를 쓰세요"라고 안 쓰면 API Route를 만든다. "named export를 쓰세요"라고 안 쓰면 default export를 쓴다. 매번 채팅에서 수정 요청을 할 수도 있지만, 컨텍스트 파일에 한 번 적어두면 모든 대화에 자동으로 적용된다.

구조: 뭘 넣어야 하나#

세 가지 카테고리로 나눈다.

1. 기술 스택과 제약 조건#

프로젝트가 어떤 도구를 쓰는지 명시한다. 의외로 이게 가장 중요하다.

markdown

## 기술 스택
- Next.js 15 App Router (Pages Router 아님)
- TypeScript strict mode
- Tailwind CSS (CSS Modules 사용하지 않음)
- TanStack Query v5 (React Query)
- Prisma + PostgreSQL

"Pages Router 아님", "CSS Modules 사용하지 않음" 같은 부정형이 핵심이다. AI는 비슷한 기술 중 아무거나 골라서 쓰려 하니까, 안 쓰는 걸 명시적으로 배제해야 한다.

2. 코드 컨벤션#

팀이 합의한 패턴을 적는다.

markdown

## 컨벤션
- 컴포넌트는 named export (default export 사용하지 않음)
- 서버 컴포넌트 기본. 클라이언트 컴포넌트는 파일 최상단에 'use client'
- API 호출은 Server Actions으로. API Route는 웹훅 등 외부 연동에만 사용
- 에러 처리: try-catch 대신 Result 타입 패턴 사용
- 테스트: Vitest + Testing Library. E2E는 Playwright
- 커밋 메시지: Conventional Commits (feat:, fix:, chore:)

3. 프로젝트 구조#

디렉토리 구조와 각 역할을 설명한다.

markdown

## 프로젝트 구조
- app/ — Next.js App Router 라우트
- components/ — 공유 UI 컴포넌트
- features/ — 도메인별 기능 모듈 (components, hooks, actions)
- lib/ — 유틸리티, 설정, 외부 서비스 클라이언트
- prisma/ — DB 스키마, 마이그레이션

효과적인 작성법#

구체적으로 쓴다. "깔끔한 코드를 작성하세요"는 의미 없다. "함수는 20줄 이내, 매개변수는 3개 이내"가 실행 가능한 지시다.

markdown

# 나쁜 예
- 좋은 코드를 작성하세요
- 성능을 고려하세요

# 좋은 예
- 하나의 함수는 하나의 책임만
- 컴포넌트 props는 5개를 넘지 않도록. 넘으면 객체로 묶기
- 이미지는 next/image 사용. 외부 이미지는 next.config.js에 도메인 등록

하지 말 것을 명시한다. AI가 자주 하는 실수를 "하지 마라"로 적는다.

markdown

## 하지 않는 것
- any 타입 사용하지 않음
- console.log를 커밋하지 않음 (디버깅 후 제거)
- 인라인 스타일 사용하지 않음 (Tailwind 사용)
- useEffect 안에서 데이터 fetching하지 않음 (Server Components 또는 TanStack Query 사용)
- index.ts에서 re-export하지 않음 (직접 import)

예시 코드를 넣는다. 말로 설명하기 어려운 패턴은 코드 예시가 효과적이다.

markdown

## Server Action 패턴 예시
```typescript
'use server'

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;

  const post = await prisma.post.create({
    data: { title },
  });

  revalidatePath('/posts');
  return post;
}
```

유지보수#

컨텍스트 파일도 코드처럼 관리해야 한다. 프로젝트가 발전하면서 컨벤션이 바뀌면 업데이트해야 한다. 안 쓰는 라이브러리가 남아 있으면 AI가 그걸 계속 쓰려고 한다.

팀 프로젝트라면 컨텍스트 파일을 코드 리뷰 대상에 포함시키는 것도 좋다. 새 팀원이 합류했을 때 컨텍스트 파일을 읽으면 프로젝트 컨벤션을 빠르게 파악할 수 있다. AI를 위해 만든 문서가 사람에게도 유용하다.

길게 쓸 필요는 없다. 50줄이면 충분하다. AI에게 가장 중요한 건 "여기서는 이렇게 하고, 저건 하지 마라"는 명확한 경계선이다.