[AI] MSA 서비스를 분석하는 가장 확실한 방법– 문서 중심 지식기반 개발 전략

 

ㅁ 들어가며

 MSA 구조는 유연하고 확장성이 높다. 하지만 그만큼 복잡하다. 모듈 간 호출 흐름이 얽혀 있고, 장애 발생 시 근본 원인을 빠르게 파악하기 어렵다. 이런 구조를 효율적으로 분석하고 이해하기 위해선 명확한 접근 방식이 필요하다.

그 해답이 문서 기반 지식 엔지니어링(Documentation-Driven Knowledge Engineering) 이다.

 

 

ㅁ 왜 문서 중심인가?

 

코드는 진실이다. 하지만 항상 빠르게 이해할 수 있는 진실은 아니다. MSA 환경에서는 다음과 같은 문제가 자주 발생한다.

• 서비스 구조가 머릿속에 들어오지 않는다.
• API 호출 경로가 명확하지 않다.
• 장애 발생 시 관련 모듈을 찾기 어렵다.
• 분석 시간이 오래 걸린다.

이런 문제를 해결하려면, 각 모듈의 기능, 구조, API, 연동 흐름을 체계적으로 기록하고, 이를 기반으로 질문하고 이해하는 방식이 효과적이다.

 

ㅁ분석 방식

 

1. 모듈 단위로 폴더 분리

서비스 하나를 여러 모듈(STT, NLU, 라우터 등)로 나누고, 각 모듈별 폴더를 만든다.

project-docs/
├── module-a/
├── module-b/
├── module-c/

 

2. 핵심 문서 3종 작성

각 모듈에는 다음과 같은 문서를 작성한다.

• structure.md
  → 주요 클래스, 디렉토리 구조, 내부 구성 요약
• api.md
  → 외부에 제공하는 API 목록, 호출하는 외부 API, 형식 및 동작
• flow.md
  → 실제 요청 흐름, 비즈니스 로직, 연동 흐름

 

3. 전체 시스템 요약

모듈 간 연결 구조와 흐름을 summary.md 또는 architecture.md에 정리한다. 시퀀스 다이어그램이나 구조 그림을 함께 포함하면 효과적이다.

 

ㅁ 문서로부터 지식을 추출한다

 

이제 문서가 쌓이면, 그 자체가 지식 기반이 된다. 코드를 보지 않고도 질문할 수 있다.

• 이 기능은 어떤 모듈이 처리하는가?
• A 모듈이 호출하는 외부 API는 무엇인가?
• B 모듈은 실패 시 어떤 fallback을 사용하는가?
• 사용자 요청이 C까지 도달하는 경로는 어떻게 되는가?

이 질문에 문서로 바로 답할 수 있다면, 분석 속도가 빨라진다.

 

 

ㅁ Cursor와 함께 사용한다

Cursor 같은 AI 기반 코드 분석 도구와 함께 사용할 때 강력하다. 문서를 기반으로 Cursor에게 질문하면, 단순한 코드 이해를 넘어 시스템 레벨의 이해로 이어진다.

예시:

이 프로젝트는 MSA 구조의 서비스 분석 문서입니다.
각 모듈에 구조.md, api.md, flow.md가 있습니다.

‘사용자 요청이 실패했을 때 어떤 모듈에서 에러가 나는가?’에 대한 답을 문서에서 찾아주세요.

 

ㅁ장점

• 빠른 문제 추적
• 협업 효율 향상
• 신규 인력 온보딩 가속
• 테스트 시나리오 도출
• 문서 기반 지식 관리

 

ㅁ 마무리

MSA는 분산된 만큼 정리가 필요하다.
문서로 정리하고, 그 문서로 질문하고, 그 질문으로 이해한다.
그것이 진짜 구조를 아는 방법이다.

문서 중심 지식기반 개발은 복잡한 시스템을 단순하게 만든다.