Smart Rebuild 전체 플로우
"Rebuild, not Migrate" — 코드를 변환하지 않고, 새로 만든다.
개요
Smart Rebuild는 레거시 사이트(웹빌더, PHP 등)를 현대적인 기술 스택(Next.js, Spring Boot 등)으로 새로 구축하는 AI 기반 워크플로우입니다.
전체 워크플로우 다이어그램
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SMART REBUILD 전체 워크플로우 │
│ Version 2.2.0 │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Phase 1: CAPTURE (링크 수집) │
│ /jikime:smart-rebuild capture https://example.com │
├─────────────────────────────────────────────────────────────────────────────────┤
│ • Playwright로 사이트 크롤링 │
│ • 🔴 링크만 수집 (Lazy Capture - HTML/스크린샷은 아직 안 함) │
│ • sitemap.json 생성 (captured: false) │
│ • (선택) --prefetch 시 전체 캡처 │
│ • (선택) --login 시 로그인 후 캡처 │
└─────────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Phase 2: ANALYZE (분석 & 매핑) │
│ /jikime:smart-rebuild analyze --source=./legacy-php --capture=./capture │
├─────────────────────────────────────────────────────────────────────────────────┤
│ • 레거시 소스 코드 분석 │
│ • URL ↔ 소스 파일 매칭 │
│ • 정적/동적 페이지 자동 분류 │
│ • SQL 쿼리 추출 → API 엔드포인트 식별 │
│ • mapping.json 생성 (소스 ↔ 캡처 매핑) │
│ • 🔴 api-mapping.json 생성 (commonApis + pageApis) │
└─────────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Phase 3: GENERATE (코드 생성) - 페이지별 반복 │
│ /jikime:smart-rebuild generate frontend --page 1 │
└─────────────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase A: 프론트엔드 프로젝트 초기화 (🔴 첫 페이지에서만 1회 실행) │
├───────────────────────────────────────────────────────────────────────────┤
│ • Next.js + shadcn/ui 프로젝트 생성 │
│ • 의존성 설치 │
│ • styles/legacy/ 폴더 생성 │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase B: 페이지 기본 코드 생성 │
├───────────────────────────────────────────────────────────────────────────┤
│ Step 0: 🔴 Lazy Capture 체크 (captured=false면 지금 캡처!) │
│ Step 1: sitemap.json 읽기 │
│ Step 2: 스크린샷 읽기 (시각 분석) │
│ Step 2.5: 🔴 섹션 감지 & sitemap.json 업데이트 (HITL 매칭용!) │
│ Step 3: HTML 읽기 (텍스트/이미지 추출) │
│ Step 3.5: 🔴 원본 CSS Fetch (첫 페이지만) │
│ Step 4: 섹션별 컴포넌트 생성 (data-section-id 포함) │
│ Step 5: page.tsx 생성 (섹션 컴포넌트 조합) │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase C: 개발 서버 실행 │
├───────────────────────────────────────────────────────────────────────────┤
│ • npm run dev 실행 │
│ • 🔴 localhost:3893에서 확인 가능 (기본 포트) │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase D: AskUserQuestion - 다음 단계 선택 │
├───────────────────────────────────────────────────────────────────────────┤
│ "페이지 {N} 기본 코드 완료. 다음 작업은?" │
│ │
│ options: │
│ ├── "HITL 세부 조정" → Phase E │
│ ├── "🔴 백엔드 연동" → Phase G (동적 페이지만 표시됨) │
│ ├── "다음 페이지" → Phase B (다음 pending 페이지) │
│ └── "직접 입력" → 사용자 지시 따르기 │
└───────────────────────────────────────────────────────────────────────────┘
│
┌───────────┼───────────┬───────────┐
↓ ↓ ↓ ↓
[HITL 조정] [BE 연동] [다음 페이지] [직접 입력]
│ │ │
↓ │ │
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase E: HITL 루프 (섹션별 비교 & 수정) │
├───────────────────────────────────────────────────────────────────────────┤
│ 🚨 HITL HARD RULES (절대 위반 금지!) │
│ • 🔴 Claude 혼자 결정 금지! 반드시 사용자에게 물어볼 것! │
│ • 🔴 일치율 높아도 자동 skip/approve 금지! │
│ │
│ 📍 섹션 비교 셀렉터 규칙: │
│ • 원본 페이지: 시맨틱 셀렉터 (header, .hero, #nav) │
│ • 로컬 페이지: data-section-id ([data-section-id="01-header"]) │
│ │
│ E-1. hitl-refine.ts 실행 (원본 vs 로컬 캡처 & 비교) │
│ E-2. JSON 결과 파싱 (overallMatch%, issues[], suggestions[]) │
│ E-3. 🔴 AskUserQuestion: "일치율 {N}%. 어떻게 처리?" (필수!) │
│ ├── 승인 → E-5 │
│ ├── 수정 필요 → E-4 → 🔄 E-1 (재캡처 & 재비교) │
│ └── 스킵 → E-5 │
│ E-4. 코드 수정 (suggestions 기반) │
│ E-5. 다음 섹션 체크 │
│ ├── 남은 섹션 있음 → E-1로 돌아가기 │
│ └── 모든 섹션 완료 → Phase F │
└───────────────────────────────────────────────────────────────────────────┘
│ │
↓ ↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase F: 페이지 완료 │
├───────────────────────────────────────────────────────────────────────────┤
│ • sitemap.json 업데이트 (status = "completed") │
│ • AskUserQuestion: "다음 페이지로 진행?" │
│ ├── 예 → Phase B (다음 pending 페이지) │
│ └── 아니오 → 종료 │
└───────────────────────────────────────────────────────────────────────────┘
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 Phase G: 백엔드 연동 (동적 페이지 선택 시)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌───────────────────────────────────────────────────────────────────────────┐
│ 🔴 Phase G-0: 백엔드 프로젝트 초기화 (첫 동적 페이지에서 1회 실행) │
│ /jikime:smart-rebuild backend-init --framework spring-boot │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ G-0.1: 백엔드 프로젝트 존재 확인 │
│ IF {output}/backend/ 없음 → G-0.2로 진행 │
│ ELSE → G-1로 스킵 │
│ │
│ G-0.2: AskUserQuestion (프레임워크 선택) │
│ "백엔드 프레임워크를 선택하세요" │
│ options: │
│ ├── "Spring Boot (Java)" → spring-boot │
│ ├── "FastAPI (Python)" → fastapi │
│ ├── "Go Fiber" → go-fiber │
│ └── "NestJS (Node.js)" → nestjs │
│ │
│ G-0.3: 프로젝트 Scaffolding │
│ • 선택한 프레임워크 템플릿으로 프로젝트 생성 │
│ • 기본 디렉토리 구조 생성 │
│ │
│ G-0.4: 의존성 설치 │
│ • Spring Boot: build.gradle 의존성 │
│ • FastAPI: requirements.txt / pyproject.toml │
│ • Go Fiber: go.mod │
│ • NestJS: package.json │
│ │
│ G-0.5: DB 연결 설정 │
│ • AskUserQuestion: "DB 타입과 연결 정보를 입력하세요" │
│ • application.yml / .env 설정 │
│ │
│ G-0.6: CORS + 공통 설정 │
│ • localhost:3000 허용 │
│ • 공통 예외 처리 │
│ • 로깅 설정 │
│ │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase G-1: 공통 API 체크 │
│ /jikime:smart-rebuild generate backend --common-only │
├───────────────────────────────────────────────────────────────────────────┤
│ • api-mapping.json에서 commonApis 확인 │
│ • IF 미생성 공통 API 있음 (generated: false): │
│ → 인증 API 생성 (login, logout, me) │
│ → 공통 유틸리티 생성 │
│ • api-mapping.json 업데이트 (generated: true) │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase G-2: 페이지 전용 API 생성 │
│ /jikime:smart-rebuild generate backend --page 3 --skip-common │
├───────────────────────────────────────────────────────────────────────────┤
│ • api-mapping.json에서 pageApis[{pageId}] 추출 │
│ • 각 API에 대해: │
│ ├── Controller 생성 │
│ ├── Service 생성 │
│ ├── Repository 생성 │
│ └── Entity 생성 (entities[] 참조) │
│ • api-mapping.json 업데이트 (generated: true) │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase G-3: Frontend Connect │
│ /jikime:smart-rebuild generate connect --page 3 │
├───────────────────────────────────────────────────────────────────────────┤
│ • .env.local에 NEXT_PUBLIC_API_URL 설정 │
│ • lib/api-client.ts 생성 (없는 경우) │
│ • Mock 데이터 → fetch API 호출로 교체 │
│ • api-mapping.json 업데이트 (connected: true) │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase G-4: 통합 테스트 │
├───────────────────────────────────────────────────────────────────────────┤
│ • BE 서버 실행: │
│ ├── Spring Boot: ./gradlew bootRun │
│ ├── FastAPI: uvicorn main:app --reload │
│ ├── Go Fiber: go run main.go │
│ └── NestJS: npm run start:dev │
│ • FE 서버 실행: npm run dev │
│ • AskUserQuestion: "API 연동이 정상 동작하나요?" │
│ ├── 정상 → G-5 │
│ └── 오류 → 디버깅 후 재시도 │
└───────────────────────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────────────────────┐
│ Phase G-5: 연동 완료 & 다음 단계 │
├───────────────────────────────────────────────────────────────────────────┤
│ • AskUserQuestion: "연동 완료! 다음 작업은?" │
│ ├── "HITL 재조정" → Phase E │
│ ├── "다음 페이지" → Phase B (다음 pending 페이지) │
│ └── "직접 입력" → 사용자 지시 따르기 │
└───────────────────────────────────────────────────────────────────────────┘Phase G-0: 프레임워크별 환경 구성 상세
지원 프레임워크
| 프레임워크 | 언어 | CLI 명령어 |
|---|---|---|
| Spring Boot 3.x | Java 21 | /jikime:smart-rebuild backend-init --framework spring-boot |
| FastAPI | Python 3.12+ | /jikime:smart-rebuild backend-init --framework fastapi |
| Go Fiber | Go 1.22+ | /jikime:smart-rebuild backend-init --framework go-fiber |
| NestJS | Node.js 20+ | /jikime:smart-rebuild backend-init --framework nestjs |
프레임워크별 구성 매트릭스
| 항목 | Spring Boot | FastAPI | Go Fiber | NestJS |
|---|---|---|---|---|
| 프로젝트 초기화 | Spring Initializr | uv init | go mod init | nest new |
| 의존성 파일 | build.gradle | pyproject.toml | go.mod | package.json |
| 설정 파일 | application.yml | .env | config.yaml | .env |
| DB ORM | JPA/Hibernate | SQLAlchemy | GORM | TypeORM/Prisma |
| 서버 실행 | ./gradlew bootRun | uvicorn main:app | go run main.go | npm run start:dev |
| 기본 포트 | 8080 | 8000 | 3001 | 3001 |
Spring Boot 초기화 상세
bash
# G-0.3: 프로젝트 생성
cd {output} && mkdir -p backend
cd {output}/backend && spring init \
--dependencies=web,data-jpa,mysql,lombok,validation \
--java-version=21 \
--type=gradle-project \
--name=api-server \
.디렉토리 구조:
backend/
├── build.gradle
├── settings.gradle
└── src/main/
├── java/com/example/api/
│ ├── ApiApplication.java
│ ├── config/
│ │ ├── CorsConfig.java
│ │ └── SecurityConfig.java
│ ├── controller/
│ ├── service/
│ ├── repository/
│ ├── entity/
│ └── dto/
└── resources/
└── application.ymlCorsConfig.java:
java
@Configuration
public class CorsConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("http://localhost:3893")
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("*")
.allowCredentials(true);
}
}FastAPI 초기화 상세
bash
# G-0.3: 프로젝트 생성
cd {output} && mkdir -p backend
cd {output}/backend && uv init
cd {output}/backend && uv add fastapi uvicorn sqlalchemy pymysql python-dotenv디렉토리 구조:
backend/
├── pyproject.toml
├── .env
├── main.py
├── config.py
├── routers/
│ ├── __init__.py
│ └── auth.py
├── services/
├── models/
└── schemas/main.py:
python
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3893"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/health")
def health_check():
return {"status": "ok"}Go Fiber 초기화 상세
bash
# G-0.3: 프로젝트 생성
cd {output} && mkdir -p backend
cd {output}/backend && go mod init api-server
cd {output}/backend && go get github.com/gofiber/fiber/v2
cd {output}/backend && go get gorm.io/gorm gorm.io/driver/mysql디렉토리 구조:
backend/
├── go.mod
├── go.sum
├── main.go
├── config/
│ └── config.go
├── handlers/
├── services/
├── models/
└── middleware/
└── cors.gomain.go:
go
package main
import (
"github.com/gofiber/fiber/v2"
"github.com/gofiber/fiber/v2/middleware/cors"
)
func main() {
app := fiber.New()
app.Use(cors.New(cors.Config{
AllowOrigins: "http://localhost:3893",
AllowMethods: "GET,POST,PUT,DELETE,OPTIONS",
}))
app.Get("/health", func(c *fiber.Ctx) error {
return c.JSON(fiber.Map{"status": "ok"})
})
app.Listen(":3001")
}NestJS 초기화 상세
bash
# G-0.3: 프로젝트 생성
cd {output} && npx @nestjs/cli new backend --package-manager npm
cd {output}/backend && npm install @nestjs/typeorm typeorm mysql2
cd {output}/backend && npm install @nestjs/config디렉토리 구조:
backend/
├── package.json
├── .env
├── src/
│ ├── main.ts
│ ├── app.module.ts
│ ├── auth/
│ │ ├── auth.controller.ts
│ │ ├── auth.service.ts
│ │ └── auth.module.ts
│ └── common/
└── nest-cli.jsonmain.ts:
typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.enableCors({
origin: 'http://localhost:3893',
credentials: true,
});
await app.listen(3001);
}
bootstrap();CLI 명령어 요약
Phase 1: Capture
bash
# 기본 (링크만 수집)
/jikime:smart-rebuild capture https://example.com --output=./capture
# 전체 미리 캡처
/jikime:smart-rebuild capture https://example.com --prefetch --output=./capture
# 로그인 필요
/jikime:smart-rebuild capture https://example.com --login --output=./capturePhase 2: Analyze
bash
/jikime:smart-rebuild analyze --source=./legacy-php --capture=./capturePhase 3: Generate
bash
# 프론트엔드 (페이지별)
/jikime:smart-rebuild generate frontend --page 1
/jikime:smart-rebuild generate frontend --next
/jikime:smart-rebuild generate frontend --status
# 🔴 백엔드 초기화 (NEW!)
/jikime:smart-rebuild backend-init --framework spring-boot
/jikime:smart-rebuild backend-init --framework fastapi
/jikime:smart-rebuild backend-init --framework go-fiber
/jikime:smart-rebuild backend-init --framework nestjs
# 백엔드 API 생성 (페이지별)
/jikime:smart-rebuild generate backend --common-only
/jikime:smart-rebuild generate backend --page 3 --skip-common
# 프론트엔드-백엔드 연동 (페이지별)
/jikime:smart-rebuild generate connect --page 3전체 플로우 요약
1. CAPTURE → 링크 수집 (Lazy Capture)
2. ANALYZE → 분석 & 매핑, api-mapping.json 생성
3. GENERATE → 페이지별 반복
├── Phase A → FE 프로젝트 초기화 (첫 페이지만)
├── Phase B → 페이지 코드 생성
├── Phase C → 개발 서버 실행
├── Phase D → 다음 단계 선택
│ ├── HITL 조정 → Phase E
│ ├── BE 연동 → Phase G
│ └── 다음 페이지 → Phase B
├── Phase E → HITL 루프 (섹션별 비교)
├── Phase F → 페이지 완료
└── Phase G → 백엔드 연동
├── G-0 → 🔴 BE 프로젝트 초기화 (첫 동적 페이지만)
├── G-1 → 공통 API 생성
├── G-2 → 페이지 전용 API 생성
├── G-3 → FE-BE 연동
├── G-4 → 통합 테스트
└── G-5 → 다음 단계 선택관련 문서
| 문서 | 경로 | 설명 |
|---|---|---|
| 명령어 정의 | templates/.claude/commands/jikime/smart-rebuild.md | 슬래시 커맨드 정의 |
| 실행 절차 | templates/.claude/rules/jikime/smart-rebuild-execution.md | 상세 실행 절차, 코드 예시 |
| 옵션 참조 | templates/.claude/rules/jikime/smart-rebuild-reference.md | 옵션, 프레임워크, 출력 구조 |
| 개요 문서 | docs/smart-rebuild.md | 개념 및 사용법 요약 |
작성일: 2026-02-09 버전: 2.2.0 변경 이력:
- v2.2.0: HITL HARD RULES 추가, 섹션 ID 매칭 시스템 추가, Step 2.5 섹션 감지 추가, 개발 서버 포트 3893으로 표준화
- v2.1.0: Phase G-0 (백엔드 초기화) 추가,
backend-init서브커맨드 추가 - v2.0.0: Phase G (페이지별 점진적 백엔드 연동) 추가
- v1.0.0: 초기 버전