바이브 코딩을 시작해보다

요즘 AI가 빠르게 발전함에 따라서 바이브 코딩을 해보려고 한다.

AI를 이용하여 빠르게 코딩을 할 수 있지만, 빠르게 하는 것보단 전체적인 흐름을 이해하면서 바이브 코딩을 하고 싶다.

사실 이제 문법 같은 것들은 AI가 전부 해주기 때문에 아키텍처와 기술을 사용하는 이유와 흐름을 많이 공부해야 한다고 생각한다.

따라서 프론트와 백 모두 바이브 코딩을 하면서 전체적인 흐름을 이해하는 개발자가 되고자 이 바이브 코딩을 기획하였다.

내가 사용할 것은 Github에서 개발한 spec-kit과 클로드에서 만든 클로드 코드이다.

(클로드 결제까지 해서 입에 풀 칠 하고 살아야 한다.)

 

내가 구현하고자 하는 프로젝트는 TestPanda라는 제목을 가졌고, 선생님과 학생들을 위한 사이트이다.

선생님은 문제를 낼 수 있고, 학생들은 문제를 풀 수 있는 사이트이다.

사실 이 프로젝트의 기획은 올해 초쯤에 했다.

여러 이유로 시작을 여태 미뤘지만 이제는 진짜 시작해야 될 때가 된 것 같아서 해보려 한다.

 

아래에는 내가 spec-kit과 클로드를 어떻게 활용할 것이고 설정했는지를 정리하고자 한다. 

---

spec-kit

https://github.com/github/spec-kit

GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development

• "Speckit" 시스템은 프로젝트의 기획부터 실행까지의 과정을 .speckit 디렉토리 내의 Markdown 파일로 관리
• 사실 위 링크 문서를 따라하면 어렵지 않다.

순서

1. 헌법 만들기
   • /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
   • 코딩을 하면서 지켜야 할 규칙들을 먼저 설정한다.
2. 무엇을 만들지 설명

/speckit.specify

# 서비스 설명

- **(Core)** 선생님(생성자)은 문제를 출제하여 '시험'을 만들고, 학생(풀이자)들은 이 '시험'에 응시할 수 있는 온라인 시험 플랫폼.
- **(Teacher)** 선생님은 '그룹' 단위로 학생들을 관리하며, 학생들의 시험 성적을 테이블과 차트로 시각화하여 관리함.
- **(Scope)** 초등학생부터 대학생, 스터디 그룹 등 다양한 사용자가 그룹을 만들어 문제를 내고 풀 수 있음.

# 사용자 역할

- **Teacher (문제 생성자):** 그룹을 생성/관리하고, 시험을 출제하며, 학생 성적을 조회/분석함.
- **Student (문제 풀이자):** 그룹에 가입하고, 시험에 응시하며, 자신의 성적을 확인함.
- **(Policy)** 회원가입 시 'Teacher' 또는 'Student' 역할을 선택해야 함. (역할 변경은 추후 관리자 승인 필요)

# 스토리보드

## 1. 공통 (홈, 인증)

### 홈 화면 (로그아웃 상태)

- 서비스의 핵심 기능을 설명하는 랜딩 페이지.
- "문제 만들러 가기" (Teacher용), "시험 응시하기" (Student용) CTA 버튼.
- 로그인/회원가입 모달 버튼.

### 회원가입 (모달)

- **역할 선택:** 'Teacher' / 'Student' 라디오 버튼.
- **로컬 회원가입:** 이메일, 비밀번호, 이름.
- **SNS 회원가입:** 구글, 네이버. (SNS 로그인 시에도 역할 선택 단계를 거쳐야 함)
- **정책:** 이메일 인증 절차를 거쳐야 회원가입이 완료됨.

### 로그인 (모달)

- 로컬 로그인 (이메일, 비밀번호).
- SNS 로그인 (구글, 네이버).
- 비밀번호 찾기 / 재설정 기능.

---

## 2. Teacher (문제 생성자) 대시보드

