tomevault-io 워크플로우: SPEC.md 기반 아키텍처 결정 문서 생성
목표: SPEC.md의 요구사항을 분석하고, 아키텍처 결정이 필요한 질문을 도출하여 사용자와 함께 survey.md를 작성합니다.
1단계: SPEC.md 읽기
프로젝트 루트의 SPEC.md 파일을 읽습니다.
- SPEC.md가 없는 경우: 사용자에게 "
/spec을 먼저 실행하여 SPEC.md를 생성하세요"라고 안내하고 종료합니다. - SPEC.md가 있는 경우: 다음 항목을 파악합니다:
- 기능 요구사항 (F1, F2, ...)
- 비기능 요구사항
- 제약조건
- 사용자 시나리오
2단계: 아키텍처 질문 도출
SPEC.md의 내용을 아래 참고 자료와 대조하여 아키텍처 결정이 필요한 질문들을 도출합니다.
- 참고 자료의 6개 카테고리에서 SPEC.md 내용에 관련된 질문만 필터링합니다.
- SPEC.md에서 이미 결정된 사항은 질문에서 제외합니다.
- 질문은 한국어로 생성합니다.
3단계: 사용자 응답 수집
AskUserQuestion 도구를 사용하여 아키텍처 관련 질문을 사용자에게 제시하고 답변을 수집합니다.
- 질문은 카테고리별로 그룹화하여 제시합니다.
- 사용자의 답변을 기록합니다.
4단계: survey.md 생성
SPEC.md 요구사항 + 사용자 아키텍처 결정을 합쳐서 survey.md를 프로젝트 루트에 작성합니다.
- 필수: 생성되는 내용은 반드시 한국어여야 합니다.
참고 자료: React 아키텍처 전략
1. 프로젝트 범위 및 제약조건 (구현 전)
- 팀 & 일정: 팀 구성(규모, 스쿼드)은 어떠한가? 유지보수 주기는?
- 비즈니스 동인: 핵심 가치는 무엇인가?
- 규모: 소규모 MVP인가, 대규모 엔터프라이즈 앱인가? (FSD vs Bulletproof React 결정 기준)
2. 도메인 모델링 (DDD)
- 엔터티: 핵심 불변 데이터 구조(예: User, Product)가 식별되었는가?
- 기능 시나리오: 주요 기능 흐름(예: "결제", "상품 검색")은 무엇인가?
- 유비쿼터스 언어: 디자인/비즈니스/개발 간 용어 불일치가 있는가?
3. 비기능 요구사항 (NFR 체크리스트)
- 확장성: 모듈 경계, 저장소 구조 (모노레포 여부)
- 유지보수성: 의존성 규칙
- 성능: Core Web Vitals 목표 (LCP, INP). SSR 또는 CSR?
- 테스트 용이성: 로직 격리 전략. 커스텀 훅 vs 로직 클래스
- 접근성: 준수 수준 (WCAG). 헤드리스 UI 필요 여부
- 보안: 인증 패턴, 토큰 저장 방식
4. 아키텍처 방법론 선택
- FSD (Feature-Sliced Design): 엄격한 레이어링, 단방향 흐름. 복잡한 장기 프로젝트에 적합.
- Bulletproof React: 기능 기반 폴더, 실용적. 스타트업/중규모에 적합.
- 클린 아키텍처: UI와 도메인의 엄격한 분리 (어댑터/포트). 보일러플레이트 높지만 테스트 용이성 높음.
5. 데이터 및 상태 전략
- 서버 상태: React Query / SWR
- URL 상태: 필터/페이지네이션에 검색 파라미터 사용 여부
- 클라이언트 전역 상태: Zustand/Redux (최소화 권장)
- 로컬 UI 상태: 코로케이션 (관련 위치에 배치)
- 데이터 페칭: Render-then-Fetch vs Render-as-you-fetch (Loaders/Actions)
6. 테스트 및 품질
- 정적 분석: ESLint 경계 규칙
- 통합 테스트: MSW + RTL (트로피 모델)
- E2E: Cypress/Playwright로 핵심 경로 검증
출력 형식 (survey.md):
# [SPEC.md의 기능명] 아키텍처 설문
> 기반 문서: SPEC.md
> 작성일: YYYY-MM-DD
## 1. 프로젝트 맥락
- [질문]: [사용자 답변/결정]
## 2. 도메인 분석
- [질문]: [사용자 답변/결정]
## 3. 비기능 요구사항
- [질문]: [사용자 답변/결정]
## 4. 아키텍처 방법론
- [질문]: [사용자 답변/결정]
## 5. 데이터 및 상태 전략
- [질문]: [사용자 답변/결정]
## 6. 테스트 및 품질
- [질문]: [사용자 답변/결정]
Converted and distributed by TomeVault — claim your Tome and manage your conversions.