Skip to content

Next.js 사용된 CLAUDE.md 양식 #2

New issue
New issue
Open
Open
Next.js 사용된 CLAUDE.md 양식#2
@demodev-works

Description

@demodev-works
demodev-works
opened on Aug 4, 2025

🔄 프로젝트 인식 및 컨텍스트

  • 새로운 대화를 시작할 때 항상 PLANNING.md를 읽어 프로젝트의 아키텍처, 목표, 스타일, 제약사항을 이해한다.
  • 새로운 작업을 시작하기 전에 TASK.md를 확인한다. 작업이 목록에 없다면 간단한 설명과 오늘 날짜를 추가한다.
  • PLANNING.md에 설명된 일관된 명명 규칙, 파일 구조, 아키텍처 패턴을 사용한다.
  • 개발 서버는 개발자가 직접 로컬에서 npm run dev를 실행한다. Claude Code는 백그라운드에서 서버를 실행하지 않으며, 개발자가 수동으로 서버를 시작하고 관리한다.
  • 초기 DB 구조는 **docs/references/db-structure.sql**를 따른다. 만약, 초기 DB구조로 구현이 불가능한 사항이 생기면, 어떤 변경을 해야하며 또 그 이유는 무엇인지를 논리적으로 설명하면서 반드시, 사용자에게 승인을 구해야 한다.
  • /docs/references/database-erd.mdc 를 참고하여 database 설계를 이해한다.
  • **http://localhost:8000/api/redoc/**의 설계대로 동작하도록 구현해야 한다.

🧱 코드 구조 및 모듈화- 500줄을 초과하는 컴포넌트나 파일을 절대 만들지 않는다. 파일이 이 제한에 근접하면 하위 컴포넌트나 유틸리티 함수로 분할하여 리팩토링한다.

  • Feature-based 모듈화를 사용한다.
    각 기능은 features/ 폴더 내에 독립적인 모듈로 구성된다:
    features/ ├── [feature-name]/ │ ├── components/ # 피처 전용 컴포넌트 │ ├── screens/ # 주요 화면 컴포넌트 │ ├── hooks/ # 커스텀 훅 │ ├── types.ts # 타입 정의 │ ├── constants.ts # 상수 정의 │ ├── utils/ # 유틸리티 함수 │ └── index.ts # 모듈 내보내기
  • 공통 컴포넌트는 components/ 폴더에, 공유 유틸리티는 shared/ 폴더에 배치한다.
  • 절대 경로 import를 사용한다 (@/components, @/lib, @/features 등).
  • 각 피처의 index.ts에서 명시적으로 내보내기를 정의한다.

🔨 작업 진행 방식

  • 작업을 의미있는 커밋 가능한 단위로 나누어 진행한다
  • 한 번에 모든 기능을 구현하지 말고, 논리적 단위로 나누어 작업
  • 각 단계가 완료되면 개발 서버에서 테스트하여 정상 동작 확인
  • 사용자가 원할 때 커밋할 수 있도록 완성된 상태 유지
  • 작업 단위 예시:
  1. 타입 정의 → 인터페이스 및 스키마 작성
  2. 컴포넌트 구현 → 기본 UI 구조 작성
  3. 상태 관리 → React Query 훅 또는 Zustand 스토어 구현
  4. 비즈니스 로직 → 커스텀 훅으로 로직 분리
  5. 스타일링 → Tailwind CSS로 디자인 적용
  6. 테스트 → Playwright E2E 테스트 작성

  • 각 작업 단위 완료 시:

  • 구현한 내용 요약 제공

  • 개발 서버 실행 결과 확인

  • 다음 작업 단위 예고

  • 절대 하지 말아야 할 것:

  • ❌ 여러 기능을 한꺼번에 구현

  • ❌ 테스트 없이 다음 단계로 진행

  • ❌ 미완성 상태로 다음 작업 시작

🧪 테스트 및 신뢰성

  • 새로운 기능에 대해 항상 Playwright E2E 테스트를 작성한다 (사용자 시나리오, 페이지 네비게이션, 폼 제출 등).
  • 컴포넌트 로직을 업데이트한 후, 기존 테스트의 업데이트가 필요한지 확인한다.
    필요하다면 업데이트한다.
  • 테스트는 /tests 폴더에 위치하며 실제 사용자 워크플로우를 테스트한다.
  • 최소한 다음을 포함한다:
  • 정상 시나리오 테스트 1개
  • 에러 처리 테스트 1개
  • 반응형 디자인 테스트 1개

🔐 테스트 인증 플로우 (Custom Fixture 시스템)

