Imported from dmchoi77/turbo (AGENTS.md). Install upstream with npx skills add dmchoi77/turbo. Copyright stays with the author.

AGENTS.md

AI 에이전트를 위한 프로젝트 컨텍스트 문서입니다.

언어 설정

모든 응답은 반드시 한글로 작성해야 합니다.

• 사용자와의 모든 대화는 한글로 진행
• 코드 주석은 영어 유지 (국제 표준)
• 커밋 메시지는 영어 유지 (Git 컨벤션)
• 에러 메시지 설명은 한글로 번역하여 설명

Project Overview

Turborepo 기반 모노레포 - Blog CMS 플랫폼

Repository Structure

turbo/
├── apps/
│   ├── api/          # NestJS 10 + Prisma (Blog CMS API)
│   ├── web/          # Next.js 15 + React 19 (Main web app)
│   ├── docs/         # Next.js (Documentation site)
│   ├── my-app/       # Vite + React (Module Federation Host)
│   └── remote-app/   # Vite + React (Module Federation Remote)
├── packages/
│   ├── ui/           # @repo/ui - React component library
│   ├── hooks/        # @repo/hooks - Custom React hooks
│   ├── utils/        # @repo/utils - Utility functions
│   ├── core/         # @repo/core - Core business logic
│   ├── legacy/       # @repo/legacy - Legacy code (deprecated)
│   ├── eslint-config/    # @repo/eslint-config - Shared ESLint config
│   └── typescript-config/ # @repo/typescript-config - Shared tsconfig
├── docs/
│   └── STYLE_GUIDE.md    # Commit, branch, PR conventions
├── CONVENTION.md         # Code style conventions
└── turbo.json            # Turborepo task definitions

Apps

apps/api - Blog CMS API

주요 모듈:

• posts/ - 게시글 CRUD (페이지네이션, 검색, 필터)
• categories/ - 카테고리 관리
• comments/ - 댓글 시스템

Prisma 명령어:

pnpm --filter api db:generate  # Prisma Client 생성
pnpm --filter api db:push      # 스키마 DB 적용
pnpm --filter api db:studio    # Prisma Studio GUI

apps/web - Main Web Application

apps/my-app & apps/remote-app - Module Federation

Vite + React 기반 마이크로 프론트엔드 (Jotai 상태 관리)

Packages

@repo/ui - Component Library

Import Pattern:

import { Button } from "@repo/ui/button";
import { Tabs, Tab } from "@repo/ui/tabs";

Available Components: alert, avatar, badge, button, card, checkbox, code, data-visualization, divider, input, modal, pagination, progress, radio, select, spinner, switch, table, tabs, textarea

Build: Rollup → dist/ (ESM only)

@repo/hooks - Custom Hooks

import { useDebounce } from "@repo/hooks/useDebounce";
import { useLocalStorage } from "@repo/hooks/useLocalStorage";

Available Hooks: useAsync, useClickOutside, useDebounce, useLocalStorage, useMediaQuery, useMount, usePrevious, useSessionStorage, useThrottle, useToggle, useUnmount

@repo/utils - Utilities

import { formatDate, chunk } from "@repo/utils";

Commands

# Development
pnpm dev                    # 전체 dev 서버
pnpm --filter web dev       # web만 실행
pnpm --filter api dev       # api만 실행

# Build
pnpm build                  # 전체 빌드

# Quality
pnpm lint                   # 전체 린트
pnpm test                   # 전체 테스트
pnpm format                 # Prettier 포맷팅

# Type Check
pnpm --filter web check-types
pnpm --filter api check-types

Code Conventions

상세 규칙: CONVENTION.md

Naming

Function Prefixes

Component Structure

"use client"; // 클라이언트 컴포넌트만

import { ReactNode } from "react";
import { Button } from "@repo/ui/button";

// interface 사용, [Name]Props 명명
interface CardProps {
  children: ReactNode;
  title: string;
  isActive?: boolean;
}

// Named export (pages 제외)
export const Card = ({ children, title, isActive = false }: CardProps) => {
  return <div>{children}</div>;
};

Export Rules

FORBIDDEN

• as any
• @ts-ignore
• @ts-expect-error
• type alias for Props (use interface)
• I prefix for interfaces

Git Conventions

상세 규칙: docs/STYLE_GUIDE.md

Commit Format

<type>[scope]: <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Scopes: web, api, docs, ui, utils, hooks, core, config

Examples:

feat(ui): add Tooltip component with animation
fix(web): resolve hydration mismatch in SSR
refactor(api): simplify authentication logic

Branch Naming

<type>/<short-description>

# Examples
feat/user-authentication
fix/login-redirect
docs/api-documentation

Import Order

// 1. React & external libraries
import { useState, useEffect } from "react";
import { motion } from "framer-motion";

// 2. Internal packages (@repo/*)
import { Button } from "@repo/ui/button";
import { formatDate } from "@repo/utils";

// 3. Local files
import { postsQueryOptions } from "./api";

// 4. Type imports
import type { Metadata } from "next";

Testing

pnpm test              # Run all tests
pnpm --filter api test # Run api tests only

테스트 파일: **/*.test.ts, **/*.spec.ts

Key Files

Quick Reference

새 UI 컴포넌트 추가

pnpm --filter @repo/ui generate:component

특정 앱만 빌드

pnpm --filter web build
pnpm --filter api build

Prisma DB 작업

pnpm --filter api db:generate
pnpm --filter api db:push
pnpm --filter api db:migrate