비개발자도 원클릭! 어디서든 Cursor 개발 가능한 최적의 풀스택 환경 만들기 설계 시도

아래 TRD를 다음 기준에 따라 검토하고 개선하라. 개선할 포인트를 간단하게 설명한뒤, 모두 설명하고 나서 완성본을 응답하라.

- Next.js 15 버전 최신 권장사항에 맞는 structure로 구성.
- 가장 빠르게 MVP를 출시하기 위해 기슬스택과 복잡도 등이 최소한으로 설계되었는지 점검.
- 파일이 충돌이 일어나거나 오류 발생 가능성 점검.
---
# 기술 요구 사항 문서 (TRD)

## 1. 기술 개요
### 현대적 기술 요구사항 프레임워크 개요
본 프로젝트는 안전성, 확장성, 규정 준수를 핵심 가치로 삼는 현대적 소프트웨어 아키텍처 프레임워크를 채택합니다. 주요 원칙은 다음과 같습니다:
- **SMART 목표 기반 관리**: 모든 기술 요구사항은 비즈니스 목표에 직접적으로 연결되며, 구체적(Specific), 측정 가능(Measurable), 달성 가능(Achievable), 관련성(Relevant), 시간 제한(Time-bound)이 명확히 정의됩니다.
- **API 우선 설계**: 모든 서비스는 REST/GraphQL API를 통해 표준화된 방식으로 기능을 제공합니다.
- **관리형 서비스 우선**: Supabase, Vercel, Netlify 등 관리형 플랫폼을 우선 사용하여 운영 오버헤드를 최소화합니다.
- **보안 및 규정 준수 내재화**: 개발 및 배포 전 단계에 보안(비밀 관리, 자동 스캐닝)과 법적 데이터 보호(HIPAA, 개인정보보호법 등)를 일관되게 적용합니다.
- **자동화와 계층화된 방어**: 종속성 관리, 테스트, 보안 스캐닝, 배포 등 모든 품질 보증 프로세스에 자동화를 적용하고, 단일 실패 지점을 없애기 위해 계층화된 도구 및 전략을 병행합니다.
- **비용 인식 및 최적화**: 플랫폼 및 API, 내부 도구의 라이선스 및 사용 비용을 사전에 분석하고, 운영 중 지속적으로 모니터링합니다.

### 프로젝트 개요
본 프로젝트는 "AI+자동화 중심 DevOps·협업·배포·리뷰 완전 자동화"를 목표로, 개발 환경 구축 및 프로젝트 초기 설정을 원클릭으로 자동화하는 풀스택 개발 인프라를 구축합니다. GitHub 모노레포 구조를 활용하여 `Cursor-Core` 공통 인프라와 `Cursor-Medical`, `Cursor-Webapp`, `Cursor-Agents`와 같은 전문 도메인 레포지토리를 효율적으로 관리하고, AI 도구 및 배포 파이프라인을 통합하여 개발 생산성을 극대화합니다. 핵심은 최소한의 기술 스택으로 요구사항을 충족하며, 과도한 엔지니어링을 지양하는 것입니다.

### 핵심 기술 스택
주요 기술 스택은 PowerShell, Bash 스크립트, Node.js, Python, Docker, Supabase, GitHub Actions, Vercel/Netlify 등으로 구성됩니다. 이는 신속한 환경 구축과 자동화된 배포 파이프라인 구현에 최적화된 조합입니다.

