Claude Code로 블로그 전체를 다시 만든 이야기
2023-2024년까지만 해도 기술 블로그는 개인적으로 꽤 가치가 있다고 생각했어요. 자기 노트를 정리할 수 있고, 면접 경험이나 만났던 문제들, 심지어 삽질했던 디테일까지 기록할 수 있으니까요.
그런데 2025년 중반 이후로 모델 업데이트 속도가 점점 빨라지고, 동시에 점점 강해지더니, 2025년 상반기까지만 해도 꽤 쓸만하다고 생각했던 Cursor 같은 AI Code Editor조차 하반기에는 Claude Code를 상대하기 역부족이라는 게 확실히 느껴졌어요. 그래서 시대에 맞춰 블로그 전체를 뜯어고쳐야겠다고 마음먹었습니다(가치를 좀 살릴 수 있길 바라면서요).
데이터
먼저 숫자부터 보여드릴게요. 이 작업량을 순수하게 사람 손으로 한다고 생각하면 엄청나게 오래 걸리고, 저는 장담하건대 미루기 병에 완전히 당했을 거예요. 그런데 AI 도구의 도움으로 10일 만에 끝냈습니다(게다가 설 연휴 기간에요). 퀄리티도 나쁘지 않으니, 나름 작은 기적이라고 할 수 있죠.
| Metric | Value |
|---|---|
| Duration | 10 days (Feb 8–18, 2026) |
| Total commits | 104 |
| Files changed | 1,078 |
| Lines inserted | 263,000+ |
| Lines deleted | 21,000+ |
| Locales | 4 → 10 |
| Docs translated to English | 89 |
| Translation files generated | 801 (89 docs × 9 locales) |
| Blog posts with full i18n | 5 |
| Tools used | Claude Code |
실제로 한 것들
Phase 1: 기반 작업 (Feb 8–9) — 8 commits
홈페이지와 About 페이지를 처음부터 새로 디자인했어요. CLAUDE.md를 프로젝트의 헌법으로 만들었습니다 — commit 포맷, i18n 규칙, 파일 구조 컨벤션 등을 정의한 거죠. 언어를 4개에서 6개로 확장했고, 전 과정을 Claude Code와 대화하면서 진행했어요.
이 단계에서는 주로 아키텍처 결정을 내렸어요. 홈페이지를 어떻게 만들지? About 페이지는 어떤 구조로 갈지? 프로젝트 전체가 따라야 할 규칙은 뭔지? 이런 질문들은 Claude와 주고받으면서 특히 실행 계획을 짜는 데 활용했고, 저는 Review하고 조정하는 역할만 했습니다.
Phase 2: 스케일 업 (Feb 11–12) — 14 commits
언어를 4개 더 추가해서(pt-BR, de, fr, vi) 총 10개로 맞췄어요. 테마 번역 파일을 생성하고, navbar와 sidebar를 콘텐츠 구조 개선을 위해 새로 설계했습니다. defaultLocale을 en으로 바꾸고 Vercel i18n routing을 세팅했어요. 의존성 패키지도 업그레이드했고요. 언어 확장 작업은 거의 전부 기계적인 반복이었는데, 이게 딱 AI가 잘하는 영역이에요. Token은 엄청나게 잡아먹었지만, 사람 손으로는 이 짧은 시간 안에 끝내는 게 거의 불가능했을 거예요.
Phase 3: 콘텐츠 (Feb 13–14) — 14 commits
오래된 블로그 글을 정리했어요. 연말 회고를 하나 썼고요. 블로그 글 전부를 10개 언어로 번역했습니다. Projects 쇼케이스 페이지를 만들고, 홈페이지 i18n을 완료했어요. UI 컴포넌트 버그도 수정했습니다(ShowcaseCard 버튼 정렬, dropdown 잘림 문제).
이 단계에서 겪은 건, AI가 레이아웃 깨짐(UI 문제)을 처음부터 알아차리는 데는 잘 못한다는 거였어요. 여러 번 주고받으면서 사람(즉, 저)이 계속 수정 방향을 짚어줘야 화면이 제대로 나왔습니다.
Phase 4: Sidebar + Blog (Feb 15) — 7 commits
docs 전체의 sidebar 구조를 새로 정리했어요. 10개 언어 전체의 sidebar category 라벨을 번역했고요. 이전 리팩토링에서 남아있던 쓸모없는 번역 key 206개를 싹 정리했습니다. 해고 협상 블로그 글을 쓰고 전 언어로 번역했어요.
Phase 5: Docs i18n (Feb 16–17) — 14 commits
가장 큰 batch 작업이었어요. 89개 문서를 9개 비영어 언어로 번역해서 801개의 번역 파일을 만들었습니다. Knowledge(JavaScript, TypeScript, CSS, Vue, React, Browser, Security, Engineering), Experience, Coding 섹션을 전부 다뤘어요.
이 단계와 다음 단계는 Token을 극도로 많이 소모했는데, 고도로 기계적인 번역 작업을 전부 AI한테 맡겨서 마음껏 일하게 한 거예요(어차피 대부분의 언어는 읽지도 못하니까요).
Phase 6: 품질 수정 (Feb 17–18) — 24 commits
이 단계가 존재하는 이유는 Phase 5의 결과물이 깨끗하지 않았기 때문이에요. 무려 24개 commit이 전부 AI가 만든 번역을 고치는 데 들어갔습니다:
- German: 움라우트가 ASCII로 렌더링됨 (
ü대신ue,ä대신ae) - French: 악센트가 사라짐 (
é대신e,à대신a) - Vietnamese: 성조 부호가 통째로 누락됨 (성조 없는 베트남어는 거의 읽을 수가 없어요)
- Spanish/Portuguese: 악센트 표시가 전반적으로 빠짐
- Chinese Simplified: 번체 문자가 섞여 들어감 (AI가 두 문자 체계를 가끔 구분 못 해요)
- CJK residuals: es, pt-BR, ja, ko, vi의 코드 블록에 중국어 주석이 번역 안 된 채 남아 있음
하나 고치면 또 다른 문제가 튀어나왔어요. Portuguese 악센트를 고치다가 과교정이 돼서 frontmatter의 id와 slug 필드가 망가졌고요. Vietnamese 성조 수정할 때는 파일 하나를 빠뜨렸어요. Spanish 악센트 수정에는 오탐이 있어서 또 commit을 하나 더 해야 했고요.
사실 이 단계는 해당 언어를 아는 사람이 아니면 사람이 직접 개입할 수가 없어요. 그냥 다른 모델끼리 교차 검증하는 수밖에 없습니다.
AI가 잘 못하는 것들:
// Example：
- 첫 시도에서 움라우트, 악센트, 성조 부호를 정확하게 처리하는 것
- 번체와 간체를 안정적으로 구분하는 것
- 코드 안의 주석을 원문 그대로 둘지, 번역할지 판단하는 것
- 내용을 변환하면서 frontmatter 필드를 건드리지 않는 것
삽질 기록
악센트와 성조의 대참사. AI가 5개 언어에서 비 ASCII 문자를 전부 ASCII 비슷한 걸로 바꿔버렸어요. 그 때문에 수정 commit이 24개 — 전체의 거의 4분의 1이에요. 베트남어가 가장 심각했는데, 성조 부호가 없으면 그 언어 자체를 거의 알아볼 수가 없거든요.
번체/간체 혼용. zh-cn 번역에서 코드 주석이나 인라인 인용에 번체 문자가 섞여 있었어요. AI가 두 문자 체계를 일관되게 구분하지 못했습니다.
Frontmatter 손상. 문서를 번역하면서 AI가 가끔 frontmatter의 id와 slug 필드를 건드려서 Docusaurus routing이 깨졌어요. commit 하나가 통째로 Portuguese에서 악센트 수정하다 망가진 id와 slug를 고치는 데 쓰였습니다.
과교정의 연쇄 반응. 하나를 고치면 다른 게 터지는 일이 자주 있었어요. Portuguese 악센트 수정이 기술 용어 일부를 과교정했고, Vietnamese 성조 수정에서 파일 하나를 놓쳤고, 매번 "수정" commit을 할 때마다 새 문제가 생길 가능성이 있었습니다.
사람이 개입해야 하는 부분
아키텍처 결정. 어떤 10개 언어를 지원할 건지. Sidebar를 어떻게 구성할 건지. 뭘 navbar dropdown에 넣고, 뭘 최상위에 둘 건지. 이 결정들이 이후 모든 작업 방향을 결정했어요.
품질 판단. UI가 깨졌는지, 디자인 의도에 맞는지. 번역에 명백한 오류가 없는지, 예를 들어 기본 언어 설정 변경이 제대로 반영됐는지 같은 거요.
CLAUDE.md 파일. 본질적으로 Repo 헌법인데, AI에게 프로젝트 규칙을 알려주는 문서예요. commit 포맷, 파일 구조, i18n 규칙, 절대 하면 안 되는 것 등이요. 이 파일을 잘 써놓을수록 AI가 실수를 덜 하고, 사람이 개입할 일이 줄어들어요. 그래서 수시로 업데이트해야 합니다.
정리
잘 작성된 CLAUDE.md부터 시작하세요. 여기에 적어놓는 규칙 하나하나가 나중에 수십 번의 수정 사이클을 아껴줍니다. 처음에는 몇 줄로 시작했는데, commit 포맷, i18n 규칙, 프로젝트 구조, 명확한 금지 사항까지 담은 완전한 문서로 자라났어요.
비슷한 작업은 batch로 모아서, batch로 검토하세요. 파일 하나씩 번역하지 마세요. 비슷한 파일 15개를 한꺼번에 AI한테 던지고, 결과도 한꺼번에 검토하면 사람이 세세하게 확인해야 할 양을 줄일 수 있어요.
도구는 최대한 병렬로 쓰세요. Claude Code로 대화형 작업을 처리하면서, 동시에 Gemini나 Codex 같은 도구한테 batch 작업을 넘기는 게 가장 큰 효율 향상이었어요. 병렬화할 수 있는 일을 직렬로 하지 마세요.
모든 걸 기록하세요. 매 commit message, 매 단계 구분, 매 수정 사항 — 전부 히스토리에 남아 있어요. 대규모 AI 보조 프로젝트를 진행한다면, commit history가 곧 문서입니다.