Claude Code로 포트폴리오 + 기술 블로그 운영하기

들어가며

포트폴리오랑 기술 블로그, 언젠간 만들어야지 하면서 몇 년을 미뤘습니다. 이번에 Claude Code를 쓰면서 드디어 완성했는데, 그 과정을 정리해봤습니다.

이 글에서는 어떻게 협업했는지, 무엇을 자동화했는지, 어떻게 운영하고 있는지 공유합니다.

Claude Code와 어떻게 작업했나

브레인스토밍으로 시작

처음에는 PARA 기법(Projects, Areas, Resources, Archives)으로 콘텐츠를 관리하려 했습니다. 노트 앱에서 이미 사용하고 있었고, 검증된 방법이니까요. 그런데 웹사이트에 적용하려니 자동화가 어려웠습니다. 폴더 구조와 URL 라우팅이 안 맞고, 콘텐츠 추가할 때마다 수동 작업이 필요했습니다.

Claude Code에게 현재 구조의 문제점과 목표를 설명하고, 내가 놓치고 있는 부분이 뭔지 물어봤습니다. 대화를 통해 PARA를 고집할 필요가 없다는 걸 깨달았습니다. 결국 Content Collections 기반의 새로운 구조로 재설계했습니다.

1
현재 PARA          →    공개 사이트용 재해석
2
───────────────────────────────────────────
3
Project            →    Featured Work (대표작)
4
Area               →    Skills + Contents (전문 분야)
5
Resource           →    (통합)
6
Archive            →    숨기기 (공개 안 함)

디자인 레퍼런스 제공

디자인 감각이 부족해서 고민이었습니다. 직접 디자인하면 “개발자가 만든 티”가 날 게 뻔했습니다.

마음에 드는 포트폴리오 사이트 URL을 Claude Code에게 공유했습니다. Playwright MCP가 연결되어 있어서, 해당 사이트를 직접 방문해서 분석하고, 핵심 UI 패턴을 파악한 뒤, Astro + Tailwind로 재구현해줬습니다. 레퍼런스를 전달해주는 게 의도에 가장 잘 맞는 결과물을 받는 방법이었습니다.

이 과정에서 VitePress에서 Astro로 프레임워크를 전환하게 됐습니다. VitePress는 문서 사이트에 최적화되어 있어서, 원하는 포트폴리오 UI를 구현하기 어려웠기 때문입니다.

일시적 조치 막기

AI와 작업하다 보면 가끔 일시적인 해결책을 제안받습니다. 당장은 동작하지만, 나중에 유지보수가 어려운 코드입니다.

예를 들어, About 섹션의 “경력 3년차”를 하드코딩하면 매년 수정해야 합니다. 이런 경우 “유지보수성을 고려해서” 또는 “지속 가능한 방식으로” 라는 키워드를 추가하면, 시작일 기준 자동 계산 로직을 제안받습니다.

1
// Before: 하드코딩
2
const years = 3;
3

4
// After: 자동 계산
5
const startDate = new Date("2023-05-01");
6
const years = Math.floor(
7
  (Date.now() - startDate.getTime()) / (365.25 * 24 * 60 * 60 * 1000)
8
);

공개용으로 정리하기

회사에서 진행한 프로젝트를 포트폴리오에 넣으려면 특정 회사가 드러나지 않도록 정리해야 합니다. NDA 때문이기도 하고, 공개 사이트에서 특정 회사명을 노출하는 게 적절하지 않기 때문입니다.

처음에는 “인터넷전문은행 A사”처럼 표기했는데, 이러면 어떤 프로젝트인지 한눈에 알기 어렵습니다. Claude Code와 논의해서 프로젝트 제목은 기술 키워드 중심으로, 업종 정보는 상세 패널에서만 표시하는 방식으로 변경했습니다.

1
Before: "인터넷전문은행 A사 DevOps 환경 구축"
2
After:  "Kubernetes 기반 DevOps 플랫폼 구축" (상세: 금융권 · 인터넷전문은행)

핵심 구현 - 자동화 시스템

Content Collections로 콘텐츠 관리

Astro의 Content Collections를 활용해서 세 가지 콘텐츠 타입을 관리합니다.

마크다운 파일 하나 추가하면 목록 페이지, 상세 페이지, 필터, 검색이 자동으로 동작합니다.

