diff --git a/.context/commands.md b/.context/commands.md new file mode 100644 index 0000000..b66807c --- /dev/null +++ b/.context/commands.md @@ -0,0 +1,74 @@ +# 명령어 레퍼런스 + +프로젝트에서 사용하는 주요 명령어들을 정리합니다. + +## 개발 명령어 + +### 패키지 관리 +```bash +# 의존성 설치 +pnpm install + +# 패키지 추가/제거 +pnpm add +pnpm add -D # 개발 의존성 +pnpm remove +``` + +### 주의사항 +```bash +# 🚫 금지된 명령어들 (CLAUDE.md 지침) +pnpm dev # 개발서버 실행 금지 +pnpm build # 빌드 금지 +pnpm start # 서버 실행 금지 +``` + +## 테스트 (Vitest) + +### 기본 테스트 +```bash +# 테스트 실행 +pnpm test + +# 테스트 UI 실행 +pnpm test:ui + +# 테스트 감시 모드 +pnpm test:watch + +# 테스트 커버리지 +pnpm test:coverage +``` + +### 특정 테스트 +```bash +# 파일별 테스트 +pnpm test -- posts.test.ts + +# 패턴 테스트 +pnpm test -- --grep "태그 그래프" +``` + +## 코드 품질 (Biome) + +### 코드 검사 및 포맷팅 +```bash +# 코드 검사 +pnpm biome:check + +# 자동 수정 +pnpm biome:fix + +# 스테이지된 파일만 수정 +pnpm biome:staged +``` + +### TypeScript 타입 검사 +```bash +# 타입 검사 +pnpm type + +# 타입 검사 (감시 모드) +pnpm type -- --watch +``` + diff --git a/.context/current-status.md b/.context/current-status.md new file mode 100644 index 0000000..9d11ae2 --- /dev/null +++ b/.context/current-status.md @@ -0,0 +1,13 @@ +# current-status.md + +최근 완료 작업과 다음 작업 요소를 정리한 문서입니다. + +## 최근 완료 작업 +- ✅ **CLAUDE.md 문서 체계화**: @import 구문으로 모듈화된 문서 구조 완성 +- ✅ **development-guidelines.md 최적화**: 실제 프로젝트의 도메인 중심 설계, 모듈 레벨 캐싱, 태그 그래프 시스템 패턴 중심으로 재작성 +- ✅ **styling-guide.md 최적화**: 실제 컴포넌트 패턴(CategoryBadge, TagBadge, CVA 시스템) 반영한 실용적 가이드 +- ✅ **git-workflow.md 최적화**: 실제 프로젝트의 브랜치 패턴과 커밋 컨벤션 반영 +- ✅ **commands.md 최적화**: 실제 package.json 스크립트 기반, 개발서버/빌드 금지 지침 포함한 실용적 명령어 가이드 + +## 다음 작업 요소 +- 추후 정의 diff --git a/.context/development-guidelines.md b/.context/development-guidelines.md new file mode 100644 index 0000000..c99f9f9 --- /dev/null +++ b/.context/development-guidelines.md @@ -0,0 +1,157 @@ +# 개발 가이드라인 + +이 블로그 프로젝트의 핵심 패턴과 구현 원칙을 정의합니다. + +## 아키텍처 패턴 + +### 도메인 중심 설계 +- **도메인 로직**: `src/domain/blog/` 에 통합 +- **UI 컴포넌트**: `src/app/` 하위에 구현 +- **타입 정의**: `src/domain/blog/types.ts` 중앙 집중 + +```typescript +// 도메인 API 사용 예시 +import { getCategoryById, getPostsByCategory, getRelatedPostsByTags } from '@/domain/blog' + +const category = getCategoryById('dev') +const posts = getPostsByCategory('dev') +const related = getRelatedPostsByTags(currentSlug, 3) +``` + +### 모듈 레벨 캐싱 +빌드 타임에 모든 데이터를 사전 로드하여 SSG 최적화 + +```typescript +// src/domain/blog/index.ts +export const allPosts = await getAllPosts() +export const allCategories = await getAllCategories() +export const allTags = extractTagsFromPosts(allPosts) +export const tagGraph = createTagGraph(allPosts, allTags) +export const tagClusters = createTagClusters(tagGraph) +``` + +### 태그 그래프 시스템 +graphology 라이브러리로 태그 간 관계 분석 + +```typescript +// 태그 관계 분석 +const relationships = getTagRelationships() +const clusters = getTagClusters() +const relatedPosts = getRelatedPostsByTags(currentSlug, 3) +``` + +## 콘텐츠 구조 + +### MDX 파일 구조 +``` +src/contents/ +├── dev/ # 개발 카테고리 +│ ├── category.json +│ └── *.mdx +└── life/ # 일상 카테고리 + ├── category.json + └── *.mdx +``` + +### 포스트 frontmatter +```yaml +--- +title: '포스트 제목' +date: 2025-01-17 +tags: ['tag1', 'tag2'] +description: '포스트 설명' +category: 'dev' # 또는 'life' +--- +``` + +### 카테고리 메타데이터 +```json +{ + "name": "개발", + "description": "개발 관련 포스트", + "color": "blue", + "icon": "💻" +} +``` + +## 컴포넌트 패턴 + +### 타입 정의 +```typescript +interface PostHeaderProps { + title: string + date: string + tags: string[] + category?: CategoryId + readingTime?: number + author?: string + className?: string +} +``` + +### 컴포넌트 구현 +```typescript +// 서버 컴포넌트 기본, 상호작용 필요시만 클라이언트 +export function PostHeader({ title, date, tags, category }: PostHeaderProps) { + return ( +
+
+ {category && } +

