실전: 처음부터 배포까지

프로젝트 개요

빈 디렉토리에서 시작해서 북마크 매니저 웹 앱을 만들어봅시다. URL을 저장하고, 태그로 분류하고, 검색하는 간단한 앱입니다.

이 모듈에서는 지금까지 배운 모든 기법을 종합합니다:

• CLAUDE.md로 프로젝트 규칙 설정 (모듈 08)
• Plan 모드로 설계 (모듈 11)
• 코드 생성 (모듈 04)
• 테스트 작성 (모듈 06)
• Git 워크플로우 (모듈 07)

단계 1: 프로젝트 설계

새 디렉토리를 만들고 Claude Code를 시작합니다:

mkdir bookmark-manager && cd bookmark-manager
git init
claude

Plan 모드로 전환합니다 (Shift+Tab):

[Plan 모드]
> 북마크 매니저 웹 앱을 만들려고 해.
> 기능: URL 저장, 태그 분류, 검색
> 기술 스택을 추천해줘. 프론트/백 모두 포함해서.
> 단, 배포는 가능한 간단하게 (Vercel이나 Cloudflare).

Claude가 기술 스택과 구조를 제안합니다. 마음에 드는 방향을 선택하세요.

단계 2: 초기 셋업

일반 모드로 돌아와서:

> 먼저 CLAUDE.md를 만들어줘. 방금 정한 기술 스택과 프로젝트 구조를 담아서.

> 프로젝트를 초기화해줘. package.json, 기본 디렉토리 구조, 설정 파일들을 만들어줘.

> 커밋해줘: "chore: initialize project"

단계 3: 핵심 기능 구현

기능을 하나씩 구현합니다:

> 북마크 CRUD API를 만들어줘.
> - POST /api/bookmarks — 새 북마크 저장
> - GET /api/bookmarks — 목록 조회 (태그 필터, 검색 지원)
> - PUT /api/bookmarks/:id — 수정
> - DELETE /api/bookmarks/:id — 삭제

완성되면 테스트를 추가합니다:

> 방금 만든 API에 대한 통합 테스트를 작성해줘. 모든 엔드포인트를 커버해줘.

> 테스트를 실행해줘

통과하면 커밋:

> 변경 사항을 커밋해줘. Conventional Commits 형식으로.

단계 4: 프론트엔드

> 북마크 목록을 보여주는 메인 페이지를 만들어줘.
> - 북마크 추가 폼
> - 태그 필터
> - 검색창
> - 북마크 카드 (제목, URL, 태그, 삭제 버튼)
> 깔끔한 UI로 부탁해.

> 로컬에서 실행해줘

브라우저에서 확인하고 피드백을 줍니다:

> 카드 디자인을 좀 더 깔끔하게 해줘. 그리고 빈 상태일 때 안내 메시지를 보여줘.

단계 5: 배포

> 이 프로젝트를 배포할 수 있도록 준비해줘.
> 빌드 설정, 환경 변수 가이드, README를 작성해줘.

직접 수정하기

위 단계를 따라하되, 북마크 매니저 대신 자기만의 프로젝트를 만들어보세요:

• 할일 관리 앱
• 블로그 엔진
• 링크 단축 서비스
• 메모 앱

핵심은 프로젝트의 규모가 아니라, Claude Code와의 협업 흐름을 익히는 것입니다.

"왜?" — 전체 사이클을 경험해야 하는 이유

개별 기능(코드 생성, 테스트, Git)을 따로 연습하는 것과, 프로젝트 전체를 처음부터 끝까지 진행하는 것은 다른 경험입니다. 실전에서는 이 모든 것이 하나의 흐름으로 이어져야 합니다.

프로젝트 진행 워크플로우

1. CLAUDE.md 작성 → 프로젝트 규칙 수립
2. Plan 모드 → 설계
3. 기능 구현 → 테스트 → 커밋 (반복)
4. 코드 리뷰 → 리팩토링
5. 배포 준비 → 배포

각 단계에서 /compact로 컨텍스트를 관리하고, 큰 작업 전에는 커밋으로 체크포인트를 만드세요.