대규모 시스템 및
레거시 DB 대응 전략

개요

본 문서는 A-JADM v1.3의 확장 문서로, 실전에서 가장 빈번한 두 가지 시나리오를 다룹니다.
두 주제는 별개이지만, 현실의 ERP 현대화 프로젝트는 거의 항상 두 문제를 동시에 직면하므로 하나의 확장 문서로 묶었습니다.

핵심 원칙 · 1 프로젝트 = 1~소수 BC

ERP를 하나의 모노리식 프로젝트로 열어서 Claude Code로 개발하려 하면 실패합니다.
컨텍스트 윈도우, 추론 비결정성, 세션 간 일관성 문제가 규모에 비례해 누적되기 때문입니다.

erp-system/
├── erp-shared-kernel/     # 공통 VO만
├── erp-master-data/       # 기준정보 BC
├── erp-sales/             # 영업·수주 BC
├── erp-purchase/          # 구매 BC
├── erp-inventory/         # 재고 BC
├── erp-accounting/        # 회계 BC
└── erp-hr/                # 인사 BC

Wave 위상 정렬

ERP에서 BC 간 의존성은 명확합니다. 의존성 방향대로 Wave(물결)로 묶어 순차 개발합니다.
같은 Wave 내의 BC는 병렬 개발이 가능합니다.

ERP 7 BC Wave 배치 예시

Wave Gate — 전환 조건

BC 간 통신 원칙

ERP에서 가장 위험한 실수는 BC 간 직접 참조입니다.
다음 두 패턴만 허용하고, 어느 것을 쓸지는 arch-decisions.md에 명시합니다.

// sales/application/port/output/
public interface InventoryPort {
    boolean checkStock(ProductId id, int qty);
}

// inventory/adapter/outbound/
@Component
public class InventoryPortAdapter
        implements InventoryPort { ... }

// sales → OrderConfirmed → Kafka
// accounting이 order.confirmed 구독

@KafkaListener(topics = "order.confirmed")
public void onOrderConfirmed(
        OrderConfirmedMessage msg) { ... }

arch-decisions.md 선언 예시

communications:
  - from: sales
    to: inventory
    mode: sync-acl
    port: InventoryPort

  - from: sales
    to: accounting
    mode: async-event
    event: OrderConfirmed
    topic: order.confirmed

Claude Code 세션 운영 전략

Claude Code로 ERP를 개발할 때 가장 중요한 결정은 어디서 세션을 끊을 것인가입니다.
세션 누적이 품질을 결정합니다.

세션 유형별 역할 분리

실전 체크리스트

ERP 프로젝트 시작 전 반드시 확인할 사항입니다.

진단 프레임 · A/B/C/D 유형 분류

리버스 엔지니어링을 시작하기 전에 레거시 DB의 유형을 먼저 판정해야 합니다.
유형에 따라 전략이 완전히 달라지기 때문입니다.

진단 체크리스트

리버스 엔지니어링 파이프라인

A-JADM의 표준 파이프라인 앞단에 레거시 처리 단계를 추가합니다.
/reverse-schema가 /ddd-modeling보다 먼저 실행된다는 것이 핵심입니다.
기존 테이블의 물리적 경계를 무시하고 DDD부터 시작하면 나중에 매핑이 불가능해집니다.

[ Phase 0 ] 레거시 진단 — 세션 밖에서 사람이 수행
   → classification: A/B/C/D 판정

[ Phase 1 ] 스키마 추출
/reverse-schema --source postgres --conn "jdbc:..."
   → legacy-db-context.md (계약 파일)

[ Phase 2 ] UC 추출 (기존 화면/배치 기반)
/usecase --from-legacy
   → usecases/UCxxx.md

[ Phase 3 ] DDD 모델링 (레거시 참조)
/ddd-modeling --with-legacy
   → domain-context.md (legacy-db-context.md 참조)

[ Phase 4 ] 매핑 결정
/arch-design --legacy-strategy strangler
   → arch-decisions.md (매핑 전략 포함)

[ Phase 5 ] 구현 (기존 A-JADM과 동일)
/uc-to-skeleton → /implement-bc → /gen-test

legacy-db-context.md 계약 파일 구조

이것이 전략의 핵심입니다.
레거시 DB의 사실(fact)을 Claude Code가 추론 없이 참조할 수 있도록 YAML로 고정합니다.

