사이드 프로젝트를 시작할 때 가장 큰 장벽은 초기 세팅이다. 보일러플레이트 만들고, 린트 설정하고, CI 붙이고, 배포 파이프라인 만들고 — 본격적인 기능 개발에 들어가기 전에 지쳐버린다. 이번에는 Claude Code를 써서 이 과정을 얼마나 단축할 수 있는지 실험해봤다.

만든 건 간단한 북마크 관리 웹앱이다. URL을 저장하면 메타데이터를 자동으로 추출하고, 태그로 분류하고, 검색할 수 있는 도구.

프로젝트 초기화#

터미널에서 Claude Code를 열고 의도를 설명했다.

"Next.js App Router, TypeScript, Tailwind CSS, Prisma, SQLite로
북마크 관리 앱을 만들 거야. 프로젝트 초기화해줘."

프로젝트 구조, 패키지 설치, 기본 설정 파일까지 한 번에 만들어줬다. tsconfig.json의 path alias, ESLint 설정, Prisma 스키마까지. 이 과정이 보통 30분~1시간인데 2분 만에 끝났다.

여기서 중요한 건 CLAUDE.md 파일을 바로 만든 것이다:

# Bookmark Manager

## 기술 스택
- Next.js 15 App Router
- TypeScript strict mode
- Tailwind CSS
- Prisma + SQLite
- Server Actions

## 컨벤션
- 컴포넌트는 named export
- 서버 컴포넌트 기본, 클라이언트 컴포넌트는 'use client' 명시
- API 대신 Server Actions 사용

CLAUDE.md가 컨텍스트 역할을 해서, 이후 대화에서 일관된 코드를 생성해준다. 이걸 안 만들면 Claude가 매번 다른 패턴으로 코드를 만들어서 프로젝트가 중구난방이 된다.

기능 개발 과정#

스키마 설계

"북마크에는 URL, 제목, 설명, 썸네일, 태그(다대다), 생성일이 필요해.
Prisma 스키마 만들어줘."

스키마를 만들고 npx prisma db push까지 실행해줬다. 다대다 관계를 위한 중간 테이블도 알아서 만들었다.

OG 메타데이터 추출

URL을 입력하면 Open Graph 태그에서 제목, 설명, 이미지를 가져오는 Server Action이 필요했다. "URL에서 OG 메타데이터를 추출하는 Server Action 만들어줘"라고 하니까 cheerio로 HTML을 파싱하는 코드를 만들었다.

그런데 에러 처리가 빠져 있었다. OG 태그가 없는 사이트, 타임아웃, 잘못된 URL — 이런 엣지 케이스를 하나씩 알려주니까 추가해줬다. AI한테 한 번에 완벽한 코드를 기대하면 안 된다. 코드를 받고, 빠진 부분을 찾고, 수정을 요청하는 반복이 필요하다.

검색 기능

SQLite의 전문 검색을 쓸까 했는데, 데이터 규모가 작아서 그냥 Prisma의 contains로 충분했다. Claude에게 "검색 기능인데, 제목과 설명에서 검색되게 해줘. 디바운스도 걸어줘"라고 했더니 서버 컴포넌트 + useSearchParams 조합으로 만들어줬다. URL에 검색어가 남으니까 공유도 가능하고 새로고침해도 유지된다.

잘 된 것#

보일러플레이트와 반복 코드. CRUD의 C, R, U, D는 패턴이 비슷하니까 AI가 빠르게 만들어준다. 하나를 잘 만들어놓으면 나머지를 그에 맞춰서 만든다.

CSS/스타일링. "이 카드 컴포넌트를 그리드로 배치하고, hover 시 살짝 올라오는 효과 넣어줘" — 이런 지시에 Tailwind 클래스를 척척 붙여준다. CSS 속성 이름이 기억 안 날 때 특히 편하다.

에러 메시지 해석. 빌드 에러나 타입 에러가 나면 에러 메시지를 붙여넣고 "이거 왜 그래?"라고 물어보면 된다. 스택오버플로우 검색보다 빠르다.

안 된 것#

복잡한 상태 관리 설계. 태그 필터, 정렬, 검색이 동시에 적용되는 상태를 어떻게 관리할지 — 이건 AI가 여러 방향을 제안하지만 "어떤 게 이 프로젝트에 맞는지"는 내가 판단해야 했다. URL state로 갈지, zustand로 갈지, 그냥 useState로 충분한지.

디버깅. "저장 버튼을 누르면 가끔 두 번 저장되는데?"라고 하면, 가능성을 여러 개 나열해주지만 정확한 원인은 직접 찾아야 했다. React Strict Mode의 이중 호출이 원인이었는데, AI는 그 가능성을 세 번째쯤에 언급했다.

UI/UX 감각. 기능적으로는 동작하는 UI를 만들어주지만, "이게 사용자 입장에서 직관적인가?"는 스스로 판단해야 한다. 버튼 위치, 피드백 타이밍, 빈 상태 처리 같은 건 내가 하나씩 지시해야 했다.

소요 시간#

총 8시간 정도 걸렸다. AI 없이 했으면 주말 이틀은 잡아야 했을 분량이다.

AI가 시간을 절약해주는 건 맞다. 그런데 절약된 시간의 상당 부분을 "AI가 만든 코드를 이해하고 검증하는 데" 다시 쓰게 된다. 이해하지 못하는 코드를 그대로 쓰면, 나중에 수정할 때 처음부터 다시 파악해야 한다.

AI 코딩 도구의 최적 사용법은 "시니어 개발자의 속도를 높이는 것"이지, "코딩을 모르는 사람이 앱을 만드는 것"이 아니다. 무엇을 만들어야 하는지 알고, 만들어진 결과를 평가할 수 있어야 제대로 쓸 수 있다.