Design Library

Design Library — API/라이브러리 설계 판단 기준

/design command의 D step에서 기술 라이브러리를 설계할 때 참조하는 판단 기준.

사용 방법:

• /design command의 D step에서 자동 참조됨
• 단독 참조도 가능 (라이브러리 API 리뷰 시)

Library Design 딥다이브 진입 조건

아래 중 2개 이상 해당하면 Library Design 딥다이브가 필요하다:

• 다른 개발자가 소비하는 코드이다 (패키지, SDK, 내부 공유 모듈)
• 공개 API surface를 설계해야 한다
• 하위 호환성/버전 관리를 고려해야 한다
• 추상화 레벨 선택이 설계의 핵심이다

설계 Phase 개요

Phase 1: 소비자의 멘탈 모델을 정의한다 (누가, 어떻게 쓰는가)
         ↓
Phase 2: 공개할 것과 숨길 것의 경계를 긋는다 (API Surface)
         ↓
Phase 3: 경계 안에서 구체적으로 설계한다
         - 타입으로 잘못된 사용을 막고 (Type Contract)
         - 확장 방법을 정하고 (Extension Point)
         - 안정성 약속을 정한다 (Stability Commitment)

Phase 1: Consumer Mental Model (소비자 이해)

"이 라이브러리를 쓰는 개발자가 머릿속에 가져야 할 개념은?"

1-1. 소비자 정의

검증 질문:

• "README의 한 줄 소개를 적을 수 있는가?"
• 적을 수 없으면 아직 범위가 명확하지 않은 것.

1-2. 핵심 개념 (Concept Glossary)

소비자가 알아야 할 개념을 3~5개로 정리한다.

검증 질문:

• 이 개념들만 알면 기본 사용이 가능한가?
• 너무 많으면 → 추상화 경계를 재검토

1-3. 사용 예시 (README-Driven)

구현 전에 사용 예시를 먼저 작성한다.

Simple (1줄):  가장 흔한 사용법. 80%의 케이스.
Advanced:      설정을 바꾸거나 동작을 커스터마이즈. 19%.
Escape Hatch:  추상화를 우회해 내부에 직접 접근. 1%.

검증 질문:

• Simple 예시가 1줄(또는 최소한의 코드)인가?
• 잘못된 사용이 이 예시보다 더 쉽지는 않은가?

Phase 2: API Surface (공개 경계)

"무엇을 공개하고, 무엇을 숨기는가?"

2-1. Public vs Internal

Q: 이 심볼을 공개해야 하는가?
├─ 소비자의 use case에 필요하다 → Public
└─ 내부 구현 편의를 위한 것이다 → Internal

핵심 원칙: "확신이 없으면 빼라" (Bloch)

• 나중에 추가는 가능하지만, 제거는 breaking change
• Public으로 공개한 모든 심볼은 영원한 약속

2-2. Progressive Disclosure

3계층으로 API를 설계한다:

검증 질문:

• Layer 1만으로 80%의 use case를 해결하는가?
• Layer 1을 배운 뒤 Layer 2로 자연스럽게 전환되는가? (호환되는가?)
• 추상화가 실패할 때 escape hatch가 존재하는가?

2-3. Naming

판단 기준:

• 이름 짓기가 어려우면 추상화 경계가 잘못된 것 (Bloch)
• 관련 메서드는 일관된 이름 패턴을 따르는가? (대칭성)
• 코드 샘플이 산문처럼 읽히는가?
• 파라미터 순서가 모든 메서드에서 일관적인가?

2-4. Module 구조

Q: import 경로가 깊은가?
├─ 3단계 이상 → flat하게 재구성 고려
└─ 2단계 이하 → OK

• Flat is better than nested (자동완성과 발견 용이)
• 단, 논리적으로 독립된 하위 모듈이면 분리 가능

Phase 3: Contract & Extension (계약과 확장)

3-1. Type Contract

"타입으로 잘못된 사용을 컴파일 타임에 막을 수 있는가?"

결정 트리:

Q: 유효하지 않은 상태가 타입으로 표현 가능한가?
├─ Yes → Q: 그 상태가 조용한 오동작을 유발하는가?
│         ├─ Yes → 타입으로 방지 (discriminated union, branded type)
│         └─ No  → 런타임 검증 + 명확한 에러 메시지로 충분
└─ No  → 문서화로 안내

기법:

적용하지 않을 때:

• 타입 시그니처가 이해 불가능하게 복잡해질 때
• 제약이 문서로 충분히 전달될 때 ("양수여야 한다" 수준)

3-2. Error Model

Q: 호출자가 에러를 프로그래밍적으로 분기해야 하는가?
├─ Yes → typed exception 또는 Result type
└─ No  → 메시지만 포함된 일반 에러

원칙:

• 에러는 문자열이 아닌 머신 리더블 구조를 가져야 한다
• 에러는 잘못 사용한 지점에서 즉시 발생해야 한다 (fail fast)
• 정상 흐름에 예외를 사용하지 않는다

3-3. Extension Point

"소비자가 동작을 확장해야 하는 지점은 어디인가?"

패턴 선택:

판단 흐름:

Q: 확장이 동작을 변경하는가, 관찰만 하는가?
├─ 관찰만 → Hook/Event
└─ 변경 → Q: 전후 처리 파이프라인인가?
            ├─ Yes → Middleware
            └─ No  → Q: 기능 단위로 교체 가능한가?
                      ├─ Yes → Plugin
                      └─ No  → Adapter (외부 의존 주입)

Extension interface 설계 원칙:

• interface는 최소화한다 (메서드 1~3개)
• Extension 간에 서로를 알 필요 없어야 한다
• 등록 방법이 명시적이어야 한다

3-4. Stability Commitment

"공개한 모든 것은 영원한 약속이다"

Hyrum's Law: "충분한 사용자가 있으면, 문서화하지 않은 관측 가능한 행위에도 누군가 의존한다"

체크리스트:

• 관측 가능한 행위를 최소화했는가? (불필요한 정보 노출 금지)
• 의존성(dependency)은 최소한인가? (각 dep는 소비자의 짐)
• SemVer 전략은? (PATCH: 버그 수정 / MINOR: 추가 / MAJOR: 제거·변경)
• Deprecation 정책은? (MINOR에서 deprecated 표시 → 다음 MAJOR에서 제거)
• Tree-shaking / 모듈별 import가 가능한가?

흔한 실수