Claude Code를 이용한 정적 포트폴리오 사이트 구축 보고서

요약. 본 보고서는 개발 경험이 없는 사용자가 AI 코딩 에이전트(Claude Code)와 협업하여 정적 포트폴리오 사이트 ASTRACE의 골격을 구축한 과정을 기록하고 분석한다. 작업은 2026년 9월 12일 하루 동안 이루어졌으며, 환경 준비부터 페이지 구조와 분류 체계 완성까지 총 4단계를 마쳤다. 커밋 14건 가운데 6건이 로고 이미지의 가장자리 결함을 바로잡는 데 쓰였고, 이 과정에서 “에이전트의 수정 완료 보고를 검증 없이 수용하면 결함이 그대로 남는다”는 사실이 확인되었다. 분석 결과, 지연의 주요 원인은 기술 난도가 아니라 판정 기준의 부재와 검증 절차의 부재였다. 이에 따라 수치 기반 검증, 단일 진실 원천, 판정 기준을 포함한 요구사항 등 다섯 가지 운영 원칙을 도출하였다.

1. 서론

1.1 배경

포트폴리오의 주제가 “AI와 함께 만든다”라면, 포트폴리오를 담는 사이트 역시 같은 방식으로 만들어져야 한다. 사용자는 기존에 사용하던 블로그 플랫폼이 외부 도구로 글을 읽고 쓸 공식 통로를 제공하지 않아 자동화가 불가능하다는 점을 확인하고, 마크다운 파일을 원본으로 하는 별도의 정적 사이트를 구축하기로 결정하였다. 사이트의 소스가 저장소에 남으면 그 자체가 첫 번째 프로젝트의 증빙이 된다.

1.2 목적과 범위

본 보고서의 목적은 두 가지다. 첫째, 구축 과정을 재현 가능한 수준으로 기록한다. 둘째, 진행 중 발생한 문제의 원인을 사용자 요인, 에이전트 요인, 협업 구조 요인으로 나누어 분석하고, 이후 작업에 적용할 원칙을 도출한다. 범위는 기획서에 정의된 7단계 가운데 1단계(프로젝트 생성)부터 4단계(분류 체계)까지이며, 배포와 운영 문서는 후속 과제로 남긴다.

1.3 용어

• 사용자: 사이트 소유자. 프로그래밍 경험이 없으며, 기획·승인·화면 검수를 담당하였다.
• 에이전트: Claude Code. 조사·구현·검증·커밋을 담당하였다.
• 단계: 기획서 7번 항목의 작업 순서. 각 단계는 계획 제시, 승인, 구현, 화면 확인, 커밋으로 구성된다.

2. 작업 환경과 방법

작업 절차는 다음과 같이 고정하였다. 에이전트가 단계별 계획을 제시하면 사용자가 승인하고, 에이전트가 구현한 뒤 브라우저 화면으로 결과를 제시하며, 사용자가 확인하면 커밋한다. 코드를 짜기 전에 방향을 승인받는 규칙은 작업 지침 파일에 명문화되어 있었고, 실제로 예외 없이 지켜졌다.

3. 진행 과정

3.1 준비: 환경 점검

에이전트는 폴더 내 문서(기획서, 작업 지침, 브랜드 시안 4장)를 읽은 뒤 도구 설치 상태를 점검하였다. Node.js, npm, Python이 모두 없었고 Git만 설치되어 있었다. 또한 작업 폴더가 클라우드 동기화 폴더 안에 있어, 수만 개 파일이 생기는 의존성 설치가 동기화와 충돌할 위험이 확인되었다. 사용자 승인 하에 Node.js를 설치하고 프로젝트를 로컬 폴더로 옮겼다. 비용은 전 과정에서 0원이었다.

3.2 템플릿 선정

기획서는 별 입자 배경을 가진 다크 테마 템플릿을 1순위로 지정하고 있었다. 1단계에서 이 템플릿으로 프로젝트를 생성한 직후, 사용자는 로고와 어울리는 “항공우주 느낌”을 요청하였다. 에이전트는 공식 테마 갤러리와 저장소 검색을 통해 후보를 수집하였고, 위성·지상국·별자리가 실제 기하학으로 움직이는 첫 화면을 가진 Astro Orbit을 추천하였다. 사용자가 이를 채택하여 템플릿을 교체하였다. 교체는 1단계 완료 후에 이루어졌으므로 1단계 작업 일부가 폐기되었다.

3.3 브랜드 적용

