---
name: write-tech-design-doc
description: 기술설계문서(TDD, Technical Design Document)를 작성하는 스킬. 기능 개발이나 시스템 유지보수 시 아키텍처 판단 근거, 계층 분리 설계, 트랜잭션 경계, 예외·실패 처리 전략, 동시성·정합성 보장 방안, 확장 가능성까지 포함하는 실제 구현 가능 수준의 기술설계문서를 생성한다. "기술설계문서 작성해줘", "TDD 작성해줘", "기술 설계 문서", "설계 문서 만들어줘", "아키텍처 설계", "기술 스펙 작성", "상세 설계서", "technical design document" 등의 요청 시 반드시 이 스킬을 사용할 것. 새로운 기능의 상세 설계가 필요하거나, 기존 기능의 설계 의도를 문서화해달라는 요청, 설계 리뷰 자료가 필요한 경우에도 트리거한다.
argument-hint: 기술설계문서를 작성할 대상을 입력하세요 (예: "주문 취소 환불 처리 기능")
---

# 기술설계문서(TDD) 작성 스킬

기술설계문서(TDD)는 "무엇을 만든다"보다 **"왜 이렇게 설계했는가"**에 초점을 맞춘 엔지니어링 문서다.
실행 계획서가 작업 순서와 범위를 다룬다면, TDD는 아키텍처 판단의 근거, 계층 간 책임 분배, 트랜잭션 경계, 실패 시나리오 대응, 동시성 제어, 확장성 설계를 다룬다.

이 문서를 읽는 사람이 "이 코드가 왜 이렇게 생겼는지"를 이해할 수 있어야 한다.

---

## 절차 개요

전체 절차는 **10단계**로 구성되며, 반드시 순서대로 진행한다.
앞 단계의 분석 결과가 뒤 단계의 설계 결정에 영향을 주므로 순서를 건너뛰지 않는다.

```
[1단계] 인수 파싱 및 설계 대상 식별
    ↓
[2단계] 프로젝트 컨텍스트 수집 (병렬 탐색)
    ↓
[3단계] 설계 배경 및 요구사항 정의
    ↓
[4단계] 현행 시스템 분석
    ↓
[5단계] 아키텍처 설계 및 계층 분리
    ↓
[6단계] 도메인 모델링 및 데이터 설계
    ↓
[7단계] 트랜잭션 경계 및 정합성 설계
    ↓
[8단계] 예외·실패 처리 전략
    ↓
[9단계] 동시성 제어 및 성능 고려사항
    ↓
[10단계] 문서 조합 및 저장
```

---

## 1단계: 인수 파싱 및 설계 대상 식별

스킬 호출 시 전달받은 인수에서 설계 대상을 추출한다.

### 수행 작업
1. 인수 텍스트에서 **설계 대상 기능**을 파악한다
2. 설계 범위가 **신규 기능인지 기존 기능 변경인지** 판별한다
3. 인수만으로 설계 대상이 불명확하면 사용자에게 구체적으로 질문한다

### 질문이 필요한 경우
- 설계 범위가 모호: "주문 취소 중 어떤 시나리오를 다루나요? 전체 취소만인가요, 부분 취소도 포함인가요?"
- 기술적 제약이 불분명: "외부 PG사 연동이 포함되나요?"
- 비기능 요구사항 미확인: "동시 요청 처리량이나 응답 시간 제약이 있나요?"

요구사항이 충분히 명확하면 질문 없이 바로 2단계로 진행한다.

---

## 2단계: 프로젝트 컨텍스트 수집

설계의 정확성을 위해 현재 프로젝트의 구조, 규칙, 관련 코드를 파악한다.
이 단계의 탐색은 **병렬로** 수행하여 효율을 높인다.

### 수행 작업
1. **CLAUDE.md 참조**: 프로젝트 아키텍처, 모듈 구조, 네이밍 규칙, 코딩 패턴 파악
2. **DDL 탐색**: `sql/{관련 도메인}/` 디렉토리에서 기존 테이블 구조 확인 ([DDL-First 원칙](../../../docs/backend/architecture/storage/ddl-management.md))
3. **도메인 모델 탐색**: 관련 도메인의 모델, 엔티티, 서비스 코드 탐색
4. **유사 도메인 참조**: 이미 구현 완료된 유사 도메인의 패턴을 참조하여 일관성 확보
5. **기존 설계 문서 확인**: `docs/backend/design/` 디렉토리의 관련 문서 확인

