# 제10장: 웹 애플리케이션 구축 > "실습은 이론을 현실로 만든다" - 벤자민 프랭클린 ```mermaid %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%% mindmap root((학습 목표)) 아키텍처 설계 엔터프라이즈급 시스템 설계 마이크로서비스 아키텍처 확장 가능한 구조 풀스택 개발 백엔드 API 구축 프론트엔드 최적화 실시간 통신 품질 보장 테스트 자동화 성능 최적화 보안 강화 DevOps 실천 컨테이너화 CI/CD 파이프라인 모니터링 시스템 ``` ## 학습 목표 이 장을 완료하면 다음을 할 수 있습니다. - 전체적인 웹 애플리케이션 아키텍처를 설계하고 구현할 수 있습니다. - Claude Code를 활용하여 백엔드와 프론트엔드를 체계적으로 개발할 수 있습니다. - 실시간 기능과 대화형 UI를 구현하고 최적화할 수 있습니다. - 테스트, 배포, 모니터링을 포함한 전체 개발 라이프사이클을 관리할 수 있습니다. ## 개요 이 장에서는 지금까지 학습한 모든 이론과 기법을 실제 프로젝트에 적용하는 종합적 실습을 진행합니다. Claude Code를 활용해 실시간 채팅이 있는 협업 도구 ‘CollabSpace’를 처음부터 끝까지 구축하면서, 전문적인 웹 애플리케이션 개발의 전 과정을 경험해보겠습니다. 이 프로젝트를 통해 아키텍처 설계부터 배포와 모니터링까지, 전체적인 개발 라이프사이클을 경험하고 실무에서 직접 활용할 수 있는 실전 역량을 배양하겠습니다. ## 10.1 엔터프라이즈 프로젝트 설계와 아키텍처 성공적인 웹 애플리케이션 구축은 체계적인 설계와 명확한 아키텍처에서 시작됩니다. 특히 실시간 협업 플랫폼과 같은 복잡한 시스템에서는 초기 설계 결정이 전체 프로젝트의 성패를 좌우합니다. 엔터프라이즈급 애플리케이션은 단순한 기능 구현을 넘어서 확장성, 안정성, 보안성, 유지보수성을 모두 고려해야 합니다. Claude Code는 이러한 다차원적 요구사항을 종합적으로 분석하고, 검증된 아키텍처 패턴을 제안하여 프로젝트의 기술적 위험을 최소화합니다. **아키텍처 설계의 핵심 원칙** 1. **도메인 주도 설계(DDD)**: 비즈니스 로직을 중심으로 한 서비스 경계 정의 2. **관심사의 분리**: 각 컴포넌트의 책임과 역할을 명확히 구분 3. **느슨한 결합**: 서비스 간 의존성을 최소화하여 독립적 개발과 배포 가능 4. **높은 응집도**: 관련 기능들을 논리적으로 그룹화하여 코드 품질 향상 5. **확장성 고려**: 사용자 증가와 기능 확장에 대비한 유연한 구조 ### 프로젝트 개요: "CollabSpace" - 엔터프라이즈급 협업 플랫폼 CollabSpace는 현대적인 원격 협업 환경의 모든 요구사항을 충족하는 포괄적인 협업 플랫폼입니다. Slack과 Notion의 장점을 결합하면서도 개발팀을 위한 전문적인 기능들을 추가로 제공합니다. **핵심 기능 및 비즈니스 가치** **1. 실시간 협업 엔진** - WebSocket 기반 실시간 통신 (1000+ 동시 사용자 지원) - 동시 편집과 충돌 해결 알고리즘 - 실시간 커서 추적과 사용자 인식 - 오프라인 동기화와 충돌 해결 **2. 지능형 워크스페이스 관리** - 계층적 조직 구조 (Organization > Team > Project) - 역할 기반 접근 제어 (RBAC) 시스템 - 동적 권한 위임과 임시 액세스 - 감사 로그와 활동 추적 **3. 통합 커뮤니케이션 허브** - 멀티미디어 지원 실시간 채팅 - 스레드 기반 대화 구조 - 지능형 알림 시스템 - 통합 검색과 콘텐츠 발견 **4. 프로젝트 관리 도구** - 사용자 정의 가능한 칸반 보드 - 간트 차트와 타임라인 뷰 - 자동화된 워크플로우 - 진행률 추적과 리포팅 **5. 파일과 지식 관리** - 버전 관리가 있는 파일 시스템 - 실시간 문서 협업 편집기 - 위키 시스템과 지식베이스 - 통합 코드 리뷰 도구 ### 엔터프라이즈급 아키텍처 설계 복잡한 협업 플랫폼의 아키텍처 설계는 기능적 요구사항뿐만 아니라 비기능적 요구사항(성능, 확장성, 가용성, 보안)을 모두 고려해야 합니다. **아키텍처 설계 방법론** 현대적인 웹 애플리케이션 설계는 다음과 같은 체계적 접근법을 따릅니다: 1. **요구사항 분석**: 비즈니스 요구사항과 기술적 제약사항을 명확히 정의 2. **도메인 모델링**: 핵심 비즈니스 엔티티와 그들 간의 관계 설계 3. **서비스 분해**: 마이크로서비스 경계 설정과 API 인터페이스 정의 4. **데이터 아키텍처**: 데이터 저장, 캐싱, 검색 전략 수립 5. **통신 패턴**: 동기/비동기 통신, 이벤트 기반 아키텍처 설계 6. **보안 아키텍처**: 인증, 인가, 데이터 보호 전략 구축 7. **운영 아키텍처**: 모니터링, 로깅, 배포 전략 설계 Claude Code를 활용하여 이러한 전체적인 설계 과정을 체계적이고 검증된 방식으로 진행해보겠습니다. **시스템 요구사항 정의** ```bash claude "CollabSpace 엔터프라이즈 협업 플랫폼의 아키텍처를 설계해줘. 비기능적 요구사항 - 성능: 1000+ 동시 사용자, 100ms 이하 API 응답 - 확장성: 수평적 확장 가능한 마이크로서비스 구조 - 가용성: 99.9% 업타임, 다중 가용 영역 배포 - 보안: 제로 트러스트 아키텍처, 종단간 암호화 - 데이터 일관성: 이벤트 소싱과 CQRS 패턴 적용 기능적 요구사항 - 실시간 협업: WebSocket 기반 실시간 통신 - 멀티 테넌시: 조직별 데이터 격리 - 파일 시스템: 대용량 파일 처리와 CDN 연동 - 검색 엔진: 전문 검색과 자동 완성 - 분석 시스템: 사용 패턴 분석과 인사이트 기술 제약사항 - 클라우드 네이티브 (Kubernetes 기반) - 컨테이너 우선 아키텍처 - API 우선 설계 (API-First) - 이벤트 기반 아키텍처 - 관찰 가능성 내장 (모니터링, 로깅, 추적)" ``` **Claude Code가 제안하는 아키텍처 개요** ```mermaid %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%% graph TB subgraph frontend [프론트엔드 계층] A[Web App
Next.js] B[Mobile App
React Native] C[Desktop App
Electron] end subgraph gateway [API Gateway 계층] D[API Gateway
Kong/Istio
인증/인가, Rate Limiting
로드 밸런싱, 서비스 디스커버리] end subgraph microservices [마이크로서비스 계층] E[Auth Service] F[User Service] G[Workspace Service] H[Project Service] I[Chat Service] J[File Service] K[Search Service] L[Notification Service] M[Realtime Service] N[Analytics Service] O[Audit Service] P[Email Service] end subgraph data [데이터 계층] Q[PostgreSQL
Primary DB] R[Redis
Cache] S[Elasticsearch
Search] T[MinIO
Files] U[Kafka
Events] V[TimescaleDB
Analytics] W[Vault
Secrets] end A --> D B --> D C --> D D --> E D --> F D --> G D --> H D --> I D --> J D --> K D --> L D --> M D --> N D --> O D --> P E --> Q F --> Q G --> Q H --> Q I --> R J --> T K --> S L --> R M --> U N --> V O --> Q P --> R classDef frontendStyle fill:#e2e8f0,stroke:#334155,stroke-width:2px,color:#1e293b classDef gatewayStyle fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#1e293b classDef microserviceStyle fill:#cbd5e1,stroke:#475569,stroke-width:1px,color:#1e293b classDef dataStyle fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#64748b class A,B,C frontendStyle class D gatewayStyle class E,F,G,H,I,J,K,L,M,N,O,P microserviceStyle class Q,R,S,T,U,V,W dataStyle ``` **상세 아키텍처 설계 요청** ```bash # 마이크로서비스 경계 정의 claude "CollabSpace의 마이크로서비스 경계를 DDD 원칙에 따라 정의해줘. 도메인 컨텍스트 분석 - 각 바운디드 컨텍스트의 책임과 경계 - 서비스 간 통신 패턴 (동기 vs 비동기) - 데이터 소유권과 일관성 전략 - 이벤트 스토밍 결과 반영 서비스별 상세 설계 1. 인증 서비스: OAuth2/OIDC, JWT, 다중 ID 제공자 2. 사용자 관리: 프로필, 설정, 팀 멤버십 3. 워크스페이스: 조직 구조, 권한 관리 4. 실시간 통신: WebSocket 연결 관리, 메시지 라우팅 5. 파일 서비스: 업로드, 저장, CDN 연동 6. 검색 서비스: 인덱싱, 전문 검색, 자동 완성 7. 알림 서비스: 실시간 알림, 이메일, 푸시 각 서비스는 - 독립적 배포 가능 - 자체 데이터베이스 소유 - API 버전 관리 지원 - 헬스체크와 모니터링 내장" # 실시간 통신 아키텍처 claude "대규모 실시간 협업을 위한 WebSocket 아키텍처를 설계해줘. 요구사항 - 1000+ 동시 연결 지원 - 메시지 보장과 순서 유지 - 연결 복구와 재동기화 - 수평적 확장 가능성 설계 요소 1. WebSocket 클러스터 관리 2. 메시지 브로커 (Redis Streams/Kafka) 3. 세션 관리와 로드 밸런싱 4. 백프레셔와 플로우 제어 5. 연결 상태 모니터링 성능 최적화 - 연결 풀링과 재사용 - 메시지 배칭과 압축 - 네임스페이스별 격리 - 지리적 분산 배포" # 데이터 아키텍처 설계 claude "멀티 테넌트 데이터 아키텍처를 설계해줘. 격리 전략 - 행 수준 보안 (Row-Level Security) - 스키마 분리 vs 데이터베이스 분리 - 암호화와 접근 제어 일관성 모델 - ACID vs BASE 트레이드오프 - 이벤트 소싱 적용 영역 - CQRS 패턴 구현 - 분산 트랜잭션 관리 성능 최적화 - 샤딩 전략 - 읽기 복제본 활용 - 캐싱 계층 설계 - 인덱스 최적화" ``` ### 전략적 기술 스택 선정 기술 스택 선정은 단순한 기술적 선호도를 넘어서 비즈니스 목표, 팀 역량, 장기적 유지보수성을 모두 고려해야 하는 전략적 의사결정입니다. Claude Code를 활용하여 각 계층별로 최적의 기술을 체계적으로 선택해보겠습니다. **종합적 기술 스택 평가 요청** ```bash claude "CollabSpace 엔터프라이즈 플랫폼을 위한 최적의 기술 스택을 추천해줘. 평가 기준 1. 성능과 확장성: 1000+ 동시 사용자 처리 능력 2. 개발 생산성: 팀 러닝 커브와 개발 속도 3. 생태계 성숙도: 라이브러리, 도구, 커뮤니티 지원 4. 운영 안정성: 프로덕션 검증과 장기 지원 5. 비용 효율성: 라이선스, 인프라, 인력 비용 6. 보안: 보안 패치와 취약점 대응 7. 인재 확보: 시장에서 개발자 확보 용이성 기술 영역별 후보 - 프론트엔드: React/Next.js vs Vue/Nuxt vs Angular vs Svelte - 백엔드 언어: Node.js vs Python vs Java vs Go vs Rust - 웹 프레임워크: Express vs FastAPI vs Spring Boot vs Gin - 데이터베이스: PostgreSQL vs MySQL vs MongoDB vs Cassandra - 캐시: Redis vs Memcached vs Hazelcast - 메시지 큐: Kafka vs RabbitMQ vs Redis Streams vs NATS - 검색 엔진: Elasticsearch vs Solr vs Algolia vs Typesense - 컨테이너: Docker vs Podman vs containerd - 오케스트레이션: Kubernetes vs Docker Swarm vs Nomad - 클라우드: AWS vs GCP vs Azure vs 멀티 클라우드 각 선택에 대한 상세한 근거와 트레이드오프 분석을 포함해줘." ``` **Claude Code가 추천하는 최종 기술 스택** ```yaml # 프론트엔드 스택 frontend: framework: "Next.js 14" language: "TypeScript" styling: "Tailwind CSS + HeadlessUI" state_management: "Zustand + TanStack Query" ui_components: "Radix UI + shadcn/ui" animation: "Framer Motion" testing: "Vitest + Testing Library + Playwright" bundler: "Turbopack (Next.js built-in)" 선택_근거: - "Next.js 14: App Router의 서버 컴포넌트로 성능 최적화" - "TypeScript: 대규모 팀 개발에서 타입 안전성 보장" - "Tailwind CSS: 일관된 디자인 시스템과 빠른 프로토타이핑" - "Zustand: 간단하지만 강력한 상태 관리, Redux 대비 보일러플레이트 최소화" - "Radix UI: 접근성 기본 제공, 기업 환경 필수 요구사항" # 백엔드 스택 backend: runtime: "Node.js 20 LTS" framework: "Fastify 4.x" language: "TypeScript" validation: "Zod" orm: "Prisma" authentication: "Passport.js + Auth0" websockets: "Socket.io 4.x" api_documentation: "OpenAPI 3.0 + Swagger" testing: "Jest + Supertest" 선택_근거: - "Node.js: 프론트엔드와 동일 언어로 팀 효율성 극대화" - "Fastify: Express 대비 2배 성능, 플러그인 생태계 우수" - "Prisma: 타입 안전한 데이터베이스 액세스, 마이그레이션 관리 우수" - "Socket.io: 실시간 통신의 산업 표준, 폴백 메커니즘 내장" # 데이터베이스 스택 database: primary: "PostgreSQL 15" cache: "Redis 7.x" search: "Elasticsearch 8.x" analytics: "TimescaleDB" message_queue: "Redis Streams" object_storage: "MinIO (S3 compatible)" 선택_근거: - "PostgreSQL: ACID 보장, JSON 지원, 확장성 우수" - "Redis: 고성능 캐싱, pub/sub, 스트림 처리 모두 지원" - "Elasticsearch: 전문 검색, 실시간 분석, 자동 완성 최적화" - "TimescaleDB: 시계열 데이터 처리에 특화된 PostgreSQL 확장" # 인프라 스택 infrastructure: containerization: "Docker + Docker Compose" orchestration: "Kubernetes 1.28+" ingress: "Istio Service Mesh" api_gateway: "Kong Gateway" monitoring: "Prometheus + Grafana + Jaeger" logging: "Fluentd + Elasticsearch + Kibana" secrets: "HashiCorp Vault" ci_cd: "GitLab CI + ArgoCD" cloud: "AWS (multi-AZ deployment)" 선택_근거: - "Kubernetes: 컨테이너 오케스트레이션 표준, 멀티 클라우드 지원" - "Istio: 서비스 메시로 보안, 관찰성, 트래픽 관리 통합" - "Kong: 엔터프라이즈급 API 게이트웨이, 플러그인 생태계" - "Prometheus: 클라우드 네이티브 모니터링 표준" # 개발 도구 development: package_manager: "pnpm" monorepo: "Turborepo" code_quality: "ESLint + Prettier + Husky" type_checking: "TypeScript strict mode" testing: "Jest + Playwright + k6" documentation: "Storybook + Docusaurus" 선택_근거: - "pnpm: npm 대비 3배 빠른 설치 속도, 디스크 공간 절약" - "Turborepo: 모노레포 빌드 최적화, 캐싱으로 CI 시간 단축" # 보안 스택 security: authentication: "OAuth 2.0 + OpenID Connect" authorization: "RBAC + ABAC hybrid" secrets_management: "HashiCorp Vault" encryption: "TLS 1.3 + AES-256" vulnerability_scanning: "Snyk + OWASP ZAP" compliance: "SOC 2 Type II ready" ``` **기술 스택 의사결정 매트릭스** ```bash claude "선정된 기술 스택의 의사결정 과정을 투명하게 문서화해줘. 비교 매트릭스 생성 - 각 기술 선택지에 대한 점수화 (1-10점) - 가중치 적용 (성능 30%, 개발 생산성 25%, 운영 안정성 20%, 비용 15%, 학습 곡선 10%) - 총점과 순위 - 선택하지 않은 기술의 배제 이유 리스크 분석 - 기술별 주요 리스크와 완화 전략 - 업그레이드 경로와 마이그레이션 계획 - 벤더 종속성과 대안 기술 - 팀 교육 계획과 일정 성능 벤치마크 - 예상 성능 지표 - 병목 지점 예측 - 확장성 시나리오 - 모니터링 포인트" ``` **프로토타입 검증** ```bash claude "기술 스택 검증을 위한 프로토타입을 만들어줘. 검증 목표 1. 성능 벤치마크: 동시 사용자 수, 응답 시간, 처리량 2. 개발 생산성: 기능 개발 속도, 디버깅 용이성 3. 운영 복잡성: 배포, 모니터링, 문제 해결 4. 통합성: 서비스 간 연동, 데이터 일관성 프로토타입 범위 - 사용자 인증과 세션 관리 - 실시간 채팅 (100명 동시 연결) - 파일 업로드와 다운로드 - 검색 기능 - 기본적인 모니터링과 로깅 성공 기준 - API 응답 시간 < 100ms (95%) - WebSocket 메시지 지연 < 50ms - 파일 업로드 처리량 > 10MB/s - 검색 응답 시간 < 200ms - 시스템 리소스 사용률 < 70%" ``` ## 10.2 엔터프라이즈급 프로젝트 초기 설정 프로젝트 초기 설정은 전체 개발 라이프사이클의 효율성을 결정하는 중요한 단계입니다. 엔터프라이즈 환경에서는 단순한 프로젝트 생성을 넘어서 확장 가능한 아키텍처, 팀 협업 체계, 자동화된 품질 관리 시스템을 모두 고려해야 합니다. **엔터프라이즈급 프로젝트 설정의 핵심 요소** 1. **모노레포 아키텍처**: 여러 서비스와 패키지를 효율적으로 관리 2. **자동화된 개발 환경**: 새로운 팀원의 빠른 온보딩 지원 3. **코드 품질 관리**: 일관된 코딩 스타일과 품질 기준 적용 4. **CI/CD 기반 구축**: 자동화된 테스트와 배포 파이프라인 5. **모니터링 및 로깅**: 운영 단계를 고려한 관찰 가능성 시스템 6. **보안 정책**: 개발 단계부터 적용되는 보안 가이드라인 잘 구조화된 모노레포와 자동화된 개발 환경은 팀 생산성을 크게 향상시키고 코드 품질을 보장합니다. 특히 마이크로서비스 아키텍처에서는 서비스 간 의존성 관리와 공통 라이브러리 공유가 프로젝트 성공의 핵심 요소입니다. ### 고급 모노레포 아키텍처 모노레포는 여러 관련 프로젝트를 하나의 저장소에서 관리하는 소프트웨어 개발 전략입니다. 엔터프라이즈 환경에서 모노레포는 코드 공유, 의존성 관리, 버전 동기화를 크게 단순화하며 개발팀 간의 협업을 향상시킵니다. **모노레포의 핵심 장점** 1. **코드 공유**: 공통 라이브러리와 유틸리티를 여러 프로젝트에서 쉽게 재사용 2. **의존성 관리**: 전체 프로젝트의 의존성을 중앙에서 일관되게 관리 3. **빌드 최적화**: 변경된 부분만 빌드하는 증분 빌드로 시간 단축 4. **타입 안전성**: TypeScript를 통한 전체 프로젝트의 타입 안전성 보장 5. **일관된 도구**: 린팅, 테스팅, 포매팅 도구의 통일된 설정 **Turborepo 선택 이유** Turborepo는 현재 가장 진보된 모노레포 도구 중 하나로, 다음과 같은 특징을 제공합니다. - **지능형 캐싱**: 이전 빌드 결과를 캐시하여 빌드 시간 대폭 단축 - **병렬 실행**: 독립적인 작업들을 병렬로 처리하여 효율성 극대화 - **원격 캐싱**: 팀원 간 빌드 캐시 공유로 전체 팀 생산성 향상 - **의존성 그래프**: 패키지 간 의존성을 자동으로 분석하여 최적 빌드 순서 결정 ```bash claude "CollabSpace를 위한 엔터프라이즈급 모노레포를 구성해줘. 요구사항 - Turborepo 기반 고성능 빌드 시스템 - 서비스별 독립적 배포 가능 - 공통 라이브러리 효율적 공유 - 타입 안전성 전체 프로젝트 보장 - 개발 도구 통합 (린팅, 테스팅, 포매팅) - Docker 기반 컨테이너화 준비 프로젝트 구조 ```mermaid %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%% graph TD A[collab-space/] --> B[apps/
애플리케이션] A --> C[packages/
공유 라이브러리] A --> D[tools/
개발 도구] A --> E[infrastructure/
인프라 코드] A --> F[docs/
문서] A --> G[.github/
GitHub 설정] B --> B1[web/
Next.js 14] B --> B2[mobile/
React Native] B --> B3[api-gateway/
Fastify] B --> B4[auth-service/
인증] B --> B5[chat-service/
채팅] B --> B6[file-service/
파일 관리] C --> C1[ui/
공통 UI 컴포넌트] C --> C2[types/
TypeScript 타입] C --> C3[config/
설정 관리] C --> C4[utils/
공통 유틸리티] C --> C5[database/
DB 관련] C --> C6[monitoring/
모니터링] D --> D1[build/
빌드 스크립트] D --> D2[scripts/
자동화] D --> D3[generators/
코드 생성] D --> D4[testing/
테스트 유틸] E --> E1[docker/
컨테이너 설정] E --> E2[kubernetes/
K8s 매니페스트] E --> E3[terraform/
인프라 프로비저닝] E --> E4[monitoring/
모니터링 설정] F --> F1[architecture/
아키텍처] F --> F2[api/
API 문서] F --> F3[deployment/
배포 가이드] F --> F4[development/
개발 가이드] classDef rootStyle fill:#e2e8f0,stroke:#334155,stroke-width:3px,color:#1e293b classDef categoryStyle fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#1e293b classDef itemStyle fill:#f8fafc,stroke:#94a3b8,stroke-width:1px,color:#64748b class A rootStyle class B,C,D,E,F,G categoryStyle class B1,B2,B3,B4,B5,B6,C1,C2,C3,C4,C5,C6,D1,D2,D3,D4,E1,E2,E3,E4,F1,F2,F3,F4 itemStyle ``` 추가 설정 요구사항 - 각 서비스는 독립적인 Dockerfile과 CI/CD 파이프라인 - 공통 패키지 변경 시 영향받는 앱만 재빌드 - 타입 체크, 린팅, 테스트 병렬 실행 - 의존성 그래프 최적화로 빌드 시간 최소화 - 개발 환경 Hot Reload 지원 - 프로덕션 빌드 최적화 (트리 쉐이킹, 코드 분할)" ``` **Turborepo 고급 설정** ```json { "name": "collabspace", "version": "0.1.0", "private": true, "workspaces": [ "apps/*", "packages/*", "tools/*" ], "scripts": { "build": "turbo run build", "dev": "turbo run dev --parallel", "test": "turbo run test", "test:e2e": "turbo run test:e2e", "lint": "turbo run lint", "type-check": "turbo run type-check", "clean": "turbo run clean && rm -rf node_modules", "format": "prettier --write .", "docker:dev": "docker-compose -f docker-compose.dev.yml up", "docker:prod": "docker-compose -f docker-compose.prod.yml up", "k8s:deploy": "kubectl apply -k infrastructure/kubernetes/overlays/dev", "seed": "turbo run seed", "migrate": "turbo run migrate", "generate": "turbo run generate" }, "devDependencies": { "@turbo/gen": "^1.10.0", "turbo": "^1.10.0", "prettier": "^3.0.0", "husky": "^8.0.3", "lint-staged": "^14.0.0" }, "engines": { "node": ">=20.0.0", "pnpm": ">=8.0.0" }, "packageManager": "pnpm@8.10.0" } ``` **turbo.json 엔터프라이즈 설정** ```json { "$schema": "https://turbo.build/schema.json", "globalDependencies": ["**/.env.*local"], "pipeline": { "build": { "dependsOn": ["^build"], "outputs": [".next/**", "!.next/cache/**", "dist/**"], "env": ["NODE_ENV", "API_URL", "DATABASE_URL"] }, "test": { "dependsOn": ["^build"], "outputs": ["coverage/**"], "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "**/*.test.*"] }, "test:e2e": { "dependsOn": ["build"], "cache": false }, "lint": { "outputs": [] }, "type-check": { "dependsOn": ["^build"], "outputs": [] }, "dev": { "cache": false, "persistent": true }, "clean": { "cache": false }, "migrate": { "cache": false }, "seed": { "dependsOn": ["migrate"], "cache": false }, "generate": { "outputs": ["generated/**"] } }, "remoteCache": { "signature": true } } ``` ### 개발 환경 자동화 개발 환경 자동화는 새로운 팀원이 최소한의 수동 작업으로 개발을 시작할 수 있도록 하는 중요한 투자입니다. 자동화된 환경 설정은 인적 오류를 줄이고, 일관된 개발 환경을 보장하며, 팀의 전반적인 생산성을 향상시킵니다. **자동화의 핵심 목표** 1. **제로 설정 온보딩**: 저장소 클론 후 한 번의 명령으로 개발 시작 가능 2. **환경 일관성**: 모든 개발자가 동일한 환경에서 작업 3. **의존성 자동 관리**: 필요한 도구와 서비스 자동 설치 및 설정 4. **검증 시스템**: 설정 완료 후 자동 검증으로 문제 조기 발견 5. **문서 동기화**: 설정 과정과 문서의 자동 동기화 **개발 환경 구성 요소** - **런타임 환경**: Node.js, 패키지 매니저, 개발 도구 - **데이터베이스**: 로컬 개발용 데이터베이스와 시드 데이터 - **외부 서비스**: Redis, Elasticsearch 등 필수 인프라 - **개발 도구**: IDE 설정, 디버거, 린터, 포매터 - **테스트 환경**: 단위 테스트 및 통합 테스트 실행 환경 ```bash claude "개발자 온보딩을 위한 완전 자동화된 개발 환경을 구성해줘. 자동화 범위 1. 환경 요구사항 자동 확인 및 설치 - Node.js 20+ LTS - pnpm 8+ - Docker & Docker Compose - VS Code 확장 프로그램 2. 프로젝트 초기 설정 - 의존성 설치 (pnpm install) - 환경 변수 설정 (.env 파일 생성) - 데이터베이스 초기화 (Docker Compose) - 시드 데이터 삽입 3. 개발 도구 설정 - Git 훅 설정 (Husky) - VS Code 설정 동기화 - 디버깅 설정 구성 - 테스트 데이터베이스 준비 4. 검증 프로세스 - 모든 서비스 빌드 테스트 - 기본 E2E 테스트 실행 - 코드 품질 검사 - 성능 벤치마크 기준 확인 스크립트 구현 - setup.sh (Linux/macOS) - setup.ps1 (Windows PowerShell) - Makefile (크로스 플랫폼 명령) - GitHub Codespaces 설정 - Docker 개발 컨테이너" ``` **자동화 설정 스크립트** ```bash #!/bin/bash # setup.sh - 개발 환경 자동 설정 set -e echo "🚀 CollabSpace 개발 환경 설정 시작..." # 1. 시스템 요구사항 확인 echo "📋 시스템 요구사항 확인 중..." check_command() { if ! command -v $1 &> /dev/null; then echo "❌ $1이 설치되지 않았습니다. 설치 가이드: $2" exit 1 else echo "✅ $1 확인됨" fi } check_command "node" "https://nodejs.org/" check_command "pnpm" "npm install -g pnpm" check_command "docker" "https://docs.docker.com/get-docker/" check_command "docker-compose" "https://docs.docker.com/compose/install/" # Node.js 버전 확인 NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1) if [ "$NODE_VERSION" -lt 20 ]; then echo "❌ Node.js 20+ 필요. 현재 버전: $(node --version)" exit 1 fi # 2. 의존성 설치 echo "📦 의존성 설치 중..." pnpm install # 3. 환경 변수 설정 echo "⚙️ 환경 변수 설정 중..." if [ ! -f .env.local ]; then cp .env.example .env.local echo "📝 .env.local 파일이 생성되었습니다. 필요한 값들을 설정해주세요." fi # 4. 데이터베이스 초기화 echo "🗄️ 개발 데이터베이스 초기화 중..." docker-compose -f docker-compose.dev.yml up -d db redis elasticsearch # 데이터베이스 준비 대기 echo "⏳ 데이터베이스 준비 대기 중..." sleep 30 # 5. Prisma 마이그레이션 및 시드 echo "🔄 데이터베이스 마이그레이션 실행 중..." pnpm run migrate:dev pnpm run seed # 6. Git 훅 설정 echo "🔧 Git 훅 설정 중..." pnpm run prepare # 7. VS Code 설정 echo "💻 VS Code 설정 동기화 중..." if command -v code &> /dev/null; then # 추천 확장 프로그램 설치 code --install-extension bradlc.vscode-tailwindcss code --install-extension prisma.prisma code --install-extension ms-vscode.vscode-typescript-next code --install-extension esbenp.prettier-vscode code --install-extension ms-vscode.vscode-eslint echo "✅ VS Code 확장 프로그램 설치 완료" fi # 8. 개발 서버 시작 가능 여부 확인 echo "🧪 설정 검증 중..." pnpm run build # 9. 개발 서버 시작 echo "🎉 설정 완료! 개발 서버를 시작합니다..." echo "" echo "다음 명령어로 개발을 시작할 수 있습니다:" echo " pnpm dev - 모든 서비스 개발 모드 시작" echo " pnpm test - 테스트 실행" echo " pnpm lint - 코드 품질 검사" echo " pnpm type-check - TypeScript 타입 검사" echo "" echo "📚 문서: http://localhost:3001/docs" echo "🔍 API: http://localhost:3000/api" echo "💻 웹 앱: http://localhost:3000" echo "" # 선택적으로 개발 서버 시작 read -p "지금 개발 서버를 시작하시겠습니까? (y/N): " -n 1 -r echo if [[ $REPLY =~ ^[Yy]$ ]]; then pnpm dev fi ``` ### 포괄적인 CLAUDE.md 작성 프로젝트의 CLAUDE.md는 Claude Code가 프로젝트의 맥락을 완전히 이해하고 일관된 품질의 코드를 생성할 수 있도록 하는 핵심 문서입니다. 이 문서는 단순한 설정 파일을 넘어서 프로젝트의 지식 베이스 역할을 수행합니다. **CLAUDE.md의 전략적 중요성** 1. **컨텍스트 제공**: AI가 프로젝트의 비즈니스 로직과 기술적 맥락을 이해 2. **일관성 보장**: 모든 생성되는 코드가 프로젝트 표준을 준수 3. **지식 보존**: 팀의 암묵적 지식을 명문화하여 보존 4. **온보딩 가속화**: 새로운 팀원이 프로젝트를 빠르게 이해 5. **품질 향상**: 코드 리뷰 기준과 모범 사례를 명확히 정의 **엔터프라이즈급 CLAUDE.md 구성 요소** - **비즈니스 맥락**: 프로젝트 목표, 사용자, 핵심 가치 제안 - **기술 아키텍처**: 시스템 설계, 패턴, 제약사항 - **코딩 표준**: 네이밍 규칙, 코드 스타일, 모범 사례 - **보안 가이드라인**: 인증, 데이터 보호, 취약점 방지 - **성능 기준**: 응답 시간, 처리량, 리소스 사용량 목표 - **테스트 전략**: 테스트 유형, 커버리지, 자동화 정책 엔터프라이즈급 프로젝트에서는 특히 상세하고 체계적인 가이드라인이 필요합니다. 이는 대규모 팀에서 일관된 코드 품질을 유지하고, 복잡한 비즈니스 요구사항을 정확히 반영하기 위해서입니다. ```bash claude "CollabSpace 프로젝트를 위한 포괄적인 CLAUDE.md를 작성해줘. 포함 내용 1. 프로젝트 개요와 비즈니스 목표 2. 기술 아키텍처 요약 3. 코딩 표준과 컨벤션 4. 서비스별 특화 가이드라인 5. 보안 및 성능 요구사항 6. 테스트 전략 7. 배포 프로세스 8. 트러블슈팅 가이드 각 섹션은 구체적인 예시와 함께 실무에서 바로 적용 가능한 수준으로 작성해줘." ``` **생성된 포괄적인 CLAUDE.md** ````markdown # CollabSpace 엔터프라이즈 협업 플랫폼 개발 가이드 ## 프로젝트 개요 CollabSpace는 1000+ 동시 사용자를 지원하는 엔터프라이즈급 실시간 협업 플랫폼입니다. Slack의 실시간 커뮤니케이션과 Notion의 구조화된 정보 관리를 결합한 차세대 협업 도구입니다. ### 핵심 가치 제안 - **실시간 협업**: WebSocket 기반 즉각적인 커뮤니케이션 - **통합 워크플로우**: 채팅, 프로젝트 관리, 파일 공유를 하나의 플랫폼에서 - **엔터프라이즈 보안**: 제로 트러스트, 종단간 암호화, SOC 2 준수 - **무한 확장성**: 마이크로서비스 아키텍처로 수평적 확장 가능 ### 타겟 사용자 - 중대형 기업의 개발팀 (50-5000명) - 원격 우선 조직 - 애자일/DevOps 문화를 가진 팀 ## 기술 아키텍처 ### 시스템 아키텍처 ```mermaid %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%% graph TB subgraph clients [클라이언트 계층] A[Web
Next.js] B[Mobile
React Native] C[Desktop
Electron] end subgraph gateway [API Gateway 계층] D[API Gateway
Kong/Istio
인증 | 라우팅 | 로드밸런싱 | 모니터링] end subgraph services [마이크로서비스 계층] E[Auth] F[User] G[Workspace] H[Chat] I[File] J[Notification] end subgraph data [데이터 계층] K[PostgreSQL] L[Redis] M[Elasticsearch] N[MinIO] O[Kafka] end A --> D B --> D C --> D D --> E D --> F D --> G D --> H D --> I D --> J E --> K F --> K G --> K H --> L I --> N J --> O classDef clientStyle fill:#e2e8f0,stroke:#334155,stroke-width:2px,color:#1e293b classDef gatewayStyle fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#1e293b classDef serviceStyle fill:#cbd5e1,stroke:#475569,stroke-width:1px,color:#1e293b classDef dataStyle fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#64748b class A,B,C clientStyle class D gatewayStyle class E,F,G,H,I,J serviceStyle class K,L,M,N,O dataStyle ``` ### 기술 스택 - **Frontend**: Next.js 14, TypeScript, Tailwind CSS, Zustand - **Backend**: Node.js 20, Fastify, Prisma, Socket.io - **Database**: PostgreSQL 15, Redis 7, Elasticsearch 8 - **Infrastructure**: Docker, Kubernetes, AWS - **Monitoring**: Prometheus, Grafana, Jaeger ## 코딩 표준과 컨벤션 ### TypeScript 규칙 ```typescript // ✅ 좋은 예: 명시적 타입, 인터페이스 우선 interface UserCreateInput { email: string; name: string; role: UserRole; } async function createUser(input: UserCreateInput): Promise { // 구현 } // ❌ 나쁜 예: any 타입, 암시적 반환 function createUser(input: any) { // 구현 } ``` ### 에러 처리 패턴 ```typescript // 커스텀 에러 클래스 사용 export class BusinessError extends Error { constructor( public code: string, message: string, public statusCode: number = 400 ) { super(message); this.name = 'BusinessError'; } } // Result 타입 패턴 type Result = | { ok: true; value: T } | { ok: false; error: E }; // 사용 예시 async function updateUser(id: string, data: UpdateUserInput): Promise> { try { const user = await prisma.user.update({ where: { id }, data }); return { ok: true, value: user }; } catch (error) { return { ok: false, error: new BusinessError('USER_NOT_FOUND', 'User not found', 404) }; } } ``` ### 네이밍 컨벤션 - **파일명**: kebab-case (`user-service.ts`, `auth-middleware.ts`) - **컴포넌트**: PascalCase (`UserProfile.tsx`, `ChatWindow.tsx`) - **함수/변수**: camelCase (`getUserById`, `isAuthenticated`) - **상수**: SCREAMING_SNAKE_CASE (`MAX_FILE_SIZE`, `API_TIMEOUT`) - **타입/인터페이스**: PascalCase (`UserDto`, `AuthPayload`) ### 폴더 구조 규칙 ``` src/ ├── controllers/ # HTTP 요청 처리 (얇은 계층) ├── services/ # 비즈니스 로직 ├── repositories/ # 데이터 액세스 ├── models/ # 도메인 모델 ├── dto/ # Data Transfer Objects ├── middleware/ # Express/Fastify 미들웨어 ├── utils/ # 공통 유틸리티 └── types/ # TypeScript 타입 정의 ``` ## 서비스별 특화 가이드라인 ### 인증 서비스 (auth-service) // JWT 토큰 처리 - Access Token: 15분 만료 - Refresh Token: 7일 만료 - 토큰 로테이션 정책 적용 - Redis에 블랙리스트 관리 // 보안 요구사항 - bcrypt rounds: 12 - 비밀번호 정책: 최소 12자, 대소문자+숫자+특수문자 - 2FA 지원 (TOTP) - 계정 잠금: 5회 실패 시 15분 잠금 ### 실시간 통신 서비스 (chat-service) // Socket.io 이벤트 네이밍 - 서버 → 클라이언트: `:` (예: `message:created`) - 클라이언트 → 서버: `:` (예: `create:message`) // 네임스페이스 구조 /workspace/:workspaceId ├── /channel/:channelId ├── /direct/:userId └── /presence // 메시지 처리 - 메시지 큐잉: Redis Streams - 배치 처리: 100ms 디바운싱 - 최대 메시지 크기: 10KB - 파일 첨부: 별도 업로드 후 참조 ### 파일 서비스 (file-service) // 업로드 제한 - 최대 파일 크기: 100MB - 허용 확장자 화이트리스트 - 바이러스 스캔 필수 - 이미지 자동 리사이징 // 저장 전략 - 원본: MinIO/S3 - 썸네일: CDN 캐시 - 메타데이터: PostgreSQL - 임시 파일: 24시간 후 자동 삭제 ## 보안 요구사항 ### 인증/인가 - OAuth 2.0 + OpenID Connect - Role-Based Access Control (RBAC) - Attribute-Based Access Control (ABAC) - API Key 관리 (해싱, 만료, 회전) ### 데이터 보호 - 전송 중 암호화: TLS 1.3 - 저장 시 암호화: AES-256-GCM - PII 필드 마스킹 - 감사 로그 (불변성 보장) ### 보안 헤더 ```typescript // 필수 보안 헤더 app.use(helmet({ contentSecurityPolicy: { directives: { defaultSrc: ["'self'"], styleSrc: ["'self'", "'unsafe-inline'"], scriptSrc: ["'self'"], imgSrc: ["'self'", "data:", "https:"], }, }, hsts: { maxAge: 31536000, includeSubDomains: true, preload: true, }, })); ``` ## 성능 요구사항 ### API 응답 시간 - P50: < 50ms - P95: < 200ms - P99: < 500ms ### 처리량 - 일반 API: 10,000 RPS - 검색 API: 1,000 RPS - WebSocket: 100,000 동시 연결 ### 캐싱 전략 // Redis 캐싱 계층 - 사용자 세션: 15분 - 권한 정보: 5분 - 자주 조회되는 데이터: 1시간 - 검색 결과: 10분 // 캐시 무효화 - Write-through 패턴 - 이벤트 기반 무효화 - TTL 기반 만료 ## 테스트 전략 ### 테스트 피라미드 ``` E2E (10%) 통합 테스트 (30%) 단위 테스트 (60%) ``` ### 테스트 커버리지 목표 - 전체: 80% 이상 - 핵심 비즈니스 로직: 95% 이상 - 유틸리티 함수: 100% ### 테스트 작성 규칙 ```typescript // 테스트 구조: AAA 패턴 describe('UserService', () => { describe('createUser', () => { it('should create a new user with valid input', async () => { // Arrange const input = { email: 'test@example.com', name: 'Test User' }; // Act const result = await userService.createUser(input); // Assert expect(result.ok).toBe(true); expect(result.value.email).toBe(input.email); }); it('should return error for duplicate email', async () => { // 구현 }); }); }); ``` ## 모니터링과 로깅 ### 구조화된 로깅 ```typescript // 로그 레벨과 컨텍스트 logger.info('User created', { userId: user.id, email: user.email, timestamp: new Date().toISOString(), traceId: context.traceId, }); // 에러 로깅 logger.error('Failed to create user', { error: error.message, stack: error.stack, input: sanitizeInput(input), traceId: context.traceId, }); ``` ### 메트릭 수집 ```typescript // Prometheus 메트릭 - API 응답 시간 히스토그램 - 동시 사용자 수 게이지 - 에러율 카운터 - 비즈니스 메트릭 (가입, 활성 사용자 등) ``` ## 배포 프로세스 ### 환경별 설정 - **개발**: 자동 배포, 디버깅 활성화 - **스테이징**: 프로덕션 미러링, 성능 테스트 - **프로덕션**: 블루-그린 배포, 자동 롤백 ### 배포 체크리스트 1. [ ] 모든 테스트 통과 2. [ ] 보안 스캔 완료 3. [ ] 성능 벤치마크 기준 충족 4. [ ] 문서 업데이트 5. [ ] 데이터베이스 마이그레이션 검증 6. [ ] 롤백 계획 수립 ## 트러블슈팅 가이드 ### 일반적인 문제 해결 1. **메모리 누수**: 힙 덤프 분석, 이벤트 리스너 확인 2. **느린 쿼리**: EXPLAIN ANALYZE, 인덱스 최적화 3. **WebSocket 연결 끊김**: 하트비트 확인, 네트워크 정책 4. **높은 CPU 사용률**: 프로파일링, 동기 작업 확인 ### 디버깅 도구 - **로컬**: Chrome DevTools, VS Code 디버거 - **원격**: Node.js Inspector, 원격 디버깅 - **프로덕션**: APM 도구, 분산 추적 ## 팀 협업 규칙 ### 코드 리뷰 - PR은 200줄 이하로 유지 - 최소 2명의 승인 필요 - 24시간 내 리뷰 완료 - 건설적이고 구체적인 피드백 ### 커밋 메시지 ``` ():