CLAUDE.md 프로젝트 규칙, 코딩 컨벤션, 워크플로우 설정

# Project Context

This is a Next.js 14 blog built with:
- Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS
- Content: MDX files in /content/posts/
- Deployment: Vercel

## Directory Structure
- /app: Next.js app router pages
- /components: React components
- /content/posts: Blog post MDX files
- /lib: Utility functions

## Coding Conventions

### TypeScript
- Always use strict mode
- Prefer type over interface for object types
- Use explicit return types for all functions
- No any types - use unknown instead

### React
- Use functional components only (no class components)
- Prefer named exports over default exports
- Use React Server Components by default
- Client components must have 'use client' directive

## Development Workflow

### Before Making Changes
1. Read existing code first - understand before modifying
2. Check for related tests
3. Verify the change aligns with our architecture

### After Implementation
1. Run `npm run typecheck` - must pass
2. Run `npm test` - all tests must pass
3. Run `npm run build` - verify production build succeeds
4. Manual testing in dev environment

### Git Workflow
- Feature branches: `feature/short-description`
- Commit messages: Follow conventional commits
- Always squash before merging to main

- Write good error messages

- Error messages should be user-facing and actionable:
  ✅ "Email format invalid. Expected: user@example.com"
  ❌ "Invalid input"

## Critical Rules (MUST follow)
- Never commit secrets or API keys
- All database queries must use prepared statements
- Authentication required for all /api/admin/* endpoints

## Style Preferences (SHOULD follow)
- Prefer functional programming patterns
- Use descriptive variable names
- Keep functions under 50 lines

## API Route Pattern

All API routes should follow this structure:

```typescript
// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const schema = z.object({
  title: z.string().min(1),
  content: z.string(),
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = schema.parse(body);

    // Business logic here

    return NextResponse.json({ success: true });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

### 4. 자주 발생하는 실수 명시

프로젝트에서 반복적으로 발생하는 문제를 미리 방지할 수 있습니다.

```markdown
## Common Mistakes to Avoid

❌ Don't use `fetch` in Server Components - use our `db` client directly
❌ Don't use `useEffect` for data fetching - use React Server Components
❌ Don't import from `@/components/index` - import directly from component files
❌ Don't use CSS modules - we use Tailwind only

✅ Do use Server Actions for mutations
✅ Do use `<Link>` instead of `<a>` for internal navigation
✅ Do use absolute imports with `@/` prefix
✅ Do validate all user input with Zod

# Blog Project - Claude Code Instructions

## Project Overview
Next.js 14 blog with MDX content, series support, and search functionality.

## Tech Stack
- Next.js 14.2+ (App Router, React Server Components)
- TypeScript 5.4+ (strict mode)
- Tailwind CSS 3.4+
- MDX for blog content
- Vercel for deployment

## File Organization

### Content Structure
- Blog posts: `/content/posts/*.md`
- Front matter required: title, date, description, tags, series (optional), draft
- Use ISO date format: YYYY-MM-DD

### Code Structure
- `/app`: Next.js app router (layouts, pages, API routes)
- `/components`: Reusable React components
- `/lib`: Utilities (mdx processing, search indexing, etc.)
- `/public`: Static assets (images, favicon, etc.)

## Development Rules

### Content Guidelines
1. All blog posts must include proper front matter
2. Code blocks must specify language for syntax highlighting
3. Use h2/h3 headings for automatic TOC generation
4. Keep line length under 100 characters for readability

### Code Standards
1. TypeScript strict mode - no implicit any
2. Named exports only (no default exports except page.tsx)
3. Server Components by default - add 'use client' only when needed
4. Tailwind for all styling - no CSS modules or inline styles

### Before Committing
- Run `npm run build` to verify production build
- Check that all MDX files have valid front matter
- Verify no hardcoded URLs (use env vars)
- Test search functionality if content changed

## Architecture Decisions

### Why Server Components?
We use React Server Components for all blog pages to:
- Reduce client-side JavaScript
- Improve SEO and initial page load
- Simplify data fetching

### Why MDX in /content?
- Version control friendly
- Easy to edit in any text editor
- Supports front matter for metadata
- Can embed React components when needed

## Common Tasks

### Adding a New Blog Post
1. Create `/content/posts/slug-name.md`
2. Add front matter (copy from existing post)
3. Write content with proper headings
4. Test locally: `npm run dev`
5. Verify in production build: `npm run build && npm start`

### Adding a New Component
1. Create in `/components/ComponentName.tsx`
2. Use named export: `export function ComponentName()`
3. Add TypeScript props interface
4. Use Tailwind for styling
5. Test in Storybook if applicable

## Don't Do This
- Don't modify /node_modules or /package-lock.json manually
- Don't use `any` type - use `unknown` or proper types
- Don't create new CSS files - use Tailwind
- Don't use client-side rendering for static content
- Don't commit commented-out code - delete it

## Workflow Preferences
- Read existing code before making changes
- Make surgical changes - only touch what's necessary
- Verify changes don't break existing functionality
- Keep commits focused and atomic