### 탐색 우선순위
```
1순위: sql/{domain}/*.sql                    → DB 스키마 (DDL-First 원칙)
2순위: :core:domain → domain/.../           → 도메인 모델, ErrorCode
3순위: :core:application → application/...  → UseCase, Flow, Validator, Handler, Policy, Port
4순위: :infra:storage, :infra:external       → StorageAdapter, QueryDsl Repository, ApiClient
5순위: :app:{channel}                        → Controller, Request/Response DTO
```

---

## 3단계: 설계 배경 및 요구사항 정의

설계 문서의 독자가 "왜 이 기능을 이렇게 만들었는지" 이해할 수 있도록 배경 맥락을 명확히 서술한다.
단순 요구사항 나열이 아니라, 해당 설계가 존재하는 이유를 담아야 한다.

### 산출물 형식

```markdown
## 1. 설계 배경 및 목적

### 1.1 배경 (Background)
[이 기능이 왜 필요한지, 어떤 비즈니스 문제를 해결하는지 서술]

### 1.2 설계 목표 (Design Goals)
1. **[목표 1]**: [달성 기준과 이유]
2. **[목표 2]**: [달성 기준과 이유]

### 1.3 설계 비목표 (Non-Goals)
- [이번 설계에서 의도적으로 제외한 항목과 그 이유]

### 1.4 기술적 제약사항 (Constraints)
- **아키텍처 제약**: [헥사고날 아키텍처, CQRS 등 프로젝트 고유 제약]
- **인프라 제약**: [멀티테넌트, 분산 환경 등]
- **비기능 요구사항**: [성능, 가용성, 일관성 요구 수준]
```

### 작성 규칙
- **설계 비목표(Non-Goals)** 를 반드시 명시한다. 범위를 한정해야 설계가 비대해지지 않는다.
- 제약사항에는 프로젝트 고유 규칙(멀티테넌트 격리, ID 참조 패턴, DDL-First 등)을 포함한다.

---

## 4단계: 현행 시스템 분석

설계 대상이 영향을 미치는 현행 시스템의 구조를 분석한다.
신규 기능이더라도 연관 도메인의 현재 구조를 파악해야 일관성 있는 설계가 가능하다.

### 수행 작업

**4-1. 관련 도메인 구조 파악**
- 관련 엔티티 간의 관계를 ASCII 다이어그램으로 표현
- ID 참조 관계 명시 (JPA 연관관계가 아닌 ID 참조 기준)

```
EntityA (1) ──→ (N) EntityB     [entityAId로 참조]
EntityB ──→ EntityC             [entityCId로 참조, nullable]
```

**4-2. 현재 처리 흐름 분석**
- 요청이 처리되는 전체 흐름을 계층별로 추적
- 변경/확장이 필요한 지점 식별

```
Controller → UseCase → Service → Port → Adapter → Repository
                         ↑ 이 지점에서 분기 필요
```

**4-3. 기존 스키마 분석**
- 관련 테이블의 주요 필드를 테이블 형태로 정리
- 추가/변경이 필요한 필드 명시

---

## 5단계: 아키텍처 설계 및 계층 분리

이 단계가 TDD의 핵심이다. 각 계층이 어떤 책임을 가지며, 왜 그렇게 나눴는지를 문서화한다.

> 참조 문서
> - 계층별 책임: [domain-layer-guidelines](../../../docs/backend/architecture/domain/domain-layer-guidelines.md) · [application-layer-guidelines](../../../docs/backend/architecture/application/application-layer-guidelines.md) · [storage-layer-guidelines](../../../docs/backend/architecture/storage/storage-layer-guidelines.md) · [external-layer-guidelines](../../../docs/backend/architecture/external/external-layer-guidelines.md) · [app-layer-guidelines](../../../docs/backend/architecture/app/app-layer-guidelines.md)
> - Command/Query 분리: [use-case-convention](../../../docs/backend/architecture/application/use-case-convention.md) · [flow-convention](../../../docs/backend/architecture/application/flow-convention.md)
> - 설계 대안 분석 형식: [design/README.md](../../../docs/backend/design/README.md)

### 산출물 형식

