넥사크로 마이그레이션을 에이전트에게 맡기기까지
10년 넘게 굴러온 넥사크로 A/S 업무시스템을 React로 걷어내는 일을 맡았다. 화면을 사람이 하나씩 옮기는 대신 에이전트 파이프라인을 만드는 쪽에 시간을 썼고, 그 구조가 자리 잡기까지 여섯 달이 걸렸다.
처음엔 한 세션에 다 맡겼다
레거시 소스를 통째로 읽히고, Playwright MCP로 실제 화면을 띄워 동작까지 확인시킨 다음, 같은 세션에서 React 코드를 쓰게 했다. 반복되는 프롬프트가 보이길래 스킬로도 묶었다.
동작은 했다. 문제는 화면이 커질수록 드러났다.
- 분석 결과·레거시 코드·구현 중인 코드가 한 컨텍스트에 쌓여 뒤로 갈수록 앞의 분석을 잊는다
- 기능이 조용히 빠진다. 빠진 걸 사람이 나중에 발견한다
- Playwright MCP는 세션을 공유하지 않아 매번 토큰을 손으로 넣어야 했고, 그 토큰이 작업 도중에 만료됐다
인증은 Claude in Chrome으로 옮겨 브라우저 세션을 그대로 쓰는 것으로 해결했다. 컨텍스트는 그렇게 해결되지 않았다. 1세대 스킬은 결국 deprecated로 내렸다.
전환점은 분석과 구현을 가른 것
한 세션에서 분석과 구현을 다 하려던 걸 멈추고, 분석 결과를
PRD 문서로 떨궈놓는 스킬(nexacro-react-prd)과 그 PRD만
읽고 코드를 쓰는 스킬(nexacro-react-migration)로 나눴다.
이게 가장 큰 차이를 만들었다.
- 구현 세션은 레거시 전체가 아니라 PRD 한 장만 들고 시작한다
- PRD 품질과 구현 품질을 따로 손볼 수 있다
- 사람이 검토할 대상이 “생성된 코드”에서 “명세”로 앞당겨진다
기능 누락은 PRD 쪽에 자동 보완 루프를 붙여 잡았다. 같은 분석을 다시 돌려 PRD에 바뀌는 게 없을 때까지 반복하고, 최대 10회에서 끊는다.
결국 굴러간 파이프라인
| 단계 | 도구 | 하는 일 |
|---|---|---|
| 화면 목록 추출 | 에이전트 | 레거시 메뉴 트리를 파싱해 대상 화면 뽑기 |
| 일감 생성 | jira-query |
에픽 아래로 화면별 일감 일괄 생성 |
| PRD 작성 | nexacro-react-prd |
화면 단위 명세 생성 + 자동 보완 루프 |
| 워크트리 생성 | git-ops |
화면별 브랜치·디렉터리·세션을 동시에 개설 |
| 구현 | nexacro-react-migration |
PRD를 코드·테스트로 |
| 리뷰 | 컨벤션 리뷰 + /code-review |
컨벤션 위반 수정, 코드 품질 정리 |
| 커밋·PR | git-ops |
리베이스 → 커밋 → PR 생성 |
두 가지가 이 표를 실제로 돌아가게 만들었다.
워크트리 + 멀티플렉서. 화면마다 독립된 브랜치·디렉터리·세션을 가지니 충돌 없이 여러 화면을 동시에 진행할 수 있다. 워크트리를 만들 때 의존성 설치·빌드·개발 서버 기동은 서브에이전트로 떼어 메인 컨텍스트 밖에서 병렬로 돌린다.
공유 컨벤션 스킬. 구현 스킬이 코드를 건드리기 전에
basis-web-conventions를 반드시 로드하도록 게이트를 걸었다.
가이드라인 자체는 한 번에 다 읽히지 않고 주제별로 2차 로드한다 —
FSD 규칙이 필요한 에이전트만 FSD 문서를 읽는다.
여섯 달 동안 이 파이프라인으로 화면 50여 개, 일감 418건, PR 469건을 처리했다. 명세의 수용 기준을 검증하는 테스트 파일이 261개 쌓였다.
아쉬운 것
더 일찍 갈랐어야 했다. 올인원이 무너지는 걸 확인하는 데 한 달을 썼다. 컨텍스트가 커지면 품질이 떨어진다는 건 시작 전에도 알던 사실이었는데, 직접 겪고 나서야 구조를 바꿨다.
TDD로 가지 못했다. 마이그레이션이라 기존 화면의 동작을 검증할 테스트가 애초에 없었고, 구현이 끝난 뒤에 테스트를 붙이는 순서가 됐다. 테스트가 먼저 있었다면 스킬을 고칠 때마다 회귀를 즉시 볼 수 있어 더 과감하게 손댔을 것이다.
스킬은 컴파일 에러가 없다. 지침이 길어질수록 의도대로
도는지 확인하기 어려웠다. --verbose와 훅 로그로 버텼지만,
스킬 전용 테스트 환경이 있었으면 했다.