도메인 주도 개발 (DDD) 워크플로우

개발 모드 설정 (중요)

[참고] 이 워크플로우는 .moai/config/sections/quality.yaml을 기반으로 선택됩니다:

yaml

constitution:
  development_mode: hybrid    # 또는 ddd, tdd
  hybrid_settings:
    new_features: tdd        # 새 코드 → TDD 사용
    legacy_refactoring: ddd  # 기존 코드 → DDD 사용 (이 워크플로우)

이 워크플로우를 사용하는 경우:

•development_mode: ddd → 항상 DDD 사용
•development_mode: hybrid + 기존 코드 리팩토링 → DDD 사용
•development_mode: hybrid + 새 패키지/모듈 → 대신 TDD 사용 (moai-workflow-tdd)

핵심 구분:

•새 파일/패키지 (아직 존재하지 않음) → TDD (RED-GREEN-REFACTOR)
•기존 코드 (파일이 이미 존재함) → DDD (ANALYZE-PRESERVE-IMPROVE)

빠른 참조

도메인 주도 개발은 동작 보존이 가장 중요한 기존 코드베이스 리팩토링을 위한 체계적인 접근 방식을 제공합니다. 새로운 기능을 생성하는 TDD와 달리, DDD는 동작을 변경하지 않고 구조를 개선합니다.

핵심 사이클 - ANALYZE-PRESERVE-IMPROVE:

•ANALYZE: 도메인 경계 식별, 결합 지표, AST 구조 분석
•PRESERVE: 특성화 테스트, 동작 스냅샷, 테스트 안전망 검증
•IMPROVE: 지속적인 동작 검증을 통한 점진적 구조 변경

DDD 사용 시기:

•기존 테스트가 있는 레거시 코드 리팩토링
•기능 변경 없이 코드 구조 개선
•프로덕션 시스템의 기술적 부채 감소
•API 마이그레이션 및 지원 중단 처리
•코드 현대화 프로젝트
•코드가 이미 존재하여 DDD가 적용되지 않는 경우
•초기 프로젝트 (아래 적용 사이클 참조)

DDD를 사용하지 않는 경우:

•동작 변경이 필요한 경우 (먼저 SPEC 수정)

초기 프로젝트 적용:

기존 코드가 없는 새 프로젝트의 경우, DDD는 사이클을 조정합니다:

•ANALYZE: 코드 분석 대신 요구사항 분석
•PRESERVE: 명세서 테스트를 통한 의도된 동작 정의 (테스트 우선)
•IMPROVE: 정의된 테스트를 충족하는 코드 구현

이로 인해 DDD는 TDD의 슈퍼셋이 됩니다 - TDD의 테스트 우선 접근 방식을 포함하면서 리팩토링 시나리오도 지원합니다.

핵심 철학

DDD vs TDD 비교

TDD 접근 방식 (새 기능용):

•사이클: RED-GREEN-REFACTOR
•목표: 테스트를 통해 새 기능 생성
•시작점: 코드가 존재하지 않음
•테스트 유형: 예상 동작을 정의하는 명세서 테스트
•결과: 테스트 커버리지를 갖춘 새로운 작동 코드

DDD 접근 방식 (리팩토링용):

•사이클: ANALYZE-PRESERVE-IMPROVE
•목표: 동작 변경 없이 구조 개선
•시작점: 정의된 동작을 가진 기존 코드
•테스트 유형: 현재 동작을 포착하는 특성화 테스트
•결과: 동일한 동작을 가진 더 잘 구조화된 코드

동작 보존 원칙

DDD의 황금 규칙은 리팩토링 전후의 관찰 가능한 동작이 동일해야 한다는 것입니다. 이는 다음을 의미합니다:

•모든 기존 테스트가 변경 없이 통과해야 함
•API 계약이 동일하게 유지됨
•사이드이펙트가 동일하게 유지됨
•성능 특성이 허용 범위 내에 유지됨

구현 가이드

1단계: ANALYZE

analyze 단계는 현재 코드베이스 구조를 이해하고 리팩토링 기회를 식별하는 데 집중합니다.

도메인 경계 식별

다음을 검토하여 코드베이스의 논리적 경계를 식별합니다:

•모듈 의존성 및 import 패턴
•컴포넌트 간 데이터 흐름
•공유 상태 및 결합 지점
•공개 API 표면

AST-grep을 사용하여 구조적 패턴을 분석합니다. Python에서는 import 패턴을 검색하여 모듈 의존성을 이해합니다. 클래스 계층 구조의 경우 상속 관계 및 메서드 분포를 분석합니다.