색은 로고 이미지에서 추출하여 다크·라이트 두 팔레트를 만들었다. 템플릿이 색을 7개의 CSS 변수로 관리하고 첫 화면의 위성 통신선까지 같은 변수를 읽도록 되어 있어, 강조색 하나를 바꾸면 화면 전체가 일관되게 바뀌었다. 본문 서체는 Pretendard로 교체하고, 로고는 브랜드 시안 모음에서 잘라내어 투명 배경으로 변환하였다.

이 로고 변환이 이후 가장 많은 수정을 유발하였다. 사용자는 궤적의 시작 부분 얼룩, 그라데이션 손실, 가장자리의 회색 띠를 차례로 지적하였고, 에이전트는 네 차례에 걸쳐 수정하였다. 세부 원인은 5장에서 다룬다.

3.4 개인 정보 제거

사용자는 사이트에 직업, 지역, 경력 등 개인 정보가 드러나지 않도록 요청하였다. 에이전트는 설정 파일, 소개 페이지, 명령창 출력, 검색엔진용 메타데이터에서 해당 항목을 모두 제거하고, 템플릿이 제공하던 경력·학력·자격증 섹션과 관련 부품을 삭제하였다. 소개는 한 줄 문장으로 축소되었다.

3.5 페이지 골격

기획서 3.1의 페이지 5개(홈, 프로젝트, 글 목록, 글 상세, 소개)를 구현하였다. 글과 프로젝트의 파일 형식을 확정하고, 형식에 어긋난 값(예: 정의되지 않은 카테고리)은 빌드 단계에서 오류로 차단되도록 하였다. 글 상세에는 넓은 화면에서 오른쪽에 고정되는 목차를 추가하였다.

3.6 분류 체계

카테고리 3개(바이브코딩, 지식 나눔, 일상 AI)를 고정하고, 카테고리별·태그별 목록 페이지를 빌드 시점에 정적으로 생성하였다. 이 방식은 자바스크립트 없이 동작하고 주소를 공유할 수 있으며 검색엔진에도 노출된다. 검색은 빌드 때 만드는 JSON 색인을 브라우저에서 읽는 방식이다.

4. 신규 도입 기술

이 가운데 sharp 기반 로고 파이프라인은 템플릿에 없던 것으로, 로고 원본 하나에서 다크·라이트 버전, 심볼, SNS 공유 카드를 자동 생성한다. 명령 한 줄로 재실행할 수 있도록 스크립트화하였다.

5. 구현이 막힌 지점과 조치

3번부터 5번까지의 로고 문제는 서로 다른 세 가지 원인이 겹쳐 있었다. 에이전트는 두 차례 “수정 완료”를 보고하였으나 사용자가 화면에서 결함을 다시 발견하였고, 세 번째에 이르러서야 픽셀 값을 직접 측정하여 원인을 확정하였다. 측정 결과 궤적 중심은 (12, 130, 240)이었으나 가장자리는 (71, 157, 229)로 밝았고, 바깥쪽에는 검정에 가까운 픽셀이 부분 투명도로 남아 있었다. 즉 밝은 안쪽 띠와 어두운 바깥 띠가 동시에 존재하였다.

6. 분석

6.1 사용자 요인

사용자의 약점은 다음과 같이 정리된다.

1. 코드 검증 불가. 프로그래밍 경험이 없어 구현의 정확성을 확인할 수단이 화면뿐이었다. 그 결과 에이전트의 “수정 완료” 보고를 두 차례 그대로 수용하였고, 결함은 화면에서 다시 발견될 때까지 남아 있었다.
2. 요구사항의 점진적 노출. 로고에 대한 기준(“원본과 동일할 것”, “그라데이션 유지”, “테두리 없음”)은 처음에 제시되지 않고 네 차례의 왕복 끝에 드러났다. 기준이 처음부터 명시되었다면 수정 횟수는 줄었을 것으로 판단된다.
3. 방향 전환. 템플릿은 1단계 완료 후 교체되었고, 배포 방식은 공개(GitHub Pages)에서 비공개(Cloudflare Pages + Access)로 바뀌었으며, 개인 정보 제거는 3단계 직전에 추가되었다. 각 전환은 타당했으나 기획서와의 차이를 낳았다.
4. 환경 준비 부족. 필수 런타임이 없었고 작업 폴더 위치가 부적절하였다.

한편 사용자의 시각 검수는 결함을 발견한 유일한 경로였다. 픽셀 단위의 미세한 띠를 두 차례 모두 사용자가 잡아냈다는 점은, 비전문가의 검수가 무용하지 않으며 오히려 에이전트의 자기 보고를 견제하는 장치였음을 보여 준다.