### 그룹 관리

- **그룹 생성:** 그룹 이름, 설명, 초대 코드(자동 생성)를 설정하여 그룹 생성.
- **그룹 목록:** 내가 생성했거나 속한 그룹 목록 조회.
- **그룹 상세 (관리 페이지):**
    - 그룹 이름/설명 변경.
    - 그룹 삭제 (그룹 내 모든 데이터 삭제).
    - 초대 코드 재발급 또는 비활성화.
- **그룹 인원 관리:**
    - **초대:** 학생들에게 '초대 코드' 또는 '초대 링크'를 공유.
    - **멤버 목록:** 그룹 멤버 목록 조회 (이름, 이메일, 역할).
    - **권한 변경:** 'Student' 멤버를 'Teacher'(공동 출제자)로 권한 변경 가능.
    - **강제 퇴장:** 그룹에서 멤버를 내보내기.

### 시험지 관리 (내가 낸 문제들)

- **시험지 생성:** '시험지' 단위로 문제를 생성함 (예: 2025년 1학기 중간고사).
- **시험지 설정:**
    - 시험지 이름, 설명.
    - 응시 기간 (시작일시 ~ 종료일시).
    - 응시 제한 시간 (예: 60분).
    - 문제 순서 섞기 (셔플) 여부.
    - 성적 공개 시점 (즉시 공개 / 시험 종료 후 공개).
- **문제 추가/수정:** 생성된 시험지에 아래 '문제 타입'에 맞는 문제들을 추가, 수정, 삭제.

### 성적 및 통계

- **대시보드:** 그룹별/시험지별 평균 점수, 응시율 등 핵심 지표 요약.
- **시험별 성적 테이블:**
    - 특정 시험의 모든 학생 성적을 테이블로 표시 (이름, 점수, 응시일시, 소요 시간).
    - **커스텀 컬럼 추가:** 출결, 수행평가 등 오프라인 점수를 최대 5개까지 추가하여 합산 관리.
    - 테이블 데이터 Sort, Filter링, CSV/Excel로 내보내기.
- **시험별 통계 (시각화):**
    - 점수 분포 (히스토그램), 평균, 중앙값, 최솟값/최댓값, 표준편차, 분산.
- **문제별 통계 (시각화):**
    - 각 문제의 정답률 (%), 가장 많이 선택한 오답 (객관식).
- **학생 개인 통계:**
    - 특정 학생의 누적 성적 그래프, 강/약점 분석 (문제 유형별 정답률).

### 채점 관리 (서술형)

- 학생들이 제출한 '서술형' 답안 중 채점이 필요한 목록을 보여줌 (채점 대기 큐).
- 선생님이 직접 답안을 읽고 점수를 입력 (부분 점수 가능).

---

## 3. Student (문제 풀이자) 대시보드

### 그룹 관리

- **그룹 가입:** 선생님에게 받은 '초대 코드'를 입력하여 그룹에 가입.
- **그룹 목록:** 내가 속한 그룹 목록 조회.
- **그룹 탈퇴:** 가입한 그룹에서 스스로 탈퇴 가능.

### 시험 응시

- **응시 가능 목록:** 내가 속한 그룹에서 현재 응시 가능한 시험지 목록.
- **시험 시작:** 제한 시간 타이머 시작.
- **시험 진행:** 문제 풀이 중 답안 자동 임시 저장.
- **시험 제출:** 최종 답안 제출 및 확인.
- **(Policy)** 시험 중 페이지 이탈 시 경고 팝업.

### 내 성적 관리 (내가 푼 문제들)

- **결과 확인:** 내가 응시한 시험 목록과 점수 확인 (선생님의 공개 설정에 따름).
- **상세 리포트:** 시험별로 내가 맞힌 문제, 틀린 문제, 정답, 내 답안 확인.
- **개인 통계:** 나의 전체 평균, 그룹 내 랭킹(선생님이 공개 시), 문제 유형별 정답률.

# 문제 타입 상세 정의