### 주요 기술 목표
- **성능**: 신규 PC 환경 구축 시간 30분 이내 달성.
- **확장성**: 모노레포 구조를 통해 신규 도메인 레포 추가 및 확장을 용이하게 합니다.
- **안정성**: 자동화 스크립트 오류율 2% 미만 유지 및 GitHub Actions를 통한 CI/CD 안정성 확보.
- **보안**: `.env` 파일 관리 및 GitHub Secrets를 활용한 API 키 보안 강화.
- **SMART 기반 목표 명확화**: 모든 기술 목표는 상위 비즈니스 목표와 직접 매핑되며, 구체적(Specific), 측정 가능(Measurable), 달성 가능(Achievable), 관련성(Relevant), 시간 제한(Time-bound)이 명확히 정의됩니다.
- **자동화 수준**: 종속성 업데이트, 보안 스캐닝, 테스트, 배포 등 핵심 품질 게이트는 자동화 도구(Dependabot/Renovate, Snyk, Trivy, GitHub Actions, CodeRabbit 등)로 통합 관리합니다.
- **테스트 커버리지**: 신규 코드의 단위 테스트 커버리지 80% 이상, 주요 서비스 간 인터랙션에 대해 통합 테스트 및 주요 사용자 시나리오에 E2E 테스트 필수화.

### 주요 기술 가정
- 모든 개발 환경은 Windows 10+, macOS 13+, Ubuntu 20.04+, WSL2를 지원합니다.
- 외부 연동 서비스(Vooster, EasyNext, CodeRabbit, n8n, Make.com, Retool Cloud, Vercel, Netlify)의 API 안정성을 가정합니다.
- GitHub 모노레포 구조는 Submodule 또는 `gh deploy`를 통해 효율적으로 관리될 수 있습니다.

## 2. 기술 스택

