서론 (Introduction)

"URL을 지정하고 /clone-website를 실행하면, AI 에이전트가 사이트를 조사하고, 디자인 토큰(design tokens)과 에셋(assets)을 추출하며, 컴포넌트 명세(component specs)를 작성한 뒤, 병렬 빌더(parallel builders)를 파견하여 모든 섹션을 재구성합니다."

이 글은 "하루에 하나의 오픈 소스 프로젝트(One Open Source Project a Day)" 시리즈의 108번째 기사입니다. 오늘의 프로젝트는 ai-website-cloner-template로, AI 코딩 에이전트를 사용하여 모든 웹사이트를 Next.js 코드베이스로 역설계(reverse-engineering)하기 위한 GitHub 템플릿 저장소입니다.

"웹사이트 스크린샷"을 "실행 가능한 코드"로 변환하는 것은 전형적인 바이브 코딩(Vibe Coding) 시나리오이지만, 대부분의 구현은 표면적인 수준에서 멈춥니다. 즉, LLM에게 스크린샷을 보고 레이아웃을 근사치로 추정하며 자리 표시용(placeholder) 콘텐츠를 채우라고 요청하는 식입니다. 이 템플릿은 근본적으로 다른 접근 방식을 취합니다. 이 템플릿은 **"완전성이 속도보다 중요하다(completeness beats speed)"**라는 핵심 원칙을 가진 엄격한 다단계 에이전트 워크플로우(multi-phase agent workflow)를 정의합니다. 즉, 모든 빌더 에이전트(Builder Agent)는 코드를 건드리기 전에 정확한 getComputedStyle() 값, 실제로 다운로드된 에셋, 그리고 완전한 상호작용 상태 명세(interaction state specifications)를 반드시 갖추어야 합니다.

22k개의 스타(stars)는 이 유스케이스에 대한 실제 수요를 나타냅니다. 하지만 더 흥미로운 이야기는 엔지니어링 설계, 특히 진정한 병렬 멀티 에이전트 구축을 달성하기 위해 git worktree를 사용하는 방식에 있습니다.

학습 내용

• 5단계 클론 파이프라인: 정찰(reconnaissance) → 기반 구축(foundation) → 컴포넌트 명세(component specs) → 병렬 빌드(parallel build) → 조립 QA(assembly QA)
• git worktree 병렬 에이전트 패턴: 각 빌더 에이전트(Builder Agent)가 격리된 브랜치에서 작동하는 방식
• 컴포넌트 명세 파일 설계 원칙: 왜 명세(spec)가 "참조(reference)"가 아닌 "계약(contract)"이어야 하는가
• 상호작용 모델 식별: 빌드 전 클릭 기반(click-driven), 스크롤 기반(scroll-driven), 시간 기반(time-driven) 동작을 구분하는 방법
• 크로스 플랫폼 에이전트 지원: 13개의 AI 코딩 도구가 어떻게 단일 소스 파일로부터 모두 서비스되는가

사전 요구 사항

• Claude Code, Cursor 또는 유사한 AI 코딩 도구 사용 경험
• Next.js에 대한 기본적인 친숙함
• git 브랜치에 대한 기본적인 이해

프로젝트 배경

개요 (Overview)

ai-website-cloner-template는 Next.js 16 + shadcn/ui + Tailwind v4 프로젝트와 /clone-website AI Agent Skill (에이전트 스킬)을 미리 구성해 놓은 GitHub 템플릿 저장소(is_template: true)입니다.

사용 패턴: GitHub에서 "Use this template"을 사용하여 자신만의 저장소를 생성하고, AI 에이전트를 시작한 뒤, /clone-website <target-url>을 실행하면 에이전트가 정찰(reconnaissance)부터 작동 가능한 코드 생성까지의 전체 파이프라인을 완료합니다.

이 프로젝트의 핵심 엔지니어링 기여는 기술 스택의 선택이 아니라, /clone-website 스킬 뒤에 숨겨진 **멀티 에이전트 협업 프로토콜 (multi-agent collaboration protocol)**에 있습니다. 특히 진정한 병렬 컴포넌트 빌드를 위해 git worktree를 사용하고, "설계 우선, 빌더 후순위 (spec first, builder second)" 제약 조건을 강제하는 점이 핵심입니다.

작성자 / 팀 (Author / Team)

• 작성자 (Author): JCodesMore
• 주요 언어 (Primary Language): TypeScript
• 라이선스 (License): MIT
• 커뮤니티 (Community): Discord

프로젝트 통계 (Project Stats)

• ⭐ GitHub Stars: 22,100+
• 🍴 Forks: 3,173+ (대부분 독립적인 프로젝트를 생성하는 데 사용됨)
• 📄 라이선스 (License): MIT
• 📅 생성일 (Created): 2026년 3월

