Claude Code 학습 허브

한국어

English

한국어

English

테마

학기말 과제 프로젝트 개발: 기획부터 배포까지 ​

한 줄 요약 ​

마감 2주 전부터 Claude Code 스킬을 단계별로 조합해 요구사항 분석 → 설계 → 구현 → 배포 → 발표 자료까지 한 번에 완성한다.

대상 독자 ​

  • 학기말 프로젝트 마감이 2~3주 남았는데 어디서부터 시작할지 막막한 대학생
  • "일단 코딩부터 시작했다가 방향을 잃어버린 경험"이 있는 개발 입문자
  • 팀원과 역할을 나눠 병렬로 개발해야 하는 소규모 팀 프로젝트 참가자
  • Next.js / TypeScript / Supabase 스택을 처음 다루는 학생

핵심 워크플로우 ​

전체 타임라인 (마감 2주 전 기준) ​

D-14  brainstorming   → 아이디어 발산 및 요구사항 수집
D-13  writing-plans   → 기능 목록·ERD·컴포넌트 설계
D-10  executing-plans → 핵심 기능 구현 시작 (병렬)
D-7   subagent 분리   → 페이지별·API별 서브에이전트 투입
D-3   ship (draft)   → 스테이징 배포 + QA 체크리스트
D-2   review          → 코드 리뷰 + 타입 에러 수정
D-1   land-and-deploy → 프로덕션 배포
D-0   document-release → 발표용 README·슬라이드 정리

단계 1 — 요구사항 분석 (brainstorming) ​

교수님 과제 지문 또는 팀 아이디어를 Claude Code 세션에 붙여넣고 brainstorming 스킬을 실행한다.

bash
claude
> /skill brainstorming
> 과제 지문: "동아리 운영을 도와주는 웹 서비스를 만들어라."
> 우리 팀은 4명, 기간 2주, 스택 제한 없음.

brainstorming 스킬은 SCAMPER·마인드맵 방식으로 아이디어를 구조화한다. 세션이 끝나면 content/raw/brainstorm-[날짜].md에 결과를 저장해 팀원과 공유한다.

산출물 예시:

  • 핵심 기능 3가지 (공지 게시판, 출석 체크, 파일 공유)
  • 우선순위 매트릭스 (Must-Have / Nice-to-Have)
  • 기술 선택 근거 (Next.js 15 App Router + Supabase)

단계 2 — 기능 설계 (writing-plans) ​

brainstorming 결과를 기반으로 상세 개발 계획을 수립한다.

bash
> /skill writing-plans
> 위 brainstorming 결과를 바탕으로 개발 계획을 작성해줘.
> - ERD (공지, 사용자, 댓글 테이블)
> - 컴포넌트 트리 (App Router 기준)
> - API 엔드포인트 목록
> - 역할 분담안 (프론트 2명, 백엔드 1명, 인프라 1명)

writing-plans 스킬은 마크다운 체크박스 형식의 실행 계획을 생성한다. 이 파일을 PLAN.md로 저장하고 GitHub에 커밋하면 팀원 모두가 진척 상황을 공유할 수 있다.

산출물 예시:

markdown
## Phase 1: 기반 세팅 (D-14 ~ D-12)
- [ ] Next.js 15 프로젝트 초기화
- [ ] Supabase 프로젝트 생성 + 환경변수 설정
- [ ] Tailwind CSS + shadcn/ui 설치

## Phase 2: 핵심 기능 (D-11 ~ D-7)
- [ ] 공지 CRUD API (Supabase RPC)
- [ ] 공지 목록 페이지 (SSR)
- [ ] 공지 상세 + 댓글 컴포넌트
...

단계 3 — 구현 (executing-plans + subagent-driven-development) ​

계획이 완성되면 executing-plans 스킬로 항목을 하나씩 실행한다. 복잡한 기능은 subagent-driven-development 스킬로 서브에이전트에게 위임한다.