6.2 에이전트 요인

1. 검증 없는 완료 보고. 에이전트는 원인을 추정한 뒤 수정하고, 결과를 측정하지 않은 채 완료를 보고하였다. 세 번째 시도에서야 브라우저가 실제로 불러온 이미지의 픽셀을 읽어 확인하였다. 이 절차가 처음부터 있었다면 왕복은 한 번으로 끝났을 것이다.
2. 도구 한계에 대한 인식 부족. 대용량 셸 명령의 실패, 정규식 치환의 변수 해석, 개발 서버의 상태 유지 등은 모두 도구 특성에서 비롯되었으며, 각각 한 번씩 재작업을 유발하였다.
3. 요청하지 않은 추가. 홈에 도구 목록 섹션을 임의로 추가하였다가 이후 소개 페이지로 옮겼다. 작업 지침에 “요청하지 않은 기능을 추가하지 않는다”가 명시되어 있었음에도 발생한 위반이다.

6.3 협업 구조 요인

단계별 승인 구조는 큰 방향의 오류를 막는 데 유효하였다. 그러나 각 단계의 “확인”이 화면 관찰에만 의존하였기 때문에 화면으로 판별하기 어려운 결함은 통과되었다. 반대로 기획서와 작업 지침이 사전에 문서화되어 있었던 점은 이름, 철학, 카테고리 수와 같은 결정을 재론하지 않게 하여 시간을 절약하였다.

6.4 종합

지연의 주된 원인은 기술 난도가 아니었다. 페이지 골격과 분류 체계는 각각 한 번의 커밋으로 완료되었다. 시간이 소요된 곳은 판정 기준이 없는 시각적 요구사항(로고)이었고, 그 안에서도 원인 분석 없이 반복된 수정이 문제였다. 커밋 14건 중 6건(43%)이 로고에 쓰인 것이 이를 뒷받침한다.

7. 결론 및 도출 결과

7.1 결과물 상태

7.2 도출된 원칙

1. 수정 보고는 측정값과 함께 한다. 화면이 아니라 픽셀 값, 응답 코드, 빌드 결과처럼 숫자로 확인한 뒤 보고한다.
2. 단일 진실 원천을 둔다. 문구는 설정 파일 하나, 색은 변수 7개, 로고는 원본 파일 하나에서만 바꾼다.
3. 요구사항에는 판정 기준을 포함한다. “예쁘게”가 아니라 “원본과 동일”, “테두리 없음”처럼 통과 조건을 적는다.
4. 개인 정보는 기본적으로 노출하지 않는다. 노출할 정보는 사용자가 선별하여 명시한다.
5. 단계마다 승인, 구현, 검증, 커밋을 한 묶음으로 한다. 되돌릴 수 있는 단위를 유지한다.

7.3 후속 과제

비공개 배포(Cloudflare Pages + Access), 운영 문서 작성, 프로젝트 내용 채우기, 라이트 모드와 모바일 화면 점검이 남아 있다. 본 보고서는 이 사이트의 첫 글이며, 후속 단계의 결과는 별도의 글로 기록한다.

부록 A. 프로젝트 구조

astrace/
├── brand/                      로고 원본, 브랜드 시안
├── public/brand/               사이트용 로고 (자동 생성)
├── scripts/build-brand-assets.mjs
├── src/
│   ├── config.ts               사이트 문구·메뉴·링크
│   ├── content.config.ts       글·프로젝트 형식 정의
│   ├── content/posts/          글 (YYYY-MM-DD-slug.md)
│   ├── content/projects/       프로젝트 (slug.md)
│   ├── data/                   카테고리, 브랜드 문구
│   ├── components/             화면 부품
│   ├── layouts/                페이지 틀
│   ├── pages/                  주소별 페이지
│   └── styles/global.css       색 변수, 서체, 본문 스타일
├── PLAN.md                     기획서
└── CLAUDE.md                   에이전트 작업 지침

부록 B. 글 파일 형식

---
title: "글 제목"
date: 2026-09-12
category: vibe-coding        # vibe-coding | insights | daily-ai
tags: [claude-code, astro]   # 영문 소문자
description: "한 줄 요약"
cover: ./images/cover.png    # 선택
draft: false                 # true 면 사이트에 보이지 않음
---

본 보고서는 작업 기록을 바탕으로 에이전트가 초안을 작성하고 사용자가 검토하였다.