Claude Code로 포트폴리오 사이트를 2일 만에 완성한 과정 — 기획부터 배포, 댓글까지

핵심요약은 무엇인가?

• Claude Code 9개 세션, 실작업 약 4시간 반으로 103페이지 포트폴리오 사이트를 완성했다.
• 네이버 블로그 95개 글을 자동 마이그레이션하고, 카테고리·시리즈 시스템까지 구축했다.
• Giscus(GitHub 댓글) 시도 후 Github 로그인이 필수여서, Firebase Firestore 기반 자체 댓글 시스템으로 전환했다.

프로젝트 진행 전

1. Claude Code의 /init 명령으로 CLAUDE.md를 생성해보자 — 프로젝트 컨텍스트가 자동으로 정리된다.
2. 반복 작업이 보이면 커스텀 스킬(.claude/commands/)을 만들어보자.
3. AI 코딩 도구를 "다 만들어줘" 대신 세션 단위로 점진적으로 사용해보자.

AI 코딩 도구로 "진짜" 사이트를 만들 수 있을까?

이 글에서는 다음 질문에 답한다:

• 진짜 프로덕션 사이트를 AI와 함께 만들 수 있나?
• 어떤 판단은 AI에게 맡기고, 어떤 판단은 직접 해야 하나?
• 2일이라는 시간에 실제로 얼마나 진행할 수 있나?

어떤 기술 스택과 아키텍처로 만들었나?

최종 결과물

설계 원칙

처음부터 정한 원칙은 3가지였다:

1. 데이터 주도 — TypeScript 파일에 데이터만 추가하면 페이지가 자동 생성되는 구조
2. 정적 우선 — DB를 최소화하고, 콘텐츠는 MDX 파일로 관리
3. 모노톤 디자인 — 컬러 없이 그레이스케일만으로 깔끔하게

9개 세션에서 실제로 무엇을 했나?

Day 1 (3/10 저녁 ~ 3/11)

세션 1: 프로젝트 초기 설정 (37분)

/init 명령으로 CLAUDE.md를 생성하는 것부터 시작했다. 이 파일이 있으면 Claude Code가 프로젝트 구조, 빌드 명령, 데이터 패턴을 이해한 상태로 대화가 시작된다.

그 다음, 프로젝트를 추가하는 작업이 앞으로 반복될 것이라는 판단 아래 커스텀 스킬(/add-project)을 만들었다. 이 스킬은 slug 생성, HTML 워드그룹 래핑, SVG 아이콘 적용, projects.ts 배열 삽입까지 자동 처리한다.

TIP: 반복 작업이 2번 이상 예상되면 바로 스킬로 만드는 게 낫다. 3번째부터 시간을 벌기 시작한다.

세션 2: 프로젝트 추가 + UI/UX 개선 (약 12시간, 야간 공백 포함)

만든 스킬로 첫 프로젝트를 추가하고, 여러 UI 이슈를 잡았다:

• 플로팅 목차(TOC) 추가 — 처음엔 너무 작아서 크기 조정
• 커스텀 커서 제거 — 멋있어 보이지만, 콘텐츠 영역에서 마우스가 사라지는 버그 발생. 사용성 우선으로 OS 기본 커서로 전환
• About 페이지 이미지 — Problem-Thinking-Solution 이미지를 넣어봤지만 투명 배경 미지원, 반응형 깨짐으로 삭제

여기서 배운 점: 멋있어 보이는 것과 잘 작동하는 것은 다르다. 커스텀 커서를 포기하는 판단은 AI가 아니라 내가 직접 했다.

Day 2 (3/12 새벽)

세션 3: 블로그 기능 기획 (57분)

네이버 블로그에 약 100개 글이 있었다. 이걸 어떻게 가져올지가 핵심 이슈였다.

검토한 옵션:

• CMS (Notion, Contentful 등) → 오버스펙
• DB 기반 → 불필요한 복잡도
• MDX 파일 기반 → 기존 프로젝트 데이터 패턴과 일관성 있음. 채택.

세션 4: 블로그 구현 + 네이버 마이그레이션 (48분)

이 세션이 가장 밀도가 높았다. 48분 안에:

1. next-mdx-remote + gray-matter 기반 블로그 엔진 구축
2. Python 크롤링 스크립트로 네이버 블로그 95개 글 마이그레이션
3. 마크다운 변환 품질 문제 해결 (취소선, 볼드, 목록 깨짐)
4. 7가지 추가 기능 — OG 메타태그, sitemap.xml, 코드 구문 강조, 읽기 시간 표시, XSS 방지, 이전/다음 네비게이션, prefers-reduced-motion 접근성

TIP: 네이버 블로그는 공식 백업이 PDF뿐이다. HTML 크롤링 스크립트를 미리 만들어둔 게 결정적이었다. 마이그레이션을 고려한다면 크롤러부터 준비하자.

세션 5~6: 카테고리 + 시리즈 (25분)

95개 글을 그냥 나열하면 찾기 어렵다. 폴더 기반 카테고리 시스템을 만들었다:

마이그레이션 스크립트를 만들어서 95개 파일을 태그 기반으로 자동 분류했다. 수작업 zero.

세션 7: 블로그 목록 UI 개선 (15분)