bash
> /skill executing-plans
> PLAN.md의 Phase 2를 실행해줘.
> 첫 번째 항목인 "공지 CRUD API"부터 시작할게.

서브에이전트 분리 예시 (D-7 시점):

bash
> /skill subagent-driven-development
> 다음 작업을 병렬로 처리해줘:
> - Agent A: 공지 목록 페이지 (app/notices/page.tsx)
> - Agent B: 공지 상세 페이지 (app/notices/[id]/page.tsx)
> - Agent C: 댓글 API 라우트 (app/api/comments/route.ts)

서브에이전트는 각자 독립된 파일 범위에서 작업하므로 Git 충돌이 최소화된다. 결과물은 각 에이전트의 세션 로그에서 확인하고 메인 브랜치에 병합한다.

단계 4 — QA 및 스테이징 배포 (ship) ​

D-3에 ship 스킬을 사용해 배포 전 체크리스트를 자동 생성한다.

bash
> /skill ship
> Vercel 스테이징 배포를 준비해줘.
> 환경변수 목록과 배포 전 체크리스트를 만들어줘.

ship 스킬이 생성하는 체크리스트:

  • [ ] .env.local 항목이 Vercel 환경변수에 모두 등록됨
  • [ ] Supabase RLS(Row Level Security) 정책 활성화
  • [ ] next build 에러 없음
  • [ ] Lighthouse 접근성 점수 80점 이상
  • [ ] 모바일 뷰포트 반응형 확인

단계 5 — 프로덕션 배포 (land-and-deploy) ​

스테이징 QA가 통과되면 land-and-deploy 스킬로 프로덕션에 배포한다.

bash
> /skill land-and-deploy
> 스테이징 테스트 완료. 프로덕션(main 브랜치)에 배포해줘.
> 배포 후 smoke test 스크립트도 만들어줘.

단계 6 — 발표 자료 정리 (document-release) ​

마감 당일, document-release 스킬로 발표용 문서를 자동 생성한다.

bash
> /skill document-release
> 이번 프로젝트의 릴리즈 노트를 작성해줘.
> - 구현된 기능 요약
> - 기술 스택 및 아키텍처 다이어그램
> - 팀원 기여도 섹션 포함

실전 시나리오 ​

상황: Next.js 15 + TypeScript + Supabase 기반 동아리 공지 게시판 전체 개발 (4인 팀, 2주)

D-14: 킥오프 세션 ​

bash
# 팀장 노트북에서 Claude Code 실행
claude

# 과제 지문 입력 후 brainstorming
> /skill brainstorming
> 교수님 지문: 웹 서비스를 설계·구현·배포하라.
> 우리 팀 아이디어: 동아리 공지 게시판 (글쓰기, 댓글, 파일 첨부, 역할 기반 접근제어)
> 기간: 14일, 스택: Next.js 15, TypeScript, Supabase, Tailwind CSS

산출물: BRAINSTORM.md (팀원 공유 → 기능 목록 합의)

D-13: 설계 세션 ​

bash
> /skill writing-plans
> BRAINSTORM.md를 기반으로 다음을 설계해줘:
> 1. Supabase 스키마 (notices, comments, users, roles 테이블)
> 2. Next.js App Router 컴포넌트 트리
> 3. 14일 일정표 (역할 분담 포함)

산출물:

  • PLAN.md — 체크박스 일정표
  • schema.sql — Supabase 마이그레이션 파일
  • ROLES.md — 팀원 역할 분담 (프론트A/프론트B/백엔드/인프라)

D-10 ~ D-7: 병렬 구현 ​

각 팀원이 자신의 담당 기능을 Claude Code 세션에서 executing-plans로 구현한다.

프론트A (공지 목록/상세 페이지):

bash
> /skill executing-plans
> PLAN.md에서 공지 목록 페이지 항목들을 순서대로 실행해줘.
> 파일: app/notices/page.tsx (SSR, Supabase 서버 컴포넌트)

백엔드 (API 라우트):