로그인에서 홈화면까지의 완전한 플로우:

  1. 테스트 계정 토글 선택 → 데모계정 선택(demo@example.com) → 로그인버튼 활성화
  2. 로그인버튼 클릭 → access token 발급 완료
  3. 사용자 상태 확인: hasCompletedOnboarding 값에 따라
  • true: 온보딩 패스 → 바로 홈화면
  • false: 온보딩 단계 진행
  1. 홈화면 진입 → 성과보고서 모달 등장
  2. 성과보고서 6단계 진행: "다음" 버튼 6번 클릭 → "완료" 버튼 클릭
  3. 공복체중 입력 모달 등장 → ESC키로 모달 닫기 (개발모드)
  4. meals 테스트 진행 가능 상태Custom Fixture 사용법:
    typescriptimport { test, expect } from '../fixtures/authenticated-page'test('meals API test', async ({ authenticatedPage }) => { // 이미 로그인 완료, 성과보고서 완료, 공복체중 모달 닫기 완료된 상태 await authenticatedPage.goto('/meal-logging') // 실제 테스트 로직...})
    관련 파일:- tests/fixtures/authenticated-page.ts: Custom Fixture 구현- tests/helpers/auth-helper.ts: 로그인 플로우 로직

✅ 작업 완료

  • 작업을 완료한 직후 TASK.md에 완료된 작업을 표시한다.
  • 개발 중 발견된 새로운 하위 작업이나 TODO를 TASK.md의 "작업 중 발견 사항" 섹션에 추가한다.
  • 작업을 완료한 직후 사용한 프롬프트를 prompts/prompt-list.md 위치에 저장한다.

📎 스타일 및 규칙

  • TypeScript를 주 언어로 사용한다.
  • React 함수형 컴포넌트와 Hooks를 사용한다.
  • Tailwind CSS를 사용하여 스타일링한다 (인라인 클래스 사용).
  • shadcn/ui 컴포넌트를 우선 사용한다 (Button, Input, Dialog 등).
  • 상태 관리는 React Query (서버 상태) + Zustand (클라이언트 상태)를 사용한다.
  • 폼 관리는 React Hook Form + Zod를 사용한다.
  • 모든 컴포넌트와 함수에 JSDoc 주석을 작성한다:
    typescript /** * 사용자 프로필 카드 컴포넌트 * * @param user - 사용자 정보 객체 * @param onEdit - 편집 버튼 클릭 핸들러 * @returns 사용자 프로필 카드 JSX 엘리먼트 */ function UserProfileCard({ user, onEdit }: UserProfileCardProps) { // ... }

🔧 TypeScript 타입 에러 수정 규칙**

타입 에러 발생 시 반드시 docs/development/typescript-error-handling-rules.md의 규칙을 따른다.

🚨 절대 금지 사항

  • any 타입으로 에러를 숨기지 않는다
  • @ts-ignore 주석 사용 금지
  • 타입 단언(as) 남용 금지

📋 에러 처리 우선순위

  1. Critical: undefined/null 접근 → 옵셔널 체이닝(?.) + 기본값
  2. High: API 메서드 미존재 → 실제 API 인터페이스 확인 후 수정
  3. Medium: 타입 불일치 → 타입 매핑 함수 또는 유니온 타입 확장

🛠 표준 해결 패턴

typescript// ✅ Undefined 처리const items = response.data?.items || []// ✅ API 메서드 확인// 추측하지 말고 실제 메서드 존재 여부 확인const methods = Object.getOwnPropertyNames(api)console.log('Available methods:', methods)// ✅ 타입 매핑const MAPPING = { 'carbs': 'carbohydrates' } as constconst mappedType = MAPPING[frontendType] || frontendType

📚 문서화 및 설명- 새로운 기능이 추가되거나, 의존성이 변경되거나, 설정 단계가 수정될 때 README.md를 업데이트한다.

  • 명확하지 않은 코드에 주석을 달고 모든 것이 중급 React 개발자에게 이해 가능하도록 한다.
  • 복잡한 비즈니스 로직을 작성할 때, 인라인 주석을 추가하여 무엇을 하는지가 아닌 왜 하는지를 설명한다.

🎨 UI/UX 가이드라인

  • shadcn/ui 컴포넌트를 최대한 활용한다 (일관된 디자인 시스템 유지).
  • 반응형 디자인을 항상 고려한다 (모바일 우선 접근).
  • 접근성을 고려한다 (ARIA 라벨, 키보드 네비게이션 등).
  • 로딩 상태와 에러 상태를 적절히 처리한다.

🔌 API 및 데이터 관리

  • React Query를 사용하여 서버 상태를 관리한다.
  • API 호출은 /lib/api/ 폴더에 모듈화한다.
  • 타입 안전성을 보장하기 위해 API 응답에 대한 타입을 정의한다.
  • 에러 처리를 적절히 구현한다 (토스트 메시지, 에러 바운더리 등).

🚨 Mock API 사용 금지 정책

  • ✅ 절대 Mock API나 Mock 데이터를 사용하지 않는다
  • ✅ 모든 데이터는 Real API에서만 조회한다 (/lib/api/real/ 사용)
  • ✅ Mock 폴더(/lib/api/mock/)의 파일들은 사용하지 않는다
  • ✅ 하드코딩된 값 대신 백엔드 API 응답값을 사용한다
  • ✅ 새로운 Mock 데이터를 생성하지 않는다
  • ✅ 기존 Mock 데이터 참조를 Real API로 교체한다

🧠 AI 동작 규칙

  • 누락된 컨텍스트를 가정하지 않는다. 불확실할 때는 질문한다.
  • 라이브러리나 함수를 임의로 만들지 않는다
    – 알려진, 검증된 React/Next.js 패키지만 사용한다.
  • 코드에서 참조하기 전에 파일 경로와 컴포넌트 이름이 존재하는지 항상 확인한다.
  • 명시적으로 지시받거나 TASK.md의 작업의 일부가 아닌 한 기존 코드를 삭제하거나 덮어쓰지 않는다.

📝 Git 커밋 컨벤션

"작은 단위로, 명확한 목적을 가진 커밋"

커밋 메시지 형식

<type>(<scope>): <subject><body><footer>

Type (필수)

  • feat: 새로운 기능 추가
  • fix: 버그 수정
  • docs: 문서 수정
  • style: 코드 포맷팅, 세미콜론 누락 등 (코드 변경 없음)
  • refactor: 코드 리팩토링 (기능 변경 없음)
  • test: 테스트 추가 또는 수정
  • chore: 빌드 작업, 패키지 매니저 설정 등
  • perf: 성능 개선#### Scope (선택)
  • ui: UI 컴포넌트
  • api: API 관련
  • auth: 인증 관련
  • test: 테스트 관련
  • 기능명: meal-tracking, analytics 등

Subject (필수)

  • 50자 이내로 작성
  • 명령문으로 작성 (동사원형 사용)
  • 마침표 없음
  • 한글 사용 가능

Body (선택)

  • 무엇을, 왜 변경했는지 설명
  • 줄바꿈은 72자마다
  • 리스트 사용 가능 (-, *)

커밋 순서 가이드

  1. 기능 구현: 컴포넌트/로직 먼저
  2. 테스트 추가: 구현한 기능의 테스트
  3. 문서화: 필요한 문서 업데이트
  4. 정리: 불필요한 코드 제거

예시

bashfeat(ui): WheelPicker 컴포넌트에 마우스 휠 이벤트 지원 추가- WheelPicker와 DecimalWheelPicker에 onWheel 핸들러 구현- 마우스 휠로 값을 증가/감소할 수 있도록 개선- 스프링 애니메이션과 햅틱 피드백 지원- E2E 테스트 자동화를 위한 접근성 향상
bashtest: localStorage 인증 토큰 저장 E2E 테스트 추가- 로그인 후 accessToken/refreshToken 저장 확인- JWT 토큰 형식 검증- 페이지 새로고침 후 토큰 유지 확인

커밋 분리 원칙

  • 한 커밋에는 하나의 논리적 변경사항만
  • 커밋은 독립적으로 실행 가능한 상태 유지
  • 테스트가 통과하는 상태로 커밋
  • 관련없는 변경사항은 별도 커밋으로 분리

커밋 메시지 제외 사항

  • Claude Code 관련 내용을 절대 포함하지 않는다
  • 다음과 같은 내용들은 커밋 메시지에서 제외:
    • 🤖 Generated with [Claude Code](https://claude.ai/code)
    • Co-Authored-By: Claude <noreply@anthropic.com>
    • 기타 Claude Code 도구 관련 언급

📱 모바일 최적화

  • 모든 UI는 모바일 우선으로 설계한다.
  • 터치 인터페이스를 고려한다 (적절한 터치 타겟 크기, 제스처 지원).
  • 성능을 최적화한다 (이미지 최적화, 지연 로딩 등).

중요 지시사항
알림요청받은 것만 한다.
더도 말고 덜도 말고.
목표 달성에 절대적으로 필요한 경우가 아니라면 파일을 생성하지 않는다.
항상 새 파일을 만드는 것보다 기존 파일을 편집하는 것을 선호한다.
사용자가 명시적으로 요청하지 않는 한 문서 파일(*.md)이나 README 파일을 생성하지 않는다.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions