Claude Code 멀티에이전트로 포트폴리오 사이트 리뉴얼한 후기
토요일 오후, 나는 사장이 됐다. 직원은 6명. 전부 AI다.
Claude Code의 멀티에이전트 기능(bkit)을 써서 포트폴리오 사이트를 한번에 리뉴얼하는 실험을 했다. 디자인 수정, 3D 씬 강화, 블로그 카테고리 추가, 이미지 변환, 콘텐츠 작성까지 — 원래라면 며칠 걸릴 작업을 AI 팀에게 맡긴 기록이다.
왜 멀티에이전트인가
혼자 Claude Code를 쓰면 한 번에 하나씩 작업한다. 파일 수정 → 확인 → 다음 파일. 순차적이다. 프로젝트가 커지면 이게 답답해진다.
멀티에이전트는 다르다. 팀장 에이전트가 작업을 분배하고, 팀원 에이전트들이 각자 맡은 파일을 동시에 수정한다. 파일 충돌만 없으면 진짜 병렬로 돌아간다.
실제로 어떻게 했는지 처음부터 끝까지 정리한다.
팀 구성
UPGRADE_PLAN.md 파일에 전체 계획을 작성했다. 6명의 에이전트를 이렇게 배치했다.
| 에이전트 | 역할 | 담당 파일 |
|---|---|---|
| @design-dev | UI 리뉴얼 | AboutMe.tsx, Stats.tsx, Features.tsx, Pricing.tsx |
| @page-dev | 새 페이지 | /resume, /contact, /art, /tools |
| @blog-dev | 블로그 기능 | 태그, 검색, 카테고리 시스템 |
| @3d-dev | 3D 씬 | HeroScene.tsx |
| @image-processor | 이미지 변환 | HEIC → WebP |
| @content-writer | 글 작성 | 키보드 리뷰, 데스크 투어 |
핵심 규칙은 파일 충돌 방지다. 각 에이전트에게 "이 파일만 건드려, 나머지는 절대 손대지 마"라고 못 박았다. 사람 팀이랑 똑같다 — 같은 파일을 두 명이 동시에 수정하면 머지 충돌이 난다.
실행
환경변수를 설정하고 Claude Code에서 팀을 가동했다.
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
cd ~/jjygo.github.io && claude
팀장 에이전트가 UPGRADE_PLAN.md를 읽고 질문을 시작했다. "AboutMe에 넣을 프로젝트 3개를 골랐는데 맞나요?" "자기소개 스타일은?" "이력서 정보 알려주세요."
나는 사장이니까 결정만 내렸다. "이대로 진행", "화이트 미니멀 감성", "기본정보만 사용."
질문이 끝나자 팀원들이 동시에 작업을 시작했다.
팀이 작업하는 모습
실시간 모니터링 대시보드. 왼쪽에 팀원 진행 상황, 오른쪽에 localhost:3000 프리뷰.
iTerm2에서 Claude Code 팀장이 작업 지시하는 화면과 대시보드를 나란히 띄운 모습.
삽질: 사이트가 박살났다
팀원들이 열심히 일한 결과, 사이트가 완전히 깨졌다.
3D 에이전트가 HeroScene.tsx에 13개 아이콘 텍스처를 불러오는 코드를 넣었는데, 해당 PNG 파일이 public/icons/에 존재하지 않았다. 결과는 화면 전체를 덮는 거대한 파란색 원. CSS가 깨진 줄 알았는데 Three.js의 깨진 텍스처가 뷰포트를 전부 가려버린 거였다.
3D 에이전트가 만든 결과물. 거대한 파란색 원이 전체 화면을 덮었다.
이게 멀티에이전트의 함정이다. 에이전트끼리 의존성을 확인하지 않는다. "나는 텍스처 경로를 쓸 테니 다른 에이전트가 파일을 넣어주겠지"라는 암묵적 가정은 통하지 않는다.
수정
FIX_INSTRUCTIONS.md를 작성해서 우선순위를 지정했다.
- CSS 로딩 문제 진단 (결론: CSS는 정상, 3D 오버플로우가 원인)
- HeroScene.tsx를 외부 텍스처 의존 없이 완전 재작성
- 빌드 검증
Claude Code에 한 줄 명령을 줬다.
FIX_INSTRUCTIONS.md 읽고 전부 수정해. CSS 깨진거 먼저 고쳐.
2분 44초 후, 팀장이 원인을 찾고 HeroScene을 새로 작성했다. 이번엔 외부 파일에 의존하지 않는 순수 Three.js 지오메트리만 사용했다. 반투명 유리 구체 6개, 미세한 파티클 40개, 거의 안 보이는 커서 라이트. Apple 제품 페이지 수준의 미니멀을 주문했다.
npm run build 통과. npx tsc --noEmit 에러 없음. 사이트 복구 완료.
수정 후. 반투명 유리 구체가 우측에 조용히 떠다닌다.
결과물
하나의 세션에서 나온 결과다.
디자인 변경:
- AboutMe 섹션이 스킬 바에서 프로젝트 카드로 변경
- Stats 섹션의 "0+ 프로젝트, 0+ 커밋"이 실제 숫자로 교체
- Features 섹션의 "Coming Soon" 배지 제거, 실제 링크 연결
- Pricing 섹션 간소화
새 기능:
- 네비게이션에 이력서, 연락처 링크 추가
- 블로그에 데스크테리어 카테고리 추가
- 태그 기반 필터링
content-writer 에이전트가 자동 생성한 데스크 셋업 블로그 포스트들.
콘텐츠:
- "2026 화이트 데스크 투어" 포스트 자동 생성
- "Razer BlackWidow V4 75% 리뷰" 포스트 자동 생성
3D:
- HeroScene을 텍스처 의존 없는 순수 지오메트리로 재구축
배운 것
멀티에이전트는 생각보다 잘 된다. 파일 범위만 명확하게 나누면 진짜 병렬로 작업한다. 한 명이 Features.tsx를 고치는 동안 다른 한 명이 블로그 카테고리를 추가하고, 또 다른 한 명이 HEIC를 WebP로 변환한다.
파일 의존성은 직접 관리해야 한다. 에이전트끼리 "이 파일은 네가 만들어줄 거지?"라고 소통하지 않는다. 의존성이 있으면 명시적으로 순서를 지정해야 한다 (content-writer는 image-processor 완료 후 시작).
수정 지시는 짧고 명확하게. 긴 명령은 입력 자체가 안 될 수 있다. "FIX_INSTRUCTIONS.md 읽고 전부 수정해"가 400자짜리 설명보다 효과적이다.
영어 명령이 더 잘 먹힌다. 한국어도 이해하지만, 기술적 지시는 영어가 더 정확하게 파싱된다.
결과물은 반드시 직접 확인해야 한다. 빌드가 통과해도 화면이 깨질 수 있다. npm run build 성공 ≠ 사이트 정상. localhost를 직접 열어서 눈으로 확인하는 과정은 생략하면 안 된다.
다음 스텝
아직 완벽하지 않다. 3D 씬이 좀 더 세련되어야 하고, 데스크 투어 포스트에 실제 사진이 들어가야 한다. Notion에 정리해둔 장비 목록도 반영해야 하고.
하지만 토요일 오후 한 세션으로 이 정도 나왔으면 나쁘지 않다. AI 에이전트 6명이 동시에 일하는 걸 보는 건 꽤 재미있는 경험이었다. 사장 놀이는 계속된다.