{title}

+
+ +
+ ) +} +``` + +## 품질 기준 + +### TypeScript 엄격 모드 +- `any` 타입 사용 금지 +- 모든 Props 인터페이스 명시적 정의 +- 도메인 타입 재사용 (`CategoryId`, `Post`, `Tag`) + +### 테스트 패턴 +```typescript +// 비즈니스 로직 테스트 +describe('태그 그래프 시스템', () => { + it('관련 포스트를 태그 유사도로 찾는다', () => { + const related = getRelatedPostsByTags('test-slug', 3) + expect(related).toHaveLength(3) + }) +}) +``` + +### 성능 최적화 +- 모든 데이터 빌드 타임 사전 계산 +- `generateStaticParams()` 사용한 정적 경로 생성 +- 컴포넌트 간 props 최소화 + +## 디렉토리 구조 + +``` +src/ +├── app/ # Next.js App Router +│ ├── [category]/ # 카테고리 페이지 +│ │ ├── [slug]/ # 포스트 상세 +│ │ └── _components/ # 페이지별 컴포넌트 +│ └── _components/ # 전역 컴포넌트 +├── domain/blog/ # 도메인 로직 +│ ├── index.ts # 공개 API + 캐싱 +│ ├── types.ts # 타입 정의 +│ └── logic/ # 비즈니스 로직 +│ ├── posts.ts +│ ├── categories.ts +│ └── tags.ts +└── contents/ # MDX 콘텐츠 + ├── dev/ + └── life/ +``` + +## 구현 원칙 + +1. **도메인 API 사용**: 직접 파일 시스템 접근 금지 +2. **타입 안전성**: 모든 데이터 흐름 타입 보장 +3. **모듈 레벨 캐싱**: 빌드 타임 데이터 사전 로드 +4. **컴포넌트 단순화**: 단일 책임 원칙 \ No newline at end of file diff --git a/.context/git-workflow.md b/.context/git-workflow.md new file mode 100644 index 0000000..c4aaf94 --- /dev/null +++ b/.context/git-workflow.md @@ -0,0 +1,70 @@ +# Git 워크플로우 + +브랜치 전략, 커밋 컨벤션, PR 프로세스를 정의합니다. + +## 브랜치 전략 + +### 기본 브랜치 +- **main**: 배포용 안정화 브랜치 +- **feature/**: 기능 개발용 브랜치 +- **fix/**: 버그 수정용 브랜치 +- **docs/**: 문서 작업용 브랜치 + +### 브랜치 네이밍 +```bash +# 기능 개발 (실제 프로젝트 패턴) +feat/entities +feat/post-navigation +feat/entity-optimization-and-category-system + +# 버그 수정 +fix/resolve-navigation-issue +fix/correct-typo-in-header + +# 문서/설정 작업 +docs/claude-pr-workflow +config/github-templates +config/tailwind-setup +``` + +## 커밋 컨벤션 + +### 기본 형식 +``` +type: subject + +body (optional) + +footer (optional) +``` + +### 커밋 타입 +- **feat**: 새로운 기능 추가 +- **fix**: 버그 수정 +- **docs**: 문서 수정 +- **style**: 코드 포맷팅, 세미콜론 누락 등 +- **refactor**: 코드 리팩토링 +- **test**: 테스트 추가 또는 수정 +- **chore**: 빌드 프로세스 또는 보조 도구 변경 + +## 논리적 단위 커밋 + +- 커밋은 변경사항 그룹끼리 묶여서 작성 + +## PR 프로세스 + +### PR 생성 전 체크리스트 +- [ ] `pnpm test` 통과 확인 +- [ ] `pnpm biome:check` 통과 확인 +- [ ] `pnpm type` 통과 확인 +- [ ] 커밋 메시지 정리 완료 +- [ ] 관련 이슈 연결 + +### PR 템플릿 +```markdown +## 변경사항 요약 + + +## 변경 이유 + +``` \ No newline at end of file diff --git a/.context/project-overview.md b/.context/project-overview.md new file mode 100644 index 0000000..70e43e5 --- /dev/null +++ b/.context/project-overview.md @@ -0,0 +1,115 @@ +# 프로젝트 개요 + +Next.js 15 기반의 정적 블로그 애플리케이션으로, MDX를 사용한 콘텐츠 관리와 도메인 주도 설계를 따릅니다. + +## 기술 스택 + +- **프레임워크**: Next.js 15 (App Router) +- **콘텐츠**: MDX with rehype-pretty-code +- **스타일링**: Tailwind CSS 4.0 + shadcn/ui +- **언어**: TypeScript (엄격 모드) +- **코드 품질**: Biome (formatting/linting) +- **테스팅**: Vitest +- **패키지 매니저**: pnpm +- **그래프**: graphology (태그 관계 분석) + +## 아키텍처 + +### 디렉토리 구조 + +``` +src/ +├── app/ # Next.js App Router 루트 +│ ├── [category]/ # 카테고리별 포스트 목록 페이지 +│ │ ├── [slug]/ # 개별 포스트 상세 페이지 +│ │ │ └── page.tsx +│ │ ├── _components/ # 카테고리/포스트 관련 컴포넌트 +│ │ └── page.tsx +│ ├── _components/ # 전역 공통 컴포넌트 +│ ├── _fonts/ # 폰트 설정 +│ ├── _lib/ # 공통 유틸리티 함수 +│ ├── about/ # About 페이지 +│ ├── layout.tsx # 루트 레이아웃 +│ └── page.tsx # 메인 페이지 +├── contents/ # MDX 블로그 포스트 원본 파일 +│ ├── dev/ # 개발 관련 포스트 +│ │ ├── category.json # 카테고리 메타데이터 +│ │ └── *.mdx +│ └── life/ # 일상 관련 포스트 +│ ├── category.json +│ └── *.mdx +├── entities/ # 도메인 엔티티 (통합) +│ └── blog/ # 블로그 도메인 통합 구조 +│ ├── index.ts # 공개 API + 모듈 레벨 캐싱 +│ ├── types.ts # 모든 타입 정의 +│ └── logic/ # 비즈니스 로직 분리 +│ ├── posts.ts # 포스트 관련 로직 +│ ├── categories.ts # 카테고리 관련 로직 +│ └── tags.ts # 태그 관련 로직 +├── mdx-components.tsx # MDX 렌더링 시 사용할 커스텀 컴포넌트 +└── test/ # 테스트 관련 설정 +``` + +### 데이터 흐름 + +1. **빌드 타임**: MDX 파일 → gray-matter 파싱 → 모듈 레벨 캐싱 +2. **엔티티 레이어**: 비즈니스 로직 처리 (태그 그래프, 관련 포스트 등) +3. **App Router**: 서버 컴포넌트에서 캐시된 데이터 활용하여 렌더링 + +### 성능 최적화 + +#### SSG 최적화 +- **모듈 레벨 캐싱**: 빌드 타임에 모든 포스트, 카테고리, 태그 데이터 한 번만 로드 +- **사전 계산**: 태그 그래프, 클러스터, 관련 포스트 관계 빌드 타임에 계산 +- **정적 생성**: `generateStaticParams()`로 모든 경로 사전 생성 + +```typescript +// 모듈 레벨 캐싱 예시 +export const allPosts = await getAllPosts() +export const allCategories = await getAllCategories() +export const tagGraph = createTagGraph(allPosts, allTags) +export const tagClusters = createTagClusters(tagGraph) +``` + +## 네이밍 컨벤션 + +- **라우트가 아닌 폴더**: 언더스코어 접두사 (`_components`, `_lib`) +- **컴포넌트 스코프**: + - 전역: `src/app/_components/` + - 페이지별: `src/app/[route]/_components/` +- **파일명**: kebab-case 또는 PascalCase (컴포넌트) +- **변수/함수**: camelCase +- **타입/인터페이스**: PascalCase +- **상수**: UPPER_SNAKE_CASE + +## 콘텐츠 관리 + +### MDX 구조 +```yaml +--- +title: '포스트 제목' +date: 2025-01-17 +tags: ['tag1', 'tag2'] +description: '포스트 설명' +--- + +# 포스트 내용 +``` + +### 카테고리 메타데이터 (category.json) +```json +{ + "name": "Development", + "description": "개발 관련 포스트", + "color": "blue", + "icon": "💻" +} +``` + +## 라우팅 구조 + +- `/` - 메인 페이지 (Hero, 카테고리, 최신 포스트, 태그) +- `/{category}` - 카테고리별 포스트 목록 (dev, life) +- `/{category}/{slug}` - 개별 포스트 상세 페이지 +- `/tags` - 태그 목록 및 필터링 +- `/about` - About 페이지 \ No newline at end of file diff --git a/.context/styling-guide.md b/.context/styling-guide.md new file mode 100644 index 0000000..92f8184 --- /dev/null +++ b/.context/styling-guide.md @@ -0,0 +1,85 @@ +# 스타일링 가이드 + +Tailwind CSS, shadcn/ui, 디자인 시스템 가이드라인을 정의합니다. + +## 기본 원칙 + +- 구조를 나타내는 것 이상의 상세한 UI 스타일링은 유저의 요청이 없으면 진행하지 않음 + +### 스타일링 우선순위 +1. **기능 구조 우선**: 스타일링보다 로직과 구조 집중 +2. **일관성**: 전체 애플리케이션에서 일관된 디자인 언어 +3. **접근성**: 모든 사용자가 접근 가능한 디자인 +4. **반응형**: 모바일 퍼스트 접근 + +## shadcn/ui 컴포넌트 사용 + +### 설치 및 사용 +```bash +npx shadcn-ui@latest add button +npx shadcn-ui@latest add card +npx shadcn-ui@latest add input +``` + +### 실제 프로젝트 패턴 + +#### 색상 클래스 객체 패턴 (CategoryBadge) +```typescript +const colorClasses = { + blue: 'bg-blue-100 text-blue-800 border-blue-200 hover:bg-blue-200', + green: 'bg-green-100 text-green-800 border-green-200 hover:bg-green-200', + gray: 'bg-gray-100 text-gray-800 border-gray-200 hover:bg-gray-200', +} + +const className = cn( + 'inline-flex items-center gap-1 px-2 py-1 text-sm font-medium rounded-md border transition-colors', + colorClasses[category.color as keyof typeof colorClasses] || colorClasses.gray +) +``` + +#### 해시 기반 색상 할당 (TagBadge) +```typescript +// getTagColor.ts - 태그별 고유 색상 생성 +const TAG_COLORS = [ + 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300', + 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300', + // ... 더 많은 색상 +] as const + +export function getTagColor(tag: string): string { + const hash = /* 해시 함수 구현 */ + const index = Math.abs(hash) % TAG_COLORS.length + return TAG_COLORS[index] +} +``` + +#### CVA 기반 변형 시스템 (Badge) +```typescript +const badgeVariants = cva( + 'inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium', + { + variants: { + variant: { + default: 'border-transparent bg-primary text-primary-foreground', + secondary: 'border-transparent bg-secondary text-secondary-foreground', + outline: 'text-foreground hover:bg-accent hover:text-accent-foreground', + }, + }, + defaultVariants: { variant: 'default' }, + } +) +``` + +### 성능 고려사항 +- **클래스 동적 생성**: `cn()` 유틸리티 사용 +- **조건부 스타일**: 삼항 연산자보다 `cn()` 활용 +- **재사용성**: 공통 스타일 컴포넌트화 + +```typescript +// 올바른 예시 +const buttonStyles = cn( + "px-4 py-2 rounded-md font-medium transition-colors", + isActive && "bg-blue-600 text-white", + isDisabled && "opacity-50 cursor-not-allowed" +) +``` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index ae9bfad..eb0b71e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,364 +1,86 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Next.js 15 기반 정적 블로그의 아키텍처 지침과 작업 가이드입니다. -## 프로젝트 개요 +## 🔧 핵심 원칙 -Next.js 15 기반의 정적 블로그 애플리케이션으로, MDX를 사용한 콘텐츠 관리와 도메인 주도 설계를 따릅니다. +### ⚠️ 가장 중요한 지침 +- **스코프별 CLAUDE.md 유지**: 작업할 때마다 해당 디렉토리의 CLAUDE.md를 업데이트 +- **계층적 컨텍스트 상속**: 하위 CLAUDE.md는 상위 문서들을 import하여 전체 맥락 확보 +- **컨텍스트 지역화**: 각 디렉토리별로 구체적이고 정확한 작업 컨텍스트 유지 +- **실시간 업데이트**: 코드 변경과 동시에 해당 영역의 CLAUDE.md 즉시 반영 -## 기술 스택 +### 제약사항 +- 개발서버/빌드 실행 금지 +- 코드에 실제 레터링 대신 placeholder 사용 +- 스코프별 CLAUDE.md는 50줄 이내로 간결 작성 -- **프레임워크**: Next.js 15 (App Router) -- **콘텐츠**: MDX with rehype-pretty-code -- **스타일링**: Tailwind CSS + shadcn/ui -- **언어**: TypeScript -- **코드 품질**: Biome (formatting/linting) -- **테스팅**: Vitest -- **패키지 매니저**: pnpm -- **그래프**: graphology +## 🏗️ 아키텍처 원칙 -## 디렉토리 구조 +### 도메인 주도 설계 (DDD) +- **도메인 로직**: `src/domain/` 에 비즈니스 로직 중앙집중 +- **UI 분리**: `src/app/` 에 프레젠테이션 레이어 분리 +- **데이터 흐름**: 도메인 → UI 단방향 의존성 -``` -src/ -├── app/ # Next.js App Router 루트 -│ ├── [category]/ # 카테고리별 포스트 목록 페이지 -│ │ ├── [slug]/ # 개별 포스트 상세 페이지 -│ │ │ └── page.tsx -│ │ ├── _components/ # 카테고리/포스트 관련 컴포넌트 -│ │ └── page.tsx -│ ├── _components/ # 전역 공통 컴포넌트 -│ ├── _fonts/ # 폰트 설정 -│ ├── _lib/ # 공통 유틸리티 함수 -│ ├── about/ # About 페이지 -│ ├── layout.tsx # 루트 레이아웃 -│ └── page.tsx # 메인 페이지 -├── contents/ # MDX 블로그 포스트 원본 파일 -├── entities/ # 도메인 엔티티 (비즈니스 로직) -│ ├── categories/ # 카테고리 도메인 로직 -│ ├── posts/ # 포스트 도메인 로직 -│ └── tags/ # 태그 도메인 로직 -├── mdx-components.tsx # MDX 렌더링 시 사용할 커스텀 컴포넌트 -└── test/ # 테스트 관련 설정 -``` - -## 네이밍 컨벤션 - -- **라우트가 아닌 폴더**: 언더스코어 접두사 사용 (`_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'] ---- - -# 포스트 내용 -``` +### 모듈 레벨 캐싱 +- **빌드 타임 최적화**: 모든 데이터 사전 로드 및 캐싱 +- **SSG 최적화**: 정적 사이트 생성을 위한 성능 최적화 +- **관계 사전 계산**: 태그 그래프, 클러스터, 관련 포스트 빌드 타임 계산 -## 작업 진행 원칙 +### 타입 안전성 +- **TypeScript 엄격 모드**: `any` 타입 금지 +- **명시적 타입**: 모든 인터페이스와 함수 시그니처 명시 +- **도메인 타입 중심**: 비즈니스 로직의 타입 우선 설계 -- 작업의 단위를 가능하면 작게 설정 -- 지시가 모호하다고 느껴지면 질문 후 진행 +## 📁 전체 구조 맵 -## 구현 원칙 - -### 점진적 개발 -- 한 번에 하나의 태스크만 집중하여 구현 -- 태스크 완료 후 사용자 검토 대기, 자동으로 다음 태스크 진행하지 않음 -- 각 단계에서 이전 단계의 결과물을 기반으로 구축 - -### 코드 품질 -- 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', () => { - // 테스트 구현 - }) -}) +/ +├── src/ +│ ├── domain/ # 🧠 비즈니스 로직 +│ │ └── blog/ # 블로그 도메인 (SSG 캐싱, 태그 그래프) +│ ├── app/ # 🎨 UI 레이어 (Next.js App Router) +│ │ ├── [category]/ # 동적 라우팅 (카테고리별 페이지) +│ │ ├── _components/ # 전역 공통 컴포넌트 +│ │ └── _lib/ # UI 유틸리티 함수 +│ └── contents/ # 📝 MDX 콘텐츠 +├── .context/ # 📚 프로젝트 문서 +└── CLAUDE.md # 🗺️ 마스터 아키텍처 (이 문서) ``` -### Next.js 아키텍처 준수 -- App Router의 이점과 서버 컴포넌트를 적극 활용 - -### 기능 구조 우선 -- 스타일링보다 기능적 구조와 로직에 집중 -- 컴포넌트의 역할과 책임을 명확히 정의 -- 데이터 흐름과 상태 관리 구조 우선 설계 -- UI는 기본적인 레이아웃만 구현하고 세부 스타일링은 후순위 +## 🔗 스코프별 CLAUDE.md 링크 -### 아키텍처 중심 접근 -- 도메인 로직과 UI 로직의 명확한 분리 -- 컴포넌트 간의 의존성과 데이터 전달 구조 설계 -- 재사용 가능한 로직의 추상화 -- 확장 가능한 구조로 설계 +### 1뎁스 - 주요 영역 +- `src/domain/CLAUDE.md` - 도메인 로직 전체 맥락 +- `src/app/CLAUDE.md` - App Router 구조와 패턴 +- `src/contents/CLAUDE.md` - MDX 콘텐츠 관리 규칙 -### 최소 스타일링 -- 구조화에 필요한 최소한의 스타일링 가능 -- 필요시 shadcn/ui의 컴포넌트를 이용 +### 2뎁스 - 세부 구현 +- `src/domain/blog/CLAUDE.md` - 블로그 도메인 세부사항 +- `src/app/[category]/CLAUDE.md` - 동적 라우팅 구조 +- `src/app/_components/CLAUDE.md` - 전역 컴포넌트 역할 +- `src/app/_lib/CLAUDE.md` - 유틸리티 함수 목적 -```typescript -// 구조에 집중한 컴포넌트 예시 -
{/* 기본 레이아웃만 */} -
- {/* 기능적 구조 우선 */} -
-
-
- {/* ... */} -
-
-
-``` - -### UI 구현 -- **플레이스홀더 사용**: 실제 콘텐츠 대신 `[Page Title]`, `[Description]` 등 사용 -- **사용자 승인**: UI 구조 구현 전 명시적 요구사항 확인 -- **점진적 구현**: 한 번에 모든 기능 구현하지 않기 +## 📖 추가 프로젝트 문서 -## 접근성 고려사항 +### 개발 가이드 +- @.context/development-guidelines.md - 구현 패턴, 품질 기준 +- @.context/styling-guide.md - Tailwind CSS, shadcn/ui 가이드 +- @.context/git-workflow.md - 브랜치 전략, 커밋 컨벤션 -### 필수 요소 -- 시맨틱 HTML 태그 사용 -- 적절한 ARIA 레이블 -- 키보드 네비게이션 지원 -- 충분한 색상 대비 - -### 구현 예시 -```typescript -