Template

Files

T

ttipo 6306160dda refactor: .claude 규칙 체계를 skills·rules 구조로 재편

- 슬래시 커맨드(nestjs/vue3/flutter)를 정식 스킬(.claude/skills)로 전환하고
  docker 스킬을 신설(루트 command.md 이관)
- 공통 규칙을 .claude/rules 로 모듈화(coding-common·response-format·error-codes·
  git-convention·security·env-structure·testing·checklist)하고 CLAUDE.md 에서 @import
- 파일·식별자 네이밍 규약, 테스트 규칙 추가
- .claude/settings.json(권한·환경) 추가
- CLAUDE.md·README.md 참조 갱신, 단독 실행(non-Docker) 안내 정리

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-28 13:58:01 +09:00

5.2 KiB

Raw Blame History

풀스택 모노레포 기본 템플릿

NestJS(백엔드) · Vue 3(웹) · Flutter(모바일)를 하나의 저장소에서 운영하는 풀스택 템플릿입니다. 세 클라이언트는 동일한 표준 응답 포맷과 공통 에러 코드 맵을 공유하며, Docker Compose로 한 번에 구동됩니다.

구성

디렉터리	스택	역할	포트(기본)
`backend/`	NestJS + TypeORM	REST API 서버	3000
`frontend/`	Vue 3 + Vite	웹 프론트엔드	5173
`flutter/`	Flutter + Riverpod	모바일 앱	-
`db`	PostgreSQL	데이터베이스	5432
`redis`	Redis	캐시 / 세션	6379

사전 요구사항

Docker / Docker Compose — backend·frontend·db·redis 구동
Flutter SDK ^3.11 — 모바일 앱 실행용 (compose 대상 아님)

빠른 시작 (Docker)

# 1) 환경변수 파일 생성 (예제 복사)
#    실제 설정값은 루트 .env.development 한 곳에서 관리한다 (SSOT).
#    backend/frontend 는 docker-compose 가 값을 주입하므로 예제만 복사하면 된다.
cp .env.development.example .env.development                       # ← 여기에만 값 입력
cp backend/.env.development.example backend/.env.development       # (존재 필요: JWT 등 고유 시크릿)
# frontend 는 compose 가 빌드 시 값을 주입하므로 자체 env 복사 불필요

# 2) 개발 환경 기동 (코드만 수정 시)
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d

# 3) 의존성 변경 시에만 --build
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d --build

기동 후:

웹: http://localhost:5173
API: http://localhost:3000/api
Swagger 문서: http://localhost:3000/api-docs

전체 실행/배포 명령어는 .claude/skills/docker/SKILL.md 참조.

모바일 앱 실행 (Flutter)

Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합니다.

cd flutter && cp .env.example .env && flutter pub get && flutter run

flutter/.env 의 API_URL 을 백엔드 주소로 설정합니다. (Android 에뮬레이터는 http://10.0.2.2:3000/api)

환경변수

.env* 는 커밋하지 않습니다. 각 디렉터리의 *.example 파일을 복사해 사용하세요.

루트 .env.{env} 가 단일 진실 공급원(SSOT) 입니다. backend·frontend 는 docker-compose 가 루트 값을 주입하므로 자체 env 에 값을 중복 작성하지 않습니다. (자세한 위임 구조는 CLAUDE.md 의 "환경변수 구조" 참조)

파일	용도	값 작성 위치
`.env.{env}.example`	루트 — 모든 설정의 SSOT (compose 주입)	✅ 여기에 작성
`backend/.env.{env}.example`	백엔드 — 고유 시크릿(JWT 등)만	최소 (존재 필수)
`frontend/.env.{env}.example`	프론트 — 빌드 시 루트 `BACKEND_API_URL` 주입	작성 불필요
`flutter/.env.example`	모바일 — `API_URL` (compose 비대상)	✅ 독립 관리

{env} = development | production

표준 응답 포맷

// 성공
{ "success": true, "data": { /* ... */ } }
// 실패
{ "success": false, "error": { "code": "VAL_001", "message": "..." } }

에러 코드 맵과 코딩 규칙 전문은 CLAUDE.md 및 .claude/rules/·.claude/skills/ 의 규칙 문서를 참고하세요.

개발 규칙

영역	문서
공통/보안	`CLAUDE.md` · `.claude/rules/`
NestJS	`.claude/skills/nestjs/SKILL.md`
Vue 3	`.claude/skills/vue3/SKILL.md`
Flutter	`.claude/skills/flutter/SKILL.md`
Docker	`.claude/skills/docker/SKILL.md`

디렉터리 구조

.
├── backend/    # NestJS API (Controller / Service / DTO / 공통 필터·인터셉터)
├── frontend/   # Vue 3 (pages / components / composables / stores / router)
├── flutter/    # Flutter (core / features / widgets)
├── docker-compose.yml         # 베이스 정의
├── docker-compose.dev.yml     # 개발 오버라이드 (핫리로드, 포트 노출)
├── CLAUDE.md   # 프로젝트 개요 + 공통 규칙 @import
└── .claude/
    ├── settings.json   # Claude Code 권한·환경 설정
    ├── rules/          # 공통 규칙 (코딩·응답 포맷·에러 코드·커밋·보안·환경변수)
    └── skills/         # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)

5.2 KiB Raw Blame History