Capstone Topic Explorer v2.0 - 개발 문서
📋 개요
GKS 장학생을 위한 캡스톤 프로젝트 주제 탐색 도구의 v2.0 개발 문서입니다.
이 문서들은 Cursor AI + SuperNext/Ruler 템플릿 환경에서 최적화되어 있으며, Supabase와 Vercel을 사용한 개발 워크플로우에 맞춰져 있습니다.
📁 폴더 구조
capstone-topic-explorer/
├── README.md # 이 파일
├── doc/ # 기술 문서
│ ├── PROJECT_OVERVIEW.md # 프로젝트 개요
│ ├── DATABASE_SCHEMA.md # 데이터베이스 스키마
│ ├── API_DESIGN.md # API 엔드포인트 설계
│ ├── AUTH_FLOW.md # 간편 로그인 흐름
│ ├── UN_COUNTRIES.md # UN 193개국 데이터
│ ├── SECURITY.md # API 보안 가이드
│ ├── FEATURE_MYPAGE.md # My Page 기능 명세
│ └── ANTI_HALLUCINATION.md # 할루시네이션 방지 전략
├── prompts/ # AI 프롬프트
│ ├── 00_OVERVIEW.md # 프롬프트 개요
│ ├── 01_PROJECT_INIT.md # 프로젝트 초기화
│ ├── 02_UN_COUNTRIES.md # UN 회원국 기능
│ ├── 03_AUTH_SYSTEM.md # 인증 시스템
│ ├── 04_API_ROUTES.md # API 라우트 보안
│ ├── 05_MYPAGE_FEATURE.md # My Page 기능
│ ├── 06_ANTI_HALLUCINATION.md # 할루시네이션 방지
│ ├── 07_STEP_COMPONENTS.md # Step 컴포넌트 마이그레이션
│ └── 08_DEPLOYMENT.md # Vercel 배포
└── claude/
└── agents/ # Cursor AI 에이전트 정의
├── 00_OVERVIEW.md # 에이전트 개요
├── fullstack-developer.md
├── frontend-developer.md
├── backend-developer.md
├── security-reviewer.md
└── code-reviewer.md
🚀 개선사항 요약
| # | 개선사항 | 관련 문서 |
|---|
| 1 | UN 193개국 선택 (한국 우선) | doc/UN_COUNTRIES.md |
| 2 | API 보안 강화 | doc/SECURITY.md |
| 3 | 9자리 학번 간편 로그인 | doc/AUTH_FLOW.md |
| 4 | My Page (저장된 분석 조회) | doc/FEATURE_MYPAGE.md |
| 5 | Data Sources 할루시네이션 방지 | doc/ANTI_HALLUCINATION.md |
| 6 | Key References 할루시네이션 방지 | doc/ANTI_HALLUCINATION.md |
🔧 기술 스택
| 구분 | 기술 |
|---|
| IDE | Cursor AI |
| 템플릿 | SuperNext + Ruler |
| 프레임워크 | Next.js 14+ (App Router) |
| 언어 | TypeScript |
| 스타일링 | Tailwind CSS |
| 데이터베이스 | Supabase (PostgreSQL) |
| AI API | Google Gemini |
| 검색 API | Serper (Google Search) |
| 배포 | Vercel |
📖 사용 방법
1. 문서 읽기
개발 전 다음 문서들을 순서대로 읽어보세요:
doc/PROJECT_OVERVIEW.md - 전체 그림 파악doc/DATABASE_SCHEMA.md - DB 구조 이해doc/API_DESIGN.md - API 설계 확인
2. 프롬프트 실행
Cursor AI에서 프롬프트를 순서대로 실행하세요:
01 → 02 → 03 → 04 → 05 → 06 → 07 → 08
각 프롬프트 파일의 내용을 Cursor AI의 Chat 또는 Composer에 붙여넣고 실행합니다.
3. 에이전트 활용
복잡한 작업은 적절한 에이전트를 활용하세요:
- 풀스택 개발:
claude/agents/fullstack-developer.md
- 프론트엔드:
claude/agents/frontend-developer.md
- 백엔드:
claude/agents/backend-developer.md
- 보안 검토:
claude/agents/security-reviewer.md
- 코드 리뷰:
claude/agents/code-reviewer.md
📌 주요 체크리스트
개발 전
개발 중
배포 전
📅 작업 일정 제안
| 일차 | 작업 | 프롬프트 |
|---|
| 1일 | 프로젝트 초기화, DB 설정 | 01 |
| 2일 | UN 회원국, 인증 시스템 | 02, 03 |
| 3일 | API 라우트 보안화 | 04 |
| 4일 | My Page 기능 | 05 |
| 5일 | 할루시네이션 방지 | 06 |
| 6일 | Step 컴포넌트 마이그레이션 | 07 |
| 7일 | 배포 및 테스트 | 08 |
🆘 문제 해결
API 키 관련
- API 키 노출 시: 즉시 키 재발급 후 환경 변수 업데이트
- Rate limit 초과 시: 재시도 로직 확인, 필요시 할당량 증가
인증 관련
- 로그인 안 됨: 쿠키 설정 확인 (httpOnly, secure)
- 세션 유지 안 됨: 쿠키 maxAge 확인
배포 관련
- 빌드 실패: 타입 에러 확인, 환경 변수 확인
- API 오류: Vercel 환경 변수 설정 확인
📞 연락처
문서에 대한 질문이나 개선 제안이 있으시면 알려주세요.
이 문서는 2024년 기준으로 작성되었습니다.