| Category | Technology / Library | Reasoning (Why it's chosen for this project) |
| :---------------- | :--------------------------- | :----------------------------------------------------------- |
| **스크립트 언어** | PowerShell 7 | Windows 환경에서 강력한 시스템 자동화 및 스크립팅 기능을 제공합니다. |
| | Bash 5 | macOS 및 Linux(Ubuntu, WSL2) 환경에서 표준적인 시스템 자동화 및 스크립팅 기능을 제공합니다. |
| **런타임 환경** | Node.js 18 (LTS) | `npm`을 통한 패키지 관리 및 Supabase CLI, Vercel CLI 등 다양한 개발 도구의 실행 환경으로 활용됩니다. |
| | Python | `sns-auto-post.py`와 같은 예제 스크립트 실행 및 데이터 처리, AI/ML 관련 기능 확장에 용이합니다. |
| **컨테이너** | Docker | 개발 환경의 일관성을 보장하고, 향후 복잡한 서비스 배포에 활용될 수 있습니다. |
| **데이터베이스** | Supabase (PostgreSQL) | 오픈 소스 기반의 강력한 PostgreSQL 데이터베이스와 인증, 스토리지 기능을 제공하여 빠른 개발 및 확장에 적합합니다. |
| **CI/CD & 자동화** | GitHub Actions | 코드 변경 시 자동 테스트, 빌드, 배포를 위한 강력하고 유연한 CI/CD 파이프라인을 제공합니다. |
| **배포 플랫폼** | Vercel | 프론트엔드 웹 애플리케이션의 빠르고 쉬운 배포 및 자동화된 CI/CD 연동을 지원합니다. |
| | Netlify | Vercel과 유사하게 정적 사이트 및 프론트엔드 애플리케이션 배포에 용이하며, 다양한 빌드 기능을 제공합니다. |
| **외부 연동** | REST API | Vooster, EasyNext, CodeRabbit 등 다양한 외부 AI 및 협업 도구와의 표준적인 연동 방식입니다. |
| | GraphQL | Supabase와의 효율적인 데이터 통신 및 복잡한 쿼리 처리에 활용됩니다. |
| **워크플로우 자동화** | n8n | 다양한 서비스 간의 자동화된 워크플로우를 시각적으로 구성하고 실행할 수 있습니다. |
| | Make.com | n8n과 유사하게 다양한 앱과 서비스를 연결하여 자동화된 워크플로우를 구축하는 데 사용됩니다. |
| **대시보드** | Retool Cloud | 빠르고 쉽게 내부 도구 및 대시보드를 구축할 수 있어 병원 마케팅 대시보드 구현에 적합합니다. |

## 3. 시스템 아키텍처 설계

### 최상위 빌딩 블록
- **클라이언트 환경**: 개발자가 사용하는 로컬 PC 환경으로, `quick-install` 스크립트를 통해 필요한 모든 개발 도구와 환경이 자동 설정됩니다.
- **GitHub 레포지토리**: `cursor_fullstack_infra` 모노레포를 중심으로 `Cursor-Core`와 각 도메인 레포(Medical, Webapp, Agents)가 관리됩니다. GitHub Actions를 통해 CI/CD 및 자동화가 이루어집니다.
- **Supabase**: 프로젝트의 핵심 데이터베이스(PostgreSQL) 및 스토리지, 인증 기능을 제공합니다.
- **외부 서비스 연동**: Vooster, EasyNext, CodeRabbit, n8n, Make.com, Retool Cloud, Vercel, Netlify 등 다양한 외부 서비스와 API 연동을 통해 자동화된 워크플로우 및 기능을 제공합니다.

### 최상위 컴포넌트 상호작용 다이어그램

```mermaid
graph TD
    A[개발자 로컬 PC] --> B[quick-install 스크립트]
    B --> C[GitHub 레포지토리]
    C --> D[GitHub Actions]
    C --> E[Supabase]
    D --> E
    D --> F[Vercel/Netlify]
    C --> G[외부 AI/자동화 도구]
    G --> H[Retool Cloud]
    E --> H
```

- **개발자 로컬 PC**: `quick-install` 스크립트를 실행하여 개발 환경을 설정합니다.
- **`quick-install` 스크립트**: Git, Node, Python, Docker, gcloud, Supabase CLI 등을 설치하고, `.env` 파일을 생성하며, GitHub 레포지토리를 초기화합니다.
- **GitHub 레포지토리**: `Cursor-Core` 및 전문 레포(Medical, Webapp, Agents)를 포함하며, 코드 변경 시 GitHub Actions를 트리거합니다.
- **GitHub Actions**: CI/CD 파이프라인을 실행하여 테스트, Supabase 마이그레이션, Vercel/Netlify 배포를 자동화하고, CodeRabbit 자동 리뷰를 연동합니다.
- **Supabase**: 데이터베이스, 스토리지, 인증 서비스를 제공하며, `supabase-init` 스크립트를 통해 프로젝트별 DB가 생성됩니다.
- **Vercel/Netlify**: 웹 애플리케이션의 자동 배포를 담당하며, GitHub Actions와 연동됩니다.
- **외부 AI/자동화 도구**: Vooster, EasyNext, CodeRabbit, n8n, Make.com 등과 REST/GraphQL API를 통해 연동되어 AI 기반 코드 리뷰, 워크플로우 자동화 등의 기능을 제공합니다.
- **Retool Cloud**: Supabase 데이터와 연동하여 병원 마케팅 대시보드를 제공합니다.

### 코드 구성 및 규칙
**도메인 중심 조직화 전략**
- **도메인 분리**: 비즈니스 도메인(예: `Cursor-Medical`, `Cursor-Webapp`, `Cursor-Agents`)별로 코드를 분리하여 관리합니다. 각 도메인은 독립적인 기능을 수행하며, `Cursor-Core`는 공통 인프라를 제공합니다.
- **계층 기반 아키텍처**: 각 도메인 내에서 프레젠테이션, 비즈니스 로직, 데이터 접근, 인프라 계층으로 관심사를 분리합니다.
- **기능 기반 모듈**: 특정 기능과 관련된 파일들을 하나의 모듈로 묶어 관리하여 응집도를 높입니다.
- **공유 컴포넌트**: 공통 유틸리티, 타입 정의, 재사용 가능한 스크립트 등은 `Cursor-Core` 내의 공유 모듈에 위치시킵니다.

**범용 파일 및 폴더 구조**
```
/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── deploy.yml
│       └── coderabbit-review.yml
├── Cursor-Core/
│   ├── scripts/
│   │   ├── quick-install.ps1
│   │   ├── quick-install.sh
│   │   ├── connect-ai-tools.ps1
│   │   ├── connect-ai-tools.sh
│   │   ├── supabase-init.ps1
│   │   ├── supabase-init.sh
│   │   ├── vercel-deploy.ps1
│   │   ├── vercel-deploy.sh
│   │   ├── netlify-deploy.ps1
│   │   └── netlify-deploy.sh
│   ├── .env.template
│   ├── README.md
│   └── shared/
│       ├── utils/
│       └── types/
├── Cursor-Medical/
│   ├── n8n-workflows/
│   │   └── instagram-sms-supabase.json
│   ├── retool-dashboards/
│   │   └── sns-performance.yaml
│   ├── python-examples/
│   │   └── sns-auto-post.py
│   └── README.md
├── Cursor-Webapp/
│   ├── templates/
│   ├── design-references/
│   └── README.md
├── Cursor-Agents/
│   ├── ai-agent-examples/
│   ├── mcp-server/
│   ├── workflow-examples/
│   └── README.md
├── .gitignore
└── README.md
```

### 데이터 흐름 및 통신 패턴
- **클라이언트-서버 통신**: `quick-install` 스크립트는 로컬 환경에서 실행되며, GitHub API, Supabase CLI, Vercel/Netlify CLI 등과 통신하여 환경 설정 및 배포를 수행합니다.
- **데이터베이스 상호작용**: Supabase CLI를 통해 로컬에서 DB 생성, 권한 설정, 마이그레이션이 이루어지며, 애플리케이션은 Supabase SDK를 통해 데이터에 접근합니다.
- **외부 서비스 통합**:
    - **AI 툴**: `connect-ai-tools` 스크립트는 `.env` 파일의 API 키를 읽어 Vooster, EasyNext, CodeRabbit의 REST API를 호출하여 연동을 설정합니다.
- **자동화된 테스트 및 검증**: GitHub Actions를 통해 스크립트 실행 후 `.cursor_check` 파일 생성 여부, CodeRabbit 리뷰 결과 등을 자동으로 검증하여 오류 발생 시 신속하게 인지하고 대응합니다.
- **종속성/보안 자동화**: 모든 저장소에서 Dependabot(기본) 또는 복잡한 모노레포에는 필요시 Renovate를 통한 종속성 자동 업데이트를 필수화합니다. 종속성 업데이트는 주간 단위로 그룹화, CODEOWNERS 기반 자동 리뷰어 지정, 고정 종속성 주석화 규칙을 적용합니다.
- **데이터 보안/법적 준수**: Supabase의 RLS(행 수준 보안) 및 RBAC, 데이터 암호화(AES-256), 익명화(비-프로덕션 데이터 집합), 각 관할권별 데이터 처리 기준(예: HIPAA, 대한민국 개인정보보호법/의료법)에 따라, 수집 동의, 보존 기간, 제3자 제공 제한, 환자 권리 보장, CCTV 안내 등 주요 요구사항을 준수합니다.
- **계층화된 테스트 표준화**: PowerShell(Pester), Bash(Bats-core) 기반 단위 테스트(커버리지 80% 이상), 중요 서비스 간 통합 테스트(전용 테스트 환경, 이벤트/엔드포인트 시뮬레이션), 주요 사용자 여정에 대한 E2E 테스트(Playwright, Allure Report 등) 구성 및 CI/CD 게이트 적용.

- **중앙 집중식 비밀 관리**: API 키, 데이터베이스 자격증명 등은 GitHub Secrets 및(필요시) 외부 비밀 관리 도구를 통해 관리되며, 자동 순환 정책을 적용합니다.
- **관찰 가능성 및 복원력**: 로그, 메트릭, 트레이스를 중앙 집중식 플랫폼(Grafana Loki, SigNoz, Datadog 등)에 연동하고, 경고 및 복구 런북을 운영 표준으로 채택합니다.
- **데이터 보안/법적 준수**: Supabase의 RLS(행 수준 보안) 및 RBAC, 데이터 암호화, 익명화, 각 관할권별 데이터 처리 기준(예: HIPAA, 개인정보보호법)을 준수합니다.
    - **배포 플랫폼**: Vercel/Netlify는 GitHub Webhook을 통해 코드 변경을 감지하고, GitHub Actions와 연동하여 자동 배포를 수행합니다.
- **데이터 동기화**: GitHub Actions를 통해 Supabase 마이그레이션 스크립트가 실행되어 DB 스키마 변경 사항을 동기화합니다.

## 4. 성능 및 최적화 전략

- **스크립트 실행 최적화**: `quick-install` 스크립트는 불필요한 종속성 설치를 최소화하고, 병렬 설치가 가능한 경우 이를 활용하여 실행 시간을 단축합니다.
- **캐싱 활용**: Node.js `npm` 및 Python `pip` 패키지 설치 시 캐싱을 활용하여 반복 설치 시간을 줄입니다.
- **경량화된 도구 선택**: 시스템 리소스를 적게 사용하는 CLI 기반 도구들을 우선적으로 선택하여 전체적인 환경 구축 속도를 향상시킵니다.
- **자동화된 테스트 및 검증**: GitHub Actions를 통해 스크립트 실행 후 `.cursor_check` 파일 생성 여부, CodeRabbit 리뷰 결과 등을 자동으로 검증하여 오류 발생 시 신속하게 인지하고 대응합니다.

## 5. 구현 로드맵 및 마일스톤

### 1단계: 기반 (MVP 구현)
- **핵심 인프라**: `quick-install.ps1/.sh` 스크립트 개발 (OS 감지, Git·Node·Python·Docker·gcloud·Supabase CLI 자동 설치).
- **필수 기능**: `.env` 자동 생성 및 API Key 입력 유도, GitHub 자동 init/add/commit/push 구현.
- **기본 보안**: `.env` 파일 `.gitignore` 처리 및 GitHub Secrets를 통한 API 키 관리.
- **개발 환경 설정**: GitHub Actions를 통한 기본적인 CI/CD 파이프라인 구성 (린트, 테스트).
- **온보딩/멘토링**: 신규 개발자 온보딩 시 표준화된 개발 환경 세팅, 첫날 사소한 버그 수정 과제(저위험 시작 과제), 관찰 가능성 도구(로깅/모니터링) 소개, 90일 시니어 멘토 배정, 회사 문화 및 보안 우선 사고 세션을 온보딩 프로세스에 포함합니다.
- **지속적 교육/SMART 목표**: 기술력 향상과 아키텍처/보안 원칙 내재화를 위해 정기적인 교육, 기술 스택/아키텍처 패턴/핵심 도구 소개, SMART 목표 기반 성과 평가 및 멘토-멘티 프로그램을 운영합니다.
## 6. 위험 평가 및 완화 전략

### 프로젝트 거버넌스 및 온보딩 표준
- **온보딩/멘토링**: 신규 개발자 온보딩 시 표준화된 개발 환경 세팅, 첫날 사소한 버그 수정 과제, 관찰 가능성 도구 소개, 90일 시니어 멘토 배정 등을 운영 표준으로 채택합니다.
- **지속적 교육/SMART 목표**: 기술력 향상과 아키텍처/보안 원칙 내재화를 위해 정기적인 교육과 SMART 목표 기반 역량 평가를 시행합니다.
- **고급 기능**: `connect-ai-tools` 스크립트 개발 (Vooster·EasyNext·CodeRabbit REST 연동), PR 생성 시 CodeRabbit 자동 리뷰 및 GitHub Check 등록.
- **성능 최적화**: 설치 스크립트 실행 시간 15분 이내 달성 목표.
- **향상된 보안**: GitHub Actions Encrypted Secrets 활용 강화.
- **모니터링 구현**: CLI 진행률 바, 실패 시 복구 가이드 출력 기능 구현.
- **예상 완료 시점**: M+2 ~ M+3

### 3단계: 확장 및 최적화
- **확장성 구현**: 신규 도메인 레포 추가 시 동일 스크립트 재사용 가능하도록 구조화.
- **고급 통합**: n8n JSON 워크플로우, Retool YAML 대시보드, Python 예제 (`sns-auto-post.py`) 통합 및 안정화.
- **엔터프라이즈 기능**: `Cursor-Agents` 레포 내 AI-Agent, MCP 서버, Workflow 예제 구현.
- **규정 준수 및 감사**: 의료법 준수 및 컴플라이언스 체크 모듈 개발 (향후 계획).
- **예상 완료 시점**: M+4 ~ M+6

## 6. 위험 평가 및 완화 전략

### 기술 위험 분석
- **기술 위험**: 다양한 OS(Windows, macOS, Linux) 및 버전별 스크립트 호환성 문제.
    - **완화 전략**: PowerShell 7 및 Bash 5와 같은 최신 버전 스크립트 언어 사용을 표준화하고, WSL2를 통한 Windows 환경에서의 Linux 호환성 확보. 각 OS별 충분한 테스트를 수행합니다.
- **성능 위험**: `quick-install` 스크립트의 실행 시간이 목표(15분)를 초과할 가능성.
    - **완화 전략**: 설치 스크립트의 병렬 처리, 불필요한 설치 항목 제거, 네트워크 의존성 최소화를 통해 최적화를 지속적으로 수행합니다.
- **보안 위험**: API 키 등 민감 정보 노출 위험.
    - **완화 전략**: `.env` 파일은 `.gitignore`에 포함하고, 실제 CI/CD 환경에서는 GitHub Secrets를 사용하여 민감 정보를 안전하게 관리합니다.
- **통합 위험**: 외부 서비스(Vooster, CodeRabbit 등) API 변경 또는 서비스 중단.
    - **완화 전략**: 외부 API의 버전 모니터링을 주기적으로 수행하고, API 변경 시 신속하게 스크립트를 업데이트합니다. 주요 외부 서비스에 대한 Fallback 또는 대체 서비스 고려.

### 프로젝트 제공 위험
- **일정 위험**: 복잡한 환경 설정 및 다양한 외부 서비스 연동으로 인한 개발 일정 지연.
    - **완화 전략**: MVP를 중심으로 단계별 개발 로드맵을 엄격히 준수하고, 각 단계별 마일스톤을 명확히 설정하여 진행 상황을 주기적으로 검토합니다.
- **자원 위험**: 스크립트 개발 및 유지보수에 필요한 전문 인력 부족.
    - **완화 전략**: PowerShell, Bash, Node.js, Python 등 범용적인 스크립트 언어를 사용하여 개발 인력 확보를 용이하게 하고, 문서화를 통해 온보딩 시간을 단축합니다.
- **품질 위험**: 자동화 스크립트의 오류율이 높아 사용자 경험 저하.
    - **완화 전략**: GitHub Actions를 통한 자동화된 테스트 및 검증 프로세스를 강화하고, 사용자 피드백을 적극적으로 수집하여 스크립트의 안정성을 지속적으로 개선합니다.
- **배포 위험**: 다양한 환경에서의 배포 파이프라인 구성 실패.
    - **완화 전략**: Vercel, Netlify 등 검증된 배포 플랫폼을 활용하고, GitHub Actions를 통해 배포 프로세스를 표준화하여 환경 간의 일관성을 유지합니다.
- **비상 계획**: 주요 스크립트 실패 시 사용자에게 명확한 오류 메시지와 복구 가이드를 제공하여 자가 해결을 돕습니다.