Skip to content

Commit 0b5e673

Browse files
kickbelldevclaude
kickbelldev
and
claude
authored
feat: Table of Contents 및 블로그 시스템 종합 개선 (#12)
* feat: Table of Contents 구현 포스트 페이지에 인터랙티브한 목차 기능을 추가하여 사용자 경험을 개선했습니다. 주요 기능: - MDX 헤딩 자동 추출 및 ID 생성 - 스크롤 스파이를 통한 현재 위치 표시 - 부드러운 스크롤 네비게이션 - 반응형 디자인 (데스크톱 사이드바, 모바일 상단) - 접근성 개선 (ARIA 라벨, 키보드 네비게이션) 기술적 구현: - extractHeadingsFromMDX(): 정규식 기반 헤딩 파싱 - TableOfContents: IntersectionObserver 활용 스크롤 스파이 - mdx-components: 헤딩 요소에 자동 ID 주입 - 계층적 들여쓰기 및 시각적 구분 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * docs: 지침 문서 시스템을 실행 중심으로 개편 장황한 문서들을 간결하고 실행 가능한 체크리스트 중심으로 전면 재구성: - development-guidelines.md: 157줄→51줄 압축, 핵심 원칙과 품질 체크리스트 중심 - git-workflow.md: TodoWrite 강제화로 논리적 단위 커밋 보장 - quality-checklist.md: 새로 추가, 커밋/PR/개발 단계별 필수 검증 항목 - CLAUDE.md: 작업 원칙 간소화, 핵심 체크 항목 명시 - current-status.md: 실질적 내용 없어 제거 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * feat: 메타데이터 시스템 및 RSS 피드 구현 포스트, 카테고리, 홈페이지별 동적 메타데이터 생성과 RSS 구독 기능 완성: - metadata.ts: 페이지별 SEO 메타데이터 생성 유틸리티 - rss.ts: RSS/Atom 피드 생성 로직 - generateMetadata: 각 페이지에 동적 메타데이터 적용 - /rss.xml, /atom.xml: 구독 가능한 피드 라우트 - layout.tsx: RSS 링크 및 기본 메타데이터 설정 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * refactor: UI/레이아웃 시스템 개선 사용자 경험과 성능을 위한 레이아웃 및 컴포넌트 최적화: - TableOfContents: 서버 컴포넌트로 리팩토링, 고정 사이드바 구현 - PostContent/Header: 간소화된 구조로 성능 개선 - Header: z-index 최적화로 TOC와 겹침 방지 - NavLink: 활성 상태 시각화 추가 - Footer: RSS 링크 추가 - 레이아웃: max-width 4xl→5xl 확장으로 가독성 향상 - Hero 섹션: 제거하여 콘텐츠 중심 홈페이지 구성 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
1 parent c9ab909 commit 0b5e673

File tree

25 files changed

+829
-252
lines changed

25 files changed

+829
-252
lines changed

‎.context/current-status.md‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.context/development-guidelines.md‎

Lines changed: 29 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,51 @@
11
# 개발 가이드라인
22

3-
이 블로그 프로젝트의 핵심 패턴과 구현 원칙을 정의합니다.
3+
## 필수 원칙
44

5-
## 아키텍처 패턴
5+
### 도메인 API 사용
6+
- ✅ `import { getCategoryById } from '@/domain/blog'`
7+
- ❌ 직접 파일 시스템 접근 금지
68

7-
### 도메인 중심 설계
8-
- **도메인 로직**: `src/domain/blog/` 에 통합
9-
- **UI 컴포넌트**: `src/app/` 하위에 구현
10-
- **타입 정의**: `src/domain/blog/types.ts` 중앙 집중
9+
### 타입 안전성
10+
- ✅ 모든 Props 인터페이스 명시
11+
- ❌ `any` 타입 사용 금지
12+
- ✅ 도메인 타입 재사용 (`CategoryId`, `Post`, `Tag`)
1113

12-
```typescript
13-
// 도메인 API 사용 예시
14-
import { getCategoryById, getPostsByCategory, getRelatedPostsByTags } from '@/domain/blog'
15-
16-
const category = getCategoryById('dev')
17-
const posts = getPostsByCategory('dev')
18-
const related = getRelatedPostsByTags(currentSlug, 3)
19-
```
20-
21-
### 모듈 레벨 캐싱
22-
빌드 타임에 모든 데이터를 사전 로드하여 SSG 최적화
23-
24-
```typescript
25-
// src/domain/blog/index.ts
26-
export const allPosts = await getAllPosts()
27-
export const allCategories = await getAllCategories()
28-
export const allTags = extractTagsFromPosts(allPosts)
29-
export const tagGraph = createTagGraph(allPosts, allTags)
30-
export const tagClusters = createTagClusters(tagGraph)
31-
```
32-
33-
### 태그 그래프 시스템
34-
graphology 라이브러리로 태그 간 관계 분석
35-
36-
```typescript
37-
// 태그 관계 분석
38-
const relationships = getTagRelationships()
39-
const clusters = getTagClusters()
40-
const relatedPosts = getRelatedPostsByTags(currentSlug, 3)
41-
```
14+
### 아키텍처 구조
15+
- **도메인 로직**: `src/domain/blog/` 통합
16+
- **UI 컴포넌트**: `src/app/` 분리
17+
- **모듈 레벨 캐싱**: 빌드 타임 데이터 사전 로드
4218

4319
## 콘텐츠 구조
4420

45-
### MDX 파일 구조
21+
### MDX 파일
4622
```
4723
src/contents/
48-
├── dev/ # 개발 카테고리
49-
│ ├── category.json
50-
│ └── *.mdx
51-
└── life/ # 일상 카테고리
52-
├── category.json
53-
└── *.mdx
24+
├── dev/category.json + *.mdx
25+
└── life/category.json + *.mdx
5426
```
5527

56-
### 포스트 frontmatter
28+
### frontmatter 필수 필드
5729
```yaml
58-
---
5930
title: '포스트 제목'
6031
date: 2025-01-17
6132
tags: ['tag1', 'tag2']
62-
description: '포스트 설명'
63-
category: 'dev' # 또는 'life'
64-
---
65-
```
66-
67-
### 카테고리 메타데이터
68-
```json
69-
{
70-
"name": "개발",
71-
"description": "개발 관련 포스트",
72-
"color": "blue",
73-
"icon": "💻"
74-
}
75-
```
76-
77-
## 컴포넌트 패턴
78-
79-
### 타입 정의
80-
```typescript
81-
interface PostHeaderProps {
82-
title: string
83-
date: string
84-
tags: string[]
85-
category?: CategoryId
86-
readingTime?: number
87-
author?: string
88-
className?: string
89-
}
90-
```
91-
92-
### 컴포넌트 구현
93-
```typescript
94-
// 서버 컴포넌트 기본, 상호작용 필요시만 클라이언트
95-
export function PostHeader({ title, date, tags, category }: PostHeaderProps) {
96-
return (
97-
<header className={cn('mb-8 pb-8', className)}>
98-
<div className="flex items-center gap-3 mb-4">
99-
{category && <CategoryBadge categoryId={category} />}
100-
<h1 className="text-3xl font-bold">{title}</h1>
101-
</div>
102-
<TagList tags={tags} />
103-
</header>
104-
)
105-
}
33+
category: 'dev' # 또는 'life'
10634
```
10735
108-
## 품질 기준
36+
## 품질 체크리스트
10937
110-
### TypeScript 엄격 모드
111-
- `any` 타입 사용 금지
112-
- 모든 Props 인터페이스 명시적 정의
113-
- 도메인 타입 재사용 (`CategoryId`, `Post`, `Tag`)
38+
### 컴포넌트 작성시
39+
- [ ] Props 인터페이스 정의
40+
- [ ] 서버 컴포넌트 우선 (상호작용 필요시만 클라이언트)
41+
- [ ] `cn()` 유틸리티로 클래스 병합
11442

115-
### 테스트 패턴
116-
```typescript
117-
// 비즈니스 로직 테스트
118-
describe('태그 그래프 시스템', () => {
119-
it('관련 포스트를 태그 유사도로 찾는다', () => {
120-
const related = getRelatedPostsByTags('test-slug', 3)
121-
expect(related).toHaveLength(3)
122-
})
123-
})
124-
```
43+
### 데이터 처리시
44+
- [ ] 도메인 API 함수 사용
45+
- [ ] 타입 안전성 보장
46+
- [ ] 빌드 타임 사전 계산 활용
12547

12648
### 성능 최적화
127-
- 모든 데이터 빌드 타임 사전 계산
128-
- `generateStaticParams()` 사용한 정적 경로 생성
129-
- 컴포넌트 간 props 최소화
130-
131-
## 디렉토리 구조
132-
133-
```
134-
src/
135-
├── app/ # Next.js App Router
136-
│ ├── [category]/ # 카테고리 페이지
137-
│ │ ├── [slug]/ # 포스트 상세
138-
│ │ └── _components/ # 페이지별 컴포넌트
139-
│ └── _components/ # 전역 컴포넌트
140-
├── domain/blog/ # 도메인 로직
141-
│ ├── index.ts # 공개 API + 캐싱
142-
│ ├── types.ts # 타입 정의
143-
│ └── logic/ # 비즈니스 로직
144-
│ ├── posts.ts
145-
│ ├── categories.ts
146-
│ └── tags.ts
147-
└── contents/ # MDX 콘텐츠
148-
├── dev/
149-
└── life/
150-
```
151-
152-
## 구현 원칙
153-
154-
1. **도메인 API 사용**: 직접 파일 시스템 접근 금지
155-
2. **타입 안전성**: 모든 데이터 흐름 타입 보장
156-
3. **모듈 레벨 캐싱**: 빌드 타임 데이터 사전 로드
157-
4. **컴포넌트 단순화**: 단일 책임 원칙
49+
- [ ] `generateStaticParams()` 정적 경로 생성
50+
- [ ] 컴포넌트 간 props 최소화
51+
- [ ] 모듈 레벨 캐싱 활용

‎.context/git-workflow.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,9 @@
1111
- **docs/**: 문서 작업용 브랜치
1212

1313
### 브랜치 네이밍
14-
```bash
15-
# 기능 개발 (실제 프로젝트 패턴)
16-
feat/entities
17-
feat/post-navigation
18-
feat/entity-optimization-and-category-system
19-
20-
# 버그 수정
21-
fix/resolve-navigation-issue
22-
fix/correct-typo-in-header
23-
24-
# 문서/설정 작업
25-
docs/claude-pr-workflow
26-
config/github-templates
27-
config/tailwind-setup
28-
```
14+
- `feat/feature-name` - 기능 개발
15+
- `fix/issue-name` - 버그 수정
16+
- `docs/document-name` - 문서 작업
2917

3018
## 커밋 컨벤션
3119

@@ -49,7 +37,20 @@ footer (optional)
4937

5038
## 논리적 단위 커밋
5139

52-
- 커밋은 변경사항 그룹끼리 묶여서 작성
40+
### 기본 원칙
41+
- **하나의 커밋 = 하나의 논리적 변경사항**
42+
- 서로 다른 기능/목적의 변경사항은 별도 커밋으로 분리
43+
- 각 커밋은 독립적으로 동작할 수 있어야 함
44+
45+
### 커밋 워크플로우 (TodoWrite 필수)
46+
1. **변경사항 분석**: `git status`, `git diff` 확인
47+
2. **TodoWrite로 논리적 단위 계획**: 각 기능별 커밋 목록 작성
48+
3. **단계별 커밋**: 할일 완료하며 순차 실행
49+
4. **진행 추적**: TodoWrite에서 완료 체크
50+
51+
### 올바른 커밋 분리
52+
- ✅ 기능별 분리: 메타데이터 / RSS / 레이아웃
53+
- ❌ 모든 변경사항을 한 번에 커밋
5354

5455
## PR 프로세스
5556

‎.context/quality-checklist.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# 품질 체크리스트
2+
3+
## 커밋 전 필수 체크
4+
5+
### TodoWrite 사용
6+
- [ ] 여러 변경사항이 있을 때 TodoWrite로 논리적 단위 계획
7+
- [ ] 각 커밋 단위별로 할일 목록 작성
8+
- [ ] 완료된 항목 실시간 체크
9+
10+
### 코드 품질
11+
- [ ] `pnpm biome:check` 통과
12+
- [ ] `pnpm type` 통과
13+
- [ ] `pnpm test` 통과
14+
15+
### 아키텍처 준수
16+
- [ ] 도메인 API 사용 (`@/domain/blog` import)
17+
- [ ] `any` 타입 사용 없음
18+
- [ ] Props 인터페이스 정의
19+
20+
## PR 생성 전 체크
21+
22+
### 문서 업데이트
23+
- [ ] 변경된 영역의 CLAUDE.md 업데이트
24+
- [ ] 새로운 기능/패턴이 있으면 가이드라인 반영
25+
26+
### 최종 검증
27+
- [ ] 모든 커밋이 논리적 단위로 분리됨
28+
- [ ] 커밋 메시지가 명확함
29+
- [ ] 테스트 통과 확인
30+
31+
## 일상 개발 체크
32+
33+
### 컴포넌트 작성
34+
- [ ] 서버 컴포넌트 우선 (상호작용 필요시만 클라이언트)
35+
- [ ] `cn()` 유틸리티로 클래스 병합
36+
- [ ] TypeScript 엄격 모드 준수
37+
38+
### 성능 최적화
39+
- [ ] `generateStaticParams()` 정적 경로 생성
40+
- [ ] 모듈 레벨 캐싱 활용
41+
- [ ] 불필요한 props 전달 최소화

‎.kiro/steering/ui-design-system.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ text-4xl: 36px / 40px
144144
</div>
145145

146146
// 최대 너비 제한
147-
<div className="max-w-4xl mx-auto px-5">
147+
<div className="max-w-5xl mx-auto px-5">
148148
{/* 콘텐츠 */}
149149
</div>
150150
```

‎CLAUDE.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -69,18 +69,18 @@ Next.js 15 기반 정적 블로그의 아키텍처 지침과 작업 가이드입
6969
- @.context/git-workflow.md - 브랜치 전략, 커밋 컨벤션
7070

7171
### 참조 정보
72-
- @.context/current-status.md - 최신 작업 상태
7372
- @.context/project-overview.md - 기술 스택, 상세 구조
7473
- @.context/commands.md - 개발 명령어, 빌드 설정
74+
- @.context/quality-checklist.md - 품질 체크리스트
7575

76-
## 🚀 작업 흐름
76+
## 🚀 작업 원칙
7777

78-
1. **작업 영역 파악**: 수정할 파일의 디렉토리 확인
79-
2. **컨텍스트 확보**: 해당 영역의 CLAUDE.md 및 상위 문서 읽기
80-
3. **아키텍처 준수**: 도메인 분리, 타입 안전성, 성능 원칙 적용
81-
4. **문서 업데이트**: 작업 완료 후 해당 CLAUDE.md 즉시 업데이트
82-
5. **상위 영향 확인**: 변경사항이 상위 아키텍처에 미치는 영향 검토
78+
### 필수 체크
79+
- **TodoWrite 사용**: 복잡한 작업시 할일 목록으로 계획
80+
- **스코프별 CLAUDE.md 업데이트**: 작업 완료 후 즉시 반영
81+
- **품질 검증**: @.context/quality-checklist.md 준수
8382

84-
---
85-
86-
💡 **Tip**: 새로운 기능 개발 시 먼저 해당 영역의 CLAUDE.md를 확인하고, 기존 패턴을 따라 일관성을 유지하세요.
83+
### 아키텍처 준수
84+
- **도메인 API 사용**: 직접 파일 시스템 접근 금지
85+
- **타입 안전성**: `any` 금지, 인터페이스 명시
86+
- **논리적 단위 커밋**: TodoWrite로 계획 후 분리 커밋

0 commit comments

Comments
 (0)