From a676df999579f503ee5d291095a45c1378d85da6 Mon Sep 17 00:00:00 2001 From: Jongchan Date: Thu, 17 Jul 2025 01:45:34 +0900 Subject: [PATCH 1/6] =?UTF-8?q?config:=20=ED=94=84=EB=A1=9C=EC=A0=9D?= =?UTF-8?q?=ED=8A=B8=20=EC=84=A4=EC=A0=95=20=EB=B0=8F=20=EC=9D=98=EC=A1=B4?= =?UTF-8?q?=EC=84=B1=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 테스트 환경 설정 (Vitest, test setup) - Next.js 정적 내보내기 설정 - VS Code 설정 및 개발 환경 구성 - 프로젝트 문서 업데이트 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .gitignore | 4 + .kiro/steering/task-execution-process.md | 7 +- .vscode/settings.json | 3 +- CLAUDE.md | 367 ++++++++++----- next.config.ts | 4 + package.json | 5 + pnpm-lock.yaml | 557 ++++++++++++++++++++++- src/test/setup.ts | 1 + vitest.config.ts | 5 +- 9 files changed, 829 insertions(+), 124 deletions(-) diff --git a/.gitignore b/.gitignore index 5ef6a52..df2dfc3 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,7 @@ yarn-error.log* # typescript *.tsbuildinfo next-env.d.ts + +.kiro/specs + +*.bak \ No newline at end of file diff --git a/.kiro/steering/task-execution-process.md b/.kiro/steering/task-execution-process.md index 5784d53..a811550 100644 --- a/.kiro/steering/task-execution-process.md +++ b/.kiro/steering/task-execution-process.md @@ -32,7 +32,6 @@ - **커스텀훅**: 로직은 커스텀훅으로 분리함 - **컴포넌트 분리**: 50줄 이상의 컴포넌트는 분리 고려 -### 컴포넌트 구현 ```typescript // 1. 인터페이스 정의 interface ComponentProps { @@ -52,6 +51,9 @@ export function Component({ ``` ### 비즈니스 로직 구현 + +- ESM 모듈 시스템을 활용해 적절히 인터페이스 노출 + ```typescript // 1. 타입 정의 export type DataType = { @@ -72,6 +74,9 @@ describe('processData', () => { }) ``` +### Next.js 아키텍처 준수 +- App Router의 이점과 서버 컴포넌트를 적극 활용 + ### 기능 구조 우선 - 스타일링보다 기능적 구조와 로직에 집중 - 컴포넌트의 역할과 책임을 명확히 정의 diff --git a/.vscode/settings.json b/.vscode/settings.json index ef56b78..09df56b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -27,5 +27,6 @@ }, "[tailwindcss]": { "editor.defaultFormatter": "biomejs.biome" - } + }, + "biome.enabled": true } diff --git a/CLAUDE.md b/CLAUDE.md index 67ad26c..5b472c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,35 +2,239 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## Development Commands +## 프로젝트 개요 -- `pnpm dev` - Start development server on localhost:3000 -- `pnpm build` - Build the application for production (configured for static export) -- `pnpm start` - Start production server -- `pnpm biome:check` - Run Biome formatter and linter -- `pnpm biome:fix` - Run Biome formatter and linter with auto-fix -- `pnpm biome:staged` - Run Biome on staged files only +Next.js 15 기반의 정적 블로그 애플리케이션으로, MDX를 사용한 콘텐츠 관리와 도메인 주도 설계를 따릅니다. -## Code Quality +## 기술 스택 -This project uses Biome for formatting and linting. Always run `pnpm biome:check` before committing changes. The project has a pre-commit hook (lefthook) that automatically runs Biome on staged files. +- **프레임워크**: Next.js 15 (App Router) +- **콘텐츠**: MDX with rehype-pretty-code +- **스타일링**: Tailwind CSS + shadcn/ui +- **언어**: TypeScript +- **코드 품질**: Biome (formatting/linting) +- **테스팅**: Vitest +- **패키지 매니저**: pnpm +- **그래프**: graphology -**IMPORTANT**: -- Do NOT run `pnpm dev` or `pnpm build` during development tasks unless specifically requested by the user. The build process is mainly for final deployment verification. -- When implementing new pages or components, use placeholders instead of actual content. Show what type of content should go in each position rather than writing fake content. -- Do NOT create UI structures arbitrarily. Always ask the user for specific requirements and approval before implementing any UI design or structure. +## 디렉토리 구조 + +``` +src/ +├── app/ # Next.js App Router 루트 +│ ├── _components/ # 전역 컴포넌트 +│ ├── _fonts/ # 폰트 설정 +│ ├── _lib/ # 유틸리티 함수 +│ ├── posts/[slug]/ # 동적 포스트 페이지 +│ ├── about/ # About 페이지 +│ ├── layout.tsx # 루트 레이아웃 +│ └── globals.css # 전역 스타일 +├── entities/ # 도메인 엔티티 +│ ├── posts/ # 포스트 도메인 로직 +│ └── tags/ # 태그 도메인 로직 +└── contents/ # MDX 블로그 포스트 +``` + +## 네이밍 컨벤션 + +- **라우트가 아닌 폴더**: 언더스코어 접두사 사용 (`_components`, `_hooks`) +- **컴포넌트 스코프**: + - 전역: `src/app/_components/` + - 페이지별: `src/app/[route]/_components/` +- **파일명**: kebab-case 또는 PascalCase (컴포넌트) + +## 도메인 아키텍처 + +### 엔티티 구조 +- `src/entities/posts/`: 포스트 관련 비즈니스 로직 + - `index.ts`: 공개 API + - `types.ts`: 타입 정의 + - `logic.ts`: 비즈니스 로직 + - `*.test.ts`: 테스트 파일 + +### 데이터 흐름 +1. MDX 파일 (`src/contents/`) → gray-matter 파싱 +2. 엔티티 레이어에서 비즈니스 로직 처리 +3. App Router 페이지에서 렌더링 + +## 스타일링 가이드라인 + +### Tailwind CSS +- **컬러 팔레트**: `stone` 계열 사용 (`text-stone-900`, `border-stone-200`) +- **반응형**: 모바일 퍼스트 접근 +- **다크모드**: CSS 변수 기반 테마 지원 + +### shadcn/ui 컴포넌트 +- **설치**: `npx shadcn@latest add ` +- **위치**: `src/app/_components/ui/` +- **스타일**: "new-york" 스타일, stone 베이스 컬러 +- **아이콘**: Lucide React 사용 + +## 콘텐츠 관리 + +### 콘텐츠 위치 +`src/contents/*.mdx` + +### MDX 구조 +```yaml +--- +title: '포스트 제목' +slug: 'post-slug' +date: 2025-01-01 +tags: ['tag1', 'tag2'] +--- + +# 포스트 내용 +``` + +## 작업 진행 원칙 + +- 작업의 단위를 가능하면 작게 설정 +- 지시가 모호하다고 느껴지면 질문 후 진행 + +## 구현 원칙 + +### 점진적 개발 +- 한 번에 하나의 태스크만 집중하여 구현 +- 태스크 완료 후 사용자 검토 대기, 자동으로 다음 태스크 진행하지 않음 +- 각 단계에서 이전 단계의 결과물을 기반으로 구축 + +### 코드 품질 +- TypeScript 엄격 모드 준수, any 타입 사용 금지 +- 컴포넌트는 단일 책임 원칙 적용 +- Props 인터페이스 명시적 정의 +- 적절한 기본값 설정 + +### 테스트 우선 +- 비즈니스 로직 구현 시 단위 테스트 함께 작성 +- AAA 패턴 (Arrange, Act, Assert) 준수 +- 의미있는 테스트명 사용 + +## 구현 패턴 + +### 컴포넌트 설계 +- **단일 책임 원칙**: 하나의 컴포넌트는 하나의 역할만 +- **Props 인터페이스**: 모든 props에 대한 명시적 타입 정의 +- **기본값 설정**: 선택적 props에 대한 적절한 기본값 +- **커스텀훅**: 로직은 커스텀훅으로 분리함 +- **컴포넌트 분리**: 50줄 이상의 컴포넌트는 분리 고려 +- **테스트 금지**: 컴포넌트 자체는 테스트하지 않아야함 + +```typescript +// 1. 인터페이스 정의 +interface ComponentProps { + required: string + optional?: boolean + children?: React.ReactNode +} + +// 2. 컴포넌트 구현 +export function Component({ + required, + optional = false, + children +}: ComponentProps) { + // 구현 +} +``` + +### 비즈니스 로직 구현 + +- **모듈화**: ESM 모듈 시스템을 활용해 적절히 인터페이스 노출 +- **테스트**: 비즈니스 로직의 경우엔 테스트를 해야함 + +```typescript +// 1. 타입 정의 +export type DataType = { + id: string + value: string +} + +// 2. 로직 함수 구현 +export function processData(data: DataType[]): DataType[] { + // 구현 +} + +// 3. 테스트 작성 +describe('processData', () => { + it('should process data correctly', () => { + // 테스트 구현 + }) +}) +``` + +### Next.js 아키텍처 준수 +- App Router의 이점과 서버 컴포넌트를 적극 활용 + +### 기능 구조 우선 +- 스타일링보다 기능적 구조와 로직에 집중 +- 컴포넌트의 역할과 책임을 명확히 정의 +- 데이터 흐름과 상태 관리 구조 우선 설계 +- UI는 기본적인 레이아웃만 구현하고 세부 스타일링은 후순위 + +### 아키텍처 중심 접근 +- 도메인 로직과 UI 로직의 명확한 분리 +- 컴포넌트 간의 의존성과 데이터 전달 구조 설계 +- 재사용 가능한 로직의 추상화 +- 확장 가능한 구조로 설계 + +### 최소 스타일링 +- 구조화에 필요한 최소한의 스타일링 가능 +- 필요시 shadcn/ui의 컴포넌트를 이용 + +```typescript +// 구조에 집중한 컴포넌트 예시 +
{/* 기본 레이아웃만 */} +
+ {/* 기능적 구조 우선 */} +
+
+
+ {/* ... */} +
+
+
+``` + +### UI 구현 +- **플레이스홀더 사용**: 실제 콘텐츠 대신 `[Page Title]`, `[Description]` 등 사용 +- **사용자 승인**: UI 구조 구현 전 명시적 요구사항 확인 +- **점진적 구현**: 한 번에 모든 기능 구현하지 않기 + +## 접근성 고려사항 + +### 필수 요소 +- 시맨틱 HTML 태그 사용 +- 적절한 ARIA 레이블 +- 키보드 네비게이션 지원 +- 충분한 색상 대비 + +### 구현 예시 +```typescript +