테크 랩

에이전틱 개발 파이프라인 – 04. Claude Code로 MSA 설계·구현하기

2026.08.20

3줄 요약

MSA의 서비스 경계는 에이전틱 개발의 작업 단위와 구조적으로 일치한다 — AI가 한 번에 온전히 소화할 수 있는 범위가 곧 서비스 경계다.
Claude Code로 도메인 분해 → 서비스 정의 → API 인터페이스 → 데이터 소유 경계를 단계별 프롬프트 패턴으로 설계하고, 단계마다 사람이 검토한다.
각 서비스는 Gitea 이슈로 매핑된다 — Claude Code가 이슈를 등록·담당자 지정·PR 연결까지 하고, 사람은 경계·트레이드오프 판단과 오케스트레이션을 맡는다.

Claude Code로 MSA를 설계한다면, 사람은 무엇을 해야 할까?

마이크로서비스 아키텍처(MSA)의 가장 어려운 부분은 코드가 아니다. 서비스 경계를 어디서 나눌 것인가, 어떤 서비스가 어떤 데이터를 소유할 것인가, API 계약은 어떻게 정의할 것인가다. 이 판단들이 틀리면 수개월 뒤 분산 모놀리스라는 최악의 결과를 만난다.

Claude Code는 MSA 설계의 이 지점에서 실질적으로 기여한다. 도메인 분석, 서비스 후보 도출, OpenAPI 스키마 초안, 디렉토리 스캐폴딩까지 구현의 상당 부분을 AI가 처리한다. 더 나아가 설계가 확정되면 Claude Code가 Gitea에 서비스별 이슈를 스스로 등록하고, 담당자를 지정하며, 그 이슈 안에서 실제 개발을 진행한다.

왜 MSA와 에이전틱 개발이 잘 맞나?

에이전틱 AI가 코드를 작성할 때 가장 잘 동작하는 조건이 있다. 범위가 명확하고, 입출력이 정의되어 있으며, 다른 컨텍스트에 의존하지 않는 작업이다. MSA의 개별 서비스가 정확히 이 조건을 충족한다.

서비스 경계 = AI 작업 단위: 각 서비스는 명확한 도메인 책임을 갖는다. “주문 서비스의 API와 비즈니스 로직을 구현하라”고 위임하면 컨텍스트 범위가 정해지고, AI는 그 안에서 집중한다.
독립 배포 = 독립 이슈·PR: 서비스마다 별도 디렉토리·Dockerfile·CI 파이프라인을 갖는다. AI가 한 서비스를 구현해도 다른 서비스를 건드리지 않는다. 이슈·브랜치·머지가 서비스 단위로 깔끔하게 분리된다.
API 계약 = 검증 가능한 경계: OpenAPI 스키마나 protobuf 정의처럼 기계가 읽을 수 있는 계약이 존재한다. AI가 생성한 구현이 계약을 만족하는지 자동 검증할 수 있다.

반면 모놀리식 구조에서는 컨텍스트가 비대해진다. 코드베이스 전체를 파악해야 하나의 기능을 수정할 수 있다면, AI도 사람도 생산성이 떨어진다. MSA는 코드베이스를 인지 가능한 크기로 쪼개는 구조이고, 이것이 에이전틱 개발과 시너지를 내는 핵심 이유다.

AI에게 서비스 경계를 그리게 하는 프롬프트 패턴

설계를 AI에 통째로 맡기면 과분함(too fine-grained)에 빠지거나 책임이 흐릿한 서비스가 나온다. 4단계 프롬프트로 사람이 각 단계에 검증 게이트를 갖는 구조가 안전하다.

1단계 — 도메인 분해

먼저 비즈니스 도메인을 언어로 설명하고, 핵심 명사(엔티티)와 동사(행위)를 추출하게 한다.

우리 서비스의 도메인은 아래와 같습니다:
[비즈니스 설명 붙여넣기]

1. 핵심 엔티티(명사)를 추출하세요.
2. 각 엔티티가 갖는 주요 행위(동사)를 나열하세요.
3. 자연스럽게 묶이는 엔티티+행위 그룹을 도메인 후보로 제시하세요.

결과로 나온 도메인 후보를 팀이 검토한다. AI가 제안한 경계 중 실제 비즈니스 흐름과 맞지 않는 것을 사람이 조정한다.

2단계 — 서비스 정의

승인된 도메인 후보를 기반으로 각 서비스의 책임과 비책임을 명시적으로 정의하게 한다.

