개인 사이트(davdevs-laravel)를 위해 진행 중인 콘텐츠 마이그레이션에 대한 짧은 개발 로그(devlog)입니다. 플랫 파일(flat-file) 기반의 Astro 콘텐츠 저장소에서 PostgreSQL을 백엔드로 사용하고 Cloudinary가 미디어를 처리하는 Laravel 앱으로 전환하고 있습니다.

낭비된 하루 (어느 정도는)

Claude Code가 자율적으로 마이그레이션을 처리할 수 있도록 단계별 지침이 담긴 .md 가이드라인 문서를 작성하는 데 꼬박 하루를 보냈습니다.

다음 날, 맑은 정신으로 검토해 보니 전체 계획이 잘못된 토폴로지(topology)를 기반으로 설계되었다는 것을 깨달았습니다. 현재 기존 저장소와 새 저장소 모두 제 개발 머신에 있기 때문에, 저는 이를 로컬 대 로컬(local-to-local) 전송으로 설계했습니다. 하지만 실제 마이그레이션 대상은 로컬 대 클라우드(local-to-cloud)입니다(미디어는 Cloudinary, 데이터는 호스팅된 Postgres 사용). 이는 시퀀싱(sequencing), 검증(validation), 롤백(rollback) 과정을 충분히 변화시키기 때문에 기존 문서를 그대로 사용할 수 없었습니다. 오늘의 커밋(commit)들이 그 이야기를 직접적으로 보여줍니다:

• 마이그레이션 문서 업데이트
• 이미지 감사를 위한 마이그레이션 계획 업데이트
• feat: 콘텐츠 마이그레이션 감사 + 가져오기 명령 (Phase 22, step 1)

또한 Claude Code가 이와 같은 마이그레이션을 처음부터 끝까지 얼마나 깔끔하게 실행할지에 대해 여전히 어느 정도 회의적입니다. 미세한 콘텐츠 손상은 놓치기 쉽기 때문입니다. 그래서 이미지 임포터(importer)를 하나의 거대한 원자적 작업(atomic job)으로 취급하는 대신, 재개 가능하고 파일별 실패에 탄력적으로 대응할 수 있도록 만들었습니다 (Make migration:import-images resumable and resilient to per-file failures). 500개 중 340번째 파일에서 중단된다면, 처음부터 다시 시작하고 싶지는 않으니까요.

실제 설계 결정이 필요했던 두 가지 콘텐츠 유형

1. React 컴포넌트가 첨부된 도구(Tool) 페이지

각 /tools 포스트에는 React 컴포넌트가 함께 임베드되어 있습니다. Claude Code에 내린 지침은 좁은 범위로 설정되었습니다:

• /tools 내부의 컴포넌트만 마이그레이션할 것
• 새 사이트에 맞춰 색상 체계를 업데이트할 것 — 예: 파란색 버튼을 노란색으로 교체

'Add React Component Manager for Tools'로 배포되었습니다.

2. 전자책(Ebook) 제품 페이지 (전자책마다 독특하게 설계됨)

이 부분이 더 어려웠습니다. 모든 전자책(Ebook) 제품 페이지는 일회성으로 수작업 설계되었습니다. 이는 맞춤형 출시(bespoke launches)에는 훌륭하지만, 가공되지 않은 코드(raw code)를 저장 가능한 DB 레코드로 마이그레이션하기에는 최악이었습니다.

해결책: 각 페이지를 고유한 것으로 취급하는 것을 중단했습니다. 모든 전자책 제품 페이지를 두 가지 레이아웃 변형(layout variants) — 개별(individual) 및 번들(bundle) — 으로 통합하고, 출판물 모듈(publications module)이 이 두 가지 변형 내에서 완전한 디자인 커스터마이징을 지원하도록 조정했습니다. 이는 도구 작업과 동일한 커밋인 87346c7: Add React Component Manager for Tools + Publication Template Manager for eBooks에서 '전자책용 출판 템플릿 관리자(Publication Template Manager for eBooks)'로 배포되었습니다.

이 작업은 이전 단계에서 이미 구축된 더 긴 아키텍처 — 출판물 관리자(publication manager), 분류 체계 CRUD(taxonomy CRUD), 헤드리스 REST API(headless REST API), JSON-LD/OG 태그 — 를 기반으로 한다는 점을 주목할 만합니다. 따라서 템플릿 통합은 별도로 덧붙이는 방식(bolt-on)이 아니라 기존의 콘텐츠 모델(content model)에 자연스럽게 끼워 맞춰집니다.