결합 및 응집 지표

코드 품질 지표를 평가합니다:

•구심 결합 (Ca): 이 모듈에 의존하는 클래스 수
•원심 결합 (Ce): 이 모듈이 의존하는 클래스 수
•불안정성 (I): Ce / (Ca + Ce) - 높을수록 덜 안정적
•추상성 (A): 추상 클래스 / 총 클래스
•주요 시퀀스로부터의 거리: |A + I - 1|

낮은 응집력과 높은 결합력은 리팩토링 후보를 나타냅니다.

구조적 분석 패턴

AST-grep을 사용하여 문제가 있는 패턴을 식별합니다:

•너무 많은 메서드나 책임을 가진 God 클래스
•다른 클래스 데이터를 과도하게 사용하는 메서드의 Feature Envy
•누락된 추상화를 나타내는 긴 파라미터 목록
•모듈 간 중복 코드 패턴

다음을 문서화하는 분석 보고서를 작성합니다:

•현재 아키텍처 개요
•심각도 등급이 있는 식별된 문제 영역
•위험 평가가 있는 제안된 리팩토링 대상
•결합 관계를 보여주는 의존성 그래프

2단계: PRESERVE

preserve 단계는 변경을 가하기 전에 안전망을 구축합니다.

특성화 테스트

특성화 테스트는 정확성에 대한 가정 없이 기존 동작을 포착합니다. 목표는 코드가 해야 하는 것이 아닌 실제로 하는 것을 문서화하는 것입니다.

특성화 테스트 생성 단계:

•1단계: 실행을 통해 핵심 코드 경로 식별
•2단계: 이 경로를 실행하는 테스트 생성
•3단계: 실제 출력을 발견하기 위해 초기에 테스트가 실패하도록 함
•4단계: 실제 출력을 기대하도록 테스트 업데이트
•5단계: 발견된 놀라운 동작 문서화

특성화 테스트 명명 규칙: test_characterize_[component]_[scenario]

동작 스냅샷

복잡한 출력의 경우, 현재 동작을 포착하기 위해 스냅샷 테스팅을 사용합니다:

•API 응답 스냅샷
•직렬화 출력 스냅샷
•상태 변환 스냅샷
•오류 메시지 스냅샷

스냅샷 파일은 리팩토링 중 동작 계약 역할을 합니다.

테스트 안전망 검증

improve 단계로 진행하기 전에 다음을 확인합니다:

•모든 기존 테스트 통과 (100% 녹색)
•새 특성화 테스트가 리팩토링 대상을 커버
•영향받는 영역에서 코드 커버리지가 임계값을 충족
•안전망에 불안정한 테스트가 없음

가능하다면 뮤테이션 테스팅을 실행하여 테스트 효과를 검증합니다.

3단계: IMPROVE

improve 단계는 지속적으로 동작 보존을 검증하면서 구조적 변경을 수행합니다.

점진적 변환 전략

한 번에 큰 변경을 하지 마세요. 이 패턴을 따르세요:

•가능한 가장 작은 구조적 변경을 수행
•전체 테스트 스위트 실행
•테스트가 실패하면 즉시 되돌리기
•테스트가 통과하면 변경사항 커밋
•리팩토링 목표를 달성할 때까지 반복

안전한 리팩토링 패턴

메서드 추출: 코드 블록의 이름을 지정하고 분리할 수 있을 때. AST-grep을 사용하여 반복되는 코드 블록이나 긴 메서드를 검색하여 후보를 식별합니다.

클래스 추출: 클래스가 여러 책임을 가질 때. 원래 API를 위임을 통해 유지하면서 관련 메서드와 필드를 새 클래스로 이동합니다.

메서드 이동: 메서드가 자신의 클래스보다 다른 클래스의 데이터를 더 많이 사용할 때. 모든 호출 사이트를 보존하면서 재배치합니다.

인라인 리팩토링: 간접 참조가 이점 없이 복잡성을 추가할 때. 위임을 직접 구현으로 교체합니다.

이름 변경 리팩토링: 이름이 현재 이해를 반영하지 않을 때. AST-grep 재작성을 사용하여 모든 참조를 원자적으로 업데이트합니다.

AST-Grep 보조 변환

안전하고 의미론적으로 인식된 변환을 위해 AST-grep을 사용합니다:

메서드 추출의 경우, 코드 패턴을 식별하고 추출된 형식으로 재작성하는 규칙을 생성합니다.

API 마이그레이션의 경우, 이전 API 호출과 일치하고 새 API 형식으로 재작성하는 규칙을 생성합니다.