위 도메인 후보 중 [주문 도메인]을 마이크로서비스로 정의하세요.
다음 형식으로 작성:
- 서비스명:
- 이 서비스가 책임지는 것:
- 이 서비스가 책임지지 않는 것:
- 외부 의존(소비하는 다른 서비스 API):
- SLA 요구사항(응답시간·가용성 등, 모르면 생략):

3단계 — API 인터페이스 초안

서비스 정의가 확정되면 OpenAPI 스키마 초안을 생성한다. 계약이 구현보다 먼저 존재하는 “계약 우선(Contract-First)” 원칙이다.

위 [주문 서비스] 정의를 바탕으로 OpenAPI 3.1 스키마를 작성하세요.
- 엔드포인트는 REST 관례를 따르세요.
- 요청/응답 스키마에 필수 필드와 타입을 명시하세요.
- 에러 응답(4xx, 5xx)도 포함하세요.
- 구현 코드는 작성하지 말고 스키마만 작성하세요.

생성된 스키마를 사람이 검토하고 수정한다. 이 파일이 이후 모든 구현(서버 스텁, 클라이언트 SDK, 테스트)의 소스오브트루스가 된다.

4단계 — 데이터 소유 경계

가장 중요하고 가장 틀리기 쉬운 단계다. 어떤 서비스가 어떤 테이블(또는 컬렉션)을 소유하는지를 명확히 한다.

현재 설계된 서비스 목록과 각 서비스의 정의를 보고:
1. 각 서비스가 단독으로 쓰기 권한을 갖는 데이터 엔티티를 나열하세요.
2. 두 서비스 이상이 쓰기를 공유하는 엔티티가 있으면 명시하세요(이것이 문제다).
3. 공유 쓰기가 발생하는 경우, 소유를 어느 서비스로 일원화할지 두 가지 옵션을 제시하세요.

공유 쓰기가 나오면 경계 재조정이 필요하다는 신호다. AI가 제안한 두 옵션을 사람이 판단한다.

★ MSA 개발 = 프로젝트 관리 — Gitea 이슈로 서비스를 추적한다

이 시리즈의 핵심 논지를 꺼낼 때다. 개발 환경의 AX(AI 전환)는 결국 프로젝트 관리 능력과 비례한다. AI가 개발 주체가 될수록, 그 AI를 조율·추적·소통시키는 관리 체계가 성패를 가른다.

MSA에서 이 원칙은 매우 구체적인 형태로 나타난다. 각 서비스 = Gitea 이슈 = 개발 담당이라는 1:1:1 매핑이다.

설계 4단계가 끝나면 Claude Code에게 이슈 등록을 지시한다.

# 예시 — Claude Code에게 서비스별 이슈 일괄 등록 지시
아래 서비스 목록에 대해 Gitea 레포지토리 [repo-name]에 이슈를 하나씩 등록해줘.
각 이슈 제목: "[서비스명] 초기 구현"
본문에는: 단일 책임 설명, 소유 데이터 엔티티, 연관 서비스(→ 방향), 완료 기준(DoD) 3개.
담당자는 [계정]으로 지정하고, 라벨은 "service-init"으로 붙여줘.

Claude Code는 Gitea API를 통해 서비스별 이슈를 자동 등록한다. 개발 시작 전부터 어떤 서비스가 있고, 누가 담당이며, 완료 기준이 무엇인지가 한눈에 보이는 프로젝트 보드가 생긴다. (Gitea MCP 통합 설정은 이 시리즈 06편에서 상세히 다룬다.)

각 이슈 안에서 Claude Code는 실제 개발을 진행한다. 브랜치를 만들고, 코드를 작성하고, PR을 열고, 자기가 연 이슈를 참조해 머지한다. 이슈와 PR이 히스토리로 남기 때문에 “이 서비스가 왜 이 구조를 선택했는가”를 나중에 누구든 추적할 수 있다.

이것이 오케스트레이션의 실체다. 사람 팀이 협업하듯 AI를 소통시키는 구조 — 이 관리 체계가 없으면 AI가 열심히 코드를 짜도 그 결과가 어디에, 왜 존재하는지 아무도 모르게 된다. “개발 환경의 AX는 프로젝트 관리 능력과 비례한다”는 논지가 여기에 실체를 갖는다.

사람의 역할 = 오케스트레이션

에이전틱 개발에서 사람이 빠지면 안 되는 판단이 있다. AI가 아무리 정교해도 이 판단을 대신하게 두면 나중에 비용을 치른다.

