AI 코딩으로 대규모 리포지토리를 정확하게 이해시키기 위한 컨텍스트 설계 및 프롬프트 구축 기법

GitHub Copilot이나 Cursor, Claude 3.5 Sonnet 등의 AI 코딩 어시스턴트는 일상적인 개발에서 강력한 도구입니다. 하지만 대규모 리포지토리나 복잡한 마이크로 서비스 그룹을 대상으로 할 경우 다음과 같은 문제가 자주 발생합니다.

• 컨텍스트 창 고갈: 리포지토리 전체의 코드를 그대로 읽히면 토큰 상한에 도달하거나 처리 비용이 급증합니다.
• '길을 잃는' AI: 관련성이 낮은 파일이나 오래된 코드를 컨텍스트에 포함시켜, AI가 잘못된 의존 관계나 오래된 API 사양에 기반한 코드를 생성합니다.
• 환각(Hallucination) 유발: 디렉토리 구조나 모듈 간의 경계가 모호하기 때문에 존재하지 않는 함수나 라이브러리를 전제로 한 구현을 제안받습니다.

이러한 문제들은 AI에게 '무엇을 읽게 하고, 무엇을 읽지 않게 할지'에 대한 컨텍스트 설계를 함으로써 완화할 수 있습니다.

• 대규모 리포지토리에서 AI에게 적절한 컨텍스트를 제공하기 위한 구체적인 설계 방법

• .gitignore나 .cursorignore/.copilotignore 등을 활용한 컨텍스트 제한 구현 예시 - AI가 리포지토리의 전체 개요와 의존 관계를 효율적으로 전달하기 위한 '시스템 구성 문서' 템플릿

• 개발 프로세스에서 사용할 수 있는 컨텍스트 지정 체크리스트

• 대상 독자: 실무에서 AI 코딩 어시스턴트(Cursor, VS Code + GitHub Copilot, Cline, Claude 등)를 사용하는 엔지니어

• 특정 IDE나 도구에 의존하지 않는 범용적인 접근 방식을 중심으로 설명하지만, 일부 설정 예시에서는 Cursor나 GitHub Copilot의 사양을 언급합니다.

AI 어시스턴트가 리포지토리를 스캔할 때 빌드 결과물, 캐시, 외부 라이브러리, 거대한 로그 파일 등이 컨텍스트에 포함되면 정확도 저하 및 토큰 소비의 원인이 됩니다.

각 도구가 제공하는 제외 설정 파일을 리포지토리 루트에 배치하여 스캔 대상을 '인간이 편집하는 소스 코드'로 한정합니다.

# 빌드 결과물과 의존 패키지
node_modules/
dist/
...

주의사항: 설정 파일의 사양이나 동작은 도구나 버전에 따라 다를 수 있습니다. 도입 시에는 각 도구의 공식 문서를 확인해 주세요 (예: Copilot 관리 설정, Cursor 문서).

AI는 개별 파일의 내용은 읽을 수 있지만, 시스템 전체의 아키텍처나 '왜 그 설계가 되었는지'라는 배경(컨텍스트)을 자발적으로 이해하기는 어렵습니다.

리포지토리 루트에 README_AI.md 또는 .github/ai-context.md와 같은 AI 전용 메타데이터 파일을 배치하고, 채팅 시작 시나 인덱스 생성 시 읽히도록 하는 방법이 효과적입니다.

# 시스템 컨텍스트 & 아키텍처 가이드
## 1. 시스템 개요
- **시스템명**: [시스템명을 기입]
...

src/

├── app/ # Next.js 페이지 라우팅 (프레젠테이션 계층)

├── components/ # UI 컴포넌트 (상태를 가지지 않는 순수 컴포넌트)

├── hooks/ # 커스텀 React Hooks (상태 관리 및 API 호출 로직)

├── lib/ # 외부 서비스 연동, 공통 유틸리티 (Prisma 클라이언트 등)

└── types/ # TypeScript 타입 정의 파일

## 3. 중요한 설계 규칙과 제약
- **상태 관리**: 전역 상태 관리는 가능한 피하고, React Server Components와 URL 쿼리 파라미터를 우선해 주세요.
- **데이터 접근**: 데이터베이스 작업은 반드시 `src/lib/prisma.ts`를 경유하고, 서비스 계층 외에서 직접 호출하지 마세요.
...

AI에게 코드 생성이나 수정을 요청할 때, 컨텍스트 지정 방식에 따라 출력 품질이 크게 달라집니다.

'사용자 등록 기능에 유효성 검사를 추가해 줘'

• 문제점: 어느 파일의 어떤 유효성 검사 라이브러리(Zod, Yup, 자작 등)를 사용해야 할지 판단할 수 없어, AI가 임의의 라이브러리를 임포트하거나 기존 규칙을 무시한 코드를 생성합니다.

'```
src/app/api/register/route.ts

사용자 등록 처리 로직에 비밀번호 강도 검사(password strength check)를 추가해 주세요.

컨텍스트 정보:

• 유효성 검사에는 src/lib/validation.ts에서 정의된 Zod 스키마인 passwordSchema를 사용하세요.
• 기존의 타입 정의는 src/types/user.d.ts를 참조하세요.
• 관련 에러 핸들링 패턴은 src/app/api/login/route.ts의 구현을 참고하세요.

효과: 참조해야 할 파일이 명확하기 때문에, AI가 기존 프로젝트 규약에 맞는, 임포트 오류가 없는 정확한 코드를 출력하기 쉬워집니다.

AI와의 협업을 원활하게 하기 위해, 태스크 실행 전에 다음 체크리스트를 확인해 주세요.

리포지토리 구성이나 사용 라이브러리를 변경했음에도 불구하고, AI용 문서를 업데이트하지 않고 방치하면, AI가 오래된 규칙에 기반하여 계속해서 코드를 생성합니다. **'코드 사양 변경 시에는 AI용 문서도 동시에 업데이트한다'**는 운영 규칙을 팀 내에서 수립해 주세요.

'만약을 대비해서'라며 관련성이 낮은 파일을 대량으로 컨텍스트에 포함하면, AI의 주의력이 분산되어 지시한 요구사항을 놓칠 가능성이 높아집니다 (소위 'Lost in the Middle' 현상). 지시와 관련된 파일은 필요 최소한(기준으로 5~10개 정도)으로 줄여서 지정해 주세요.

AI 코딩 어시스턴트의 성능을 최대한 끌어내는 핵심은, 모델의 성능 향상을 기다리는 것이 아니라, **'AI에게 제공하는 컨텍스트를 인간이 통제하는 것'**에 있습니다.

불필요한 파일을 적절히 제외하고, 시스템 전체 구조를 보여주는 메타데이터를 준비하며, 핵심 참조 파일을 지정한다. 이 세 가지 단계를 습관화함으로써, 대규모 리포지토리에서도 수정 작업이 적고 일관성 있는 코드 생성이 가능해집니다.