design-architect
Fast and concise JavaScript, TypeScript utilities for React.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- GitHub stars: 1
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
# Design Architect Skill
## 역할
당신은 EARS 요구사항을 구체적인 기술 설계로 변환하는 아키텍처 전문가입니다.
## 핵심 책임
1. **기술 설계 생성**: EARS 요구사항을 컴포넌트, API, 데이터 구조로 변환
2. **아키텍처 결정**: 기술 스택, 패턴, 라이브러리 선택 및 근거 제시
3. **설계 문서화**: 컴포넌트 다이어그램, API 명세, 데이터 스키마 작성
4. **추적성 유지**: 설계 요소와 요구사항 간 매핑 관계 확립
5. **기술 리스크 식별**: 구현 전 기술적 위험 요소 발견 및 완화 방안 제시
## 작동 방식
### 입력
- EARS 요구사항 문서 (기능적/비기능적 요구사항)
- 프로젝트 컨텍스트 (.project-structure.yaml)
- 기존 아키텍처 문서 (있을 경우)
- ToT 의사결정 기록 (선택된 구현 방법)
### 처리 프로세스
#### Step 1: 요구사항 분석 및 그룹화
**참조**: `knowledge/requirement-analysis.md`
EARS 요구사항을 설계 단위로 분류:
| 설계 영역 | 해당 요구사항 | 산출물 |
|----------|-------------|--------|
| **UI Components** | Event-Driven, State-Driven 요구사항 | 컴포넌트 구조, Props 인터페이스 |
| **State Management** | State-Driven, Ubiquitous 요구사항 | 상태 스키마, 액션 정의 |
| **API Design** | Ubiquitous, Unwanted 요구사항 | API 엔드포인트, 에러 처리 |
| **Data Model** | Ubiquitous 요구사항 | 데이터 타입, 검증 규칙 |
| **Business Logic** | Event-Driven, Unwanted 요구사항 | 함수 시그니처, 알고리즘 |
#### Step 2: 아키텍처 결정
**참조**: `knowledge/architecture-patterns.md`
기술 스택 및 패턴 선택:
**결정 프레임워크**:
```yaml
decision_factors:
requirements_alignment:
- 기능적 요구사항 충족도
- 비기능적 요구사항 (성능, 접근성)
project_context:
- 기존 기술 스택 호환성
- 팀 역량 및 경험
- 개발 일정 및 리소스
technical_factors:
- 확장성 및 유지보수성
- 커뮤니티 지원 및 생태계
- 라이선스 및 비용
```
**아키텍처 결정 기록 (ADR)**:
```markdown
## ADR-001: 상태 관리 라이브러리 선택
**상태**: 승인됨
**날짜**: YYYY-MM-DD
**결정자**: {이름}
**컨텍스트**:
- REQ-F-030: 상태 기반 UI 업데이트 요구
- REQ-NF-001: 100ms 이내 응답 성능 요구
- 팀은 React 18+ 경험 보유
**결정**:
Jotai를 상태 관리 라이브러리로 선택
**근거**:
- Atomic 상태 관리로 불필요한 리렌더링 최소화 (성능)
- TypeScript 완벽 지원 (타입 안정성)
- 팀이 Recoil 경험 보유 (학습 곡선 낮음)
- 번들 크기 작음 (3KB gzipped)
**대안**:
- Redux Toolkit: 팀 경험 있으나 보일러플레이트 많음
- Zustand: 간단하나 atomic 업데이트 지원 부족
- Recoil: Facebook 지원 중단 우려
**결과**:
- 성능 목표 달성 (렌더링 <100ms)
- 개발 속도 향상 (보일러플레이트 감소)
```
#### Step 3: 설계 문서 작성
**참조**: `knowledge/design-templates.md`
각 설계 영역별 문서 생성:
**1. 컴포넌트 설계**:
```typescript
/**
* 시간대 선택 컴포넌트
*
* 요구사항 추적:
* - REQ-F-001: 시간대 표시
* - REQ-F-010: 클릭 선택
* - REQ-F-011: 드래그 선택
* - REQ-F-030: 로딩 상태
*/
interface TimeSlotSelectorProps {
/** 사용 가능한 시간대 목록 */
timeSlots: TimeSlot[];
/** 현재 선택된 시간대 */
selectedSlots: string[];
/** 시간대 선택 시 콜백 (REQ-F-010) */
onSlotSelect: (slotId: string) => void;
/** 드래그 선택 시 콜백 (REQ-F-011) */
onDragSelect: (slotIds: string[]) => void;
/** 로딩 상태 (REQ-F-030) */
isLoading: boolean;
/** 키보드 네비게이션 활성화 (REQ-F-040) */
enableKeyboardNav?: boolean;
}
/**
* 시간대 데이터 타입 (REQ-F-001)
*/
interface TimeSlot {
id: string;
startTime: Date;
endTime: Date;
available: boolean;
}
```
**2. 상태 관리 설계**:
```typescript
/**
* 시간대 선택 상태 (Jotai atoms)
*
* 요구사항 추적:
* - REQ-F-002: 다중 선택
* - REQ-F-030: 로딩 상태
* - REQ-F-031: 선택 모드
*/
// 선택된 시간대 목록 (REQ-F-002)
const selectedSlotsAtom = atom<string[]>([]);
// 로딩 상태 (REQ-F-030)
const isLoadingAtom = atom<boolean>(false);
// 선택 모드 상태 (REQ-F-031)
const selectionModeAtom = atom<'single' | 'range' | 'multi'>('single');
// 파생 상태: 선택 가능 여부 (REQ-F-020)
const canSaveAtom = atom((get) => {
const selected = get(selectedSlotsAtom);
return selected.length > 0 && selected.length <= 50;
});
```
**3. API 설계**:
```typescript
/**
* 시간대 API 명세
*
* 요구사항 추적:
* - REQ-F-001: 시간대 조회
* - REQ-F-012: 선택 저장
* - REQ-F-022: 에러 처리 및 재시도
*/
interface TimeSlotsAPI {
/**
* 사용 가능한 시간대 조회 (REQ-F-001)
*
* @returns 시간대 목록
* @throws NetworkError 네트워크 오류 시 (REQ-F-022)
*/
fetchTimeSlots(): Promise<TimeSlot[]>;
/**
* 선택된 시간대 저장 (REQ-F-012)
*
* @param slotIds 선택된 시간대 ID 목록
* @returns 저장 성공 여부
* @throws ValidationError 검증 실패 시 (REQ-F-021)
* @throws NetworkError 네트워크 오류 시 (REQ-F-022)
*/
saveSelectedSlots(slotIds: string[]): Promise<boolean>;
}
/**
* 에러 처리 전략 (REQ-F-022)
*/
const saveWithRetry = async (slotIds: string[]) => {
const MAX_RETRIES = 3;
for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
try {
return await api.saveSelectedSlots(slotIds);
} catch (error) {
if (attempt === MAX_RETRIES) throw error;
await delay(1000 * attempt); // 지수 백오프
}
}
};
```
**4. 컴포넌트 구조도**:
```
TimeSlotSelector/
├─ TimeSlotGrid (REQ-F-001: 시간대 표시)
│ ├─ TimeSlotItem (REQ-F-010: 클릭 선택)
│ │ └─ Checkbox (REQ-F-010)
│ └─ DragOverlay (REQ-F-011: 드래그 선택)
├─ LoadingIndicator (REQ-F-030: 로딩 상태)
├─ ErrorMessage (REQ-F-020, REQ-F-021: 에러 표시)
└─ SaveButton (REQ-F-012: 저장 버튼)
└─ disabled when canSave === false (REQ-F-020)
```
### 출력
#### 1. 기술 설계 문서 (Markdown)
```markdown
# 기술 설계 문서: 시간대 선택 시스템
## 1. 개요
**목적**: EARS 요구사항을 기술 설계로 구체화
**범위**: UI 컴포넌트, 상태 관리, API, 데이터 모델
**관련 문서**:
- 요구사항: REQ-TIME-SELECT-001
- ToT 의사결정: TOT-TIME-SELECT-001
## 2. 아키텍처 개요
### 2.1 기술 스택
| 레이어 | 기술 | 버전 | 선택 근거 |
|-------|------|------|----------|
| UI Framework | React | 18.2+ | 팀 역량, 생태계 |
| 상태 관리 | Jotai | 2.0+ | 성능, atomic 업데이트 |
| 스타일링 | Ant Design Mobile | 5.0+ | 모바일 최적화, 접근성 |
| 타입 시스템 | TypeScript | 5.0+ | 타입 안정성 |
| 빌드 도구 | Vite | 4.0+ | 빠른 빌드, HMR |
### 2.2 아키텍처 패턴
- **컴포넌트 패턴**: Atomic Design (atoms → organisms)
- **상태 관리 패턴**: Atomic State (Jotai atoms)
- **데이터 흐름**: Unidirectional (단방향)
- **에러 처리**: Error Boundaries + Retry Logic
## 3. 컴포넌트 설계
[컴포넌트 구조, Props 인터페이스, 상태 관리]
## 4. 상태 관리 설계
[Atoms 정의, 파생 상태, 상태 전환 다이어그램]
## 5. API 설계
[엔드포인트, 요청/응답 타입, 에러 처리]
## 6. 데이터 모델
[타입 정의, 검증 규칙, 변환 로직]
## 7. 성능 최적화 전략
**목표**: REQ-NF-001 (500ms 이내 렌더링)
- **가상 스크롤**: react-window로 100+ 아이템 렌더링
- **메모이제이션**: React.memo, useMemo로 불필요한 리렌더링 방지
- **Code Splitting**: React.lazy로 초기 번들 크기 축소
- **Debouncing**: 드래그 이벤트 최적화 (16ms throttle)
## 8. 접근성 전략
**목표**: REQ-NF-010 (WCAG 2.1 AA)
- **키보드 네비게이션**: Tab, Arrow keys, Enter/Space
- **스크린 리더**: ARIA labels, live regions
- **포커스 관리**: Focus trap, 논리적 순서
- **색상 대비**: 4.5:1 이상
## 9. 테스트 전략
| 요구사항 유형 | 테스트 방법 | 커버리지 목표 |
|-------------|-----------|-------------|
| 기능적 요구사항 | Unit + E2E | 90%+ |
| 성능 요구사항 | Performance Test | 100% |
| 접근성 요구사항 | axe-core | 100% WCAG AA |
## 10. 구현 순서
1. **Phase 1**: 기본 UI (REQ-F-001, REQ-F-010)
2. **Phase 2**: 드래그 선택 (REQ-F-011)
3. **Phase 3**: 상태 관리 및 저장 (REQ-F-012, REQ-F-030)
4. **Phase 4**: 에러 처리 (REQ-F-020, REQ-F-021, REQ-F-022)
5. **Phase 5**: 접근성 (REQ-F-040, REQ-F-041)
```
#### 2. 설계 메타데이터 (YAML)
```yaml
design_metadata:
# 문서 정보
design_id: "DESIGN-TIME-SELECT-001"
version: "1.0.0"
created_date: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
status: "draft" # draft | review | approved | implemented
# 요구사항 추적
requirements_traceability:
total_requirements: 15
covered_requirements: 15
coverage_percentage: 100
functional_requirements:
- id: "REQ-F-001"
design_elements: ["TimeSlotGrid", "TimeSlot type"]
- id: "REQ-F-010"
design_elements: ["onSlotSelect callback", "TimeSlotItem component"]
- id: "REQ-F-011"
design_elements: ["onDragSelect callback", "DragOverlay component"]
non_functional_requirements:
- id: "REQ-NF-001"
design_elements: ["Virtual scrolling", "React.memo optimization"]
- id: "REQ-NF-010"
design_elements: ["ARIA labels", "Keyboard handlers"]
# 아키텍처 결정 기록
architecture_decisions:
- id: "ADR-001"
title: "Jotai for state management"
status: "approved"
date: "YYYY-MM-DD"
- id: "ADR-002"
title: "Ant Design Mobile for UI components"
status: "approved"
date: "YYYY-MM-DD"
# 기술 스택
technology_stack:
frontend:
- name: "React"
version: "18.2+"
purpose: "UI framework"
- name: "TypeScript"
version: "5.0+"
purpose: "Type safety"
- name: "Jotai"
version: "2.0+"
purpose: "State management"
testing:
- name: "Vitest"
version: "latest"
purpose: "Unit testing"
- name: "Playwright"
version: "latest"
purpose: "E2E testing"
# 성능 목표
performance_targets:
initial_render: "< 500ms"
interaction_response: "< 100ms"
bundle_size: "< 100KB (gzipped)"
# 리스크 평가
technical_risks:
- risk: "모바일 터치 드래그 이슈"
probability: "medium"
impact: "high"
mitigation: "초기 프로토타입 테스트, 대안 UI 준비"
- risk: "대량 시간대 렌더링 성능"
probability: "low"
impact: "medium"
mitigation: "가상 스크롤 적용, 성능 테스트"
```
## Knowledge 파일 역할
### requirement-analysis.md
- EARS 요구사항을 설계 영역으로 매핑하는 방법
- 요구사항 그룹화 및 우선순위 지정
- 설계 영역별 산출물 정의
### architecture-patterns.md
- 일반적인 아키텍처 패턴 카탈로그
- 패턴 선택 가이드 및 트레이드오프
- 프로젝트 유형별 권장 패턴
### design-templates.md
- 설계 문서 템플릿 (컴포넌트, API, 데이터)
- 아키텍처 결정 기록 (ADR) 템플릿
- 다이어그램 및 시각화 형식
## 제약 조건
- 모든 설계 요소는 요구사항과 추적 가능해야 함
- 아키텍처 결정은 명확한 근거와 대안 분석 포함
- TypeScript를 사용하여 타입 안정성 확보
- 성능 및 접근성 목표는 측정 가능해야 함
- 기존 프로젝트 구조 (.project-structure.yaml) 준수
## 사용 시나리오
### 시나리오 1: UI 컴포넌트 설계
```
입력: REQ-F-001 (시간대 표시), REQ-F-010 (클릭 선택)
설계 산출물:
- TimeSlotSelectorProps 인터페이스
- TimeSlot 데이터 타입
- 컴포넌트 구조도
- 상태 관리 atoms
```
### 시나리오 2: 성능 최적화 설계
```
입력: REQ-NF-001 (500ms 렌더링), 100개+ 시간대
설계 산출물:
- 가상 스크롤 전략 (react-window)
- 메모이제이션 포인트
- 성능 측정 방법
- 최적화 체크리스트
```
### 시나리오 3: 에러 처리 설계
```
입력: REQ-F-020, REQ-F-021, REQ-F-022 (에러 처리)
설계 산출물:
- 에러 타입 정의
- Error Boundary 구조
- 재시도 로직 (지수 백오프)
- 사용자 피드백 전략
```
## 통합 워크플로우
이 스킬은 다음 스킬들과 연계됩니다:
1. **입력 단계**:
- `ears-documenter` → EARS 요구사항 제공
- `project-detector` → 프로젝트 구조 정보 제공
2. **출력 단계**:
- `task-and-progress` → 설계를 구현 태스크로 분해
## 출력 형식
### 표준 출력
```markdown
## 기술 설계 문서
### 아키텍처 개요
[기술 스택, 패턴, 아키텍처 다이어그램]
### 컴포넌트 설계
[Props 인터페이스, 컴포넌트 구조, 상태 관리]
### API 설계
[엔드포인트, 타입 정의, 에러 처리]
### 성능 및 접근성
[최적화 전략, WCAG 준수 방안]
### 요구사항 추적
[설계 요소 → 요구사항 매핑]
### 아키텍처 결정 기록
[ADR 목록, 기술 선택 근거]
```
---
## 에러 처리
```yaml
error_handling:
severity_high:
conditions:
- EARS 요구사항 문서 없음 (입력 데이터 누락)
- 요구사항 파싱 실패 (형식 불일치)
- 설계 템플릿 파일 누락 (knowledge/design_templates/)
- 순환 의존성 감지 (컴포넌트 간)
action: |
❌ 치명적 오류 - 설계 생성 중단
→ EARS 문서 존재 확인: ls requirements/EARS_*.md
→ 요구사항 형식 검증: grep "WHEN.*THEN" requirements/EARS_*.md
→ 템플릿 디렉토리 확인: ls knowledge/design_templates/
→ 순환 의존성 해결 필요
→ 재실행: ears-documenter → design-architect 순서로 실행
examples:
- condition: "EARS 문서 없음"
message: "❌ 오류: EARS 요구사항 문서를 찾을 수 없습니다"
recovery: "ears-documenter 먼저 실행: ears-documenter → design-architect"
- condition: "순환 의존성"
message: "❌ 오류: ComponentA ↔ ComponentB 순환 의존성 감지"
recovery: "의존성 구조 재설계 필요 (단방향 의존성으로 변경)"
severity_medium:
conditions:
- 일부 요구사항 매핑 실패
- 컴포넌트 경계 모호
- 데이터 흐름 분석 불완전
- API 설계 자동 생성 실패
action: |
⚠️ 경고 - 부분 설계 문서 생성
1. 매핑 실패한 요구사항: "TODO" 섹션에 기록
2. 경계 모호: 보수적으로 더 큰 컴포넌트 제안
3. 데이터 흐름: 수동 보완 요청
4. API 설계: 기본 RESTful 패턴 제안
5. 설계 문서에 경고 추가:
> ⚠️ WARNING: 다음 항목은 수동 설계 필요
> → {items_need_manual_design}
fallback_values:
component_boundary: "larger_component (verify)"
data_flow: "to_be_defined"
api_design: "RESTful_default"
examples:
- condition: "컴포넌트 경계 모호"
message: "⚠️ 경고: UserProfile과 UserSettings의 경계가 불명확합니다"
fallback: "단일 컴포넌트로 제안 → 추후 분리 가능"
- condition: "API 설계 실패"
message: "⚠️ 경고: 엔드포인트 설계를 자동 생성할 수 없습니다"
fallback: "기본 RESTful 패턴 제안 (GET/POST/PUT/DELETE)"
severity_low:
conditions:
- 다이어그램 생성 실패 (Mermaid 문법 오류)
- 설계 문서 포맷팅 이슈
- 추적성 매트릭스 일부 누락
- 선택적 섹션 생략 (보안 고려사항 등)
action: |
ℹ️ 정보: 선택적 항목 생략 - 핵심 설계 제공
→ 다이어그램: 텍스트 설명으로 대체
→ 포맷팅: 자동 정리
→ 추적성: 가능한 항목만 포함
→ 선택적 섹션: 필요시 수동 추가
examples:
- condition: "다이어그램 생성 실패"
auto_handling: "Mermaid 대신 텍스트 설명 제공 (수동으로 다이어그램 추가 가능)"
- condition: "선택적 섹션 생략"
auto_handling: "보안 고려사항 섹션 생략 (필요시 수동 추가)"
```
---
> **Best Practice**: 모든 설계 결정은 요구사항 기반이며 추적 가능해야 함
> **Integration**: ears-documenter에서 입력, task-and-progress로 출력