- **( 공통 )** 모든 문제 타입은 '문제 본문'에 이미지, 동영상(URL), 음성 파일을 첨부할 수 있음.
- **( 공통 )** 문제별 배점(점수)을 개별 설정할 수 있어야 함.

## 1. 객관식

- 선택지는 최소 2개, 최대 10개.
- **복수 정답** 허용 여부 설정 가능.
- (자동 채점)

## 2. O / X

- 'O'와 'X' 선택지 2개를 가진 객관식의 특수 형태로 구현.
- (자동 채점)

## 3. 주관식 (단답형)

- 학생이 짧은 단어 또는 구(Phrase)를 직접 입력.
- **복수 정답** 설정 가능 (예: '컴퓨터', 'computer' 둘 다 정답 처리).
- (자동 채점)

## 4. 주관식 (서술형)

- 학생이 긴 문장이나 문단을 입력.
- **(수동 채점)** 선생님이 직접 채점 큐에서 확인하고 점수 부여.

## 5. 순서 배열형

- 주어진 보기(텍스트 또는 이미지)들을 올바른 순서대로 드래그 앤 드롭.
- 예: 역사적 사건 순서, 실험 순서.
- **부분 점수** 가능 (예: 5개 중 3개 순서가 맞으면 60% 점수).
- (자동 채점)

## 6. 연결하기 / 짝짓기

- 왼쪽과 오른쪽 보기(텍스트 또는 이미지)들을 선으로 연결하거나 드래그 앤 드롭으로 짝지음.
- 예: 단어-뜻, 나라-수도.
- **부분 점수** 가능 (예: 4쌍 중 2쌍 맞으면 50% 점수).
- (자동 채점)

## 7. 빈칸 채우기형

- 문장, 수식, 코드 등의 본문 중간에 여러 개의 빈칸(입력란) 생성.
- 빈칸별로 정답(단답형) 설정.
- **부분 점수** 가능 (빈칸 1개당 배점 할당).
- (자동 채점)

## 8. 표 완성형

- 엑셀과 유사한 표(Table)의 특정 셀들을 빈칸으로 제시.
- 학생이 각 빈칸 셀에 정답(단답형)을 입력.
- **부분 점수** 가능 (셀 1개당 배점 할당).
- (자동 채점)

나는 이렇게 내가 원하는 목표를 설정해줬다.

 

3. 기술 스택 정하기

/speckit.plan

# 기술 스택

## Frontend

- **Next.js 16** (App Router, React 19)
- **TypeScript**
- **Tailwind CSS** (shadcn/ui의 필수 구성 요소)
- **shadcn/ui** (UI 컴포넌트 라이브러리)
- **Zustand** (가벼운 글로벌 상태 관리)
- **TanStack Query (React Query)** (서버 상태 및 캐시 관리)
- **React Hook Form** (폼 유효성 검사)
- **MSW (Mock Service Worker)** (선택적 API 모킹)

## Backend

- **Java 17**
- **Spring Boot 3.x**
- **Spring Data JPA** (ORM)
- **MySQL** (인증 서비스용)
- **PostgreSQL** (핵심 서비스용)
- **Spring Security** + **JWT** (인증/인가)
- **Spring Cloud Gateway** (MSA의 API 게이트웨이)
- **RabbitMQ** (MSA 간 비동기 통신)
- **Springdoc OpenAPI** (API 문서 자동화)

## DevOps

- **Docker** / **Docker Compose** (로컬 개발 환경)
- **GitHub Actions** (CI/CD)

# 아키텍처 (Infra)

- Backend만 MSA(Microservice Architecture)를 적용함.
- Frontend는 단일 Next.js 애플리케이션으로 구성.
- Backend MSA는 **서비스별 독립 데이터베이스(Polyglot Persistence)** 패턴을 따름:
    1. **인증 서비스 (Auth Service):** (Spring Boot) + **MySQL**
    2. **핵심 서비스 (Core Service):** (Spring Boot) + **PostgreSQL**