기능 (Features)

주요 기능 (What It Does)

전통적인 "스크린샷 클론 (screenshot clone)" 방식:
스크린샷 → LLM이 레이아웃 추정 → 플레이스홀더 (placeholder) 콘텐츠 → 수동 색상/간격 수정 → 반복

...

사용 사례 (Use Cases)

1. 플랫폼 마이그레이션 (Platform migration): 본인이 소유한 사이트를 WordPress/Webflow/Squarespace에서 Next.js 코드베이스로 재구축하여 완전한 코드 소유권을 확보
2. 유실된 소스 코드 (Lost source code): 사이트는 운영 중이지만 저장소가 사라졌거나, 개발자가 떠났거나, 스택이 너무 오래되어 유지보수가 불가능한 경우 — 라이브 버전을 최신 형식의 코드로 복구
3. 학습 (Learning): (단순히 스크린샷만이 아니라) 실제 코드를 다룸으로써 프로덕션 사이트가 특정 레이아웃, 애니메이션, 반응형 동작을 어떻게 구현하는지 해체 분석

권장하지 않는 용도 (Not Intended For)

README에는 다음과 같이 명시되어 있습니다:

• 피싱 또는 사칭 (Phishing or impersonation): 기만적인 목적, 사칭 또는 불법 활동을 위한 사용은 금지됩니다.
• 타인의 디자인을 자신의 것으로 속이는 행위 (Passing off others' designs as your own): 로고, 브랜드 자산 및 원본 카피는 해당 소유자에게 귀속됩니다.
• 서비스 약관 위반 (Violating terms of service): 일부 사이트는 스크래핑 (Scraping) 또는 복제를 명시적으로 금지합니다 — 먼저 확인하십시오.

빠른 시작 (Quick Start)

1. 자신만의 저장소(Repository) 생성

GitHub 프로젝트 페이지에서 Use this template → Create a new repository를 클릭하세요 (템플릿 저장소를 직접 클론(Clone)하지 마세요).

2. 클론 및 설치 (Clone and install)

git clone https://github.com/YOUR-USERNAME/YOUR-NEW-REPO.git
cd YOUR-NEW-REPO
npm install

3. Claude Code 실행 (권장)

claude --chrome   # --chrome은 브라우저 자동화를 위한 Chrome MCP를 시작합니다

4. 클론 스킬(Clone skill) 실행

/clone-website https://target-website.com

여러 URL을 병렬로 처리할 수 있습니다:

/clone-website https://site1.com https://site2.com

5. 개발 프리뷰 (Dev preview)

npm run dev        # 개발 서버 시작
npm run check      # 린트(Lint) + 타입 체크(Typecheck) + 빌드(Build) 실행

지원되는 AI 에이전트 플랫폼 (Supported AI Agent Platforms)

교차 플랫폼 지원은 다음과 같이 작동합니다: AGENTS.md는 모든 프로젝트 지침의 단일 진실 공급원 (Single source of truth)입니다. bash scripts/sync-agent-rules.sh를 실행하면 해당 단일 파일로부터 플랫폼별 복사본(CLAUDE.md, GEMINI.md, .cursor/, .windsurf/ 등)이 자동으로 생성됩니다.

심층 분석 (Deep Dive)

5단계 파이프라인 (The Five-Phase Pipeline)

1단계: 정찰 (Reconnaissance)

이것은 단순한 스크린샷 촬영이 아닙니다. 정찰에는 세 가지 필수 작업이 필요합니다:

스크린샷 (Screenshots): 1440px (데스크톱) 및 390px (모바일) 크기의 전체 페이지 스크린샷을 찍어 docs/design-references/에 저장합니다. 이는 전체 프로세스의 시각적 마스터 참조 자료가 됩니다.

필수 상호작용 스캔 (Mandatory interaction sweep) (가장 흔히 누락되는 단계):

스크롤 스윕 (Scroll sweep) — 위에서 아래로 천천히 스크롤하며 다음 사항을 관찰합니다:

• 어느 스크롤 위치에서 내비게이션 바 (navbar)의 외형이 변하는가?
• 뷰포트 (viewport)에 진입할 때 어떤 요소들이 애니메이션 효과와 함께 나타나는가?
  ...

모든 발견 사항은 docs/research/BEHAVIORS.md에 저장됩니다. 이는 전체 클로닝 (cloning) 프로세스를 위한 "행동 성서 (behavior bible)" 역할을 합니다.

페이지 토폴로지 (Page topology): 위에서 아래로 모든 개별 섹션을 매핑하고, 각 섹션의 상호작용 모델 (정적 / 클릭 기반 / 스크롤 기반 / 시간 기반)을 문서화하여 docs/research/PAGE_TOPOLOGY.md로 저장합니다. 이는 조립 설계도 (assembly blueprint)가 됩니다.

페이즈 2: 기반 구축 (Phase 2: Foundation Build)

오케스트레이터 에이전트 (Orchestrator Agent)가 직접 수행합니다 — 하위 에이전트 (sub-agents)에게 위임하지 않습니다. 이는 많은 파일을 직접 수정해야 하기 때문입니다:

1. src/app/layout.tsx 업데이트: next/font/google 또는 next/font/local을 통해 대상 사이트의 실제 폰트를 설정합니다.
2. src/app/globals.css 업데이트: 대상 사이트의 컬러 토큰 (background, foreground, primary, muted...)을 oklch 색 공간을 사용하여 shadcn 변수 시스템에 매핑합니다.
3. 모든 SVG 아이콘 추출 → src/components/icons.tsx에 이름이 지정된 React 컴포넌트로 저장합니다.
4. 에셋 다운로드 스크립트 (scripts/download-assets.mjs) 실행: 모든 이미지와 비디오를 public/ 폴더로 일괄 다운로드합니다.
5. 검증: npm run build가 통과하는지 확인합니다.

에셋 탐색 (Asset discovery)은 브라우저 MCP를 통해 JavaScript를 실행하여 모든 <img>, <video>, 그리고 CSS background-image 요소를 정밀하게 열거합니다. 여기에는 절대 위치 지정된 오버레이 레이어 (absolutely-positioned overlay layers) 도 포함됩니다. 단일 이미지처럼 보이는 섹션이 실제로는 배경 수채화 + 전경 UI 목업 PNG + 오버레이 아이콘의 조합인 경우가 많기 때문입니다. 레이어 하나라도 누락되면 클론이 텅 비어 보일 수 있습니다.

// 모든 에셋을 탐색하기 위해 브라우저 MCP를 통해 실행
JSON.stringify({
  images: [...document.querySelectorAll('img')].map(img => ({
...

페이즈 3: 컴포넌트 사양 (Phase 3: Component Specs)

빌더 에이전트 (Builder Agent)가 투입되기 전에, 해당 섹션에 대한 사양 파일(spec file)이 docs/research/components/<name>.md에 반드시 작성되어야 합니다. 이 사양은 추출 (extraction)과 구축 (construction) 사이의 **계약 (contract)**이며, 선택 사항이 아닙니다.

사양 파일에 포함되는 내용:

• 해당 섹션의 스크린샷 크롭 이미지 (로컬 경로)
• getComputedStyle()을 통해 추출된 정확한 CSS 값 (Exact CSS values) — 눈대중으로 추정한 값이 아님
• 다운로드된 에셋의 로컬 경로 (original URL이 아닌 public/ 경로)
• 실제 텍스트 콘텐츠 (placeholder가 아닌 element.textContent에서 추출)
• 모든 상호작용 상태 (탭 상태별 콘텐츠, 스크롤 트리거 전후의 CSS 차이, 트랜지션 애니메이션 파라미터)
• 반응형 브레이크포인트 (Responsive breakpoint) 동작

CSS 추출 스크립트 (브라우저 MCP를 통해 실행됨):

(function(selector) {
  const el = document.querySelector(selector);
  const computed = getComputedStyle(el);
...

복잡도 예산 규칙 (Complexity budget rule): 만약 특정 섹션의 사양 파일이 약 150라인을 초과하면, 해당 섹션은 단일 에이전트가 처리하기에 너무 복잡한 것입니다. 이를 더 작은 조각으로 나누십시오. 이는 "하지만 모두 연관되어 있다"라는 말로 무시할 수 없는 기계적인 체크 항목입니다.

4단계: git Worktrees를 통한 병렬 빌드 (Parallel Build)

이것이 핵심적인 아키텍처 결정입니다. git worktrees는 각 빌더 에이전트 (Builder Agent)에게 격리된 작업 브랜치를 제공합니다:

# 오케스트레이터(Orchestrator)가 섹션당 하나의 worktree를 생성
git worktree add .worktrees/hero-section feature/hero-section
git worktree add .worktrees/features-grid feature/features-grid
...

각 빌더 에이전트가 받는 것:

• 전체 사양 파일 내용 (경로 참조가 아닌 프롬프트 내에 인라인으로 포함됨)
• 스크린샷 크롭 경로
• 다운로드된 에셋의 로컬 경로
• 글로벌 스타일 시스템 (폰트 변수, 컬러 토큰)

빌더는 다른 섹션의 코드를 읽거나 전체 페이지 구조를 이해할 필요가 없습니다. 빌더의 유일한 임무는 TypeScript가 깔끔하게 컴파일되도록, 사양에 맞춰 이 단일 컴포넌트를 구현하는 것입니다.

5단계: 조립 및 QA (Assembly & QA)

# 오케스트레이터가 모든 worktree 브랜치를 병합
git merge feature/hero-section feature/features-grid feature/pricing-section ...
# 병합 충돌 해결 (오케스트레이터는 스마트한 해결을 위한 전체 컨텍스트를 보유함)
...

가장 비용이 많이 드는 단 한 가지 실수: 잘못된 상호작용 모델 (Wrong Interaction Model)

SKILL 파일이 이 부분에 상당한 비중을 할애하는 이유는 원본이 스크롤 기반(scroll-driven)인데 클릭 기반(click-based) UI를 구축하는 것은 단순한 CSS 수정이 아니라 완전히 새로 작성해야 함을 의미하기 때문입니다.

식별 프로토콜 (Identification protocol):

1. 먼저 클릭하지 마세요. 천천히 스크롤하며 자동으로 변하는 것이 있는지 관찰하세요.
2. 변한다면 → 스크롤 기반(scroll-driven)입니다. 메커니즘을 추출하세요: IntersectionObserver, scroll-snap, position: sticky, animation-timeline, 또는 JS 스크롤 리스너(scroll listeners).
3. 변하지 않는다면 → 클릭/호버 기반(click/hover-driven) 상호작용을 테스트하세요.
4. 명세서(spec)에 명시적으로 기록하세요: INTERACTION MODEL: IntersectionObserver를 사용한 스크롤 기반(scroll-driven) 또는 INTERACTION MODEL: 불투명도 전환(opacity transition)을 사용한 클릭 전환(click-to-switch).

주의 깊게 살펴봐야 할 전형적인 스크롤 기반 패턴:

• 콘텐츠가 스크롤됨에 따라 활성 항목이 자동으로 변경되는 스티키 사이드바 (IntersectionObserver 사용, 클릭 핸들러(click handlers) 아님)
• 클릭 기반으로 구축되었을 때 순환하는 탭/필(pill) 형태의 콘텐츠
• 부드러운 스크롤 라이브러리 (Lenis, Locomotive Scroll) — .lenis 클래스나 스크롤 컨테이너 래퍼(wrappers) 확인

프로젝트 구조 (Project Structure)

src/
  app/              # Next.js 라우트 (routes)
  components/       # 컴포넌트
...

크로스 플랫폼 디자인: 하나의 소스, 다양한 타겟 (Cross-Platform Design: One Source, Many Targets)

이 템플릿은 13개의 별도 지침 세트를 유지 관리하지 않고도 13개의 AI 코딩 플랫폼을 지원합니다:

각 스크립트는 플랫폼별 복사본을 자동으로 생성합니다. 소스 파일을 네이티브하게 읽을 수 있는 에이전트(Agents)는 재생성할 필요가 없습니다.

이 패턴 — 단일 소스 파일과 생성 스크립트의 조합 — 은 여러 AI 코딩 환경을 지원해야 하는 모든 도구에서 차용할 가치가 있습니다.

리소스 (Resources)

공식 링크 (Official Links)

• 🌟 GitHub: JCodesMore/ai-website-cloner-template
• 🎬 데모 영상 (Demo video): 프로젝트 README에 포함된 YouTube 링크
• 💬 Discord: discord.gg/hrTSX5yTpB

요약 (Summary)

ai-website-cloner-template의 가치는 기술 스택의 선택(Next.js + shadcn + Tailwind는 표준적인 조합임)에 있는 것이 아닙니다. 진정한 가치는 세심하게 설계된 **멀티 에이전트 협업 프로토콜 (multi-agent collaboration protocol)**에 있습니다.

내재화할 가치가 있는 몇 가지 설계 결정 사항은 다음과 같습니다:

"완전성이 속도보다 우선한다 (Completeness beats speed)": 빌더 에이전트 (Builder Agents)는 작업을 시작하기 전에 모든 정보를 전달받습니다. 구축 중간에 추측하는 과정이 없습니다. 이러한 제약 조건은 정찰 (reconnaissance) 단계가 느려지는 대가를 치르지만, 결과의 신뢰성을 높여줍니다. 저자는 이러한 트레이드오프 (tradeoff)가 옳다고 판단했습니다.

복잡도 예산 (Complexity budget) (150라인 사양 = 신호 분할): 이는 주관적인 판단이 아니라 작업 범위를 제어하는 기계적인 규칙입니다. 직관이 아닌 엔지니어링 규율 (Engineering discipline)입니다.

git worktree 병렬성 (git worktree parallelism): 각 빌더 (Builder)는 격리된 브랜치에서 작업하며, 오케스트레이터 (Orchestrator)가 마지막에 병합 (merge)합니다. 여기서 병렬성이란 단순히 "여러 작업을 동시에 실행하는 것"이 아니라, 명확한 병합 의미론 (merge semantics)을 가진 격리된 작업입니다.