지원 중단 처리의 경우, 지원 중단된 패턴을 식별하고 현대적인 대안을 제안하는 규칙을 생성합니다.

지속적 검증 루프

각 변환 후:

•단위 테스트 실행 (빠른 피드백)
•통합 테스트 실행 (동작 검증)
•특성화 테스트 실행 (스냅샷 비교)
•새로운 경고나 오류가 도입되지 않았는지 확인
•해당되는 경우 성능 벤치마크 확인

DDD 워크플로우 실행

표준 DDD 세션

DDD 모드에서 moai:2-run을 통해 DDD를 실행할 때:

1단계 - 초기 평가:

•리팩토링 범위를 위한 SPEC 문서 읽기
•영향받는 파일 및 컴포넌트 식별
•현재 테스트 커버리지 평가

2단계 - Analyze 단계 실행:

•대상 코드에 AST-grep 분석 실행
•결합 및 응집 지표 생성
•도메인 경계 맵 생성
•리팩토링 기회 문서화

3단계 - Preserve 단계 실행:

•모든 기존 테스트 통과 확인
•커버되지 않은 경로에 대한 특성화 테스트 생성
•동작 스냅샷 생성
•안전망 적절성 확인

4단계 - Improve 단계 실행:

•점진적으로 변환 실행
•각 변경 후 테스트 실행
•성공적인 변경사항 즉시 커밋
•발견된 이슈 문서화

5단계 - 검증 및 완료:

•전체 테스트 스위트 실행
•전후 지표 비교
•모든 동작 스냅샷 일치 확인
•리팩토링 보고서 생성

DDD 루프 패턴

여러 반복이 필요한 복잡한 리팩토링의 경우:

•범위에 따라 최대 루프 반복 횟수 설정
•각 루프는 하나의 리팩토링 대상에 집중
•종료 조건: 모든 대상이 처리되거나 반복 한도에 도달
•TODO 목록 업데이트를 통한 진행 추적

품질 지표

DDD 성공 기준

동작 보존 (필수):

•모든 기존 테스트 통과
•모든 특성화 테스트 통과
•API 계약 변경 없음
•성능이 범위 내에 유지됨

구조 개선 (목표):

•감소된 결합 지표
•향상된 응집 점수
•감소된 코드 복잡성
•더 나은 관심사의 분리

DDD 특화 TRUST 검증

DDD 포커스로 TRUST 5 프레임워크 적용:

•Testability: 특성화 테스트 커버리지 적절성
•Readability: 명명 및 구조 개선 확인
•Understandability: 도메인 경계 명확성
•Security: 새로운 취약점 미도입
•Transparency: 모든 변경사항 문서화 및 추적 가능

통합 지점

AST-Grep 스킬과의 통합

DDD는 다음을 위해 AST-grep에 크게 의존합니다:

•구조적 코드 분석
•패턴 식별
•안전한 코드 변환
•다중 파일 리팩토링

상세 패턴 구문 및 규칙 생성을 위해 moai-tool-ast-grep을 로드합니다.

테스팅 워크플로우와의 통합

DDD는 테스팅 워크플로우를 보완합니다:

•테스팅 패턴의 특성화 테스트 사용
•안전망 검증을 위한 뮤테이션 테스팅 통합
•스냅샷 테스팅 인프라 활용

품질 프레임워크와의 통합

DDD 출력은 품질 평가에 반영됩니다:

•전후 지표 비교
•변경사항에 대한 TRUST 5 검증
•기술적 부채 추적

문제 해결

일반적인 이슈

변환 후 테스트 실패:

•마지막으로 알려진 정상 상태로 즉시 되돌리기
•어떤 테스트가 실패했는지와 이유 분석
•변환이 의도치 않게 동작을 변경했는지 확인
•더 작은 변환 단계 고려

특성화 테스트 불안정:

•비결정론의 원인 식별
•외부 의존성 목킹
•시간 의존적 또는 순서 의존적 동작 수정
•스냅샷 허용 오차 설정 고려

성능 저하:

•전후 프로파일링
•변경사항의 영향을 받는 핫 경로 식별
•캐싱 또는 최적화 고려
•허용 가능한 트레이드오프 문서화

복구 절차

DDD 세션에서 이슈가 발생하면:

•git stash로 현재 상태 저장
•마지막 성공 커밋으로 재설정
•실패를 일으킨 변환 검토
•대안 접근 방식 계획
•보존된 상태에서 재개

Version: 1.0.0 Status: Active Last Updated: 2026-01-16