블로그 개발일지 #1 — Claude Code로 하루 만에 블로그 만들기
이 시리즈는 AI(Claude Code)와 함께 개인 기술 블로그를 만들고 운영하는 과정을 기록한다. 첫 번째 글에서는 블로그를 처음부터 구축한 과정과 그 과정에서 느낀 점을 정리한다.
왜 AI로 블로그를 만들었나
블로그를 만들겠다는 생각은 오래전부터 있었지만, 막상 시작하면 기술 선택부터 디자인, 콘텐츠 구조까지 결정할 것이 너무 많았다. 이번에는 접근 방식을 바꿔봤다. Claude Code와 대화하면서 처음부터 끝까지 함께 만들어보자.
결과적으로 하루 만에 다음이 완성되었다.
- Astro 6 + React 19 + Tailwind CSS 4 기반 정적 블로그
- 한/영 다국어 지원(i18n)
- MDX 커스텀 컴포넌트(Callout, Mermaid, LinkCard)
- MCP Server를 통한 AI 기반 콘텐츠 관리
- Vitest 130개 테스트 (유닛, 통합, 컴포넌트)
- CI/CD 파이프라인 + Vercel 배포
진행 과정
스펙과 계획 수립
가장 먼저 한 일은 블로그의 요구사항을 Claude Code와 브레인스토밍하는 것이었다. “개인 기술 블로그를 만들고 싶다”는 막연한 아이디어에서 시작해, 대화를 통해 구체적인 스펙 문서(docs/spec.md)와 9단계 구현 계획(docs/plans/)을 만들어냈다.
이때 느낀 점은 AI에게 전체 그림을 먼저 그리게 하는 것이 중요하다는 것이다. 바로 코드를 짜달라고 하면 부분 최적화에 빠지기 쉽다. 스펙 → 계획 → 구현 순서를 지키니 일관성 있는 결과물이 나왔다.
핵심 구현
스펙과 계획이 준비된 상태에서 Claude Code에게 각 Phase를 순서대로 구현하도록 요청했다. 프로젝트 초기화, 콘텐츠 스키마, 레이아웃, 페이지, React Islands, MDX 컴포넌트, SEO, MCP Server까지 — 각 단계가 이전 단계 위에 쌓이는 구조로 진행되었다.
테스트 도입
구현 완료 후 테스트가 전혀 없는 상태에서, 테스트 전략을 세우고 Vitest를 도입했다. 세 계층으로 나누어 접근했다.
| 계층 | 대상 | 테스트 수 |
|---|---|---|
| Unit | utils.ts, i18n, constants | 30 |
| Integration | MCP Server 8개 도구 | 63 |
| Component | ThemeToggle, SearchModal, CopyCodeButton | 24 |
MCP Server 테스트는 임시 디렉토리를 생성하여 실제 파일 I/O를 검증하는 방식을 택했다. 모킹 대신 실제 동작을 테스트하니 gray-matter 파싱, 디렉토리 생성, 파일 이동까지 통합적으로 검증할 수 있었다.
버그 수정과 문서화
테스트와 실제 사용 과정에서 4개의 버그를 발견하고 수정했다.
- Vitest + Astro config 충돌 —
getViteConfig대신 순수defineConfig사용 - LinkCard 상대 경로 에러 — 내부 링크와 외부 링크 분기 처리
- Tailwind Typography 플러그인 호환 에러 — 커스텀 prose 스타일로 대체
- Mermaid SVG 파싱 에러 —
<br>→<br/>치환
각 이슈는 docs/troubleshooting/에 증상 → 원인 → 해결 형식으로 기록했다. 이 과정에서 troubleshooting 템플릿과 plan 문서 관리 규칙도 함께 정립했다.
오늘의 회고
잘 된 것
- 반복 작업의 자동화: 8개 MCP 도구의 테스트 코드, 다국어 페이지 미러링 같은 반복적이지만 정확해야 하는 작업에서 생산성이 크게 향상되었다.
- 버그의 빠른 진단: 에러 메시지를 붙여넣으면 원인을 빠르게 파악하고 수정안을 제시했다. 특히 Mermaid SVG 파싱 에러처럼 라이브러리 내부 동작을 이해해야 하는 케이스에서 유용했다.
- 문서 구조 설계: troubleshooting 템플릿, plan 관리 방식 등 문서 체계를 잡는 데 좋은 제안을 받았다.
주의할 점
- 빌드 확인은 필수: AI가 생성한 코드가 항상 동작하지는 않는다.
@tailwindcss/typography플러그인 추가 시 Vite 7 호환 문제가 발생한 것처럼, 매 변경 후 빌드를 돌려보는 습관이 중요하다. - 컨텍스트 관리: 대화가 길어지면 앞에서 정한 규칙을 잊는 경우가 있다. CLAUDE.md나 커스텀 command 같은 영속적인 지시 방식을 활용하면 일관성을 유지할 수 있다.
- 최종 판단은 사람이: AI는 좋은 선택지를 제시하지만, 프로젝트의 맥락과 우선순위를 판단하는 것은 개발자의 몫이다.
블로그 개발일지 #2
세 가지 버그와 정적 사이트의 함정
idjaeha/my-blog
이 블로그의 소스 코드
github.com