Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
10년 된 레거시 모놀리스를 마이크로서비스로 이식하는 과정에서 발생하는 복잡성을 해결하기 위해, Claude Code의 서브 에이전트 기능을 활용했습니다. 핵심은 AI에게 역할을 부여하고 정보 접근 범위를 엄격하게 제한하여 '정보 격리'와 '파일을 통한 전달' 메커니즘을 설계한 것입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기10년 된 레거시 모놀리스(PHP / Laravel 구세대)를 여러 마이크로서비스(Laravel 12) + Vue 3 프론트엔드로 이식하는 프로젝트를 담당하고 있다. 규모가 크고, 이식 대상 엔드포인트는 수백 개, 공유 모델은 600개가 넘는다. 한 사람의 머리로 '어떤 API가 어디까지 옮겨졌는지', '구현된 로직이 올바르게 반영되었는지'를 추적하는 것은 무리가 있다.
그래서 Claude Code의 서브 에이전트 기능을 활용하여, 역할별로 읽기 범위를 제한한 16개의 AI 스태프를 편성해 마이그레이션을 진행하는 시스템을 구축했다. 이 글은 그 편성 설계의 핵심—특히 **정보 격리(情報隔離)**와 파일을 통한 전달(ファイル経由の受け渡し)—을 재현 가능한 수준으로 정리한 것이다.
대상 독자는 Claude Code나 유사 에이전트 기반에서 '단발적인 지시'를 넘어선 운영을 해보고 싶은 사람이다.
모노레포(상위 리포지토리) + Git 서브모듈 구성
인증 서비스 / 메인 업무 서비스 / 워크플로우 서비스 / 외부 연동 서비스 (각 Laravel 12)
공유 모델 패키지 / 공유 설정 패키지
프론트엔드(Vue 3 + Vite)는 독립 리포지토리
로컬은 Docker Compose, DB는 MySQL 8 + Memcached
Claude Code의 네이티브 서브 에이전트 (.claude/agents/)
마이그레이션 원본 구 모놀리스는 참조 전용(읽기만 가능, 수정 금지)
AI에게 '마이그레이션 해줘'라고 맡겨버리면 다음과 같은 실패가 일어난다.
환각(Hallucination): 구현된 코드를 읽지 않았는데도 '아마 이렇겠지'라며 응답 구조를 조작한다.
문맥 오염: 프론트엔드의 사정, 구 구현의 사정, 신 구현의 사정을 하나의 컨텍스트에 모두 넣으면 판단이 흐려진다.
임의 구현: 스펙이 확정되지 않았는데도 코드를 작성하기 시작하여 나중에 전부 다시 해야 한다.
종속 순서 파괴: 공유 패키지보다 먼저 개별 서비스를 건드려서 일관성을 망가뜨린다.
이것들은 'AI가 똑똑하지 않아서' 발생하는 것이 아니라, 역할과 정보 범위를 설계하지 않았기 때문에 발생한다. 인간 팀원들로도 모두에게 모든 정보를 주고
코드 변경 작업은 반드시 읽기 전용의 planner가 계획(20-plan.md)을 작성하고, 사람이 승인한 후에야 executor가 구현합니다. executor는 승인된 계획이 없으면 착수하지 않고 멈추도록 에이전트 정의에 게이트를 설정합니다.
planner (permissionMode: plan・읽기 전용)
→ 20-plan.md를 status: draft로 출력
→ 사람이 내용을 확인하고 승인
...
'브레인스토밍으로 정리된 사양은 정확하지 않을 수 있다' — planner의 역할은 기존 코드를 깊이 파고들어 사양과 구현의 모순점 및 영향 범위를 검증하는 것입니다. 여기서 의문점은 ❓사용자 판단 필요:로 나열하고, 임의로 채우지 않습니다.
docs/ 직하 또는 미정의 디렉터리로의 쓰기를 Claude Code의 PreToolUse 후크로 차단합니다. 서브 에이전트 내부의 쓰기도 대상에 포함합니다. '규약에 적혀 있다'는 것만으로는 드리프트(drift)가 발생할 수 있으므로, 기계적으로 막습니다.
에이전트 정의의 골격은 다음과 같습니다 (레거시 분석 담당 역할의 예).
---
name: legacy-analyst
description: 구 모놀리스의 로직 추출 전담. 구 코드만 읽고,
...
구현 담당자(executor)에게는 게이트를 명확히 기재합니다.
## 구현 시작의 전제 조건 (게이트)
- 승인된 구현 계획 (20-plan.md, status: approved)이 필요
- 계획이 없거나 / approved가 아니면 구현하지 않고,
...
모델의 사용 분배도 티어(Tier)로 고정합니다. 정밀한 대조 및 리뷰는 상위 모델을, 정형 작업은 경량 모델을, 가장 중요한 판단만 최상위 모델에 격상시키는 등, 평소에 사용하지 않는다는 운영 방식까지 명문화해 둡니다.
fetch를 수행합니다 (현역으로 업데이트가 계속되고 있기 때문에).AI 에이전트를 실무에서 구동하는 핵심은 '똑똑한 모델을 선택하는 것'이 아니라, 역할・읽기 범위・인계 방법・착수 게이트를 설계하는 것이었습니다.
인간 팀 운영에서 당연히 하는 '담당 분배', '인수인계서', '리뷰 게이트'를 그대로 에이전트 편성(編成)에 옮겨 놓았다고도 할 수 있습니다. 역설적으로, 조직 설계의 지식이 그대로 AI 오케스트레이션에 유효합니다.