1
# 새 콘텐츠 추가
2
touch astro/src/content/contents/kubernetes/new-post.md
3
# 끝. 나머지는 자동.

자동 계산 시스템

About 섹션의 통계는 전부 자동 계산됩니다.

1
export function getYearsOfExperience(): number {
2
  const earliest = timeline
3
    .filter((item) => item.type === "work")
4
    .map((item) => new Date(item.startDate))
5
    .sort((a, b) => a.getTime() - b.getTime())[0];
6

7
  return Math.floor(
8
    (Date.now() - earliest.getTime()) / (365.25 * 24 * 60 * 60 * 1000)
9
  );
10
}

데이터 파일 하나 수정하면 관련된 모든 컴포넌트에 반영됩니다.

스킬 ↔ 콘텐츠 태그 연동

Skills 섹션에서 기술 태그를 클릭하면, 해당 기술로 작성한 콘텐츠가 옆에 표시됩니다. 태그 기반 자동 매핑입니다.

1
// 스킬 정의
2
{ name: 'Kubernetes', tags: ['Kubernetes', 'K8s'] }
3

4
// 콘텐츠 frontmatter
5
tags: [Kubernetes, Helm, ArgoCD]
6

7
// 자동 매칭 → 스킬 클릭 시 관련 콘텐츠 표시

포트폴리오를 보다가 자연스럽게 기술 블로그로 넘어가게 됩니다. “이 사람이 Kubernetes를 안다고 하는데, 실제로 어떤 글을 썼지?” 라는 질문에 바로 답할 수 있습니다.

Card + Detail Panel 패턴

Work, Skills, Interests 세 섹션에 동일한 UI 패턴을 적용했습니다. 왼쪽에 카드 그리드, 오른쪽에 선택된 카드의 상세 패널이 표시됩니다. 첫 번째 항목이 자동 선택되고, 카드를 클릭하면 오른쪽 패널이 업데이트됩니다.

하나의 패턴을 세 번 재사용해서 일관된 UX를 제공합니다.

운영 자동화 - 마크다운 하나로 끝

GitHub Actions 배포 파이프라인

main 브랜치에 push하면 자동 배포됩니다.

1
on:
2
  push:
3
    branches: [main]
4
    paths:
5
      - "astro/**" # astro 폴더 변경 시에만 트리거

빌드부터 GitHub Pages 배포까지 전부 자동입니다.

환경변수로 개인정보 분리

이름, 이메일, LinkedIn URL 같은 개인정보는 환경변수로 관리합니다.

1
# .env (로컬)
2
PUBLIC_NAME_KO=홍길동
3
PUBLIC_LINKEDIN=https://linkedin.com/in/...
4

5
# GitHub Actions (배포)
6
env:
7
  PUBLIC_NAME_KO: ${{ vars.PUBLIC_NAME_KO || '기본값' }}

Claude Code 스킬로 콘텐츠 운영

콘텐츠 작성 워크플로우를 contents-creator 스킬로 만들어서 사용하고 있습니다.

1
인풋 → 정보 수집 → 목차 제안 → 톤/상세도 확인
2
    → 논리 검증 → WIP 작성 → 사용자 확인 → 발행

WIP(Work In Progress) 폴더에 먼저 작성하고, 로컬에서 확인한 뒤 발행합니다. 실수로 미완성 글이 배포되는 일이 없습니다.

LinkedIn 포스팅도 linkedin-post 스킬로 자동화했습니다. 블로그 글을 쓰면 LinkedIn용으로 요약해서 포스팅할 수 있습니다. 이런 반복 작업을 스킬로 만들어두면 꾸준히 콘텐츠를 발행하기 훨씬 수월합니다.

마치며

몇 년간 미뤄왔던 포트폴리오와 기술 블로그를 드디어 완성했습니다.

자동화 덕분에 운영 부담이 거의 없습니다.

• 콘텐츠 추가: 마크다운 파일 하나
• 통계 업데이트: 데이터 파일 수정 시 자동 반영
• 배포: push만 하면 끝

이제 콘텐츠만 꾸준히 쌓으면 됩니다.

사이트: https://www.heeho.net/

기술 스택:

• Framework: Astro v5
• Styling: Tailwind CSS v4
• Deploy: GitHub Pages + GitHub Actions