kickbelldev · kickbelldev · Jul 23, 2025 · Jul 18, 2025 · Jul 22, 2025 · Jul 22, 2025
diff --git a/.context/current-status.md b/.context/current-status.md
diff --git a/.context/development-guidelines.md b/.context/development-guidelines.md
@@ -1,157 +1,51 @@
 # 개발 가이드라인
 
-이 블로그 프로젝트의 핵심 패턴과 구현 원칙을 정의합니다.
+## 필수 원칙
 
-## 아키텍처 패턴
+### 도메인 API 사용
+- ✅ `import { getCategoryById } from '@/domain/blog'`
+- ❌ 직접 파일 시스템 접근 금지
 
-### 도메인 중심 설계
-- **도메인 로직**: `src/domain/blog/` 에 통합
-- **UI 컴포넌트**: `src/app/` 하위에 구현
-- **타입 정의**: `src/domain/blog/types.ts` 중앙 집중
+### 타입 안전성
+- ✅ 모든 Props 인터페이스 명시
+- ❌ `any` 타입 사용 금지
+- ✅ 도메인 타입 재사용 (`CategoryId`, `Post`, `Tag`)
 
-```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)
-```
+### 아키텍처 구조
+- **도메인 로직**: `src/domain/blog/` 통합
+- **UI 컴포넌트**: `src/app/` 분리  
+- **모듈 레벨 캐싱**: 빌드 타임 데이터 사전 로드
 
 ## 콘텐츠 구조
 
-### MDX 파일 구조
+### MDX 파일
 ```
 src/contents/
-├── dev/           # 개발 카테고리
-│   ├── category.json
-│   └── *.mdx
-└── life/          # 일상 카테고리
-    ├── category.json
-    └── *.mdx
+├── dev/category.json + *.mdx
+└── life/category.json + *.mdx
 ```
 
-### 포스트 frontmatter
+### 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 (
-    <header className={cn('mb-8 pb-8', className)}>
-      <div className="flex items-center gap-3 mb-4">
-        {category && <CategoryBadge categoryId={category} />}
-        <h1 className="text-3xl font-bold">{title}</h1>
-      </div>
-      <TagList tags={tags} />
-    </header>
-  )
-}
+category: 'dev' # 또는 'life'
 ```
 
-## 품질 기준
+## 품질 체크리스트
 
-### TypeScript 엄격 모드
-- `any` 타입 사용 금지
-- 모든 Props 인터페이스 명시적 정의
-- 도메인 타입 재사용 (`CategoryId`, `Post`, `Tag`)
+### 컴포넌트 작성시
+- [ ] Props 인터페이스 정의
+- [ ] 서버 컴포넌트 우선 (상호작용 필요시만 클라이언트)
+- [ ] `cn()` 유틸리티로 클래스 병합
 
-### 테스트 패턴
-```typescript
-// 비즈니스 로직 테스트
-describe('태그 그래프 시스템', () => {
-  it('관련 포스트를 태그 유사도로 찾는다', () => {
-    const related = getRelatedPostsByTags('test-slug', 3)
-    expect(related).toHaveLength(3)
-  })
-})
-```
+### 데이터 처리시  
+- [ ] 도메인 API 함수 사용
+- [ ] 타입 안전성 보장
+- [ ] 빌드 타임 사전 계산 활용
 
 ### 성능 최적화
-- 모든 데이터 빌드 타임 사전 계산
-- `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. **컴포넌트 단순화**: 단일 책임 원칙
+- [ ] `generateStaticParams()` 정적 경로 생성
+- [ ] 컴포넌트 간 props 최소화
+- [ ] 모듈 레벨 캐싱 활용
diff --git a/.context/git-workflow.md b/.context/git-workflow.md
@@ -11,21 +11,9 @@
 - **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
