설계 없이 코딩하면 벌어지는 일

흔한 실패 시나리오

[1일차] "일단 코드부터 쓰자!"
  -> RAG 코드 복사, Agent 코드 복사, 합치기 시작

[2일차] "어? 패키지 충돌이..."
  -> langchain 버전이 RAG랑 Agent에서 다름
  -> chromadb 초기화 코드가 두 군데서 충돌

[3일차] "Agent에서 RAG를 호출하려니까..."
  -> 임포트 순환 참조 (circular import)
  -> config가 여기저기 하드코딩됨

[4일차] "UI 붙이려니까 구조가..."
  -> 어디에 어떤 함수가 있는지 모름
  -> 전역 변수가 얽혀서 리팩토링 지옥

[5일차] "데모 불가능합니다..."
  -> 팀장: "..."

설계 없이 5일 코딩 = 대혼란. 설계에 1일 투자 = 나머지 4일이 순탄.

---

MVP 설계의 핵심 원칙

1. YAGNI (You Ain't Gonna Need It)

[오버엔지니어링]                    [MVP 설계]
Kubernetes 클러스터           vs    Docker Compose
마이크로서비스 8개            vs    모놀리식 1개
Kafka 메시지 큐               vs    함수 직접 호출
Redis 캐시 + CDN              vs    메모리 캐시
CI/CD 파이프라인              vs    docker compose up

MVP의 목표는 "완벽한 시스템"이 아니라 "동작하는 데모"

2. 의존성 방향 원칙

[좋은 구조]                [나쁜 구조]

  UI Layer                   UI
    |                       / | \
  Service Layer          RAG Agent KG
    |    |                 \ | /
  RAG  Agent  KG          Database
    \   |   /
   Data Layer             (서로 참조, 순환 의존)

규칙: 상위 레이어만 하위 레이어를 참조한다. 역방향 금지.

3. 단일 진입점 (Single Entry Point)

# 나쁜 예: 여러 진입점
python rag_server.py &     # 포트 8001
python agent_server.py &   # 포트 8002
python kg_server.py &      # 포트 8003
streamlit run ui.py        # 포트 8501
# -> 4개 프로세스 관리 필요

# 좋은 예: 단일 진입점
streamlit run app/main.py  # 포트 8501
# -> 내부에서 RAG, Agent, KG 모듈 import

---

아키텍처 선택: 모놀리식 MVP

구분	모놀리식 (MVP)	마이크로서비스
개발 속도	빠름 (5일 가능)	느림 (3주+)
복잡도	낮음	높음
디버깅	쉬움 (단일 프로세스)	어려움 (분산 추적)
배포	docker compose up	K8s 클러스터 필요
확장성	제한적	유연함
MVP 적합성	최적	오버엔지니어링

먼저 모놀리식으로 검증하고, 성공하면 필요한 부분만 분리하라. -- Martin Fowler, "MonolithFirst"

---

핵심 질문

다음 질문에 답할 수 있으면, 아키텍처 설계 준비가 된 것이다:

1. 시스템의 주요 컴포넌트는 몇 개인가?
2. 각 컴포넌트 사이의 데이터 흐름은 어떤가?
3. 외부 의존성 (API, DB)은 무엇인가?
4. 사용자의 핵심 유스케이스는 무엇인가?