🤖
▶ Section
PHP → Next.js AI Migration System
2025.05 — 2026.03·Frontend Engineer / AI Pipeline Lead🔒 Private서울·중구·중림동
Next.js 14TypeScriptClaude APINode.js
▶Overview
레거시 PHP로 작성된 대규모 서비스를 Next.js 14(App Router)로 이관하면서, 반복 변환 작업을 LLM 멀티 에이전트로 자동화한 사내 마이그레이션 파이프라인입니다. 라우팅 분석 → 코드 생성(Page/API/Style) → QA 검증까지 단계가 분리되어 있고, 산출물은 Raw SQL을 100% 보존한 채 모던 스택으로 떨어집니다.
▶Background
- ▸수백 개에 달하는 PHP 라우트와 템플릿을 수동 변환할 경우 일정·휴먼 에러 리스크가 큼.
- ▸기존 Raw SQL 자산은 유지하면서 프론트 아키텍처만 모던화해야 한다는 제약.
- ▸서비스 특성이 천차만별이라 Type 1(Static) · Type 2(CRUD) · Type 3(Transaction) · Type 4(Admin) 4가지로 분기 처리 필요.
- ▸jQuery·CDN CSS·PHP 세션 등 운영 중인 레거시 자산을 깨뜨리지 않으면서 점진 이관해야 함.
▶Architecture
touch_app노드 hover · 휠로 확대 · 드래그로 이동
100%
▶Key Decisions
| 결정 | 이유 | 결과 |
|---|---|---|
| ORM 미도입, mysql2 / oracledb 풀 | 기존 Raw SQL 자산을 그대로 재사용해야 함 | SQL 100% 보존, 마이그레이션 리스크 최소화 |
| Multi-Agent 역할 분리 (Analyzer/Page/API/Style/QA) | 단계별 프롬프트 최적화 + 부분 재실행 가능 | 변환 정확도 향상, 토큰 비용 감소 |
| middleware.ts에서 디바이스·인증 분기 | PHP 시절 모바일/PC/App 웹뷰 분기 로직을 유지 | 엣지에서 빠른 분기, SSR 캐시와 양립 |
| <a> 태그 표준화 (SPA Link 미사용) | FOUC · jQuery 로드 순서 충돌 회피 | 레거시 호환성 확보, 점진 이관 가능 |
| jQuery beforeInteractive 로드 | 기존 JS 자산을 Layout 단에서 한 번에 보장 | 외부 스크립트 의존 페이지 그대로 동작 |
▶What I Did
- ▸라우팅 분석 → 코드 생성(Page/API/Style) → 검증 단계를 분리한 멀티 에이전트 파이프라인 설계.
- ▸Claude API 호출 시 프롬프트 캐싱과 컨텍스트 윈도우 관리로 호출 비용 절감.
- ▸
mysql2/oracledb풀 자동 생성과 단일·혼합 DB 환경 판별 유틸 작성. - ▸
app/layout.tsx에 외부 CDN CSS·jQuery 로드를 흡수해 기존 DOM 계층·선택자 보존. - ▸NAS 파일 접근을 RSC +
unstable_cache로 감싸고 Apache Alias 우회 라우트 작성.
▶Impact
- ▸수동 마이그레이션 대비 개발 공수 40% 절감.
- ▸Raw SQL 100% 보존, 라우트 누락 0건으로 회귀 버그 최소화.
- ▸관리자 페이지 신규 스캐폴딩을 분 단위로 단축.
▶Tech Stack
Frontend
TypeScriptNext.js 14 (App Router)React QueryZustand
AI / Tools
Claude API (Opus · Sonnet)Node.js
DB / Legacy
mysql2oracledbNASCDN CSSPHP Session