# Survey > SPEC.md 기반 아키텍처 결정 문서 생성. "요구사항 분석", "아키텍처 질문", "설문 만들어" 등의 요청 시 사용 Use when this capability is needed. - Skill: `tomevault-io/survey` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/survey` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/survey/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/survey --- # 워크플로우: 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`)**: ```markdown # [SPEC.md의 기능명] 아키텍처 설문 > 기반 문서: SPEC.md > 작성일: YYYY-MM-DD ## 1. 프로젝트 맥락 - [질문]: [사용자 답변/결정] ## 2. 도메인 분석 - [질문]: [사용자 답변/결정] ## 3. 비기능 요구사항 - [질문]: [사용자 답변/결정] ## 4. 아키텍처 방법론 - [질문]: [사용자 답변/결정] ## 5. 데이터 및 상태 전략 - [질문]: [사용자 답변/결정] ## 6. 테스트 및 품질 - [질문]: [사용자 답변/결정] ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/gihwan-dev) — claim your Tome and manage your conversions.