판단 유형	AI 위임 가능	사람 필수
서비스 경계 후보 도출	초안 생성	최종 승인
API 스키마 초안 작성	가능	비즈니스 검증·수정
트레이드오프 판단 (동기/비동기, 데이터 복제 여부 등)	옵션 나열	선택·결정
Gitea 이슈 등록·담당자 지정	전담 가능	담당 배분 방침 결정
서비스 스캐폴딩·CI yaml 초안	전담 가능	보안·정책 검토
비즈니스 우선순위 (어떤 서비스를 먼저)	기여 어려움	필수
운영 리스크 판단 (장애 시나리오)	나열 지원	수용 여부 결정

오케스트레이션은 AI에게 무엇을 언제 요청할지를 결정하고, AI 결과물을 다음 단계의 입력으로 연결하며, 각 단계에서 검증 게이트를 통과시키는 것이다. 개발 팀 리더의 역할이 “코드를 많이 짜는 것”에서 “AI가 올바른 것을 만들게 조율하는 것”으로 이동한다.

실전 단계: 모노레포 구조 + 계약 우선 개발

설계가 끝나면 Claude Code가 프로젝트 골격을 만든다. 주니크가 사용하는 모노레포 패턴 기준으로 정리한다.

단계	담당	산출물
1. 모노레포 루트 구조 확정	사람(결정) + AI(생성)	`services/`, `shared/`, `infra/`, 루트 `README.md`
2. Gitea 이슈 일괄 등록	AI (Claude Code)	서비스별 이슈 + 담당자 + DoD
3. 계약 우선 스키마 커밋	AI 초안 → 사람 승인	`services/{name}/openapi.yaml`
4. 서비스별 디렉토리 스캐폴딩	AI 전담	앱 골격, Dockerfile, 테스트 초안
5. 공유 라이브러리 정의	사람(결정) + AI(초안)	`shared/types/`, `shared/utils/` 등
6. CI 파이프라인 초안	AI 전담	Gitea Actions yaml (서비스별)

계약 우선(Contract-First)이 핵심이다. API YAML이 먼저 존재하면 서비스 A를 개발하는 AI와 서비스 B를 개발하는 AI(또는 사람)가 서로 블로킹 없이 병렬로 진행할 수 있다. 계약이 없으면 AI는 자신이 만든 인터페이스가 다른 서비스와 어긋나도 모른다.

모노레포를 선택하는 이유는 단순하다. Claude Code가 서비스 간 의존성을 한 번에 읽을 수 있어야 코드 생성 품질이 올라간다. 다중 레포로 분산하면 컨텍스트가 끊겨 인터페이스 변경을 AI가 추적하지 못한다. 팀 규모가 커지면 그때 분리를 고려하는 것이 현실적이다.

CLAUDE.md에 서비스 스캐폴딩 패턴을 등록해두면 새 서비스를 추가할 때마다 일관된 구조가 나온다.

# CLAUDE.md 등록 패턴 (예시 — 실제 언어·프레임워크에 맞게 조정)
새 서비스를 추가할 때는 아래 구조를 따른다:

services/{service-name}/
├── src/
│   ├── api/          # 라우터·핸들러
│   ├── domain/       # 비즈니스 로직 (순수, 외부 의존 없음)
│   ├── infra/        # DB·메시지큐 어댑터
│   └── main.ts       # 진입점
├── tests/
├── openapi.yaml      # API 계약 (구현보다 먼저 작성)
├── Dockerfile
└── README.md

규칙:
- domain/ 에 외부 라이브러리 직접 임포트 금지 (의존성 역전)
- openapi.yaml 없이 src/ 구현 시작 금지
- 환경변수는 .env.example 에 키 목록 필수
- 새 서비스 추가 시 Gitea 이슈를 먼저 등록하고 이슈 번호를 브랜치명에 포함한다

흔한 함정 3가지

1. 과분함(Too Fine-Grained)

AI는 도메인을 지나치게 잘게 쪼개는 경향이 있다. “사용자 프로필 서비스”와 “사용자 설정 서비스”를 분리하면 초반에는 깔끔해 보이지만, 두 서비스가 항상 함께 호출된다면 네트워크 비용과 운영 복잡도만 늘어난다. 초안 검토 시 “이 서비스가 독립 배포·독립 확장 이유가 있는가?”를 사람이 반드시 검증한다.

2. 경계 흐림(Boundary Leakage)