```markdown
## 3. 아키텍처 설계

### 3.1 계층별 책임 분배

| 계층 | 구성 요소 | 책임 | 설계 근거 |
|------|----------|------|----------|
| Domain | [클래스명] | [책임] | [왜 이 계층에 배치했는지] |
| Application | [클래스명] | [책임] | [왜 이 계층에 배치했는지] |
| Infrastructure | [클래스명] | [책임] | [왜 이 계층에 배치했는지] |

### 3.2 처리 흐름 (Sequence)

[요청 → 응답까지의 전체 흐름을 단계별로 기술]

### 3.3 설계 대안 분석 (Design Alternatives)

| 대안 | 장점 | 단점 | 채택 여부 | 사유 |
|------|------|------|----------|------|
| 대안 A | ... | ... | ✅ 채택 | [근거] |
| 대안 B | ... | ... | ❌ 기각 | [근거] |
```

### 작성 규칙
- **설계 대안 분석**을 반드시 포함한다. 하나의 설계만 제시하면 "왜 이것을 선택했는지" 전달이 약하다.
  최소 2개 이상의 대안을 비교하고, 채택 사유를 명시한다.
- 처리 흐름에서 계층 경계를 넘는 지점마다 **어떤 Port/Adapter를 통해 통신하는지** 표기한다.
- Command와 Query가 분리되는 경우, 각각의 흐름을 별도로 기술한다.

---

## 6단계: 도메인 모델링 및 데이터 설계

도메인 모델의 구조, 애그리거트 경계, DB 스키마를 설계한다.