시리즈 플로팅 패널을 만들었는데, 모바일에서 안 보이는 버그가 발생했다. 원인은 CSS 선언 순서 — 미디어쿼리의 display: none이 나중에 선언된 기본 스타일에 의해 덮어씌워진 것이었다.

TIP: CSS에서 미디어쿼리 버그의 80%는 선언 순서 문제다. 기본 스타일 → 미디어쿼리 순서를 항상 지키자.

세션 8: 프로젝트 카드 밀도 + 배포 (21분)

프로젝트 카드가 한 화면에 2개만 보여서 답답했다. 간격, 비율, 패딩, 폰트 크기를 조정해서 4개가 한 화면에 보이도록 밀도를 높였다.

그리고 GitHub 레포 생성 → Vercel 배포. GitHub 연동만 하면 push할 때마다 자동 배포된다.

세션 9: 댓글 시스템 (38분)

댓글 기능을 넣고 싶었다. 처음에는 Giscus(GitHub Discussions 기반)를 시도했다.

문제가 2가지 있었다:

1. GitHub 로그인 필수 — 비개발자는 댓글을 달 수 없다
2. 디자인 불일치 — Giscus의 다크 테마가 사이트의 모노톤 라이트 테마와 안 맞았다

결국 Firebase Firestore + 닉네임/비밀번호 방식으로 전환했다:

• 서버 사이드에서 Firebase Admin SDK로 Firestore 접근
• bcryptjs로 비밀번호 해싱 (수정/삭제 시 본인 확인용)
• Next.js API Routes (/api/comments)로 CRUD 처리

TIP: 댓글 시스템을 선택할 때 "누가 댓글을 다는가"를 먼저 생각하자. 개발자 전용이면 Giscus로 충분하지만, 일반 방문자까지 고려하면 자체 구현이 필요하다.

AI에게 무엇을 맡기고, 무엇을 직접 판단했나?

핵심 인사이트: AI는 "어떻게(How)"에 강하고, 사람은 "무엇을(What)"과 "왜(Why)"에 강하다. "모노톤으로 만들어줘"는 한 줄이지만, 그 한 줄을 결정하기까지의 취향과 판단은 사람의 영역이다.

같은 구조를 2일 안에 만들려면 어떻게 해야 할까?

Day 1: 기반 구축

• npx create-next-app으로 프로젝트 생성
• Claude Code /init으로 CLAUDE.md 생성
• 디자인 방향 한 줄로 정의 (예: "모노톤 그레이스케일")
• 홈 + 프로젝트 목록 + 프로젝트 상세 페이지 구현
• 반복 작업용 커스텀 스킬 생성
• GitHub 레포 생성 + 첫 커밋

Day 2: 콘텐츠 + 배포

• 블로그 엔진 구축 (MDX + gray-matter)
• 기존 블로그 마이그레이션 (크롤러 또는 수동)
• 카테고리/시리즈 시스템
• SEO (sitemap, OG 태그)
• 댓글 시스템 (Firebase 또는 Giscus)
• Vercel 배포

TIP: Day 1에서 가장 중요한 건 CLAUDE.md다. 이 파일이 있으면 Day 2부터 Claude Code가 프로젝트 컨텍스트를 완전히 이해한 상태로 시작한다. 세션이 바뀌어도 맥락이 유지된다.

FAQ

Q. Claude Code 없이 다른 AI 도구로도 가능한가?

가능하다. 핵심은 도구가 아니라 세션 단위로 점진적으로 진행하는 방식이다. 한 번에 "포트폴리오 만들어줘"가 아니라, "CLAUDE.md 만들어줘" → "프로젝트 페이지 만들어줘" → "블로그 추가해줘"처럼 쪼개는 게 중요하다. 다만 Claude Code의 CLAUDE.md와 커스텀 스킬 시스템은 맥락 유지에 확실히 유리했다.

Q. 네이버 블로그 마이그레이션이 어렵지 않았나?

솔직히 마크다운 변환 품질이 문제였다. 취소선, 볼드, 목록 표현이 깨지는 경우가 많았다. Python 크롤링 스크립트를 여러 번 수정했고, 일부는 수작업으로 보정했다. 완벽한 자동 변환은 기대하지 않는 게 좋다. 70~80%를 자동화하고 나머지는 눈으로 확인하는 전략이 현실적이다.

Q. Firebase 무료 티어로 충분한가?

개인 포트폴리오 수준이면 충분하다. Spark(무료) 플랜 기준 Firestore는 일일 읽기 50,000건, 쓰기 20,000건을 제공한다. 댓글 수백 개 수준에서는 넘칠 일이 없다.

AI와 협업할 때 병목은 어디에 있을까?

2일간의 작업을 돌아보면, AI가 코드를 짜는 속도는 이미 충분히 빠르다. 병목은 코드가 아니라 판단이다.

• 어떤 기술 스택을 쓸지
• 커스텀 커서가 멋있지만 포기할지
• Giscus로 갈지 Firebase로 갈지
• 디자인의 톤앤매너가 맞는지

이런 판단을 빠르게 내릴 수 있으면, AI와의 협업 속도는 극적으로 올라간다.

취향을 반영하는 것이 오래 걸리지, 만드는 것은 쉬워졌다. 포트폴리오 웹 페이지 만들기에서도 같은 이야기를 했었다.

이 글은 Claude Code와의 실제 대화 기록 9개 세션을 기반으로 작성되었습니다.