oh-my-oop 0.2.0

package/lessons/woowacourse-kotlin-blackjack/s9hn/10-1/353/213/250/352/263/204-/353/270/224/353/236/231/354/236/255.md

@@ -0,0 +1,284 @@
+# PR #10 — [블랙잭 1단계] 산군 미션
+
+- **Reviewee:** [@s9hn](https://github.com/s9hn)
+- **PR:** https://github.com/woowacourse/kotlin-blackjack/pull/10
+- **단계:** 1단계 (페어)
+- **리뷰어:** @malibinYun (말리빈)
+- **라인 코멘트:** 30 (리뷰어 17 / 리뷰이 13)
+
+## 잘한 점 (설계 관점)
+
+- **View 세분화 — `LoginView`/`PlayGameView`/`GameResultView`** (LoginView 명명은 못한 점 §11에서 토론).
+- **`abstract class Player` + `Dealer`/`User` 상속** + 후속에 *팩토리 함수*로 생성 통일.
+- **`Referee` 객체 분리 시도 + 학생 자가 토론** (못한 점 §10).
+- **`Card private constructor + Card.valueOf(card)` 팩토리 + 익명 객체로 재사용 (후속 반영)** — Flyweight 패턴.
+- **`Deck` 일급 컬렉션 도입 (후속)** + 빈 덱 검증 `require()`.
+- **후속 반영 — `getCardPair → getCard(count)` 단일 메서드 + `Dealer.create()` 팩토리 + `Hand` 일급 컬렉션 + 딜러 블랙잭 룰 (16 이하라도 자기 블랙잭이면 무조건 우승)**.
+
+## 못한 점 (설계 관점)
+
+### 1. `Answer("y"/"n")` 도메인 객체 — UI 입력 형식 보유
+
+```kotlin
+class Answer(val value: String) {
+    init { require((value == YES) or (value == NO)) { ERROR_ANSWER_FORMAT } }
+    companion object { const val YES = "y"; const val NO = "n" }
+}
+```
+
+리뷰어: "Answer를 *domain에 분류*해주셨는데요, *해당 항목들은 View의 요소*네요 :) *도메인과 뷰를 꼭 분리*해주세요!" — *Y/N 입력 형식*은 UI. *enum Answer { YES, NO }* + InputView에서 매핑. PR #29·#63·#125·#128·#116과 같은 결.
+
+### 2. `Card.Value` enum — *Value*라는 만능 명사
+
+```kotlin
+class Card(val shape: Shape, val value: Value) {
+    enum class Value(val number: Int, val cardSign: String) { ... }
+}
+```
+
+리뷰어: "*Value라는 이름은 너무 범용적*입니다. *그 무엇도 Value라고 칭할 수 있어 보여요* :) *더 구체적인 이름*을 지어볼까요?" — `Value` / `Information` / `Manager` / `Rule` 만능 명사 패턴. `Rank` / `CardNumber` 같은 *도메인 어휘*. PR #92 `Information` 변형.
+
+### 3. `Card.Shape.pattern` / `Card.Value.cardSign` UI 표현
+
+```kotlin
+enum class Shape(val pattern: String) {
+    HEARTS("하트"), DIAMONDS("다이아몬드"), CLUBS("클로버"), SPADES("스페이드"),
+}
+enum class Value(val number: Int, val cardSign: String) { ... }
+```
+
+리뷰어가 직접 지적은 안 했지만 PR 흐름상 *Answer UI 분리* 권고와 동일 결. **enum UI value 9개 PR 연속**.
+
+### 4. `CardMachine` 객체 — Generator/Picker/Deck의 또 다른 변형
+
+```kotlin
+class CardMachine {
+    private val cards: MutableList<Card> = mutableListOf()
+    init { addCards(); cards.shuffle() }
+    fun getNewCard() = cards.removeFirst()
+    fun getCardPair(): List<Card> { ... }
+    fun getCardPairs(count: Int): List<List<Card>> { ... }
+}
+```
+
+리뷰어: "*이후 3장, 4장, 5장을 뽑는 규칙들이 생겨난다면, 메서드의 양이 너무 많아질 것이 우려*돼요. `getCards(count)` 등으로 카드를 뽑아보는 것은 어떨까요?" / "*count를 받아 List를 반환하는데 메서드명이 단수 형태인 건 조금 어색*해보이네요." / "*CardMachine의 랜덤에 대한 요소를 포함한 기능의 테스트를 작성할 수 있을까요?* 로또와 자동차 경주 미션을 잘 되새겨보면서, *개발자가 제어할 수 있는 환경으로 변경*해보세요"
+
+→ **`CardMachine`이라는 명사 자체 = 또 다른 만능 어휘**. `Deck`이 도메인 어휘로 자연. 학생 후속: `getCard(count): List<Card>` 단일 메서드 + `Deck` 클래스 도입.
+
+### 5. `Dealer(name, cards: MutableList<Card>)` — 방어적 복사 누락 + 외부 참조 누수
+
+```kotlin
+class Dealer(name: String = DEALER_NAME, cards: MutableList<Card>) : Player(name, cards) { ... }
+```
+
+리뷰어: "*방어적 복사의 의미가 없을 수도 있겠어요* :) 아래 코드 같이 실행한다면 어떤 일이 벌어질 수 있을까요? ```val mutableList = mutableListOf(1, 2, 3); Dealer("", mutableList); mutableList.clear()```" — PR #79·#65·#24·#28과 동일 *외부 참조 누수* 패턴. 학생 후속: `private constructor` + 팩토리에서 `toMutableList()` 복사.
+
+### 6. `Player.cards: List<Card> get() = _cards.toList()` — 방어적 복사 + 일급 컬렉션 미도입
+
+```kotlin
+abstract class Player(
+    val name: String,
+    private val _cards: MutableList<Card>,
+) {
+    val cards: List<Card> get() = _cards.toList()
+    ...
+}
+```
+
+리뷰어: "*카드들을 일급 컬렉션으로 구현*해보세요 :)" — `Hand` 또는 `Cards` 일급 컬렉션. *방어적 복사 + 일급 컬렉션*은 별개 개념. *일급 컬렉션은 비즈니스 동작 보유 + 변경 제어*. 학생 후속: `Hand` 도입.
+
+### 7. `Player.validPlayerSum()` 함수명 — *검증인지 합산인지 모호*
+
+```kotlin
+fun validPlayerSum(): Int {
+    if ((calculateCardValueSum() < ACE_CARD_PLUS_TEN) and (countAce() != NO_ACE)) {
+        return calculateCardValueSum() + ACE_CARD_PLUS_TEN
+    }
+    return calculateCardValueSum()
+}
+```
+
+리뷰어: "메서드명만 보면, *player 합계가 valid 한지 검증만 수행하는 메서드*로 보여요. *더 구체적인 이름*을 지어주어 볼까요? 🙂" — `valid*` 접두사는 *검증 동작* 연상. 실제는 *Ace 보정 적용 후 점수*. `scoreWithAceAdjusted()` 또는 `totalScore()` 같은 *결과 동사*.
+
+### 8. `Player.countAce()` — *몇 장 셀까* vs *있는지만*
+
+```kotlin
+private fun countAce(): Int = _cards.filter { it.value == Card.Value.ACE }.size
+fun validPlayerSum(): Int {
+    if (... and (countAce() != NO_ACE)) { return ... + ACE_CARD_PLUS_TEN }
+    ...
+}
+```
+
+리뷰어: "*정말 ACE가 몇 장인지 세는 것이 중요한 기능일 지 고민*해보세요 :)" — *Ace를 11점으로 한 번만 보정*하면 *몇 장인지 셀 필요 없음*. *있는지(Boolean)*만 검사. PR #79 (ii2001) 리뷰어 권고와 동일 (*Ace 두 장 = +20은 항상 Bust*).
+
+또: 리뷰어 권고 "`count{}` 확장 함수를 활용해보세요" — `_cards.count { it.value == Card.Value.ACE }`로 단순화.
+
+### 9. `Referee(dealerScore: Int, userScore: List<Int>)` — Int 비교 + 정적 객체
+
+```kotlin
+class Referee(private val dealerScore: Int, private val userScore: List<Int>) {
+    fun getResult(): List<GameResult> = userScore.map { score ->
+        when {
+            score > BUST -> GameResult.LOSE
+            dealerScore > BUST -> GameResult.WIN
+            ...
+        }
+    }
+}
+```
+
+리뷰어: "*심판 객체는 정말 필요한 객체일까요?* *객체 간에 메시지를 던지면서 게임 결과를 반환하게 변경*해보는 것은 어떨까요?" / "*블랙잭을 플레이하는 현실 세계를 반영*해보세요 :) *결과를 만들어내는 책임은 누구에게 있을까요?* 딜러와 유저를 *상속관계로 구현하셨으니, 둘 다 Player라는 점을 잊지 말아요* 🙂"
+
+학생 자가 토론: "*Referee가 필요없다면, 점수비교 계산을 해주는 로직을 누가 수행해주어야 할까?* 현재 로직상(제 생각에) Dealer 혹은 User 클래스가 *계산에 대한 작업을 해주어야할 것 같다*. User(<-> Dealer) 내부에서 딜러의 점수와 비교하는 로직을 수행한다. - *유저(혹은 딜러)는 어떻게 상대의 점수를 알 수 있는가?* - *외부로부터 주입받는다 -> 이럴거면 Referee가 낫지않나..?* 라는 의식의 흐름으로,, 도착했으나, *답을 내리지 못하겠어서 여쭤봅니다*..."
+
+→ **학생이 자가 토론으로 핵심 의문 도달**. *상대 점수를 모르는데 어떻게 비교하는가*. 정답: `player.match(other: Player): GameResult` — *상대 객체를 인자로* 받음. *상대 객체 자체*가 상대의 점수를 알게 함. PR #28·#63·#125·#29·#24·#116과 같은 결. **Referee 객체 = 정적 비교자**는 이 자가 토론을 해결하지 못함.
+
+### 10. `Card.valueOf(card: Card): Card.Value` 정적 메서드 — *카드의 점수를 외부에서 변환*
+
+```kotlin
+companion object {
+    fun valueOf(card: Card): Card.Value = card.value
+}
+
+// Player에서
+fun calculateCardValueSum(): Int = _cards.sumOf { Card.valueOf(it) }   // ⚠ Card.valueOf(it).number 누락?
+```
+
+`Card.valueOf(card)`는 *그냥 `card.value` 접근의 wrapper*. *정적 메서드*가 *getter 역할만*. 의미 없는 우회.
+
+### 11. `LoginView` 명명
+
+리뷰어: "View에 각기 역할을 분리한 점이 인상 깊네요 🙂 *View를 상세하게 나누다보니, 작명이 어려웠을 것만 같네요* 😂 *LoginView라는 이름은 조금 헷갈릴 여지가 있어보여요*" — *Login*은 인증 시나리오 어휘. 게임에서는 *이름 입력*. `IntroView` / `GameIntroView` / `PlayerNameInputView` 등 *도메인 어휘 활용*. 학생 후속: `GameIntroView`.
+
+### 12. `Deck.addCard(card: List<Card>)` — *모든 카드 vs 첫 카드만* 불일치
+
+```kotlin
+fun addCard(card: List<Card>) {
+    _cards.add(card.first())     // ⚠ 인자는 List인데 first()만 사용
+}
+```
+
+리뷰어: "*메서드명으로만 보면, 파라미터로 전달받은 모든 카드 List를 덱에 추가할 것이 기대*되는데, *실제로 하는 일은 가장 첫 번째 장만 추가*하네요. *다른 개발자들도 한 번에 예측 가능한 동작*일까요?" — 함수명 vs 동작 불일치. *cards: List* 받으면 `addAll`이 자연. `card: Card` 단수면 `add`. **메서드 시그니처가 호출 의도를 거짓말**.
+
+### 13. `Deck.require(_cards.size != EMPTY)` — `isNotEmpty()` 활용 미흡
+
+```kotlin
+init { require(_cards.size != EMPTY) { ERROR_EMPTY_DECK } }
+```
+
+리뷰어: "*List 내부의 비어 있음을 알리는 함수*를 활용해보세요 :)" — `_cards.isNotEmpty()`가 *의도 명확*. *size != EMPTY (= 0)*보다 *조건 자체가 검증의 의미*.
+
+### 14. `CardMachineTest`가 *size만 검증*
+
+```kotlin
+@Test fun `3명일 경우, 카드 세 쌍을 뽑는다`() {
+    val cardMachine = CardMachine()
+    val actual = cardMachine.getCardPairs(3)
+    assertThat(actual).hasSize(3)
+}
+```
+
+리뷰어: "*카드를 뽑는 테스트에서, 사이즈만 검증하는 것은 큰 의미를 가져오기 어려워요* :) *개발자가 제어할 수 있는 환경을 만들어서, 카드를 뽑았으니, 실제 들어있는 카드를 예측할 수 있어야 테스트에 의미를 부여*할 수 있습니다 🙂"
+
+학생 자가 의문: "1) *shuffle된 카드를 뽑는 테스트인데.. 어떻게 실제카드를 예측할 수 있는지..?* 2) *카드머신은 카드를 생성하고, 섞어주고, 뽑아주는 역할*을 수행하며, getCard는 카드를 뽑아줍니다. *getCard를 테스트하려는 목적은, 정해진 count만큼 카드가 잘 뽑히는 지를 테스트*하는 데, *실제 들어있는 카드를 왜 예측해야하는지 잘 이해가 가지 않습니다*😢"
+
+→ 리뷰어 의도는 **외부 비결정성 분리** (lotto/racingcar의 `non-newable` 패턴). *셔플 알고리즘 자체*는 stdlib 책임이고 *셔플 후 결정적 순서를 주입*하면 *카드 X가 첫 번째라면 draw 결과는 X*. 학생이 *외부 비결정성 분리 개념*을 *아직 미발견*. (PR #65·#114·#28과 같은 결.)
+
+### 15. `Controller`가 *Dealer 카드 + User 카드 zip*
+
+```kotlin
+private fun initUsers(userNames: List<String>, userCards: List<List<Card>>): List<User> {
+    val userNamesAndCards = userNames.zip(userCards)
+    return userNamesAndCards.map { userNameAndCard -> User.create(userNameAndCard) }
+}
+```
+
+리뷰어: "*이름과 카드들을 따로 받아서 Pair로 처리하기 보다, 메서드 체이닝으로 이름부터, 카드가져와서 유저를 만들어내는 방법*을 고민해보아요 🙂" — `userNames.map { name -> User.create(name, deck.draw(2)) }` 같은 *체이닝*이 *zip + Pair 변형*보다 자연. *데이터 변환의 단계*가 *코드 가독성*에 영향.
+
+### 16. `Controller`가 *블랙잭 룰 직접 분기* — 딜러 16 이하 + 블랙잭 21점 검사 누락
+
+리뷰어가 *실제 6장 카드로 시뮬레이션* 후 버그 발견: "임의로 코드를 조작해서, *6장의 카드로만 구성된 게임에서 모두가 블랙잭을 갖게 실행*해보았는데요, *딜러의 점수가 16이하인 경우*가 나옵니다. 딜러가 블랙잭인 경우, *플레이어가 블랙잭이 아니면 모두 패배*하는 룰이 있는데요, *블랙잭에 대한 도메인을 더 파악하시고 게임을 구현*해보시면 좋겠어요 :)"
+
+→ **리뷰어가 시뮬레이션으로 룰 누락 발견**. 학생: "딜러가 *A+ J/Q/K일 때, 블랙잭으로 무조건 우승할 수 있도록 리팩토링*하였습니다!" — *블랙잭 룰의 핵심 분기*(딜러 블랙잭 시 16 이하라도 추가 뽑기 안 함). PR #128·#116 *블랙잭 룰 오해*와 같은 결.
+
+### 17. `dealerPickNewCardIfNeed`의 *깊은 if 중첩*
+
+```kotlin
+private fun dealerPickNewCardIfNeed(dealer: Dealer) {
+    if (!dealer.isOverSumCondition()) {
+        if (dealer.addScoreTenIfHasAce() != 21) {
+            playGameView.printDealerPickNewCard()
+            val newCard = cardMachine.getCard(1)
+            dealer.addCard(newCard)
+        }
+    }
+}
+```
+
+*if 중첩 + 매직넘버 21*. `if (!dealer.isOverSumCondition() && !dealer.isBlackjack())` 단일 조건이 자연. *Bust 또는 BlackJack이면 더 안 뽑는다*가 *도메인 룰의 표현*.
+
+### 18. 메서드 리턴 타입 명시 토론
+
+```kotlin
+class CardMachine {
+    fun getNewCard() = cards.removeFirst()    // ⚠ 리턴 타입 추론
+}
+```
+
+리뷰어: "*멤버변수와 메서드의 리턴타입은 모두 명시*해주는 것은 어떨까요? *명시해주는 것과 그렇지 않은 것은 어떤 차이점이 생길까요?* 먼저 고민해보시고, 아래 Effective Kotlin 서적의 챕터를 참고해서 스스로 생각해본 것과 비교해보아요 😀 - *Item 4 : Inferred Type으로 리턴하지 말라* - *Item 14 : 변수 타입이 명확하지 않은 경우 확실하게 지정하라*" — **공개 API의 리턴 타입은 명시 권장**. *Inferred*는 *구현 변경 시 시그니처가 의도치 않게 변경*. PR #135 (ijh1298)의 *모든 변수 타입 명시* 과잉과는 반대 방향 — *공개 API는 명시, 지역 변수는 추론*이 균형.
+
+## 리뷰어 의견 요지
+
+- ***`Answer("y"/"n")` 도메인 = UI 형식 누수***.
+- ***`Value`/`CardMachine` = 만능 명사*** — `Rank`/`Deck` 같은 도메인 어휘.
+- ***`Card 한 번 생성 후 재활용*** = Flyweight (학생 후속 반영).
+- ***Generator/Picker/Machine 패턴 폭증*** — `Deck`이 도메인 어휘.
+- ***외부 참조 누수 = 방어적 복사 또는 toMutableList()***.
+- ***일급 컬렉션 vs 방어적 복사는 별개*** — 일급은 비즈니스 동작 보유.
+- ***`validPlayerSum` 같은 모호 동사*** — *결과 동사*.
+- ***Ace 몇 장 카운트 X*** — *있는지(Boolean)*만 + 한 번 보정.
+- ***Referee 정적 비교자 = 자율성 부재*** — `player.match(other)` 메시지.
+- ***`LoginView` = 비도메인 어휘***.
+- ***`addCard(List<Card>)`에서 first()만 = 시그니처 거짓말***.
+- ***`isNotEmpty()` 활용***.
+- ***테스트가 size만 검증 = 외부 비결정성 미분리***.
+- ***zip + Pair < 메서드 체이닝*** (가독성).
+- ***딜러 블랙잭 시 16 이하라도 추가 뽑기 안 함*** — 블랙잭 룰 핵심.
+- ***공개 API 리턴 타입 명시***.
+
+## 대표 인용
+
+> Answer를 *domain에 분류*해주셨는데요, *해당 항목들은 View의 요소*네요 :)
+> — @malibinYun on `Answer.kt`
+
+> *심판 객체는 정말 필요한 객체일까요?* *객체 간에 메시지를 던지면서 게임 결과를 반환하게 변경*해보는 것은 어떨까요?
+> — @malibinYun on `Referee.kt`
+
+> *카드들을 일급 컬렉션으로 구현*해보세요 :)
+> — @malibinYun on `Player.kt`
+
+> 임의로 코드를 조작해서, *6장의 카드로만 구성된 게임에서 모두가 블랙잭을 갖게 실행*해보았는데요, *딜러의 점수가 16이하인 경우*가 나옵니다. *딜러가 블랙잭인 경우, 플레이어가 블랙잭이 아니면 모두 패배하는 룰*이 있는데요, *블랙잭에 대한 도메인을 더 파악*하시고 게임을 구현해보시면 좋겠어요 :)
+> — @malibinYun on `Controller.kt` (시뮬레이션으로 룰 누락 발견)
+
+> 카드를 뽑는 테스트에서, *사이즈만 검증하는 것은 큰 의미를 가져오기 어려워요* :) *개발자가 제어할 수 있는 환경*을 만들어서, 카드를 뽑았으니, *실제 들어있는 카드를 예측할 수 있어야 테스트에 의미*를 부여할 수 있습니다 🙂
+> — @malibinYun on `CardMachineTest.kt`
+
+## 얻은 교훈
+
+- ***`Answer("y"/"n")` 도메인은 UI 입력 형식 누수*** — 9개+ PR 연속 등장하는 *UI 형식 도메인 보유* 안티패턴.
+- ***`Value`/`CardMachine` 같은 만능 명사*** — `Rank`/`Deck` 도메인 어휘로. PR #92 `Information`·#29 `Rule`·#65 `Judge`와 같은 결.
+- ***Card Flyweight 캐싱*** — 52장 + 익명 객체로 재사용. PR #112·#128·#135와 일관.
+- ***Generator/Picker/Machine 패턴 폭증 = 도메인 어휘 흐림*** — `Deck` 단일 명사가 자연. PR #29·#24·#65와 같은 결.
+- ***`Dealer(name, cards: MutableList<Card>)` = 외부 참조 누수*** — `toMutableList()` 또는 *생성자에 List<Card>* + 내부 변환. PR #79·#65·#24·#28 재출현.
+- ***일급 컬렉션 ≠ 방어적 복사*** — *일급 컬렉션은 비즈니스 동작 보유*가 본질. *방어적 복사*는 *외부 변경 차단* 별개.
+- ***`validPlayerSum` 같은 *검증 vs 합산 모호 동사*** — *결과 동사*가 정확. `scoreWithAceAdjusted()` / `totalScore()`.
+- ***Ace 한 번만 보정 + 있는지(Boolean) 검사*** — *Ace 두 장 = +20은 항상 Bust*. PR #79 권고와 일관.
+- ***`Referee` 정적 비교자 = 자율성 부재*** — `player.match(other: Player): GameResult` 메시지. 학생이 *상대 점수를 어떻게 아는가* 자가 토론으로 *핵심 의문 도달*.
+- ***`LoginView` = 비도메인 어휘*** — 게임 컨텍스트에 *Login*은 어색. `GameIntroView` 같은 *도메인 어휘 활용*.
+- ***`addCard(List<Card>)`에서 `first()`만 = 메서드 시그니처가 거짓말*** — 함수명/시그니처/동작 *3자 일치* 원칙.
+- ***`isNotEmpty()` 활용*** — *size != 0*보다 *의도 자체*가 함수에.
+- ***테스트가 size만 검증 = 외부 비결정성 미분리 신호*** — 결정적 fake/주입으로 *카드 자체 검증*. 학생 자가 *왜 예측해야 하는지* 의문 = *외부 비결정성 분리 개념 미발견*.
+- ***zip + Pair < 메서드 체이닝*** — *데이터 변환 단계 가시화*가 가독성.
+- ***딜러 블랙잭 시 16 이하라도 추가 뽑기 X*** — *블랙잭 룰 핵심*. 리뷰어의 *시뮬레이션*으로 *룰 누락 발견*. PR #128·#116·#92와 같은 *블랙잭 룰 오해* 패턴.
+- ***공개 API는 리턴 타입 명시 + 지역 변수는 추론*** — Effective Kotlin Item 4/14. PR #135 *모든 변수 명시 과잉*과 균형 잡힌 입장.

package/lessons/woowacourse-kotlin-blackjack/sh1mj1/75-1/353/213/250/352/263/204-/353/270/224/353/236/231/354/236/255.md

@@ -0,0 +1,224 @@
+# PR #75 — [블랙잭 1단계] 심지 미션
+
+- **Reviewee:** [@sh1mj1](https://github.com/sh1mj1)
+- **PR:** https://github.com/woowacourse/kotlin-blackjack/pull/75
+- **단계:** 1단계
+- **리뷰어:** @vagabond95 — **이전 racingcar 분석에서 직접 인용된 reviewer (CLAUDE.md 의 `vagueName` 룰 인용 출처). 본 blackjack 미션에 직접 등장!**
+- **라인 코멘트:** 28 스레드 / 학생 자가 토론 매우 풍부 — *State 패턴 자가 학습 + 디자인 패턴 = 요리법 비유*
+
+## 잘한 점 (설계 관점)
+
+- **State 패턴 자가 학습 + 코드 적용 시도** — 학생 자가 학습 인용: *"제리가 이렇게 말씀해주셨지만, 제가 우테코 수업에서 상태 패턴을 배우기 전에 직접 공부하고 코드로 구현을 해보고 싶은 욕심을 느껴서 열심히 적용해보았습니다.."*. **첫 시도 + 시행착오 + 자가 분석 모범**. `sealed interface CardHandState + Running (Start/Decide/Hit) + Done (Bust/BlackJack/Stay)` 계층 시도. PR #136·#152·#93·#147 와 같은 결.
+- **`Decide` 중간 상태 자가 도출** — *블랙잭/Bust 결과 상태 + Hit/Stay 진행 상태 + `Decide` (Hit/Stay 결정 전) 중간 상태*. *vagabond95 진단 "BLACKJACK, BURST 는 결과를 나타내는 상태이고 STAY, HIT 은 진행과정을 나타내는 상태이므로 이것들이 같은 enum 으로 묶이는 것이 적절하지 고민해보면 좋겠습니다"* 후속 반영. **상태 분류 자가 학습 모범**.
+- **블로그 글 + 자가 학습 자료 인용** — 학생 자가 인용: *"과거에 sealed class 를 공부하기 위해 코틀린 인 액션과 이펙티브 코틀린을 보면서 상태 패턴을 공부했었습니다.(https://sh1mj1-log.tistory.com/199)"* + *"자동차 경주 미션을 진행하면서 디자인 패턴은 객체지향적으로 사고하고, 설계하면서 발견해내고 공부하는 것이라고 느꼈습니다. (https://sh1mj1-log.tistory.com/228)"*. **외부 자료 + 자가 정리 블로그 모범**.
+- **`runPhase(condition: () -> Boolean)` 람다 추상화 시도** — Player (입력 의지) / Dealer (점수 16 이하) 두 조건 통일을 위한 람다 인자. vagabond95 평가: *"우선 현 코드에서 가독성은 괜찮다고 생각합니다 👍 ... 이 부분은 2가지 관점으로 생각할 수 있을 것 같습니다. 1. 추상클래스의 하위 타입의 요구사항에 의해 상위 타입의 API 가 변경되었다. -> 추상 클래스의 역할을 잘못 정의했다는 신호일 수 있습니다. 2. 구현의 범용성을 고려하여 API 를 구현하였다. -> 하위 타입의 구현을 알지 못하는 상황에서 범용성을 위한 선택이므로 적절한 선택이라고 할 수 있습니다. 심지의 경우 1번의 케이스를 고민하다가 2번의 경우에 해당하게 된 것 같아 보입니다."*. **추상화 정당화 양방향 인식 모범**.
+- **`PlayerWinning + DealerWinning` 분리 vs 통합 자가 토론** — 학생 자가 답변 깊음: *"하지만 Dealer 의 승/패/무승부 는 오직, Player 의 승/패/무승부 여부만을 가지고 알아낼 수 있는데도 불구하고, ScoreBoard 에서 딜러의 승/패/무승부 를 결정하도록 하는 것은 객체 지향 프로그래밍의 도구인 추상 클래스를 사용하기 위해서, **어떠한 책임을 위한 정보보다 훨씬 더 많은 정보를 가진 클래스가 책임을 가지게 되는 것은 아닐까요?**"*. vagabond95: *"모든 구현은 trade-off 요소가 있습니다. 얻는게 있으면 거의 반드시 희생해야하는 부분이 생기게 됩니다."*. **트레이드오프 양방향 인식 모범**.
+- **`Done.draw = throw` vs API 사용자 책임** — vagabond95 답변: *"API 를 잘 설계했다면, 잘못사용했을 시 발생하는 예외는 API 사용자가 감수하는 것이므로 더 신경쓰지 않으셔도 될 것 같습니다. 실제로 많은 Android / kotlin 내부 라이브러리에서 이렇게 예외를 던지는 구현을 통해 접근을 막는 방식을 택하고 있습니다."* — 학생 자가 학습. PR #152·#147 의 *throw vs self return* 트레이드오프 와 같은 결.
+
+## 못한 점 (설계 관점)
+
+### 1. `runPhase` 메서드명 — *과도하게 모호 (vagabond95 진단 핵심)*
+
+```kotlin
+abstract class Role {
+    abstract fun runPhase(condition: () -> Boolean): Boolean
+}
+```
+
+vagabond95: *"함수 이름이 너무 모호합니다. 무엇을 run 하는 것이고 phase 는 무엇일까요? 어떤 내용이 해당 함수에 들어가도 크게 이상하지 않고, 다시 말하면 해당 함수는 수많은 역할을 가질 수 있다는 것을 의미합니다. 전반적으로 phase 라는 네이밍이 많은데, 좀 더 구체적으로 이름을 지어주어야 할 것 같습니다."*
+
+학생 자가 답변: *"저는 카드 게임에서 phase 를 진행한다는 것이 꽤나 일반적이고 직관적으로 읽힌다고 생각했습니다. 제 기억에는 어렸을 때 봤던 만화에서 phase 를 자주 사용했던 것 같았습니다."*
+
+vagabond95 후속 (네이밍 기준 정리): *"1. 모호한 의미를 가지는 이름을 지양하자. 질문 주셨던 runPhase 를 예로 들어보면, 프로그래밍 특성상 거의 대부분의 함수는 run 이라는 동사를 사용했을 때 어색하지 않습니다. 이것은 바꿔말하면 해당 함수에 어떤 내용이 들어가도 어색하지 않다는 것을 의미합니다. 객체 지향 프로그래밍의 5대 원리라고 불리는 SOLID 에서 SRP 가 제대로 지켜지지 않는 것이죠. ㅎㅎ (비슷한 사례로 executeXXX, doXXX 등이 있습니다.) 2. 많은 코드를 보고, 네이밍을 짓는 다양한 사례를 익히자. ... 3. 도메인에 대한 이해도"*
+
+→ **`runXX` / `executeXX` / `doXX` 만능 동사 안티패턴**. *SRP 위반 신호*. *vagueName 안티패턴 변형*. **MCP 룰 후보 — `vagueVerb`** (vagueName + 만능 동사). PR #125·#114·#10·#88 와 같은 결.
+
+### 2. `CardHandState enum` 의 *결과 + 진행 상태 혼재*
+
+vagabond95: *"BLACKJACK, BURST 는 결과를 나타내는 상태이고 STAY, HIT 은 진행과정을 나타내는 상태이므로 이것들이 같은 enum 으로 묶이는 것이 적절하지 고민해보면 좋겠습니다"*
+
+→ **결과 상태 vs 진행 상태 분리 부재**. *학생 자가 후속 반영 = sealed interface Running (Hit/Stay/Decide) + Done (Bust/BlackJack/Stay)*. PR #136·#147·#152 와 같은 결의 *State 분류*.
+
+### 3. `output / shape` enum 멤버 = View 의존
+
+vagabond95 다중 진단 (CardNumber/CardShape/WinningResultStatus): *"output 은 view 에서 활용되는 값으로 model 에서 알 필요가 없는 부분으로 보입니다!"* / *"shape 는 view 에서 활용되는 값으로 model 에서 알 필요가 없는 부분으로 보입니다!"*
+
+→ **enum 의 UI value 안티패턴**. PR #124·#28·#78·#112·#125·#128·#135·#137 와 같은 결 (메이저 안티패턴).
+
+### 4. `BLACK_JACK = 21` 상수 다중 선언
+
+vagabond95: *"너무 많은 곳에서 BLACK_JACK 이라는 상수에 대한 선언이 있습니다. 상수를 선언하는 것은 단순히 하드코딩을 막는 것외에 전역에서 변경되지 않는 상태를 일관되게 참조하는 것에 큰 의의가 있는데요, 이렇게 여러 군데에 선언하여 관리할 경우 일관되게 상태를 관리하는 것이 어려워지게 됩니다."*
+
+→ **상수 다중 선언 = 일관성 invariant 부재**. *한 곳 = 단일 진입점*. PR #146·#114·#125 와 같은 결.
+
+### 5. `CardDeck object + index 가변` + 예외 처리 부재
+
+vagabond95: *"object 로 구현됐다면, index 를 reset 하는 기능도 필요하지 않을까요?"* + *"index 가 범위를 넘었을 경우에 대한 예외처리가 필요해보입니다."*
+
+→ **Singleton + 가변 index = 테스트 가능성 ↓ + 재사용 불가**. PR #108·#28·#112·#125 (Singleton Deck) 와 같은 결. **MCP 룰 후보 — `singleton-deck-testability`** 메이저 패턴.
+
+### 6. `setFirstTurnCards` 가 public + 호출 순서 강제 부재
+
+vagabond95: *"해당 함수는 최초에만 호출되기를 기대하고 있는데요, public 으로 선언이 되어있으므로 N 번 호출하는 것을 막을 수 없습니다. 순서가 중요하거나 최초에 호출되기를 기대한다면 다른 형태로 리펙토링이 필요할 것 같습니다."*
+
+→ **호출 순서 invariant 부재**. *생성자 또는 internal*. PR #146·#137 와 같은 결.
+
+### 7. `Referee object` 가능성
+
+vagabond95: *"object 로 선언되어도 괜찮지 않을까요?"*
+
+→ **Referee = 상태 없음 → object** = *Kotlin 어휘*. *PR #131·#108·#146 의 *ResultCalculator object** 와 같은 결.
+
+### 8. `BLACKJACK` 결과 시 *PlayerWinning 만 PlayerName 보유* — *View 의 요구사항 누수*
+
+vagabond95: *"PlayerWinning 에만 PlayerName 이 포함되는 이유는 View 의 요구사항 때문 아닐까요?"*
+
+→ **View 의 요구사항 = 도메인 객체 멤버 누수**. *PlayerName 은 Player 의 정보 → PlayerWinning 이 별도 보유*는 *Player 와 결과의 결합*. PR #49·#88·#137 와 같은 결.
+
+### 9. `Participants` 의 *player 스스로 처리 가능 메서드 외부 추출*
+
+vagabond95: *"player 가 스스로 처리할 수 있지 않을까요?"*
+
+→ **Player 자기 책임을 Participants 가 흡수**. *Tell-Don't-Ask*.
+
+### 10. `Controller → model 내부 디테일 직접 접근` = Demeter 위반
+
+vagabond95 (BlackJackController.kt:61): *"Controller 가 Model 의 세부사항까지 너무 자세하게 알고 있을 필요가 없어보여요. 세부사항을 숨겨볼 수 있을까요? hint : `디미터 법칙`"*
+
+→ **Controller 가 model 깊이 접근 = Demeter 위반**. PR #133·#88·#137·#146·#93 와 같은 결.
+
+### 11. `showCards` 도메인에 View 의존 어휘
+
+vagabond95 (Role.kt:22): *"showCards 는 view 에 의존적인 네이밍이라고 생각돼요. 변경해볼 수 있을까요?"*
+
+→ **`showXX` / `printXX` 도메인 어휘 X**. PR #58·#88·#137 와 같은 결.
+
+### 12. `Score.determineWinning(dealerScore: Int)` 타입 강제 부재
+
+vagabond95: *"Score 에는 dealer 와 player 모두 가질 수 있는 모델인데, 딜러 score 만을 받아 처리하는 함수는 조금 어색한 것 같습니다. 더군다나, determineWinning 의 파라미터는 네이밍만 dealerScore 일 뿐 타입으로 강제하지 않기 때문에, dealer score 에서 dealer score 를 넣는 것을 막을 수 없습니다."*
+
+→ **`Int` 인자 = 타입 안전성 부재**. *DealerScore value class* 또는 *Participant 인자*로 *타입 강제*. PR #137·#90 와 같은 결의 *원시값 포장*.
+
+### 13. `BlackJack` 컨트롤러 네이밍 model 혼동
+
+vagabond95: *"컨트롤러라면 model 과 혼동을 방지하기 위해 네이밍에 명시해주는 건 어떨까요?"*
+
+→ **BlackJack = model 이름 vs Controller**. *BlackJackController* 명시. PR #58 와 같은 결.
+
+### 14. `CardHand.sum()` naming 모호
+
+vagabond95: *"무엇을 sum 한다는 것인지 내용이 구체적으로 드러나야 할 것 같아요."*
+
+→ **`sum()` = 모호 (점수? 카드 수?)**. *`totalScore()` / `cardCount()`* 명시. PR #146·#136 와 같은 결.
+
+### 15. `dealer.sum` / `player.result` 같은 결과 네이밍 비일치
+
+vagabond95: *"같은 결과를 리턴하는데, dealer 는 sum / player 는 result 로 표현되고 있는데요. 네이밍을 일치시킬 필요가 있을 것 같습니다."*
+
+→ **같은 의미 다른 네이밍 = 일관성 부재**. PR #146·#137 와 같은 결.
+
+### 16. `Done.draw / Done.stay` 가 *무의미한 메서드* — 학생 자가 의문
+
+학생 자가 인용: *"하지만 현재 구현의 `Done` 이라는 추상 클래스에서 `draw` 와 `stay` 라는 메서드가 단순히 예외를 던지도록 하고 있습니다. 이 부분에서 불편함이 느껴지더라구요.. 이렇게 되면 `Done` 의 구현체인 `BlackJack`, `Bust`, `Stay` 에서 아무 의미 없는 메서드 `draw` 나 `stay` 를 호출할 수 있게 됩니다. 물론 논리 상으로 이를 구현할 일이 없겠지만, 개발자가 `Bust(CardHand()).draw()` 와 같은 코드를 아예 사용했을 때 컴파일 오류를 발생시키거나, 경고를 띄워줄 수 있는 방법이 있나요?"*
+
+→ **인터페이스 메서드 일관성 vs 도메인 invariant 트레이드오프**. *State interface = draw/stay 모든 상태에 강제*. *Done 상태 = 의미 부재*. PR #152·#147 와 같은 결.
+
+### 17. `enum CardHandState` 의 `output: String` 필드 — *View 의존*
+
+(못한 점 §3 의 연장).
+
+### 18. CardDeck 셔플 자동 — *외부 위임 가능*
+
+vagabond95: *"카드를 재사용 처리 👍 그런데, 셔플까지는 안해도 괜찮지 않을까요? 카드 세트만 제공하고 그 이후 처리는 나머지 함수에게 위임하면 좋을 것 같습니다. 추후라도 순서가 정렬된 원본 카드를 사용할 경우도 있을지 모르니까요 :)"*
+
+→ **셔플 = 외부 책임 위임**. *전략 패턴 (ShuffleStrategy)* 또는 *Deck 외부에서 shuffle* 분리. PR #108·#133·#136 와 같은 결.
+
+## 리뷰어 의견 요지
+
+- **`runXX` / `executeXX` / `doXX` 만능 동사 = SRP 위반 신호** — vagabond95 명시.
+- **결과 상태 vs 진행 상태 분리** — *enum 혼재 회피*.
+- **enum UI value = model 누수** — *output/shape 어휘 도메인 X*.
+- **상수 다중 선언 = 일관성 invariant 부재** — *단일 진입점*.
+- **Singleton + 가변 = 테스트 ↓ + 재사용 불가** — *Strategy 주입 정공*.
+- **호출 순서 invariant = public 노출 위험** — *internal 또는 생성자*.
+- **객체 vs object Kotlin 어휘** — *상태 없음 → object*.
+- **View 어휘 (showXX/printXX) 도메인 X**.
+- **타입 강제 = `Int` 인자 회피 → value class** — *PR #90·#137 와 같은 결*.
+- **추상 클래스 = "고장난 클래스"** (말리빈도 동일) — *abstract method 가 강제*.
+- **디자인 패턴 = 요리법 비유 — 시간 + 경험 + 자가 학습*** — vagabond95 인용.
+- **트레이드오프 양방향 인식 = 모든 구현은 trade-off**.
+
+## 대표 인용
+
+**vagabond95 (디자인 패턴 = 요리법 비유, CardHandState.kt:1):**
+> 디자인 패턴은 일종의 요리법을 익히는 것이라고 생각됩니다.
+> 요리법을 한번 본다고해서, 요리를 잘하게 되는 것은 아닙니다. 하지만 최소한 이 요리가 어떻게 진행되어야할지에 대한 가이드는 얻을 수 있겠죠. 또한, 요리법에 대한 내용이 모두 한번에 이해가 되는 것이 아닙니다.
+>
+> 여러 요리에 요리법을 적용해보면서 장/단점을 익히고 사례를 쌓아나가면서, 요리법에 적힌 내용을 진정히 이해하고 또 적절히 취사선택하는 시기가 오게 됩니다.
+>
+> 디자인패턴도 이와 같다고 생각합니다. 처음부터 너무 완벽하게 익히는 것은 불가능하거니와 그렇게 되지 않은 부분에 대해 큰 스트레스 안받으셔도 될 것 같습니다. 패턴에 대해 알아보는 것만으로도 현 시점에는 충분하다고 생각합니다.
+
+**vagabond95 (네이밍 3 기준, Role.kt):**
+> 1. 모호한 의미를 가지는 이름을 지양하자.
+> 질문 주셨던 `runPhase` 를 예로 들어보면, 프로그래밍 특성상 거의 대부분의 함수는 run 이라는 동사를 사용했을 때 어색하지 않습니다. 이것은 바꿔말하면 해당 함수에 어떤 내용이 들어가도 어색하지 않다는 것을 의미합니다.
+> 객체 지향 프로그래밍의 5대 원리라고 불리는 SOLID 에서 SRP 가 제대로 지켜지지 않는 것이죠. ㅎㅎ
+> (비슷한 사례로 executeXXX, doXXX 등이 있습니다.)
+>
+> 2. 많은 코드를 보고, 네이밍을 짓는 다양한 사례를 익히자.
+> 코드를 계속 접하다보면, 유사한 비즈니스 로직에 자주 사용되는 네이밍들이 있습니다.
+> 가령, 이름의 길이를 검증하는 함수가 있다면 자주 활용 되는 verifty 라는 동사를 사용하여 `verifyNameLength()` 라고 지어볼 수 있겠습니다.
+>
+> 3. 도메인에 대한 이해도
+> 너무 당연한 말이지만 ^^; 도메인에 대한 이해도도 무척 중요합니다.
+
+**vagabond95 (추상 클래스 API 트레이드오프, Role.kt):**
+> 이 부분은 2가지 관점으로 생각할 수 있을 것 같습니다.
+> 1. 추상클래스의 하위 타입의 요구사항에 의해 상위 타입의 API 가 변경되었다. -> 추상 클래스의 역할을 잘못 정의했다는 신호일 수 있습니다.
+> 2. 구현의 범용성을 고려하여 API 를 구현하였다. -> 하위 타입의 구현을 알지 못하는 상황에서 범용성을 위한 선택이므로 적절한 선택이라고 할 수 있습니다.
+
+**vagabond95 (API 사용자 책임, Done.kt:10):**
+> 저는 이렇게 예외를 던져주는게 굉장히 좋은 방법이라고 생각됩니다. 어노테이션을 활용하면, 컴파일 타임에 경고를 주는 것도 가능하지만 불필요할 것 같습니다.
+>
+> API 를 잘 설계했다면, 잘못사용했을 시 발생하는 예외는 API 사용자가 감수하는 것이므로 더 신경쓰지 않으셔도 될 것 같습니다.
+
+**vagabond95 (BLACKJACK/BURST 결과 vs HIT/STAY 진행 분리, CardHandState.kt):**
+> BLACKJACK, BURST 는 결과를 나타내는 상태이고
+> STAY, HIT 은 진행과정을 나타내는 상태이므로 이것들이 같은 enum 으로 묶이는 것이 적절하지 고민해보면 좋겠습니다.
+
+**학생 자가 학습 (State 패턴 욕심, CardHandState.kt:1):**
+> 제리가 이렇게 말씀해주셨지만, 제가 우테코 수업에서 상태 패턴을 배우기 전에 직접 공부하고 코드로 구현을 해보고 싶은 욕심을 느껴서 열심히 적용해보았습니다..
+
+**학생 자가 학습 (자동차 경주 미션 인용 + 자기 블로그, CardHandState.kt:1):**
+> 사실 2주 전에 코치님이 블랙잭 미션을 하면, 상태 패턴이라는 디자인 패턴을 배울 것이라고 미리 이야기도 해주셨고,
+> 또 과거에 sealed class 를 공부하기 위해 코틀린 인 액션과 이펙티브 코틀린을 보면서 상태 패턴을 공부했었습니다.(https://sh1mj1-log.tistory.com/199)
+>
+> 저는 자동차 경주 미션을 진행하면서 디자인 패턴은 객체지향적으로 사고하고, 설계하면서 발견해내고 공부하는 것이라고 느꼈습니다. (https://sh1mj1-log.tistory.com/228)
+
+**학생 자가 학습 (트레이드오프 의문, PlayerWinning.kt:1):**
+> 하지만 Dealer 의 승/패/무승부 는 오직, Player 의 승/패/무승부 여부만을 가지고 알아낼 수 있는데도 불구하고, ScoreBoard 에서 딜러의 승/패/무승부 를 결정하도록 하는 것은 객체 지향 프로그래밍의 도구인 추상 클래스를 사용하기 위해서, **어떠한 책임을 위한 정보보다 훨씬 더 많은 정보를 가진 클래스가 책임을 가지게 되는 것은 아닐까요?**
+
+## 얻은 교훈
+
+1. ***`runXX` / `executeXX` / `doXX` 만능 동사 = SRP 위반 신호***. *함수 이름에 어떤 내용이 들어가도 어색하지 않으면 단일 책임 부재*. **MCP 룰 후보 — `vagueVerb` (vagueName 변형)**. PR #125·#114·#10·#88·#58 와 같은 결.
+
+2. ***결과 상태 (BLACKJACK/BUST) vs 진행 상태 (HIT/STAY) 분리***. *같은 enum 통합 X*. *sealed Running / Done 형제 분리*. PR #136·#147·#152·#137 와 같은 결.
+
+3. ***디자인 패턴 = 요리법 비유 (vagabond95)*** — *한 번 본다고 잘하지 X, 여러 사례 적용 + 장단점 익히기*. *학생 자가 학습 가치 인정*.
+
+4. ***`Done.draw / Done.stay = throw` API 사용자 책임 vs 컴파일 타임 경고 트레이드오프***. *API 잘 설계 시 잘못 사용 = 사용자 감수*. *Android/Kotlin stdlib 도 동일 패턴*. PR #152·#147·#85 와 같은 결.
+
+5. ***`enum UI value` 메이저 안티패턴***. *output/shape/koreanText 멤버 = model 누수*. PR #124·#28·#78·#112·#125·#128·#135·#137 와 같은 결.
+
+6. ***`BLACK_JACK = 21` 상수 다중 선언 = 일관성 invariant 부재***. *단일 진입점 + 상수 한 곳*. PR #146·#114·#125 와 같은 결.
+
+7. ***Singleton CardDeck + 가변 index = 테스트 ↓ + 재사용 불가***. *Strategy 패턴 + 생성자 주입 정공*. **MCP 룰 후보 — `singleton-deck-testability`** 메이저. PR #108·#28·#112·#125 와 같은 결.
+
+8. ***`Int` 인자 = 타입 안전성 부재***. *DealerScore value class* / *Participant 인자* 가 *타입 강제*. PR #137·#90·#108·#133·#132·#136·#49 와 같은 결.
+
+9. ***`showXX` / `printXX` 도메인 어휘 X***. PR #58·#88·#137 와 같은 결.
+
+10. ***학생 자가 학습 = "추상 클래스 사용 위해 책임을 가진 클래스가 정보를 더 가짐?"*** = *트레이드오프 자가 인식 모범*. *vagabond95 답변 = "모든 구현은 trade-off"* 양방향 학습. PR #137·#148·#151·#146 와 같은 결.
+
+11. ***vagabond95 = racingcar 인용 reviewer 직접 등장***. *CLAUDE.md 의 vagueName 룰 인용 출처가 본 blackjack 미션에도 등장* — **reviewer 누적 인용 보강**.
+
+12. ***학생 자가 답변에 자기 블로그 글 + 외부 자료 인용 (코틀린 인 액션, 이펙티브 코틀린) + 자동차 경주 미션 인용 = 학습 가시화 최고 수준***. *외부 자료 + 자가 정리 + 본인 코드 적용* 흐름. PR #128·#135·#108·#133·#136·#137·#146·#41·#148·#151 와 같은 결.