1만 줄 프로젝트에서 AI 가 헤매지 않게 하는 프롬프트 전략

1만 줄 프로젝트에서 AI가 헤매지 않게 하는 프롬프트 전략

대규모 프로젝트에서 AI 개발 도구를 사용할 때 흔한 문제가 있습니다. 코드가 많을수록 AI는 "숲을 보지 못하고 나무만 본다"는 식의 부정확한 제안을 합니다. 버그를 놓치거나, 아키텍처를 고려하지 않은 답변을 하거나, 이미 존재하는 유틸리티 함수를 모르고 중복 코드를 제안하는 경우가 빈번합니다.

이 문제는 AI의 한계라기보다는 정보 전달 방식의 문제입니다. 같은 질문이라도 어떻게 컨텍스트를 구성하느냐에 따라 응답 품질이 크게 달라집니다. 실제로 일하는 팀들이 검증한 5가지 프롬프트 전략을 소개합니다.

1. 파일 구조 지도 먼저 제시하기

AI에게 전체 그림을 주지 않으면 부분 최적화에만 집중합니다. 가장 먼저 할 일은 프로젝트의 파일 구조와 각 모듈의 역할을 텍스트로 정리하는 것입니다.

예를 들어 Next.js 전자상거래 프로젝트라면:

프로젝트 구조:
- /app/api: 백엔드 API 라우트 (상품 조회, 주문 처리)
- /app/products: 상품 페이지 (SSR)
- /components: 재사용 가능한 UI 컴포넌트
- /lib/db: 데이터베이스 쿼리 함수
- /lib/auth: 사용자 인증 로직
- /hooks: 커스텀 React 훅

현재 작업: 장바구니 추가 기능 구현
관련 파일: /app/api/cart/add.ts, /lib/db/cart.ts, /components/AddToCart.tsx

이렇게 구조를 먼저 제시하면 AI는 "이 함수는 이 모듈에서 이미 있을 가능성이 높다"는 식의 맥락 있는 제안을 합니다. 컨텍스트 토큰을 낭비하지 않으면서도 정확도를 높일 수 있습니다.

2. 핵심 파일만 선택적으로 포함하기

"전체 코드를 보여줘"라는 접근은 역효과입니다. AI의 컨텍스트 윈도우는 한정되어 있고, 불필요한 정보가 많으면 중요한 부분을 놓칩니다.

대신 문제 해결에 직접 필요한 파일만 선택하세요:

피해야 할 방식:

전체 utils 폴더(500줄) + 전체 components 폴더(2000줄) + 전체 api 폴더(1500줄)

올바른 방식:

현재 버그: 사용자 프로필 업데이트 시 이미지 업로드 실패

관련 파일만 첨부:
1. /app/api/profile/update.ts (50줄) - 프로필 업데이트 엔드포인트
2. /lib/upload.ts (80줄) - 이미지 업로드 유틸리티
3. /components/ProfileForm.tsx (120줄) - 폼 컴포넌트
4. /lib/validation.ts (30줄) - 입력값 검증 규칙

이렇게 하면 AI가 정확한 범위 내에서 문제를 분석할 수 있습니다. Cursor에서도 @file 기능으로 특정 파일만 참조하면 토큰 효율이 훨씬 좋습니다.

3. 제약 조건과 기존 패턴 명시하기

AI는 코드베이스의 관례나 제약을 자동으로 파악하지 못합니다. 명시적으로 알려줘야 합니다.

예시 프롬프트:

우리 프로젝트의 규칙:
- 모든 API 응답은 { success: boolean, data?: T, error?: string } 형태
- 데이터베이스 쿼리는 /lib/db의 기존 함수를 재사용 (새로 작성 금지)
- 컴포넌트는 항상 TypeScript 타입 정의 필수
- 에러 처리는 try-catch + logger.error() 사용

기존 패턴 예시:
// /lib/db/user.ts
export async function getUserById(id: string) {
  return db.users.findUnique({ where: { id } });
}

위 패턴을 따라서 상품 조회 함수를 작성해줘.

이렇게 하면 AI가 일관성 있는 코드를 생성합니다. 코드 리뷰 때 "스타일이 다르다"는 지적이 줄어듭니다.

4. 실패 사례와 원하지 않는 패턴 보여주기

"이렇게 하지 말아달라"는 지시가 생각보다 효과적입니다.

예시:

❌ 피해야 할 패턴 (우리 프로젝트에서 이미 시도했고 문제 발생):
- 전역 상태 관리를 위해 Context API + useState 조합
  (이유: 리렌더링이 과도해서 성능 저하)
- 직접 fetch() 호출 (이유: 에러 처리가 산재됨)
- 컴포넌트 내부에서 직접 데이터베이스 접근
  (이유: 서버/클라이언트 경계 모호)

✅ 대신 이 접근법 사용:
- Zustand로 상태 관리
- /lib/api.ts의 fetchWithAuth() 함수 사용
- 서버 컴포넌트에서만 DB 접근

이렇게 명시하면 AI는 반복되는 실수를 피합니다.

5. 단계별 요약으로 검증 루프 만들기

대규모 작업은 한 번에 완성하지 말고, AI의 이해도를 확인하면서 진행하세요.

3단계 프롬프트 전략:

1단계 - 이해도 확인:

다음 요구사항을 이해했는지 확인해줘:
- 사용자가 상품을 장바구니에 추가할 때
- 재고가 부족하면 에러 반환
- 이미 장바구니에 있는 상품이면 수량만 증가
- 변경 사항을 실시간으로 UI에 반영

위 4가지를 정리해서 다시 설명해줘.

2단계 - 파일별 계획:

위 요구사항을 구현하려면 어떤 파일을 수정해야 할까?
각 파일별로 변경 사항을 3줄 이내로 요약해줘.

3단계 - 구현:

위 계획에 따라 /app/api/cart/add.ts를 구현해줘.

이 방식은 시간이 조금 더 걸리지만, AI가 실수할 확률이 크게 줄어듭니다. 특히 10000줄 이상의 프로젝트에서는 검증 비용이 전체 개발 시간의 일부일 뿐입니다.

프롬프트 작성 체크리스트

대규모 프로젝트에서 AI에게 질문할 때마다 확인하세요:

• 프로젝트 구조와 관련 모듈을 텍스트로 설명했는가?
• 필요한 파일만 선택적으로 포함했는가? (전체 코드 아님)
• 프로젝트의 기술 스택과 관례를 명시했는가?
• 피해야 할 패턴이나 이전 시도의 실패 사례를 언급했는가?
• 한 번에 너무 많은 것을 요청하지 않았는가?

이 5가지 전략을 조합하면, 1만 줄 이상의 프로젝트에서도 AI의 응답 품질을 유지할 수 있습니다. 핵심은 "AI에게 충분한 맥락을 주되, 불필요한 정보는 걸러내기"입니다.

Vibeollio에서 AI 친화적인 프로젝트 공유하기

당신의 팀이나 개인 프로젝트에서 이런 프롬프트 전략을 활용하고 있다면, Vibeollio에 프로젝트를 등록해보세요. 다른 개발자들과 대규모 코드베이스 관리 경험을 공유하고, AI 도구 활용 팁을 나눌 수 있습니다. 특히 Cursor, Claude, ChatGPT 등과 함께 일하는 팀의 워크플로우는 많은 개발자에게 도움이 될 것입니다.