> 참조 문서
> - 도메인 모델 규칙 (Entity/VO/팩토리/불변식/Tell Don't Ask): [domain-model-convention](../../../docs/backend/architecture/domain/domain-model-convention.md)
> - 레이어 구성·애그리거트 경계·ID 참조 패턴: [domain-layer-guidelines](../../../docs/backend/architecture/domain/domain-layer-guidelines.md)
> - DDL-First 원칙·파일 위치·버전 관리: [ddl-management](../../../docs/backend/architecture/storage/ddl-management.md)

### 산출물 형식

```markdown
## 4. 도메인 모델 설계

### 4.1 애그리거트 경계

[애그리거트 단위를 정의하고, 왜 그렇게 나눴는지 근거 제시]

### 4.2 도메인 모델 상세

#### [도메인 클래스명]
- **역할**: [이 클래스가 담당하는 비즈니스 규칙]
- **불변식(Invariants)**: [항상 참이어야 하는 조건]
- **주요 행위**: [메서드와 각 메서드의 비즈니스 의미]
- **상태 전이**: [상태가 있는 경우, 허용되는 전이 경로]

### 4.3 데이터 스키마 설계

[DDL 또는 테이블 구조 정의]

### 4.4 데이터 변환 흐름

[Domain ↔ Entity ↔ DTO 간 변환 경로 명시]
```

### 작성 규칙
- 도메인 모델에는 **불변식(Invariants)**을 반드시 명시한다. 불변식은 코드의 `require` (입력값 전제조건) · `check` (상태 전제조건) · `CoreException` (비즈니스 규칙 위반) 검증 로직으로 직결된다.
- 상태를 가진 도메인은 **상태 전이 다이어그램**을 포함한다.
- 데이터 스키마는 DDL-First 원칙에 따라 SQL DDL 형태로 작성하되, JPA Entity 매핑 참고사항도 함께 기술한다.

---

## 7단계: 트랜잭션 경계 및 정합성 설계

어디에서 트랜잭션이 시작되고 끝나는지, 데이터 정합성은 어떻게 보장하는지 명시한다.
운영 환경에서 발생하는 대부분의 장애는 트랜잭션 경계 오설계에서 비롯된다.

> 참조 문서: [transaction-and-consistency](../../../docs/backend/policies/transaction-and-consistency.md)
> - 트랜잭션 경계 설정 원칙 및 판단 기준 (Service/Facade 레벨, 범위 최소화 원칙)
> - 정합성 수준 선택 기준 (강한 일관성 vs 최종 일관성 판단 매트릭스)
> - 이벤트 기반 최종 일관성 패턴 (`@TransactionalEventListener`)
> - 분산 락 적용 가이드 (`@DistributedLock`, waitTime/leaseTime 설정)

### 산출물 형식

```markdown
## 5. 트랜잭션 설계

### 5.1 트랜잭션 경계

| 연산 | 시작점 | 범위 | 격리 수준 | 사유 |
|------|--------|------|----------|------|
| [연산명] | [Service/Facade] | [포함 엔티티] | [READ_COMMITTED 등] | [왜 이 범위인지] |

### 5.2 정합성 보장 전략

[강한 일관성 vs 최종 일관성 선택 근거]

### 5.3 이벤트 처리 (해당 시)

| 이벤트 | 발행 시점 | 구독자 | 처리 방식 | 실패 대응 |
|--------|----------|--------|----------|----------|
| [이벤트명] | AFTER_COMMIT | [핸들러] | [동기/비동기] | [재시도/보상] |
```

### 작성 규칙
- 각 트랜잭션 경계에 대해 **"왜 이 범위로 잡았는지"** 사유를 반드시 기술한다.
- 여러 애그리거트를 하나의 트랜잭션에 묶는 경우, 그 타당성을 설명해야 한다.
- 이벤트 기반 비동기 처리가 있으면, **실패 시 보상 트랜잭션** 전략을 명시한다.

---

## 8단계: 예외·실패 처리 전략

예상 가능한 실패 시나리오를 나열하고, 각 시나리오별 대응 전략을 설계한다.

> 참조 문서
> - 도메인 예외 계층 구조 (`CoreException` / `ErrorCode` / `CoreErrorType` / `require` · `check` 사용 기준): [exception-convention (domain)](../../../docs/backend/architecture/domain/exception-convention.md)
> - API 예외 응답 형식·GlobalExceptionHandler: [exception-handling-convention (app)](../../../docs/backend/architecture/app/exception-handling-convention.md)

### 산출물 형식

```markdown
## 6. 예외 및 실패 처리

### 6.1 예외 분류

| 예외 유형 | ErrorCode | 발생 조건 | CoreErrorType | 사용자 메시지 |
|----------|-----------|----------|--------------|-------------|
| 비즈니스 규칙 위반 | `{Domain}ErrorCode.XXX` | [조건] | BAD_REQUEST / CONFLICT | [message 필드] |
| 엔티티 미존재 | `{Domain}ErrorCode.XXX_NOT_FOUND` | [조건] | NOT_FOUND | [message 필드] |
| 상태 전이 불가 | `{Domain}ErrorCode.XXX_ILLEGAL_TRANSITION` | [조건] | BAD_REQUEST | [message 필드] |

### 6.2 실패 시나리오 및 복구 전략

| # | 시나리오 | 발생 가능성 | 영향 범위 | 복구 전략 |
|---|---------|-----------|----------|----------|
| 1 | [시나리오] | 높음/중간/낮음 | [범위] | [전략] |

### 6.3 멱등성 보장 (해당 시)

[동일 요청 재처리 시 부작용이 없도록 보장하는 방법]
```

### 작성 규칙
- 실패 시나리오를 **최소 5개 이상** 도출한다. "정상 케이스만 고려한 설계"는 운영에서 반드시 문제가 된다.
- 외부 시스템 연동이 있으면 **타임아웃, 네트워크 장애, 응답 지연** 시나리오를 반드시 포함한다.
- 멱등성이 필요한 연산(결제, 재고 차감 등)은 보장 방법을 명시한다.

---

## 9단계: 동시성 제어 및 성능 고려사항

동시 요청 처리, 경합 조건(Race Condition) 해소, 성능 최적화 전략을 설계한다.

> 참조 문서: [concurrency-and-performance](../../../docs/backend/policies/concurrency-and-performance.md)
> - 동시성 제어 방식 선택 기준 (분산 락 / 낙관적 잠금 / 비관적 잠금 / 큐 기반 선택 플로우)
> - 분산 락 설계 (`@DistributedLock` 키 설계·waitTime/leaseTime 가이드)
> - 낙관적 잠금 패턴 (`@Version` + `@Retryable`)
> - N+1 문제 해결 패턴: [querydsl-convention](../../../docs/backend/architecture/storage/querydsl-convention.md) (단일 쿼리 + 인메모리 그룹핑 / 다단계 조합)
> - 캐싱 전략 설계 (TTL·무효화 정책·`@Cacheable`·`@CacheEvict`)
> - 확장 가능성 문서화 형식 (열린 확장 포인트 / 의도적 제약)

### 산출물 형식

```markdown
## 7. 동시성 및 성능

### 7.1 동시성 제어

| 경합 지점 | 제어 방식 | 구현 방법 | 대기 시간 | 사유 |
|----------|----------|----------|----------|------|
| [자원명] | 분산 락 / 낙관적 잠금 / DB 락 | [구현 상세] | [waitTime/leaseTime] | [왜 이 방식인지] |

### 7.2 성능 고려사항

| 항목 | 우려 사항 | 대응 전략 | 측정 기준 |
|------|----------|----------|----------|
| 쿼리 | N+1 문제 | [QueryDSL transform 패턴] | [예상 쿼리 수] |
| 캐시 | [캐시 전략] | [TTL, 무효화 정책] | [히트율 목표] |

### 7.3 확장 가능성

[향후 요구사항 변화에 대비한 확장 포인트와 제약]
```

### 작성 규칙
- 동시성 제어 방식 선택에 대해 **"왜 이 방식인지"** 근거를 반드시 기술한다.
  (예: "재고 차감은 정확성이 최우선이므로 분산 락 적용, 조회 카운터는 최종 일관성으로 충분하므로 비동기 집계")
- 확장 가능성 섹션에서는 현재 설계가 열어둔 **확장 포인트**와, 의도적으로 닫아둔 **제약**을 모두 서술한다.
- 성능 최적화는 현재 필요한 수준만 설계하되, "이 지점이 병목이 되면 이렇게 개선할 수 있다"는 가이드를 남긴다.

---

## 10단계: 문서 조합 및 저장

위 단계들의 산출물을 하나의 마크다운 문서로 조합하여 저장한다.

### 최종 문서 구조

```markdown
# [기능명] 기술설계문서 (TDD)

> 작성일: YYYY-MM-DD
> 상태: Draft | Reviewing | Approved | Superseded
> 대상 모듈: :app:{channel}, :core:application, :core:domain, :infra:storage 등

## 1. 설계 배경 및 목적
### 1.1 배경
### 1.2 설계 목표
### 1.3 설계 비목표
### 1.4 기술적 제약사항

---

## 2. 현행 시스템 분석
### 2.1 관련 도메인 구조
### 2.2 현재 처리 흐름
### 2.3 현행 스키마 분석

---

## 3. 아키텍처 설계
### 3.1 계층별 책임 분배
### 3.2 처리 흐름 (Command)
### 3.3 처리 흐름 (Query) [해당 시]
### 3.4 설계 대안 분석

---

## 4. 도메인 모델 설계
### 4.1 애그리거트 경계
### 4.2 도메인 모델 상세
### 4.3 데이터 스키마 설계 (DDL)
### 4.4 데이터 변환 흐름

---

## 5. 트랜잭션 설계
### 5.1 트랜잭션 경계
### 5.2 정합성 보장 전략
### 5.3 이벤트 처리 [해당 시]

---

## 6. 예외 및 실패 처리
### 6.1 예외 분류
### 6.2 실패 시나리오 및 복구 전략
### 6.3 멱등성 보장 [해당 시]

---

## 7. 동시성 및 성능
### 7.1 동시성 제어
### 7.2 성능 고려사항
### 7.3 확장 가능성

---

## 8. 변경 파일 목록

| # | 파일 | 모듈 | 변경 유형 | 설명 |
|---|------|------|----------|------|

---

## 9. 검증 계획

| 시나리오 | 유형 | 검증 내용 | 예상 결과 |
|----------|------|----------|----------|
```

### 파일 저장 규칙
- **저장 위치**: `docs/backend/design/` ([design/README.md](../../../docs/backend/design/README.md) 참조)
- **파일명**: `tdd-{feature-slug}.md` (영문 kebab-case)
  - 예: `tdd-product-wishlist.md`
  - 예: `tdd-payment-settlement.md`
- 파일명의 feature-slug는 설계 대상의 핵심을 2~4단어로 축약한다
- 단일 CRUD·단순 UseCase 추가는 작성하지 않는다. 빈 섹션은 두지 않고 해당 없는 섹션은 생략한다.

### 문서 작성 원칙
- 모든 내용은 **한국어**로 작성한다
- 코드 예시, 파일 경로, SQL, 클래스명은 원문 그대로 유지한다
- 각 섹션에서 **"왜"**를 반드시 포함한다. 설계 결정이 있으면 그 근거를 적는다.
- ASCII 다이어그램 적극 활용 (관계, 흐름, 상태 전이)
- 문서 저장 완료 후 사용자에게 파일 경로와 문서 요약을 안내한다