계기
때는 바야흐로 2021년 7월, 인턴 경험을 통해 처음 개발 실무를 경험하면서 언젠가는 저만의 웹사이트를 구축해야겠다고 다짐한 적이 있습니다.
당시에는 웹 애플리케이션 개발보다는 프로젝트나 실무를 통해 개발 감각을 익히는 게 중요하다 판단했고, 구현 과정에서 겪는 트러블슈팅이나 회고는 전용 블로그를 사용해서 빠르게 기록해야겠다 생각했습니다.
그래서 처음에는 velog로 만들어 봤다가 티스토리로도 넘어가서 글을 써보기도 했는데, 꾸준하게 쓰는 습관이 잘 안 들어있기도 하고 관리해야 할 동기부여가 덜했다 보니 소홀해지더군요.
그렇게 5년차 개발 경력 동안 축적된 노하우와 실패의 경험은 제때 제대로 기록되지 못하고 제 머릿속에만 머무르다 이내 휘발되었습니다.
개발자라면, 특히 연차가 적은 주니어 개발자일수록 배운 지식을 충분히 복기하고 기록을 통해 계속해서 소화시켜야 했는데 말입니다.
그러다 AI가 급속도로 발전하면서 소프트웨어 개발의 패러다임이 달라지기 시작했습니다. 예전이라면 병목이 됐을 개발 허들도 AI와 함께라면 충분히 넘을 수 있고, 개인 개발자도 이전보다 훨씬 자유롭고 빠르게 무언가를 만들 수 있는 시대가 된 것입니다.
이제는 그 언젠가를 실행해야 할 때라고 판단했습니다.
이직을 준비하면서 그동안 했던 프로젝트 개발 경험, 노하우, 마인드셋을 담으면서 개인 브랜딩도 가능한 포트폴리오성 웹 애플리케이션을 구축하자.
나라는 사람을 있는 그대로 보여주는 것에 강한 동기부여를 가지며, 온전히 내 손으로 구축해 애착이 있는 그런 웹 서비스를 선보이자.
그리고 AI를 제대로 활용하는 실력도 함께 키우자.
구현 방향
구현 방식을 결정하면서 가장 먼저 고민한 건 "이 프로젝트를 어떻게 진행할까"였습니다.
웹 서비스에 담고 싶은 기능은 어느 정도 정해져 있어, 이 기능들을 어떻게 구현해 나갈 것인가를 좀 더 세밀하게 고민해 봤습니다.
결론적으로 Claude Code(v2.1.142, claude-sonnet-4-6 모델)를 시니어 개발자처럼 활용하는 AI 페어프로그래밍 방식을 채택했습니다.
Codex CLI, Gemini CLI 등 다른 AI 에이전트도 검토해 봤지만, 실무에서 가장 익숙하게 다뤄온 도구이기도 하고, 서브에이전트·스킬·MCP로 이어지는 Claude Code 생태계를 이 프로젝트에서 직접 활용해 보고 싶었습니다.
이렇게 결정하기까지 두 가지 고민이 있었습니다.
먼저 프론트엔드를 직접 구현하는 방식입니다. React 웹 앱 개발 경험을 살려 컴포넌트 하나하나 설계하고 싶었지만, CSS 퍼블리싱 (반응형 레이아웃, 미세한 간격 조정, 애니메이션) 에 들어가는 에너지 소모와 속도 저하가 만만치 않을 것 같았습니다. 빠르게 구현해서 결과를 얻기보다 스타일 디버깅에 시간을 더 쏟게 될 것이 뻔했습니다.
반대로 전부 AI에게 맡기는 방식도 선뜻 내키지 않았습니다. "나만의 웹사이트"를 표방하면서 정작 코드와 애플리케이션 구조를 제대로 이해하지 못한다면 그 자체가 모순이고, 제 성장에도 도움이 되지 않을 것 같았습니다.
그래서 고안한 방식이 AI와 함께하되, 핵심 판단은 제가 직접 내리는 페어프로그래밍입니다. 단순히 코드 자동완성 수준이 아니라, 설계 결정을 함께 고민하고 구현은 Claude AI Agent가 주도하되 레이아웃 구조, 컴포넌트 연계 설계는 제가 직접 내리는 방식입니다. 적절히 공부를 겸하면서 설계자로서 개념을 이해하는 것이 중요했습니다.
여기서 중요한 개념이 Context Engineering입니다. LLM에게 막연하게 "만들어줘"라고 요청하는 것과, 구조화된 컨텍스트를 제공하는 것은 결과물의 품질 차이가 큽니다. 이를 위해 초기 기획부터 다음과 같은 파이프라인을 설계했습니다.
- PRD 생성 서브에이전트: 아이디어를 주고받으며 제품 요구사항 문서(PRD) 초안 작성
- PRD 검증 서브에이전트: 기술적 타당성과 위험도를 검토해 PRD를 보완
- ROADMAP 구현 전문 서브에이전트: PRD를 Phase/Task 단위로 분해한 개발 로드맵 생성
- Shrimp Task Manager: ROADMAP 이후 단계별 Task를 추적하며 구현 진행
이 흐름으로 개발 전반에 걸쳐 일관된 방향성을 유지할 수 있었습니다.
디자인
디자이너 없이 진행했기에, 레퍼런스를 적극 활용했습니다.
Dribbble에서 개인 포트폴리오 디자인을 서칭해보다 UntitledUI의 포트폴리오 디자인을 선택했습니다. 깔끔하면서도 정보 밀도가 높은 구성이 딱 제가 찾던 느낌이라 이를 base 삼으면 좋겠다 생각하고 밑바탕을 그렸습니다.
여기에 UX 측면에서는 박은우님의 ark-log를 참고했습니다. 기술 블로그와 프로젝트 포트폴리오를 자연스럽게 결합한 구조가 제가 원하는 방향과 딱 맞았습니다.
두 레퍼런스를 조합해서 "기술 블로그 + 포트폴리오" 하이브리드 구조를 목표로 설계했습니다.
개발
프로젝트이자 웹사이트의 이름을 뭘로 지을까 고민했습니다. 제가 사용하는 영어 이름인 "Jerome"에서 출발해, 나에 관한 모든 것을 담아내겠다는 의미로 hijero.me로 결정했습니다.
구조적으로는 Turbo를 활용한 모노레포를 채택했습니다. 장기적으로 새로운 앱·패키지를 추가할 가능성을 열어두고, 공유 코드를 하나의 저장소에서 관리하기 위해서입니다. 세부 구조는 다음 글에서 따로 다뤄볼까 합니다.
프론트엔드
Next.js App Router v16+: 블로그 포스트는 빌드 타임 정적 생성(SSG), 조회수 같은 동적 데이터는 서버 처리(SSR) — 이 하이브리드 방식을 React Server Component 단위로 자연스럽게 조합할 수 있습니다.
shadcn/ui: npm 설치가 아닌 컴포넌트 소스 코드를 프로젝트에 직접 복사해 쓰는 방식을 공부해보고 싶어 사용해보았습니다. 컴포넌트의 완전한 소유권을 가지면서, Radix UI 기반 접근성과 CVA 패턴의 타입 안전한 variant 관리를 함께 누릴 수 있습니다.
Tailwind CSS v4: 버전 4부터는 CSS 변수 기반으로 설정 체계가 바뀌면서 shadcn/ui와의 통합이 더 자연스러워졌습니다.
MDX 파일 기반 콘텐츠: 글을 데이터베이스가 아닌 .mdx 파일로 관리합니다.
수정 이력이 git 커밋 히스토리에 남고, 빌드 타임 정적 생성으로 DB 조회 없이 빠르게 제공됩니다.
MDX 파이프라인 구성은 다음 글에서 자세히 다루겠습니다.
백엔드
처음에는 PostgreSQL + NestJS, 혹은 Express 같은 경량 서버도 고려했는데요, 실제로 필요한 기능을 리스트업 해보니 생각이 바뀌었습니다.
- 포스트 조회수 카운팅 (
post_views) - 24시간 중복 방지를 위한 뷰어 핑거프린트 로그 (
post_view_logs) - 향후 댓글 기능 (Giscus로 GitHub Discussions 활용 예정)
기능이 명확히 제한적인 데다, 서빙하는 API가 많지 않아 Supabase를 도입해 보았습니다. 백엔드 통합 솔루션이라고 하여, 요즘 많이 사용하고 있다는 Supabase를 이번 기회에 한번 써보고 싶기도 했습니다. PostgreSQL + Auth + Storage + Row Level Security를 통합 제공하고, 무료 플랜이 있어 본 프로젝트 수행에 적합하다고 생각해서 입니다.
인프라
배포와 인프라는 심플하게 Vercel 을 사용하기로 정했습니다. App Router의 모든 기능이 별도 설정 없이 최적으로 동작하고, PR 생성 시 Preview URL이 자동 배포되는 것도 개발 흐름에 잘 맞았습니다.
마치며
기획부터 첫 번째 배포 가능한 상태까지 약 5일이 걸렸습니다.
PRD → 검증 → ROADMAP → Shrimp Task Manager로 이어지는 파이프라인이 개발 흐름을 잡아주는 데 실제로 효과적이었습니다. "막연하게 만들어줘"가 아니라 구조화된 컨텍스트를 제공했을 때 AI와의 협업 품질이 확연히 달라진다는 걸 직접 경험했습니다.
구현하면서 실무에서 미처 다뤄보지 못했던 테크닉과 개념을 배운 것도 있습니다.
Material Design 3의 Rail Navigation 패턴을 shadcn/ui와 결합하는 작업, SHA-256(IP + User-Agent + Accept-Language) 조합으로 쿠키 없이 24시간 중복 방지를 구현한 조회수 시스템, next-intl v4의 Server/Client Component 양쪽에서 메시지에 접근하는 구조 등,
하나씩 구현해가면서 "이런 방식도 있구나"를 배웠네요.
그렇게 이 hijero.me 웹사이트가 탄생했습니다. 작업한 깃허브 리포지토리는 hijero.me에서 확인하실 수 있습니다. 앞으로도 기능을 추가하고, 글을 쌓으며, 이 공간을 꾸준히 발전시켜 나갈 생각입니다.
본 웹서비스 구축기는 총 세 편으로 나누어 기록해볼까 합니다.
다음 포스트 주제로는 AI를 활용해서 어떻게 구현해 갔는지 구현 과정을 상세히 풀어보겠습니다.