## Meta
schema-version: 1.0
content-version: 1.0.0
extracted-at: 2026-04-16
source-db: postgres 12.4
classification: B  # A/B/C/D

## Summary
total-tables: 347
total-views: 42
total-procedures: 18
total-triggers: 9
fk-coverage: 43%  # 낮음 → B형 근거

## Tables
tables:
  - name: TB_ORDER_MST
    purpose: "수주 마스터"
    primary-key: [ORD_NO]
    candidate-aggregate-root: Order  # ddd-modeling에 힌트
    row-count: 4200000
    columns:
      - name: ORD_NO
        type: VARCHAR(20)
        nullable: false
        semantic: "YYYYMMDD + 일련번호 5자리"
      - name: CUST_CD
        type: VARCHAR(10)
        nullable: false
        implicit-fk: TB_CUSTOMER.CUST_CD  # 물리 FK 없음
        cross-bc-reference: master-data   # BC 간 참조로 변환 대상

## Implicit References
# 앱 코드에서만 존재하는 참조 관계 (grep으로 발견)
implicit-references:
  - from: TB_ORDER_DTL.ITEM_CD
    to: TB_ITEM_MST.ITEM_CD
    evidence: "src/order/OrderService.java:142"

## Stored Procedures (C/D형일 때 필수)
stored-procedures:
  - name: SP_CALCULATE_ORDER_AMOUNT
    purpose: "수주 금액 계산 (할인/세금 포함)"
    migration-strategy: keep-as-adapter  # keep-as-adapter / rewrite / delete
    risk: high  # 회계 영향

## Mapping Decisions
# 테이블 → Aggregate 매핑 초안 (사람이 확정)
mapping:
  - aggregate: Order
    root-table: TB_ORDER_MST
    child-tables: [TB_ORDER_DTL, TB_ORDER_DISC]
    bc: sales
    notes: "TB_ORDER_DLVR은 별도 Shipment Aggregate로 분리"

  - aggregate: Customer
    root-table: TB_CUSTOMER
    bc: master-data
    notes: "TB_CUST_CREDIT은 sales BC의 CreditLimit VO로 인입"

유형별 구체 전략

진단 결과 확정된 유형에 따라 완전히 다른 접근을 적용합니다.

-- 도메인 관점의 정제된 뷰
CREATE VIEW V_ORDER AS
SELECT
  ORD_NO        AS order_id,
  CUST_CD       AS customer_id,
  ORD_DT        AS order_date,
  ORD_AMT       AS total_amount,
  CASE ORD_STS
    WHEN '1' THEN 'PENDING'
    WHEN '2' THEN 'CONFIRMED'
    WHEN '9' THEN 'CANCELLED'
  END AS status
FROM TB_ORDER_MST
WHERE DEL_YN = 'N';

// application/port/output/
public interface LegacyOrderCalculator {
    OrderAmount calculate(
        OrderCalcRequest req);
}

// adapter/outbound/
@Repository
public class LegacyOrderCalculatorAdapter
        implements LegacyOrderCalculator {
    @Override
    public OrderAmount calculate(
            OrderCalcRequest req) {
        // JdbcTemplate으로 SP 호출
        // 결과 → OrderAmount VO
    }
}

# legacy-db-context.md
cdc-mapping:
  - source-table: TB_ORDER_MST
    event: LegacyOrderChanged
    topic: legacy.order.changed
    consumers: [new-sales-bc, analytics-bc]

Claude Code 세션 운영

레거시 리버스는 일반 개발보다 세션 분리가 더 중요합니다.
컨텍스트 오염이 도메인 모델의 신뢰성을 직접 해치기 때문입니다.

실무 주의점

실전에서 자주 놓치는 세 가지 포인트.

부록 · 확장 스킬 · 향후 과제

본 확장 문서는 진단 프레임과 계약 파일 스키마 초안까지 정립한 수준입니다.
아래는 실전 적용을 통해 완성해 나갈 항목입니다.

추가 커맨드 (초안)

/reverse-schema --source postgres --conn "jdbc:postgresql://..."
/reverse-schema --classify-only             # 진단만 수행
/ddd-modeling --with-legacy                 # legacy-db-context.md 참조
/arch-design --legacy-strategy strangler    # 전략 명시

향후 과제