-```
+- `feat/feature-name` - 기능 개발
+- `fix/issue-name` - 버그 수정  
+- `docs/document-name` - 문서 작업
 
 ## 커밋 컨벤션
 
@@ -49,7 +37,20 @@ footer (optional)
 
 ## 논리적 단위 커밋
 
-- 커밋은 변경사항 그룹끼리 묶여서 작성
+### 기본 원칙
+- **하나의 커밋 = 하나의 논리적 변경사항**
+- 서로 다른 기능/목적의 변경사항은 별도 커밋으로 분리
+- 각 커밋은 독립적으로 동작할 수 있어야 함
+
+### 커밋 워크플로우 (TodoWrite 필수)
+1. **변경사항 분석**: `git status`, `git diff` 확인
+2. **TodoWrite로 논리적 단위 계획**: 각 기능별 커밋 목록 작성
+3. **단계별 커밋**: 할일 완료하며 순차 실행
+4. **진행 추적**: TodoWrite에서 완료 체크
+
+### 올바른 커밋 분리
+- ✅ 기능별 분리: 메타데이터 / RSS / 레이아웃
+- ❌ 모든 변경사항을 한 번에 커밋
 
 ## PR 프로세스
 

diff --git a/.context/quality-checklist.md b/.context/quality-checklist.md
@@ -0,0 +1,41 @@
+# 품질 체크리스트
+
+## 커밋 전 필수 체크
+
+### TodoWrite 사용
+- [ ] 여러 변경사항이 있을 때 TodoWrite로 논리적 단위 계획
+- [ ] 각 커밋 단위별로 할일 목록 작성
+- [ ] 완료된 항목 실시간 체크
+
+### 코드 품질
+- [ ] `pnpm biome:check` 통과
+- [ ] `pnpm type` 통과  
+- [ ] `pnpm test` 통과
+
+### 아키텍처 준수
+- [ ] 도메인 API 사용 (`@/domain/blog` import)
+- [ ] `any` 타입 사용 없음
+- [ ] Props 인터페이스 정의
+
+## PR 생성 전 체크
+
+### 문서 업데이트
+- [ ] 변경된 영역의 CLAUDE.md 업데이트
+- [ ] 새로운 기능/패턴이 있으면 가이드라인 반영
+
+### 최종 검증
+- [ ] 모든 커밋이 논리적 단위로 분리됨
+- [ ] 커밋 메시지가 명확함
+- [ ] 테스트 통과 확인
+
+## 일상 개발 체크
+
+### 컴포넌트 작성
+- [ ] 서버 컴포넌트 우선 (상호작용 필요시만 클라이언트)
+- [ ] `cn()` 유틸리티로 클래스 병합
+- [ ] TypeScript 엄격 모드 준수
+
+### 성능 최적화
+- [ ] `generateStaticParams()` 정적 경로 생성
+- [ ] 모듈 레벨 캐싱 활용
+- [ ] 불필요한 props 전달 최소화
diff --git a/.kiro/steering/ui-design-system.md b/.kiro/steering/ui-design-system.md
@@ -144,7 +144,7 @@ text-4xl: 36px / 40px
 </div>
 
 // 최대 너비 제한
-<div className="max-w-4xl mx-auto px-5">
+<div className="max-w-5xl mx-auto px-5">
   {/* 콘텐츠 */}
 </div>
 ```

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -69,18 +69,18 @@ Next.js 15 기반 정적 블로그의 아키텍처 지침과 작업 가이드입
 - @.context/git-workflow.md - 브랜치 전략, 커밋 컨벤션
 
 ### 참조 정보  
-- @.context/current-status.md - 최신 작업 상태
 - @.context/project-overview.md - 기술 스택, 상세 구조
 - @.context/commands.md - 개발 명령어, 빌드 설정
+- @.context/quality-checklist.md - 품질 체크리스트
 
-## 🚀 작업 흐름
+## 🚀 작업 원칙
 
-1. **작업 영역 파악**: 수정할 파일의 디렉토리 확인
-2. **컨텍스트 확보**: 해당 영역의 CLAUDE.md 및 상위 문서 읽기
-3. **아키텍처 준수**: 도메인 분리, 타입 안전성, 성능 원칙 적용
-4. **문서 업데이트**: 작업 완료 후 해당 CLAUDE.md 즉시 업데이트
-5. **상위 영향 확인**: 변경사항이 상위 아키텍처에 미치는 영향 검토
+### 필수 체크
+- **TodoWrite 사용**: 복잡한 작업시 할일 목록으로 계획
+- **스코프별 CLAUDE.md 업데이트**: 작업 완료 후 즉시 반영
+- **품질 검증**: @.context/quality-checklist.md 준수
 
----
-
-💡 **Tip**: 새로운 기능 개발 시 먼저 해당 영역의 CLAUDE.md를 확인하고, 기존 패턴을 따라 일관성을 유지하세요.
+### 아키텍처 준수
+- **도메인 API 사용**: 직접 파일 시스템 접근 금지
+- **타입 안전성**: `any` 금지, 인터페이스 명시
+- **논리적 단위 커밋**: TodoWrite로 계획 후 분리 커밋