David Brain

UI (web-plate)

4 min read

ID: key_26_22_05_25_18_03_00_00000 Created date: 5월 25 2026 월요일, 22주 18:00

연관 문서

개발 전 사전 정의 | UI 개발

개요

web-plate 레포에서 Claude Code가 개발을 진행하려면
레포 루트의 CLAUDE.md 파일에 아래 항목이 정의되어 있어야 한다.

프로젝트 파일 위치

web-plate/
├── CLAUDE.md                        ← ★ Claude Code가 읽는 핵심 파일
├── .env.local                       ← 환경변수 (gitignore)
├── .env.example                     ← 환경변수 예시 (커밋 대상)
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── src/
    ├── app/                         ← Next.js App Router 루트
    │   ├── (auth)/                  ← 인증 관련 페이지 그룹
    │   │   ├── login/page.tsx
    │   │   └── register/page.tsx
    │   ├── (main)/                  ← 인증 후 페이지 그룹
    │   │   ├── dashboard/page.tsx
    │   │   ├── projects/
    │   │   │   └── [projectId]/
    │   │   │       ├── board/page.tsx
    │   │   │       ├── issues/page.tsx
    │   │   │       └── settings/page.tsx
    │   │   └── issues/
    │   │       └── [issueId]/page.tsx
    │   ├── api/                     ← Next.js API Routes (next-auth 등)
    │   │   └── auth/[...nextauth]/route.ts
    │   └── layout.tsx
    ├── components/                  ← 공통 컴포넌트
    │   ├── ui/                      ← 기본 UI (Button, Modal, Badge 등)
    │   ├── issue/                   ← 이슈 관련 컴포넌트
    │   └── board/                   ← 칸반 보드 컴포넌트
    ├── stores/                      ← Zustand 스토어
    │   ├── authStore.ts
    │   └── issueStore.ts
    ├── lib/                         ← 유틸 / API 클라이언트
    │   ├── api.ts                   ← Axios 인스턴스
    │   └── auth.ts                  ← next-auth 설정
    └── types/                       ← TypeScript 타입 정의
        └── index.ts

CLAUDE.md 정의 항목 및 예시

1. 기술 스택 요약

## Tech Stack
- Framework: Next.js 16.1.3 (App Router, Turbopack)
- Language: TypeScript 5.7.2
- React: 19.0.1
- State: Zustand 5.0.1
- Styling: Tailwind CSS 3.4.19 + tailwind-merge + clsx
- Auth: next-auth 5.0.0-beta
- HTTP: Axios 1.7.9
- Icons: lucide-react 0.460.0
- Real-time: solclientjs 10.18.3 (Solace)
- Component Library: (결정 필요 — Shadcn/ui 권장)
- Chart: (결정 필요 — Recharts 권장)
- D&D: (결정 필요 — @hello-pangea/dnd 권장)

2. 라우팅 구조

## Routing (App Router)
- (auth) 그룹: /login, /register — 미인증 접근 가능
- (main) 그룹: /dashboard, /projects/[id]/board 등 — 인증 필수
- middleware.ts에서 인증 여부 분기 처리

작성 필요: 실제 사용할 라우트 목록 확정 후 기재

3. API 호출 패턴

## API Call Pattern
- 파일 위치: src/lib/api.ts
- Axios 인스턴스에 baseURL, Authorization 헤더 자동 주입
- 서버 URL: process.env.NEXT_PUBLIC_API_URL
 
예시:
import { api } from '@/lib/api'
const { data } = await api.get('/projects/123/issues')

4. 상태 관리 패턴 (Zustand)

## State Management (Zustand)
- 파일 위치: src/stores/
- 스토어 분리 기준: 도메인 단위 (auth, issue, project, sprint)
 
예시 (src/stores/issueStore.ts):
interface IssueStore {
  issues: Issue[]
  selectedIssue: Issue | null
  setIssues: (issues: Issue[]) => void
}

5. 환경변수 목록

## Environment Variables (.env.local)
NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_SOLACE_HOST=          ← Solace 브로커 주소
NEXT_PUBLIC_SOLACE_VPN=           ← Solace VPN명

작성 필요: Solace 연결 정보 및 실제 키명 확인 후 기재

6. 컴포넌트 작성 규칙

## Component Convention
- 파일명: PascalCase (IssueCard.tsx)
- props 타입: 파일 내 interface로 정의
- Server Component 기본, 상호작용 필요 시 'use client' 명시
- 스타일: Tailwind 클래스 사용, cn() 유틸 적용
 
예시:
import { cn } from '@/lib/utils'
 
interface IssueCardProps {
  title: string
  status: IssueStatus
  className?: string
}
 
export function IssueCard({ title, status, className }: IssueCardProps) {
  return (
    <div className={cn('rounded-lg border p-4', className)}>
      {title}
    </div>
  )
}

연관 메일

Graph View

Backlinks