- API 게이트웨이(Spring Cloud Gateway)가 모든 외부 요청의 진입점 역할을 함.

# 개발 순서 (추천)

1. **API 계약 정의:** Springdoc OpenAPI를 사용해 각 마이크로서비스의 API 명세를 먼저 정의합니다.
2. **프론트엔드 (MSW 병행):** 정의된 API 명세를 바탕으로 MSW를 사용하여 프론트엔드 개발을 시작합니다. Next.js, shadcn/ui 컴포넌트를 구현합니다.
3. **백엔드 (MSA 구현):** Spring Cloud Gateway를 설정하고, 각 서비스('인증'은 MySQL, '핵심'은 PostgreSQL)를 독립된 Spring Boot 프로젝트로 구현합니다.
4. **통합 및 배포:** 프론트엔드의 MSW를 실제 백엔드 API 호출로 교체하며 통합 테스트를 진행합니다. Docker Compose로 로컬 환경을 구성하고 GitHub Actions로 CI/CD를 구축합니다.

추가적으로 프론트엔드에서 FSD 폴더 구조를 사용하게 해달라고 했다.

 

4. 작업 분류

• /speckit.tasks
• tasks.md 파일에다가 앞으로 할 작업들을 미리 계획해준다.

5. 자동화 작업

• 이거는 spec-kit의 기능은 아니지만 내가 필요로 해서 추가했다.
• package.json (npm 스크립트):
  • tasks.md 파일을 쉽게 조회하고 관리할 수 있는 스크립트를 추가했습니다.
  • "task:list": tasks.md의 모든 태스크 목록을 봅니다.
  • "task:pending": 미완료 태스크 10개를 봅니다.
  • "task:done": commit-task.sh 스크립트를 실행하여 태스크 완료와 커밋을 연동합니다.
• commit-task.sh (쉘 스크립트):
  • 태스크 완료 시 git add .를 실행하고, Conventional Commit 타입과 태스크 설명을 인자로 받아 자동으로 Git 커밋을 생성하는 스크립트입니다.

---

Claude

AI(저)가 작업을 수행할 때 따라야 할 규칙은 ".claude/instructions.md" 파일에 명확하게 정의되어 있다.

 

1. 자동 커밋 (Auto-Commit)

• **"작고 자주 커밋하라!"**는 원칙
• 즉시 커밋: 파일 1개 생성, 함수 1개 완성, 설정 1개 수정 등 의미 있는 작업 단위가 완료되면, AI가 스스로 판단하여 즉시 커밋
• 금지 사항: 여러 파일을 한 번에 커밋하거나, 사용자가 "커밋해줘"라고 요청할 때까지 기다리는 것을 금지

2. Git 커밋 메시지 규칙

• .speckit/constitution.md와 .claude/instructions.md 양쪽에서 강조된 규칙
• Conventional Commits: feat:, fix:, docs:, chore: 등 정해진 타입을 사용
• 한국어 작성: 모든 커밋 메시지는 반드시 한국어로 작성하도록 지시

3. 태스크 관리 및 연동 (Workflow)

• 세션 시작 시: AI는 작업을 시작하거나 세션이 재연결될 때마다 .speckit/tasks.md 파일을 먼저 확인하여 현재까지 완료된 작업과 다음에 할 작업을 파악
• 태스크 완료 시: AI가 tasks.md의 태스크 하나를 완료하면, 해당 항목의 체크박스를 [ ]에서 [x]로 수정한 뒤, 이 변경 사항 자체를 즉시 커밋

4. 코딩 스타일 및 아키텍처

• FSD (Feature-Sliced Design): 프론트엔드 파일 생성 시 반드시 FSD 아키텍처(app, processes, pages, widgets, features, entities, shared)를 준수해야 함
• 한국어 주석: 코드 내 모든 주석은 한국어로 작성하도록 constitution.md에 명시

---

깃허브

https://github.com/5hyun/test-panda

GitHub - 5hyun/test-panda