서비스 A가 서비스 B의 DB에 직접 접근하거나, 공유 테이블에 두 서비스가 함께 쓰면 MSA가 아니라 분산 모놀리스가 된다. 4단계 “데이터 소유 경계” 프롬프트로 설계 단계에서 잡아야 한다. PR 리뷰에서도 다른 서비스의 데이터를 직접 조회하는 코드가 있으면 반드시 걸러야 한다.

3. 이슈 없는 개발

AI가 이슈 없이 코드를 직접 작성하면 나중에 “이 코드가 왜 여기 있나”를 추적할 방법이 없다. Claude Code에게 항상 이슈 번호를 먼저 받아 브랜치명·커밋 메시지에 포함시키는 규칙을 세워라. 이 한 가지 규칙이 프로젝트 히스토리의 질을 결정한다.

🎓 바로 쓰기

비즈니스 도메인을 2~3문단으로 작성하고 1단계 도메인 분해 프롬프트를 실행한다. 서비스 후보를 3~5개로 좁힌다.
각 후보에 2단계 서비스 정의 프롬프트를 실행한다. “이 서비스가 책임지지 않는 것” 항목이 비어있으면 경계가 불명확한 것이다.
3단계로 OpenAPI 스키마를 생성하고 openapi.yaml로 저장한다. 이것이 계약이다.
4단계 데이터 소유 경계를 확인한다. 공유 쓰기가 나오면 경계를 재조정한다.
Claude Code에게 서비스별 Gitea 이슈를 등록하게 하고, 각 이슈에 담당자와 DoD를 지정한다.
CLAUDE.md에 서비스 스캐폴딩 패턴을 등록하고 Claude Code로 디렉토리 구조를 생성한다.
계약(openapi.yaml) 기반으로 서버 스텁과 테스트를 생성한다. 구현은 이 순서 이후다.

FAQ

Claude Code가 도메인 분해를 얼마나 잘 하나?

초안 품질은 제공하는 도메인 설명의 품질에 비례한다. 비즈니스 흐름을 구체적으로 설명할수록 경계가 의미 있게 나온다. AI 초안을 그대로 쓰는 것보다 “틀린 것을 교정하는” 용도로 쓰는 것이 더 빠르다. 처음부터 백지에 그리는 것보다 AI 초안을 검토하는 편이 대부분의 경우 효율적이다.

Gitea 이슈 등록을 AI가 한다는 게 실제로 가능한가?

Gitea MCP 서버를 Claude Code에 연결하면 가능하다. 이슈 생성·담당자 지정·라벨 부착·PR 연결까지 Claude Code가 API 호출로 처리한다. 구체적인 설정 방법은 이 시리즈 06편에서 다룬다.

기존 모놀리식 코드베이스에 적용할 수 있나?

가능하다. 기존 코드의 의존 관계를 Claude Code로 분석시키고 (“이 파일들의 import 관계를 분석해 도메인 클러스터를 제시하라”), 분리 가능한 경계부터 점진적으로 추출한다. 전체를 한 번에 분해하려 하면 실패한다. 경계가 명확한 하나의 도메인을 먼저 추출해 검증한 뒤 반복하는 것이 현실적이다.

MSA 서비스 간 통신은 어떤 방식이 좋은가?

이 결정은 AI가 아니라 사람이 한다. 동기 REST는 구현이 단순하지만 서비스 간 결합도가 생긴다. 비동기 메시지큐는 결합도가 낮지만 운영 복잡도가 높다. 팀의 운영 역량, 요구 응답시간, 장애 허용 수준을 고려해 결정한 뒤 CLAUDE.md에 기록한다. 이후 AI가 구현할 때 이 결정을 따르게 한다.

MSA 설계·구현에서 AI가 가져가는 부분이 늘어날수록, 사람이 집중해야 하는 판단의 질이 더 중요해진다. 경계를 잘못 그으면 AI가 빠르게 잘못된 방향으로 구현한다. 오케스트레이션은 속도를 위한 기술이기도 하지만, 품질을 지키기 위한 책임이기도 하다.

구체적인 MSA 설계 고민이 있다면 주니크에 문의하세요. 도메인 분석부터 서비스 경계 정의·Gitea 파이프라인 구성까지 실전 기반으로 함께 검토합니다.

『에이전틱 개발 파이프라인』 시리즈
← 이전: 03. Claude Code 실전 세팅 (CLAUDE.md)
→ 다음: 05. AI가 짠 코드, 어떻게 믿나 (검증 게이트)

다른 글 보기