bash
> /skill executing-plans
> app/api/notices/route.ts를 구현해줘.
> GET: 목록 조회 (페이지네이션), POST: 글쓰기 (auth 필요)
> Supabase Admin 클라이언트 사용, TypeScript strict 준수

D-3: QA 및 스테이징 ​

bash
> /skill ship
> 현재 코드베이스를 점검하고 배포 준비 체크리스트를 만들어줘.

# ship 스킬이 발견한 문제 예시:
# - notices 테이블 RLS 정책 누락
# - 파일 업로드 크기 제한 없음
# - 로그인 만료 시 에러 핸들링 없음

D-1: 프로덕션 배포 ​

bash
> /skill land-and-deploy
> main 브랜치를 Vercel 프로덕션에 배포해줘.
> 배포 완료 후 주요 페이지 URL 목록으로 smoke test 스크립트 실행

# 배포 후 자동 smoke test
> curl -s -o /dev/null -w "%{http_code}" https://club-board.vercel.app/notices
# 기대값: 200

D-0: 발표 자료 완성 ​

bash
> /skill document-release
> 오늘 발표용 자료를 준비해줘:
> - README.md (기능 설명 + 스크린샷 위치 안내)
> - ARCHITECTURE.md (기술 스택, 시스템 구성도 ASCII 버전)
> - CHANGELOG.md (구현된 기능 타임라인)

추천 스킬 조합 ​

단계스킬역할
아이디어 발산brainstorming기능 목록·우선순위 도출
계획 수립writing-plans체크박스 일정표·ERD 생성
순차 구현executing-plans계획 항목 하나씩 실행
병렬 개발subagent-driven-development서브에이전트 분리
QA 준비ship배포 전 체크리스트
프로덕션 배포land-and-deployVercel/GitHub Pages 배포
문서화document-releaseREADME·발표자료 자동화
코드 품질reviewPR 전 자가 검토

주의사항 ​

자주 하는 실수 ​

  1. 계획 없이 코딩 시작: brainstorming과 writing-plans를 건너뛰면 중반부에 방향을 잃는다. 처음 하루를 설계에 투자하면 나머지 13일이 훨씬 효율적이다.

  2. 서브에이전트 범위 충돌: subagent-driven-development로 병렬 작업 시 같은 파일을 두 에이전트가 수정하면 충돌이 발생한다. 에이전트별 담당 파일 범위를 미리 명시해야 한다.

  3. 환경변수 관리 실수: ship 스킬 사용 전에 .env.local과 Vercel 환경변수가 동기화됐는지 반드시 확인한다. Supabase URL/Key 누락이 배포 실패의 80%를 차지한다.

  4. TypeScript any 타입 방치: executing-plans 실행 중 any가 삽입되는 경우가 있다. CLAUDE.md에 any 금지 규칙을 명시하거나, 구현 후 tsc --noEmit 검사를 반드시 수행한다.

  5. 마감 전날 대규모 리팩토링: D-1에는 새 기능 추가나 구조 변경을 금지한다. ship과 land-and-deploy만 실행한다.

팁 ​

  • PLAN.md를 팀의 단일 진실 공급원(SSOT)으로: 매일 아침 팀원이 체크박스를 업데이트하면 진척 상황이 자동으로 가시화된다.
  • Claude Code 세션 로그 저장: 각 단계의 대화 로그를 docs/session-logs/에 저장해두면 발표 시 "어떻게 개발했는지" 설명 자료로 활용할 수 있다.
  • 마감 임박 시 --dangerously-skip-permissions 금지: 시간이 촉박할수록 신중하게. 파일 덮어쓰기 사고가 마감 전날 가장 많이 발생한다.
항목내용
원본 URLhttps://docs.anthropic.com/en/docs/claude-code
라이선스CC BY 4.0
해설 작성일2026-04-12
작성자Claude-Code-Study 프로젝트

MIT License · 원본 Claude Code 리소스 저작권은 각 소유자에게 있습니다

© 2026 Claude-Code-Study