1. 현대화 여정 방향 설정
이 포괄적인 Codelab은 Antigravity 및 다중 에이전트 조정을 사용하여 현대화를 자동화하는 방법이라는 심층적인 아키텍처 분석 도움말에서 직접 파생된 실습용 Codelab입니다. 실질적인 데모 도구로 기존 Node.js 프레임워크 스왑을 사용하지만 여기서 다루는 핵심 설계 패턴, 디렉터리 구조, 에이전트형 조정 프로세스는 언어에 관계없이 대규모의 기존 현대화 프로젝트에 보편적으로 적용할 수 있습니다.
단일 파일에서 줄을 자동 완성하는 표준 코딩 어시스턴트와 달리 Google Antigravity의 에이전트 우선 기능을 활용하여 전문 AI 하위 에이전트의 자율 팀을 조정하는 방법을 알아봅니다. 이러한 에이전트는 고급 설계자로서 절대적인 제어권을 유지하면서 Reflexion 루프를 사용하여 기존 코드베이스를 독립적으로 리버스 엔지니어링하고, 엄격한 테스트 모음을 작성하고, 최신 아키텍처를 스캐폴딩하고, 자체 컴파일러 오류를 자체 수정할 수 있습니다.
학습할 내용
- 워크플로 매핑: 결정론적 설정 작업을 복잡한 휴리스틱 리팩터링 문제와 올바르게 분류하고 분리하는 방법
- 기술 아키텍처: 점진적 공개 및 YAML 라우팅 메타데이터를 사용하여 확장 가능한 에이전트 기술 팩을 구성하는 방법
- 조정 설계 패턴: 라우터, 계획 및 실행, Reflexion 설계 패턴을 연결하여 대규모 리팩터링을 추진하는 방법
- 엄격한 입력/출력 계약: 다단계 리버스 엔지니어링 및 대상 스캐폴딩 파이프라인에서 명확한 입력/스킬/출력 경계를 적용하는 방법
- 패리티 검증: Antigravity의 브라우저 하위 에이전트를 활용하여 Chrome 웹브라우저 내에서 패리티 테스트를 나란히 실행하는 방법
빌드할 항목
MongoDB, 엄격한 Zod 검증, 접근 가능한 ShadCN UI 구성요소로 지원되는 엄격한 유형의 Next.js 앱 라우터 애플리케이션으로 기존의 상징적인 Express 및 Mongoose CRUD 모놀리스('madhums 데모')를 가져와서 완전히 자동화된 그린필드 리팩터링 파이프라인을 조정하고 처음부터 자율적으로 다시 빌드합니다.
필요한 항목
- 로컬에 설치된 Google Antigravity IDE (antigravity.google에서 사용 가능)
- 로컬에 설치된 Node.js (v18 이상)
- 자동화된 UI 검증을 위한 Chrome 브라우저
- 오픈소스 modernizing-expressjs 데모 모노리포의 클론
2. 현대화 환경 설정
자율 에이전트를 오래된 기존 코드베이스에 적용하기 전에 깨끗하고 매우 안정적인 모노리포 환경을 설정해야 합니다. AI 어시스턴트에 깨끗한 기준선을 제공하면 수십 년 된 패키지 취약점이나 컴파일러 불일치와 싸우는 데 토큰을 낭비하는 대신 고품질의 최신 코드를 생성하는 데 전적으로 집중할 수 있습니다.
기존 Express와 최신 Next.js 아키텍처 매핑
구성요소 | 기존 스택 | 최신 대체 | 이유 |
아키텍처 | Express 모놀리스 | Next.js 앱 라우터 | 최적화된 렌더링 및 React 서버 구성요소 (RSC) 성능을 위해 로직을 서버 구성요소로 분리합니다. |
데이터 로직 | Mongoose (ODM) | MongoDB + Zod | 암시적 ORM 후크를 명시적이고 유형이 안전한 Zod 스키마 및 원시 드라이버 성능으로 전환합니다. |
언어 | CommonJS / JavaScript | TypeScript (ESM) | 컴파일 시간 안전을 적용하고 최신 모듈 표준으로 이동합니다. |
프런트엔드 | Pug/EJS (서버 뷰) | ShadCN UI + Tailwind | 엄격한 템플릿에서 구성 가능하고 접근 가능하며 유틸리티 우선 설계 시스템으로 전환합니다. |
인증 | Passport.js | NextAuth | Edge 및 최신 제공업체를 기본적으로 지원하여 세션 관리를 현대화합니다. |
안전성 | 수동 미들웨어 | Zod (엄격한 검증) | 전체 스택에서 데이터 검증을 위한 '단일 정보 소스'를 구현합니다. |
현대화 허브 초기화
첫 번째 결정론적 작업은 격리된 모노리포 구조를 클론하는 것입니다. 이렇게 하면 읽기 전용 기존 코드가 새 그린필드 대상 저장소에서 분리되어 원래 애플리케이션에 우발적인 변경이 발생하지 않습니다.
Antigravity 터미널을 열고 다음 설정 명령어를 실행합니다.
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
클론되면 Antigravity IDE 탐색기에서 modernizing-expressjs 폴더를 직접 엽니다. 다음과 같은 격리된 레이아웃이 표시됩니다.
/modernizing-expressjs/ ├── .agents/ # Skills metadata and checklists │ └── skills/ ├── docs/ # Target directory for reverse-engineered markdown artifacts ├── legacy-app/ # Read-only root of the legacy Express monolith ├── modern-app/ # Greenfield target repository for the Next.js rewrite ├── GEMINI.md # Project-wide agent constitution └── README.md # Companion documentation
모노리포 환경을 결정론적으로 준비하고 격리하는 방법을 보여주는 이 짧은 동영상 둘러보기를 시청하세요.
3. AI 에이전트 기술 팩 및 패턴 설계
강력한 에이전트 스킬을 작성하는 것은 표준 채팅 프롬프트를 작성하는 것과는 근본적으로 다릅니다. 기술 팩을 작성할 때는 기본 LLM이 자율적으로 실행하는 모듈식 소프트웨어를 설계하는 것입니다. 에이전트가 할루시네이션을 일으키거나 "컨텍스트 윈도우 세금"을 경험하지 않도록 하기 위해 두 가지 양보할 수 없는 원칙인 간결성 과 점진적 공개 에 의해 구동되는 확장 가능한 작성 템플릿으로 오픈소스 그린필드 조정 스킬 팩을 도입합니다.
YAML 메타데이터 라우팅을 사용한 점진적 공개
모든 대상 규칙을 단일 모놀리식 시스템 프롬프트에 덤프하는 대신 디렉터리에 걸쳐 안내를 배포합니다. 모든 기술 디렉터리에는 YAML 라우팅 프런트매터 블록으로 래핑된 SKILL.md 진입점이 포함되어 있습니다.
.agents/skills/orchestrating-greenfield-migration/SKILL.md를 열고 라우터 메타데이터를 검사합니다.
---
name: orchestrating-greenfield-migration
description: >
Manages the end-to-end modernization of legacy Express
monoliths into Next.js architectures. Orchestrates subagents
for auditing, scaffolding, and verification. Use when starting
or managing a greenfield rewrite project.
---
계획 및 실행 패턴 하드코딩
자율 에이전트가 표류하거나 흥미로운 기존 미들웨어에 의해 주의가 산만해지거나 무단 데이터베이스 스왑을 시도하지 못하도록 하기 위해 안내에 계획 및 실행 패턴을 직접 하드코딩하여 표준 개방형 계획을 재정의합니다.
기본 조정자에 삽입된 리터럴 Markdown 체크리스트를 검사합니다.
### Phase 1: The AI audit (reverse engineering)
Dispatch subagents to produce specifications while identifying project-specific test scenarios.
* [ ] Init `docs/verification/Verification_Plan.md` to create baseline template.
* [ ] Run `auditing-data-models` -> Append Data Integrity Stress-Tests.
* [ ] Run `auditing-api-contracts` -> Append API Parity & Edge Case Probes.
* [ ] Run `auditing-business-logic` -> Append Logic & Authorization Stress-Tests.
* [ ] Run `auditing-ui-archeology` -> Append Interaction & Layout Targets.
워크플로를 인라인 스킬 참조가 있는 명시적 체크리스트로 형식을 지정하면 에이전트가 이 정확한 로드맵을 태스크 계획에 복사하여 '실행 전용' 모드로 잠그고, 이 모드는 상자를 체계적으로 선택하고 필요한 경우에만 고도로 전문화된 하위 에이전트를 호출합니다.
4. 1단계 - 기존 모놀리스 리버스 엔지니어링 (감사)
이제 기본 조정 시퀀스를 트리거할 준비가 되었습니다. 첫 번째 주요 단계에서는 기존 모놀리스에서 비즈니스 규칙, 데이터 스키마, API 페이로드를 추출하여 깨끗한 Markdown 아티팩트로 저장하고 10년 동안의 명령형 기술 부채를 남겨둡니다.
자율 리팩터링 시퀀스 트리거
Antigravity 에이전트 관리자 채팅 패널에서 다음 맞춤 슬래시 명령어를 입력하고 Enter를 누릅니다.
/orchestrating-greenfield-migration
이제 터미널 콘솔을 관찰합니다. 기본 에이전트가 시스템 프롬프트를 읽고, 요청을 조정자의 메타데이터와 일치시키고, 5단계 체크리스트를 출력하고, 즉시 전문 '감사자' 하위 에이전트를 병렬로 디스패치하는 것을 볼 수 있습니다.
입력/스킬/출력 안내 계약
1단계에서 에이전트는 다음 안내 계약에 의해 바인딩된 엄격한 리버스 엔지니어링 파이프라인을 실행합니다.
소비된 입력: legacy-app/ 내에 있는 읽기 전용 기존 소스 코드 파일
호출된 기술:
스킬 | 설명 |
| 기존 경로를 추적하여 정확한 JSON 응답 봉투를 문서화합니다. |
| Mongoose 스키마를 디컨스트럭팅하여 관계, 필수 필드, 기본값을 추출합니다. |
| 암시적 부작용, Passport 인증 흐름, 미들웨어 규칙을 문서화합니다. |
| 기존 Pug 템플릿을 스캔하여 상위 수준 'UI 의도'(탐색 메뉴, 양식)를 매핑합니다. |
생성된 아티팩트: docs/ 폴더에 직접 생성된 고도로 구조화된 Markdown 사양
아티팩트 | 설명 |
| 이 문서에서는 기존 Express 애플리케이션의 리버스 엔지니어링된 API 노출 영역을 자세히 설명합니다. 이 카탈로그를 사용하여 현대화된 Next.js 애플리케이션에서 경로를 다시 빌드할 때 엄격한 패리티를 보장합니다. |
| 이 문서에서는 인증 (AuthN), 승인 (AuthZ), 전역 미들웨어, 세션 관리, 부작용과 관련된 기존 Express 애플리케이션의 검증된 동작, 구성, 엄격한 규칙을 기록합니다. |
| 이 문서에서는 |
| 이 문서에서는 |
작동 중인 자율 리버스 엔지니어링 감사를 보여주는 이 실시간 터미널 캡처를 시청하세요.
5. 2단계 및 3단계 - TDD 하네스 및 그린필드 백엔드 스캐폴딩
기존 애플리케이션이 완전히 감사되고 문서화되면 기본 조정자가 최신 대상 백엔드 스캐폴딩으로 진행합니다. 이 단계에서는 엄격한 테스트 기반 개발 (TDD)에 의해 구동되는 폐쇄 루프 Reflexion (자기 성찰)이라는 툴킷에서 가장 강력한 에이전트형 설계 패턴을 소개합니다.
Reflexion 루프를 사용하여 자체 복구 코드 구동
최신 코드를 작성하는 것은 간단하지만 완벽하게 컴파일되고 엄격한 검증 제약 조건을 통과하도록 하려면 폐쇄 루프 평가가 필요합니다. 조정자는 테스트 출력을 하위 에이전트의 컨텍스트 윈도우로 직접 파이핑하여 이를 자율적으로 처리합니다.
- 2단계 (TDD 설정): 조정자는
generating-api-tests하위 에이전트를 호출합니다. 이 하위 에이전트는docs/API_Contracts.md를 읽고 정확한 필수 HTTP 상태 코드와 JSON 페이로드를 어설션하는 포괄적인 Vitest 통합 테스트 모음을 작성합니다. TDD에서 예상대로 이러한 테스트는 처음에는 실패합니다. - 3단계 (백엔드 스캐폴딩): 스캐폴딩 하위 에이전트가 최신 Next.js 경로 핸들러와 엄격한 Zod 검증 스키마를 작성하기 시작합니다.
- 자체 수정 루프: 결정론적 Vitest 하네스가 새 코드를 평가하고 실패를 반환하면 (예: 예상된
422검증 오류가500을 반환함) 에이전트가 비정상 종료되지 않습니다. 목표 오류 출력을 반영하고, 대상 경로 핸들러를 다시 열고, Zod 스키마 페이로드 구조를 수정하고, 테스트를 다시 실행합니다. 종료 코드0을 달성할 때까지 자율적으로 반복됩니다.
입력/스킬/출력 안내 계약
소비된 입력: 리버스 엔지니어링된 사양 아티팩트 (docs/API_Contracts.md, docs/Data_Models.md)
호출된 기술:
스킬 | 설명 |
| 실패하는 Vitest 통합 모음을 생성합니다. |
| 기본 Next.js 앱 라우터 레이아웃을 초기화합니다. |
| 로컬 Vitest 테스트 실행기 환경을 구성합니다. |
| 이전 Mongoose 모델을 MongoDB + Zod 스키마로 변환합니다. |
| Express 경로를 Next.js 경로 핸들러 및 모듈식 경로 가드로 다시 빌드합니다. |
생성된 출력: 초기 실패 Vitest 모음, 완전히 유형화된 Zod 스키마, 기능적 Next.js 경로 핸들러, 깨끗하고 통과하는 테스트 모음 실행
TDD 테스트 하네스의 자동 생성을 관찰합니다.
대상 백엔드를 스캐폴딩하는 자체 수정 Reflexion 루프의 실시간 실행을 관찰합니다.
6. 4단계 - 최신 프런트엔드 스캐폴딩 (UI 구성요소)
백엔드 유효성 검사 계층이 완전히 강화되고 통합 테스트를 통과하면 기본 조정자가 컨텍스트를 전환하여 시각적 프레젠테이션을 현대화합니다. 명령형 서버 렌더링 템플릿은 접근성이 높고 유틸리티 우선 구성요소 설계 시스템을 위해 삭제됩니다.
UI 의도를 구성 가능한 뷰로 변환
프런트엔드 하위 에이전트는 줄 단위 CSS 변환을 시도하는 대신 추출된 'UI 의도' 인벤토리를 읽고 구조적 요소를 고품질의 최신 동등 항목에 직접 매핑합니다.
입력/스킬/출력 안내 계약
소비된 입력: 리버스 엔지니어링된 프런트엔드 인벤토리 아티팩트 (docs/UI_Inventory.md)
호출된 기술:
스킬 | 설명 |
|
|
생성된 출력: 접근성이 높은 ShadCN UI 구성요소와 Tailwind CSS 유틸리티 레이아웃을 사용하여 구성된 프로덕션 지원 Next.js 프런트엔드 페이지
현대화된 프런트엔드 뷰 레이어의 자율 생성을 시청하세요.
7. 5단계 - 검증 및 적대적 감사
리팩터링 파이프라인은 엄격한 품질 검사로 마무리됩니다. 기본 조정자는 정적 코드 분석에서 활성 런타임 환경 테스트로 전환하여 기존 기준선과의 절대적인 기능 패리티를 증명하기 위해 새 대상 애플리케이션을 적극적으로 중단하려고 시도합니다.
2개 탭 테스트 및 브라우저 작동 실행
검증 단계에서는 Antigravity의 통합 시각적 및 DOM 기능을 활용하여 양식을 수동으로 클릭하지 않고도 자율적으로 성공을 증명합니다.
- 나란히 패리티:
auditing-parity하위 에이전트는 로컬 실행기에게 기존 Express 모놀리스와 현대화된 Next.js 애플리케이션을 동시에 시작하도록 지시하여 동일한 시각적 프레젠테이션과 데이터 렌더링을 검증합니다. - 적대적 보안 프로빙: 조정자는
adversarial-verification하위 에이전트를 호출하며, 이 하위 에이전트는 Antigravity 브라우저 하위 에이전트를 실행합니다. 이 전문 에이전트는 브라우저를 직접 작동하여 입력에 입력하고, 양식을 제출하고, 보안 회귀, 손상된 세션 쿠키 또는 처리되지 않은 특이 사례를 프로빙합니다. - 감사 추적 생성: 브라우저 하위 에이전트는 세션 작동의 WebP 동영상 캡처를 자동으로 기록하고 검증 가능한 "작업 증명"으로 최종 마이그레이션 보고서에 직접 첨부합니다.
입력/스킬/출력 안내 계약
소비된 입력: 로컬 런타임 환경에서 나란히 실행되는 기존 애플리케이션과 최신 애플리케이션
호출된 기술:
스킬 | 설명 |
| 런타임 나란히 검증 검사를 실행합니다. |
| 자동화된 브라우저 작동을 사용하여 로직 결함 및 기능 회귀를 프로빙합니다. |
생성된 출력: 완전한 성공을 확인하는 기록된 브라우저 세션 동영상과 페어링된 포괄적인 기능 패리티 감사 추적
현대화된 애플리케이션을 적극적으로 검증하는 자동화된 브라우저 하위 에이전트를 관찰합니다.
8. 마이그레이션 후 프로덕션 준비 수준 및 다음 단계
축하합니다. 고급 자율 에이전트형 리팩터링 파이프라인을 조정하여 기존 모놀리스를 처음부터 현대화하고 점진적 공개, 계획 및 실행 체크리스트, 자체 복구 Reflexion 루프와 같은 보편적이고 이전 가능한 기술을 학습했습니다.
프로덕션 배포 준비
Next.js 애플리케이션이 완전히 검증되고 감사되었으므로 프로덕션 통합으로 진행할 준비가 되었습니다. 다음과 같은 업계 표준 다음 단계를 구현해 보세요.
- 증분 라우팅: 역방향 프록시 (예: 스트랭글러 피그 패턴)를 배포하여 기존 Express 앱에서 최신 대상으로 트래픽을 점진적으로 라우팅합니다.
- SEO 보존: 기존 도메인 권한을 유지하기 위해 기존 Express 경로를 Next.js 영구 리디렉션 (
_redirects.yaml)에 매핑합니다. - 데이터 스트리밍: 정적 데이터베이스 시딩에서 엄격한 Zod 스키마를 사용하여 런타임에 안전하게 검증된 실시간 프로덕션 데이터 스트리밍으로 이동합니다.
- 모니터링 가능성: 명령형 로깅 유틸리티를 구조화된 OpenTelemetry 프레임워크로 대체합니다.
현대화 전문성 심화
이 파이프라인을 구동하는 기본 코드베이스, 맞춤 기술 안내, 포괄적인 이론적 근거를 살펴보려면 전체 상위 도움말을 읽어보세요.
에이전트형 빌더 커뮤니티 가입
이러한 보편적인 리팩터링 패턴과 에이전트형 파이프라인이 유용했기를 바랍니다. 전문 채널에서 나를 팔로우하여 향후 오픈소스 기술 팩, 심층적인 기술 콘텐츠, 예정된 컨퍼런스 강연에 대한 최신 소식을 받아보세요.
- LinkedIn에서 팔로우: linkedin.com/in/jamesor
- X (Twitter)에서 팔로우: x.com/JamesOR
의견을 보내주세요.
에이전트형 조정에서 가장 기대되는 점은 무엇인가요?
Google Antigravity를 이용해 주셔서 감사합니다.