들어가며
레거시 프론트엔드(Nexacro 기반) 1,700개+ 화면으로 구성된 사내 백오피스를 React로 전환해야 했습니다. 화면당 500~6,000줄, 수동 전환 시 추정 공수는 약 4,300 M/D — 대략 6명이 3년 걸리는 규모입니다.
솔직히 말하면, Nexacro가 뭔지도 몰랐습니다. AWS AI-DLC 워크샵에 참여할 기회가 생겼고, 열정 하나로 리서치를 시작했습니다.
워크샵 3일을 알차게 보내고 싶어서, 사전에 Claude Code로 vibe coding을 하며 방향성을 잡아봤습니다. 화면 정의 파일 .xfdl을 열어보니 XML이었고, 수천 줄의 XML 안에 컴포넌트 정의, 데이터셋, 이벤트 핸들러가 선언적으로 들어있었습니다. React에 익숙한 저는 컴포넌트 구조가 비슷하다는 걸 발견했고, 이 파일에서 필요한 정보를 추출할 수 있겠다는 생각이 들었습니다.
Claude Code로 XML에서 메타데이터를 추출하고, 컴포넌트를 React와 매핑하고, 데이터 통신 흐름을 정리해서 API 스키마대로 연결하니 어느 정도 React 코드로 마이그레이션이 가능해 보였습니다. 하지만 이것을 1,700개가 넘는 화면에 반복 적용하려면 단순 프롬프트만으로는 부족했고, 정확도도 낮아 한계가 있었습니다.
이 글에서는 이를 해결하기 위해 워크샵 3일 동안 어떤 고민들을 했는지, 멀티 에이전트 파이프라인은 어떻게 구축했고 결과는 어땠는지 그 경험담을 공유하고자 합니다.
이 글은 이런 분들께 도움이 됩니다:
AI 에이전트로 대규모 코드 마이그레이션을 고민하는 개발자 Steering/Agent/Skill/Hook 등 에이전트 아키텍처 설계에 관심 있는 분 멀티 에이전트 파이프라인의 실패와 개선 사례가 궁금한 분
1. 왜 에이전트인가 — 프롬프트 엔지니어링의 한계
사전 PoC에서 가능성은 확인했지만, 실제로 적용하려니 문제가 드러났습니다.
- 컨텍스트 부족: 변환 규칙을 매번 설명해야 합니다. 컴포넌트가 뭔지, Dataset이 뭔지, transaction()이 뭔지.
- 재현 불가능: 같은 프롬프트로도 매번 다른 결과가 나옵니다.
- 스케일 불가: 1,700개를 하나씩 프롬프트로 변환할 수는 없습니다.
프롬프트는 1회성 지시이고, 에이전트는 팀 빌딩입니다. 한 번 만든 팀이 1,700개 화면을 반복해서 처리합니다. 그리고 가장 중요한 인사이트: 스펙(AC)이 있어야 자동 재시도가 가능합니다. 기준이 없으면 AI가 실패해도 고칠 수 없습니다.
2. 기술스택 — 왜 이 조합인가
AI 도구: AWS AI-DLC 워크샵이라 Kiro CLI를 메인으로 사용했습니다. Steering/Agent/Skill/Hook을 JSON으로 선언적으로 정의할 수 있는 구조가 강점이었고, 사전 PoC에서 사용했던 Claude Code를 보조로 활용했습니다.
React 기술스택은 코드 품질보다 마이그레이션 성공 여부가 더 중요했기 때문에, 선정에 큰 의미를 두진 않았습니다. React 18 + Zustand, Vite 8, Axios + fast-xml-parser 조합으로 구성했습니다.
shadcn/ui + Tailwind CSS: 소스코드를 직접 복사하는 방식이라 커스텀이 자유롭고, MCP로 설치를 자동화할 수 있습니다. bg-primary, text-muted-foreground 같은 시맨틱 컬러 토큰을 쓰면 화면의 스타일이 자연스럽게 통일됩니다.
AG Grid: 레거시 Grid 대체 유일한 현실적 선택지. ColDef 구조가 유사하고 엔터프라이즈급 기능(merge header, cell editing, row status)을 갖추고 있습니다.
3. 아키텍처 — Steering, Agent, Skill, Hook
워크샵 첫날, "에이전트 팀"에 착안해서 역할을 나눠봤습니다. 사람이 하는 것처럼 — 레거시 코드를 분석하는 에이전트, React 코드를 생성하는 에이전트, QA하는 에이전트, 리포트를 쓰는 에이전트. 빠르게 돌려봤더니 정확도가 낮았습니다. AI가 레거시 컴포넌트를 모르니 자기 맘대로 해석하기 시작하더군요.
그래서 전체 화면의 패턴을 학습시켜 Steering 문서로 만들었습니다. 변환 규칙을 명시적으로 문서화하고, 분석하고, 규칙을 추가하고, 다시 돌려보고 — 이 반복을 통해 정확도를 끌어올렸습니다.
테스트 단계에서는 "뭐가 맞는 건지" 기준이 필요했습니다. 레거시 코드에서 수용기준(AC)과 테스트케이스를 작성하는 spec-writer를 추가했고, 테스트 결과가 좋지 않으면 최대 3번까지 자동 재시도하는 로직도 넣었습니다.
각 단계마다 리포트를 생성하고, migration-lessons.md에 교훈을 기록해서 한 번 실패한 건 반복하지 않도록 했습니다. 이렇게 만들어진 게 Steering + Agent + Skill + Hook 4계층 아키텍처입니다.
3-1. Steering — AI에게 "코드 작성 규칙"을 주입하는 방법
전체 1,629개 화면의 공통 패턴을 분석해서 스티어링 문서로 추출했습니다. 11개 문서, 총 581줄. 핵심은 conversion-rules.md (211줄)입니다:
| Nexacro | React (shadcn/ui) |
|-------------|----------------------|
| Edit | <Input> |
| MaskEdit | <Input> + mask 유틸 |
| Combo | <Select> |
| CheckBox | <Checkbox> |
| Calendar | <DatePicker> |
| Grid | AG Grid React |
| Tab | <Tabs> |
| PopupDiv | <Dialog> |
| Dataset | Zustand store |
| transaction | Axios async/await |
처음에 변환 규칙이 30줄이었는데, 3일 후 211줄이 됐습니다. 규칙이 추가될 때마다 품질이 계단식으로 올라가는 걸 눈으로 확인할 수 있었습니다. 스티어링이 없으면? AI가 "창작"을 시작합니다. 빈 껍데기 사건의 원인이 바로 이겁니다 (뒤에서 자세히 다룹니다).
3-2. Agent — JSON 하나로 AI 워커 정의
8개 에이전트를 JSON으로 정의했습니다. 처음부터 8개를 만든 게 아니라, 실제로는 4개(orchestrator → analyzer → codegen → test-runner)로 시작해서 고도화하면서 나머지 4개가 추가된 겁니다:
| # | 에이전트 | Phase | 역할 |
|---|------------------------|--------|-----------------------------------|
| 1 | migration-orchestrator | 전체 | 파이프라인 자동 실행 + 재시도 (지휘자) |
| 2 | nexacro-analyzer | 1 | .xfdl 파싱, Zone 분해, Dataset/API 추출 |
| 3 | spec-writer | 2 | 수용기준(AC) + 테스트 스켈레톤 작성 |
| 4 | react-codegen | 3 | React 코드 생성 |
| 5 | test-runner | 4 | 테스트 구현 + 실행 |
| 6 | phase-reporter | 각 Phase | Phase별 검증 리포트 |
| 7 | quality-validator | 사후 | 정합성 검증 |
| 8 | report-generator | 사후 | 최종 리포트 생성 |
에이전트 하나를 정의하는 건 JSON 파일 하나입니다. migration-orchestrator.json의 핵심 구조:
{
"name": "migration-orchestrator",
"description": "1,689개 Nexacro 화면의 전체 마이그레이션을 자율적으로 계획·실행·학습하는 오케스트레이터.",
"prompt": "당신은 Nexacro → React 전체 마이그레이션을 자율적으로 실행하는 오케스트레이터입니다...",
"tools": ["fs_read", "fs_write", "grep", "code", "execute_bash", "use_subagent", "glob"],
"resources": [
"file://.kiro/steering/**/*.md",
"file://docs/02-plans/migration-plan.md",
"file://migration-lessons.md",
"file://docs/03-analysis/catalog/screen-difficulty.csv"
]
}
prompt에 역할을, tools에 사용 가능한 도구를, resources에 참조할 문서를 선언합니다.
react-codegen 에이전트에는 5가지 필수 추출 항목이 명시되어 있습니다:
1. 그리드 컬럼: <Band id="head"> Cell text + <Band id="body"> Cell bind
2. API URL: Script 내 gfn_Transaction → strUrl
3. 검색 조건: div_search 내 Calendar/Combo/Edit/CheckBox/Radio
4. 공통코드: gfn_getCommonCode("코드그룹", ds)
5. 화면 타이틀: <Form titletext="...">
이 5가지를 원본 xfdl에서 추출하지 않으면 빈 껍데기가 됩니다.
3-3. Skill — 도메인 지식을 패키지로 만들기
스킬은 에이전트가 필요할 때 참조하는 상세 레퍼런스입니다.
- Vercel React Best Practices: React 코드 품질 유지를 위해 공개된 skill 을 사용했습니다.
- nexacro-source-parser: 1,629개 xfdl에서 추출한 9가지 패턴 카탈로그
- shadcn/ui MCP: 에이전트가 컴포넌트 설치를 직접 실행
- nexacro-component-mapping: Nexacro→React 컴포넌트 상세 매핑
3-4. Hook — 파이프라인 자동화 트리거
{
"name": "Auto Register Routes",
"when": {
"type": "fileCreated",
"patterns": ["output/react/src/features/*/*.tsx"]
},
"then": {
"type": "askAgent",
"prompt": "새 화면 컴포넌트가 생성되었습니다. 라우트와 메뉴 등록을 수행해주세요..."
}
}
화면이 생성되면 라우팅 + 메뉴 자동 등록, 변환 진행률 실시간 반영. 한 번 설정하면 잊어도 되는 자동화입니다.
웹서치로 찾은 Nexacro 공식문서는 Context7 MCP를 통해 읽어들이고, 에이전트의 reference로 저장해 동일한 정보를 반복 검색하지 않도록 했습니다.
4. 실전 파이프라인 — 화면 하나가 15분 만에 만들어지는 과정
전체 흐름을 먼저 보겠습니다. 화면명 하나만 입력하면 4단계를 자동으로 거쳐 React 코드가 나옵니다.
사용자: "VOC접수 마이그레이션 실행"
│
┌────▼────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐
│ Phase 1 │───▶│ Phase 2 │───▶│ Phase 3 │───▶│ Phase 4 │
│ 분석 │ │ 스펙 │ │ 코드 생성 │ │ 테스트 │
└─────────┘ └─────────┘ └──────────┘ └────┬────┘
xfdl 파싱 수용기준(AC) TSX/Hook/Store AC 검증
구조 추출 테스트 기준 Type 생성 자동 재시도
│
실패 시 Phase 1 재실행
(최대 3회)
│
┌────▼────┐
│ 완료 │
│ ~15분 │
└─────────┘
VOC접수(Super Hard, 6,200줄) 화면을 예시로 보겠습니다:
Phase 1 (분석): nexacro-analyzer가 xfdl에서 Zone 5개, Dataset 56개, Transaction 5개를 추출합니다. 여기서 5가지 필수 항목(그리드 컬럼, API URL, 검색 조건, 공통코드, 화면 타이틀)을 빠짐없이 뽑아내는 게 핵심입니다. 이걸 건너뛰면 빈 껍데기가 됩니다.
Phase 2 (스펙): spec-writer가 AC 57개, 테스트 스켈레톤 57개를 EARS 표기법으로 생성합니다. 스펙이 있어야 Phase 4에서 "뭐가 맞고 뭐가 틀린지" 판단할 기준이 생깁니다. 이 단계가 전체 파이프라인의 숨은 핵심입니다.
Phase 3 (코드): react-codegen이 TSX 440줄 + Store + Hook + Type을 생성합니다. 스티어링 11개 규칙을 준수하면서 shadcn/ui + AG Grid로 1:1 변환합니다.
Phase 4 (테스트): test-runner가 AC 기준으로 검증합니다. 1차 33/57(58%) → 자동 재시도 → 49/57(86%).
파이프라인이 생성하는 React 프로젝트 구조입니다. 화면 하나당 features/ 아래 폴더 하나가 만들어지고, 공통 인프라(~3,600줄)를 202개 화면이 재사용합니다:
output/react/src/
├── common/ # 공통 인프라 (~3,600줄)
│ ├── components/ # 공통 UI 컴포넌트
│ ├── hooks/ # useNexacroAdapter, useCascadeCombo 등
│ ├── services/ # nexacro-adapter (XML↔JSON 변환)
│ ├── stores/ # 공통 상태 (인증, 코드)
│ ├── types/ # 공통 타입 정의
│ └── utils/ # 유틸리티 함수
├── components/ # shadcn/ui 기반 공통 컴포넌트
├── features/ # 화면별 폴더 (222개)
│ ├── AllVocInq/ # 전체VOC조회
│ │ ├── AllVocInq.tsx # 메인 컴포넌트
│ │ ├── hooks/ # 화면 전용 훅
│ │ ├── stores/ # Zustand 스토어 (Dataset 매핑)
│ │ ├── types/ # TypeScript 타입
│ │ └── mocks/ # 테스트 목 데이터
│ ├── VocReceipt/ # VOC접수 (Super Hard)
│ ├── SoloPrmtnGdsReg/ # 단독프로모션상품등록 (Super Hard)
│ └── ... (202개 화면)
├── routes/ # 자동 생성된 라우팅
└── layout/ # 레이아웃 (사이드바, 헤더)
5. 스케일링 — 202개 화면 배치 생성과 학습 루프
5-1. 패턴 카탈로그 구축
1,629개 xfdl을 전수 스캔해서 6가지 패턴으로 분류했습니다:
| 패턴 | 비율 | 설명 |
|-----------------|-------|-------------------------------|
| search-list | 70% | 검색 + 그리드 조회 |
| master-detail | 9% | 마스터-디테일 2단 그리드 |
| tab-multi-grid | 9% | 탭별 그리드 전환 |
| simple-popup | 7% | 팝업 다이얼로그 |
| crud-form | 2.5% | 등록/수정 폼 |
| chart | 2% | 차트 대시보드 |
난이도도 자동 산정했습니다: Super Easy 703 / Easy 570 / Hard 177 / Super Hard 179
5-2. 배치 전략과 학습 루프
Wave 전략: Super Easy → Easy → Hard → Super Hard. 쉬운 것부터 파이프라인을 검증한 뒤 어려운 쪽으로 진행합니다.
앞서 언급한 migration-lessons.md의 실제 기록을 보면:
## Wave 1 - Super Easy
### Batch 1: lst (20개)
- 발견: GridToolbar의 actions prop 없음 → children으로 전달
- 에러: DatePicker에 format prop 없음 → 제거 (YYYY-MM-DD 고정)
- 개선: 다음 배치부터 GridToolbar은 children 패턴 사용
### Batch 2: lst (30개)
- 결과: 빌드 에러 0건 (Batch 1 학습 완전 반영)
생산성 변화가 극적이었습니다:
| 단계 | 속도 | 비고 |
|---------------------|-------------|-------------------|
| PoC (수동) | 5시간/화면 | 프롬프트 시행착오 |
| Batch 1 (반자동) | 6분/화면 | 파이프라인 초기 |
| Batch 4 (자동) | 45초/화면 | 학습 루프 반영 |
단, 이 400배는 Super Easy 화면의 코드 생성 시간 기준입니다. 코드 리뷰, 수동 보정, QA까지 포함한 end-to-end 시간은 난이도에 따라 다릅니다 (Super Easy 0.5일, Super Hard 3일). 전체 프로젝트 기준으로는 4,300 M/D → ~1,300 M/D, 약 3.3배 절감이며 이것이 실질적 ROI입니다. 그래도 수동 전환 대비 압도적인 차이인 건 분명합니다.
핵심은 "AI가 실수하면 규칙을 추가한다" — 자기 개선하는 파이프라인이라는 점입니다.
5-3. 실패와 교훈 — 빈 껍데기 사건
이게 가장 뼈아픈 실패입니다.
Batch 2-3에서 속도를 우선시해서 원본 xfdl 파싱을 건너뛰었습니다. 템플릿만으로 빠르게 생성하면 되지 않을까? 결과는 참담했습니다:
- 그리드 컬럼이
순번1개뿐 (원본은 12개 이상) - API URL이 추정값 (
LSTComService.get{화면ID}) - 화면명이 부정확
화면을 열어도 데이터가 표시되지 않는 빈 껍데기.
분석해보니 실제 빈 껍데기는 15개였지만 (처음에는 79개로 추정), 검색 조건 누락과 API URL 부정확 등의 품질 문제는 전체 99개 화면에 걸쳐 있었습니다.
교훈: AI도 garbage in, garbage out. 이 사건 이후 5가지 필수 추출 항목을 규칙화했고, 배치 생성 후 자동 품질 체크 스크립트도 만들었습니다.
추가로 발견한 문제들도 있었습니다:
- AG Grid 커스텀 테마 클래스 누락으로 그리드가 높이 0으로 렌더링 (75개 화면 일괄 수정)
- DatePicker에
YYYYMMDD형식 직접 전달로 Invalid Date 에러 (7개 화면 일괄 수정)
모두 conversion-rules.md에 필수 규칙으로 추가했고, 이후 배치에서는 재발하지 않았습니다.
6. 결과와 수치
| 지표 | 값 |
|--------------------|-------------------------------------------|
| DOM 매핑 | 94-100% (평균 97%) |
| 기능 통과율 | 86% (49/57 시나리오) |
| 코드 감소 | 79% (15,558줄 → 3,252줄) |
| Transaction 매핑 | 100% (21/21) — 백엔드 무변경 |
| TypeScript 빌드 | 0 에러 |
| Vite 빌드 | 2.58초, 3,026 모듈 |
| shadcn/ui 준수율 | 100% |
| 배치 생성 | PoC 8개 → 총 202개 화면 |
| 생산성 | 5시간 → 45초/화면 (400배) |
| 전체 ROI | 4,300 M/D → ~1,300 M/D (70% 절감) |
난이도별 변환율:
| 난이도 | 자동변환율 | 기능통과율 | 수동 보정 |
|-------------|------------|------------|-----------|
| Super Easy | 95% | 100% | 0.5일 |
| Easy | 85% | 94% | 1일 |
| Hard | 70% | 100% | 2일 |
| Super Hard | 40% | 63% | 3일 |
Transaction 매핑 100%가 특히 의미 있습니다. 백엔드 코드를 한 줄도 바꾸지 않고 React에서 기존 API를 그대로 호출할 수 있다는 뜻이니까요. (XML→JSON 변환 레이어는 별도 필요)
AI가 잘 못하는 것 — Super Hard의 벽
솔직하게 말하면, Super Hard 화면의 자동변환율은 40%입니다. 나머지 60%는 왜 AI가 못할까요?
연쇄 의존 로직: VOC접수 화면에는 대/중/소분류 Combo가 3단으로 연동됩니다. 대분류를 바꾸면 중분류 목록이 바뀌고, 중분류를 바꾸면 소분류가 바뀝니다. 이런 cascade 로직은 xfdl의 이벤트 핸들러 안에 절차적으로 숨어있어서, AI가 XML만 보고는 의존 관계를 추론하기 어렵습니다.
모드 전환: 같은 화면이 "조회 모드"와 "등록 모드"에서 완전히 다른 UI를 보여주는 경우. 어떤 필드가 활성화되고 어떤 버튼이 나타나는지가 비즈니스 규칙에 따라 달라집니다. 이건 코드에 명시되지 않은 도메인 지식이 필요합니다.
복잡한 그리드 조작: 셀 단위 편집, 행 상태 추적(insert/update/delete), 셀 병합, 조건부 스타일링이 동시에 적용되는 그리드. AG Grid가 이 기능들을 모두 지원하지만, 원본 xfdl에서 이 조합을 정확히 읽어내는 건 현재 파이프라인으로는 한계가 있습니다.
공통 함수 체인: gfn_Transaction() → 콜백에서 gfn_showMessage() → 조건에 따라 gfn_showConfirm() → 확인 시 다시 gfn_Transaction(). 이런 비동기 콜백 체인을 async/await + React 상태로 변환하는 건 패턴 매칭만으로 안 되고, 실행 흐름을 이해해야 합니다.
결국 **AI가 잘하는 영역은 "구조 변환"이고, 못하는 영역은 "비즈니스 로직 이해"**입니다. 이 경계를 아는 것이 파이프라인 설계의 핵심이었습니다.
7. 배운 것들 — 에이전트 시스템 설계 원칙
1. 스펙 우선 (Spec-First): 검증 기준 없이 코드만 생성하면 자동 재시도가 불가능합니다. Phase 2에서 AC를 먼저 만든 것이 전체 파이프라인의 핵심이었습니다.
2. 스티어링의 힘: 컨텍스트 없는 AI는 hallucinate합니다. 변환 규칙 211줄이 1,700개 화면의 품질을 결정합니다. 처음에는 "이 정도면 충분하겠지" 싶었는데, 부족할 때마다 규칙을 추가하니 품질이 계단식으로 올라갔습니다.
3. 학습 루프: migration-lessons.md에 실수를 누적하고 다음 배치에 자동 반영하는 구조. Batch 1에서 6건의 빌드 에러가 났지만, Batch 2에서는 0건이었습니다.
4. 원본 데이터 충실도: AI도 garbage in, garbage out. xfdl 파싱을 건너뛰면 빈 껍데기가 됩니다. 가장 비싼 교훈이었습니다.
그리고 이 원칙들은 이 프로젝트에만 적용되는 게 아닙니다. Steering + Agent + Skill + Hook 패턴은 원본을 구조적으로 파싱할 수 있고, 변환 패턴이 유한하고, 품질 기준을 자동 검증할 수 있는 곳이면 어디든 적용 가능합니다. jQuery→React, JS→TS, MUI→shadcn, REST→GraphQL — 핵심은 동일합니다.
마치며
여태 바이브코딩이나 프롬프트를 주고받는 수준에 머물렀는데, 이번 워크샵에서 커스텀 에이전트를 직접 구축하고 Steering에 지식을 축적하면서 AI를 대하는 관점이 바뀌었습니다. 이전에는 "AI한테 시키면 되지"였다면, 지금은 "어떤 에이전트를 몇 개 만들지, 어떤 규칙을 줄지, 품질 기준을 어디에 둘지"를 설계하는 것이 진짜 실력이라는 걸 체감합니다. 같은 Kiro CLI를 쓰더라도 어떤 사람이 설계하느냐에 따라 결과가 완전히 달랐거든요.
3일 워크샵이었지만 거의 해커톤처럼 2-3시간만 자면서 몰입했습니다. 단순히 AI로 코드를 생성하는 게 아니라, 에이전트 팀을 빌딩하고, 실패에서 규칙을 뽑아내고, 파이프라인이 스스로 개선되는 걸 지켜보는 과정이 정말 즐거웠습니다. "이거 진짜 되네?"라는 순간이 계속 반복됐고, 그 짜릿함이 잠을 줄여도 아깝지 않게 만들었습니다.
특히 AWS SA분들이 멘토 역할을 해주셨는데, Kiro의 steering 설계부터 에이전트 최적화까지 질문할 때마다 친절하게 답변해주셔서 정말 감사했습니다. 덕분에 혼자 삽질했으면 하루가 걸렸을 부분을 몇 시간 만에 해결할 수 있었고, AI 엔지니어링에 대한 시야도 넓어졌습니다.
물론 남은 과제도 있습니다. Hard/Super Hard 화면의 수동 보정, 비즈니스 로직 검증, 실제 백엔드 API 연동 등 자동화율 100%는 아닙니다. 하지만 수동 4,300 M/D에서 약 1,300 M/D로 줄일 수 있다면 충분히 의미 있는 결과입니다. 워크샵 주제에 그치지 않고 실제 업무에도 적용할 수 있겠다는 확신을 얻은, 전환점이 된 경험이었습니다.
AI가 개발자를 대체하는 게 아니라, 파이프라인을 설계하는 개발자가 필요하다.
에이전트는 도구입니다. 어떤 에이전트를 몇 개 만들지, 어떤 스티어링 규칙을 줄지, 품질 기준을 어디에 두는지 — 이 설계는 사람이 합니다. 레거시 플랫폼을 몰랐던 React 개발자가 3일 만에 202개 화면을 만들 수 있었던 건, AI가 대단해서가 아니라 파이프라인 설계가 제대로 됐기 때문입니다.
긴 글 읽어주셔서 감사합니다!
참고 자료
- Claude Code — Anthropic CLI
- Kiro CLI — AWS AI-DLC 도구