بنقرة واحدة
design-library
Library/API 설계 판단 기준. `/design` command의 D step에서 기술 라이브러리를 설계할 때 참조.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
القائمة
Library/API 설계 판단 기준. `/design` command의 D step에서 기술 라이브러리를 설계할 때 참조.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
DDD 도메인 모델링 판단 기준. `/design` command의 D step에서 도메인 복잡도가 높을 때 참조.
RADIO 기반 FE/BE 설계 체크리스트. `/design` command가 각 Step에서 참조하는 판단 기준과 질문 목록.
BE TechSpec 문서 작성 템플릿과 패턴. 백엔드 프로젝트의 기술 명세서를 작성할 때 참조. Use when: BE TechSpec 작성, API 설계 문서 생성, Given/When/Then 테스트 케이스 정의, DB 스키마 설계, 서비스 아키텍처 설계 문서 작성 시 사용.
Entity Object(companion object) 패턴. Entity interface와 같은 이름의 const 객체에 도메인 로직 함수를 그룹화. Use when: TDD Refactor 단계에서 반복되는 도메인 로직을 정리할 때, Entity 구현 시 도메인 로직 코드화, UI/API/테스트에서 동일 로직 재사용이 필요할 때.
FE TechSpec 문서 작성 템플릿과 패턴. Linear 프로젝트의 기술 명세서를 작성할 때 참조. Use when: TechSpec 작성, 기술 명세서 생성, Given/When/Then 테스트 케이스 정의, Acceptance Criteria 작성, Solution 설계 문서 작성 시 사용.
Seed Design React 컴포넌트 라이브러리 참고 문서. Use when: @seed-design/react 컴포넌트 사용, UI 컴포넌트 구현, seed-design 컴포넌트의 props/API 확인이 필요할 때.
| name | design-library |
| description | Library/API 설계 판단 기준. `/design` command의 D step에서 기술 라이브러리를 설계할 때 참조. |
/design command의 D step에서 기술 라이브러리를 설계할 때 참조하는 판단 기준.
사용 방법:
/design command의 D step에서 자동 참조됨아래 중 2개 이상 해당하면 Library Design 딥다이브가 필요하다:
Phase 1: 소비자의 멘탈 모델을 정의한다 (누가, 어떻게 쓰는가)
↓
Phase 2: 공개할 것과 숨길 것의 경계를 긋는다 (API Surface)
↓
Phase 3: 경계 안에서 구체적으로 설계한다
- 타입으로 잘못된 사용을 막고 (Type Contract)
- 확장 방법을 정하고 (Extension Point)
- 안정성 약속을 정한다 (Stability Commitment)
"이 라이브러리를 쓰는 개발자가 머릿속에 가져야 할 개념은?"
| 질문 | 예시 |
|---|---|
| 누가 쓰는가? | 앱 개발자 / 라이브러리 개발자 / 내부 팀 |
| 숙련도는? | 초급 → 간결한 API, 상급 → 세밀한 제어 |
| 한 문장 정의 | "{X}를 하기 위한 라이브러리" |
검증 질문:
소비자가 알아야 할 개념을 3~5개로 정리한다.
| 개념 | 정의 | 코드에서의 표현 |
|---|---|---|
| {명사} | {한 문장 정의} | {class/type/function 이름} |
검증 질문:
구현 전에 사용 예시를 먼저 작성한다.
Simple (1줄): 가장 흔한 사용법. 80%의 케이스.
Advanced: 설정을 바꾸거나 동작을 커스터마이즈. 19%.
Escape Hatch: 추상화를 우회해 내부에 직접 접근. 1%.
검증 질문:
"무엇을 공개하고, 무엇을 숨기는가?"
Q: 이 심볼을 공개해야 하는가?
├─ 소비자의 use case에 필요하다 → Public
└─ 내부 구현 편의를 위한 것이다 → Internal
핵심 원칙: "확신이 없으면 빼라" (Bloch)
3계층으로 API를 설계한다:
| 계층 | 설명 | 설계 기준 |
|---|---|---|
| Layer 1: Simple | 가장 흔한 케이스 | 최소 파라미터, 좋은 기본값 |
| Layer 2: Configurable | 커스터마이즈 필요 | options object, 선택적 파라미터 |
| Layer 3: Escape Hatch | 추상화 우회 필요 | 내부 primitive 노출 |
검증 질문:
판단 기준:
Q: import 경로가 깊은가?
├─ 3단계 이상 → flat하게 재구성 고려
└─ 2단계 이하 → OK
"타입으로 잘못된 사용을 컴파일 타임에 막을 수 있는가?"
결정 트리:
Q: 유효하지 않은 상태가 타입으로 표현 가능한가?
├─ Yes → Q: 그 상태가 조용한 오동작을 유발하는가?
│ ├─ Yes → 타입으로 방지 (discriminated union, branded type)
│ └─ No → 런타임 검증 + 명확한 에러 메시지로 충분
└─ No → 문서화로 안내
기법:
| 기법 | 언제 | 예시 |
|---|---|---|
| Discriminated Union | 상호 배타적 상태 | { kind: "email"; email: string } | { kind: "postal"; address: Address } |
| Smart Constructor | 생성 시 검증 필요 | EmailAddress.parse(raw) → Result<EmailAddress, Error> |
| Branded Type | 같은 원시 타입이지만 의미가 다름 | UserId vs OrderId (둘 다 string이지만 혼용 방지) |
| Non-empty Collection | 빈 입력이 의미 없음 | [T, ...T[]] |
적용하지 않을 때:
Q: 호출자가 에러를 프로그래밍적으로 분기해야 하는가?
├─ Yes → typed exception 또는 Result type
└─ No → 메시지만 포함된 일반 에러
원칙:
"소비자가 동작을 확장해야 하는 지점은 어디인가?"
패턴 선택:
| 패턴 | 제어 흐름 | 결합도 | 적합한 경우 |
|---|---|---|---|
| Plugin | 라이브러리가 호출 | 낮음 | 전체 기능 추가 (파서, 포매터, 백엔드) |
| Middleware | 체인, 각각 next() 호출 | 중간 | 요청/응답 파이프라인, 전후 처리 |
| Hook/Event | Pub-Sub, fire-and-forget | 매우 낮음 | 관찰만 필요, 동작 변경 불필요 |
| Adapter | 인터페이스 변환 | 낮음 | 외부 구현 주입 (HTTP 클라이언트, 로거) |
판단 흐름:
Q: 확장이 동작을 변경하는가, 관찰만 하는가?
├─ 관찰만 → Hook/Event
└─ 변경 → Q: 전후 처리 파이프라인인가?
├─ Yes → Middleware
└─ No → Q: 기능 단위로 교체 가능한가?
├─ Yes → Plugin
└─ No → Adapter (외부 의존 주입)
Extension interface 설계 원칙:
"공개한 모든 것은 영원한 약속이다"
Hyrum's Law: "충분한 사용자가 있으면, 문서화하지 않은 관측 가능한 행위에도 누군가 의존한다"
체크리스트:
| 실수 | 문제 | 해결 |
|---|---|---|
| 구현부터 시작 | API가 내부 구조를 반영 | 사용 예시(README)를 먼저 작성 |
| 모든 것을 public | 모든 변경이 breaking change | 기본 private, 필요한 것만 공개 |
| string/any 파라미터 남용 | 런타임 에러, 문자열 파싱 | 전용 타입, enum, value object |
| nullable return | 호출자가 null 체크 누락 | 빈 컬렉션, Option/Result 타입 |
| 긴 positional 파라미터 | 인자 순서 실수 | options object 또는 builder |
| escape hatch 없음 | 추상화 실패 시 막힘 | Layer 3 raw access 제공 |
| 무거운 의존성 | 번들 비대, 버전 충돌 | dep 최소화, 주입 허용 |
| global mutable 설정 | 복수 인스턴스 간 간섭 | 인스턴스 기반 설정 (class/closure) |
| 에러에 문자열만 | 호출자가 에러 문자열 파싱 | typed exception + 머신 리더블 필드 |