NestJS 프로젝트 설계 가이드

자동 활성화 시점

• NestJS 프로젝트 구조나 아키텍처 질문
• "어떤 기술 스택을 사용해야 하나요?"
• "모듈 구조는 어떻게 구성하나요?"
• Modular 아키텍처 설명 필요 시

---

기술 스택 권장사항

Core Framework

• NestJS (최신 stable 버전)
• TypeScript (strict mode)
• Node.js (LTS 버전)

데이터베이스

• TypeORM 또는 Prisma (ORM)
• PostgreSQL, MySQL, 또는 MongoDB

검증

• class-validator (DTO 검증)
• class-transformer (데이터 변환)

코드 품질 도구 선택 가이드

옵션	도구	적합한 상황
A	Biome (통합 도구)	신규 프로젝트, 빠른 설정, 대규모 코드베이스
B	ESLint + Prettier	기존 팀 표준 유지, NestJS 플러그인 필요, 세밀한 규칙 커스터마이징

테스팅

• Jest (단위/통합 테스트 - NestJS 기본)
• Supertest (E2E 테스트)

환경 관리

• @nestjs/config (환경 변수 관리)
• fnm 또는 nvm (Node.js 버전 관리)
• pnpm (패키지 매니저)

---

Modular 아키텍처 패턴

디렉토리 구조

확장 가능하고 유지보수하기 쉬운 Modular 아키텍처를 기본으로 사용합니다.

src/
├── main.ts                 # 애플리케이션 진입점
├── app.module.ts           # 루트 모듈
├── modules/                # 기능별 모듈
│   ├── auth/              # 인증 모듈
│   │   ├── auth.module.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── dto/           # 데이터 전송 객체
│   │   ├── entities/      # 데이터베이스 엔티티
│   │   ├── guards/        # 가드 (인증/인가)
│   │   └── strategies/    # Passport 전략
│   └── ...
├── shared/                 # 공유 리소스
│   ├── decorators/        # 커스텀 데코레이터
│   ├── filters/           # 예외 필터
│   ├── interceptors/      # 인터셉터
│   ├── pipes/             # 파이프
│   ├── guards/            # 공용 가드
│   ├── utils/             # 유틸리티 함수
│   └── types/             # 공용 타입
├── config/                 # 설정 파일
│   ├── database.config.ts
│   └── app.config.ts
└── __tests__/             # E2E 테스트

Modular 구조 원칙

1. 모듈 중심 설계

   • 각 기능은 독립적인 모듈로 구성
   • 모듈은 자체 완결성을 유지
   • 모듈 간 의존성은 imports를 통해 명시

2. 계층 분리

   • Controller: HTTP 요청 처리
   • Service: 비즈니스 로직
   • Repository/Entity: 데이터 접근

3. 의존성 주입

   • NestJS DI 컨테이너 활용
   • Interface 기반 설계 권장
   • Provider를 통한 느슨한 결합

4. 공유 규칙

   • 모듈 간 공유는

     shared/

     를 통해서만
   • 공통 기능은 독립 모듈로 분리 (예: CommonModule)

---

DTO 및 검증

핵심 원칙

모든 외부 입력은 class-validator를 통해 검증합니다.

DTO 작성 규칙

// ✅ 올바른 DTO
import { IsString, IsEmail, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;

  @IsString()
  name: string;
}

ValidationPipe 설정

// main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,        // DTO에 없는 속성 제거
    forbidNonWhitelisted: true, // 허용되지 않은 속성 있으면 에러
    transform: true,        // 타입 자동 변환
  })
);

---

예외 처리

표준 예외 사용

// ✅ NestJS 표준 예외 사용
import { NotFoundException, BadRequestException } from '@nestjs/common';

@Injectable()
export class UsersService {
  async findOne(id: string): Promise<User> {
    const user = await this.usersRepository.findOne(id);
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }
}

커스텀 예외 필터

// shared/filters/http-exception.filter.ts
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      message: exception.message,
    });
  }
}

---

환경 설정

@nestjs/config 사용

// app.module.ts
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: `.env.${process.env.NODE_ENV}`,
    }),
  ],
})
export class AppModule {}

설정 파일

// config/database.config.ts
export default () => ({
  database: {
    host: process.env.DB_HOST || 'localhost',
    port: parseInt(process.env.DB_PORT, 10) || 5432,
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME,
  },
});

---

CLAUDE.md 템플릿

프로젝트 루트에

CLAUDE.md

파일을 생성하여 AI 어시스턴트에게 프로젝트 규칙을 전달합니다:

# 프로젝트 개발 가이드

## 아키텍처
- Modular 구조 사용
- 각 기능은 독립적인 모듈로 구성
- 모듈 간 의존성은 imports를 통해 명시

## 계층 분리
- Controller: HTTP 요청 처리만
- Service: 비즈니스 로직 구현
- Repository/Entity: 데이터 접근

## 코드 품질

### 필수 준수
- 모든 DTO에 class-validator 적용
- 모든 엔티티에 명시적 타입 지정
- 에러 처리는 NestJS 표준 예외 사용
- 환경 변수는 @nestjs/config를 통해서만 접근

### 절대 금지
- Service에서 직접 Request 객체 사용
- DTO 없이 컨트롤러 파라미터 받기
- 하드코딩된 환경 변수 (process.env 직접 접근)

## 테스팅
- 모든 Service는 단위 테스트 작성
- E2E 테스트는 주요 API 엔드포인트에 대해 작성
- 테스트 파일은 `*.spec.ts` (단위), `*.e2e-spec.ts` (E2E)

---

설정 요구사항

버전 고정

• .nvmrc

  또는

  .node-version

  파일 생성

• package.json

  에

  engines

  필드 명시

필수 스크립트

{
  "scripts": {
    "start:dev": "nest start --watch",
    "start:prod": "node dist/main",
    "build": "nest build",
    "lint": "코드 린팅",
    "format": "코드 포맷팅",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}

---

참고사항

이 skill은 계획 및 설계 단계에서 활성화됩니다. 실제 프로젝트 초기화 실행이 필요하면 자연스럽게 대화를 이어가세요.