Skip to content

CLAUDE.md

Latest commit

 

History

History
98 lines (74 loc) · 6.66 KB

CLAUDE.md

File metadata and controls

98 lines (74 loc) · 6.66 KB

CLAUDE.md — Deck

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

셋업 & 실행

최초 셋업: mise install → cd frontend && pnpm install → docker compose up -d postgres

서비스 포트 명령
Frontend app 4011 cd frontend/app && pnpm dev
Frontend linkpie 4011 cd frontend/linkpie && pnpm dev
Frontend deskpie 4011 cd frontend/deskpie && pnpm dev
Backend app 8011 cd backend && ./gradlew :dist:app:bootRun 2>&1 | humanlog
Backend linkpie 8011 cd backend && ./gradlew :dist:linkpie:bootRun 2>&1 | humanlog
Backend deskpie 8011 cd backend && ./gradlew :dist:deskpie:bootRun 2>&1 | humanlog
DB 5011 docker compose up -d postgres

스택

  • FE: Vite (SPA), React 19, Tailwind v4, shadcn/ui (Radix), RHF + zod, Tabulator
  • BE: Java 25, Spring Boot 4, Kotlin, PostgreSQL, Flyway, Spring Modulith

구조 & 도메인 경계

  • FE: frontend/{app,linkpie,deskpie}/src/ — FSD (app/pages/features/widgets/entities/shared/)
  • BE: backend/{iam,crypto,notification,audit,linkpie,deskpie,common,dist}/
  • app (control-plane): 인증, OAuth, 레이아웃, 사용자, 권한(글로벌), workspace CRUD
  • linkpie/deskpie (data-plane): 각 서비스 도메인 코드만 — 공통은 반드시 app에 배치
  • linkpie 상세: docs/reference/linkpie.md

명령어

FE (cd frontend/app): pnpm vitest run (전체) · pnpm vitest run src/path/file.test.ts (단일) · pnpm format · pnpm test:e2e · pnpm build BE (cd backend): ./gradlew test (전체) · ./gradlew :모듈:test --tests "패키지.클래스명" (단일) · ./gradlew ktlintCheck · ./gradlew ktlintFormat · ./gradlew :dist:app:flywayMigrate Git Hooks (lefthook): pre-commit — ktlint (BE), prettier --check (FE, root: frontend/app/)

구현 완료 기준

  • 사용자가 구현을 요청한 작업은 로컬 코드 수정만으로 완료로 간주하지 않는다.
  • 구현 업무 완료 조건: 커밋, 원격 브랜치 push, PR 생성 또는 갱신, PR의 CI Pipeline 상태 확인.
  • CI 결과를 아직 확인하지 못했으면 완료라고 보고하지 말고, 대기 중 또는 실패 상태를 명시한다.

공통 규칙

  • 공식 문서 기반 작업 — 추측성 코드 금지
  • TDD — Red → Green → Refactor, 테스트 설명은 한국어
  • 아키텍처 개선 우선 — 리팩토링 시 기존 코드에 얽매이지 않는다. 더 나은 아키텍처/설계가 있으면 새롭게 작성하여 반영한다.
  • 스크립트 작성 원칙 — 간명함 우선. 정상적이고 깨끗한 실행 환경을 기본 가정으로 두고, 불필요한 wrapper function, 중간 상태 확인, 방어 분기, trace-only logging을 만들지 않는다.
  • 스크립트 실패 원칙 — 명령 실패는 숨기지 말고 즉시 실패·중단한다. 예외는 diagnostics/cleanup 같은 best-effort 구간으로 제한하고, 그 경우에도 의도를 코드에 명확히 드러낸다.
  • 언어 규칙 — 에러 메시지·로그는 영문, 주석과 docs/ 하위 문서는 한국어로 작성
  • 브랜치: develop(기본) / release(프로덕션), feature는 feature/{detail}로 분기
  • 커밋: 작업 후 즉시, WIP 허용
  • 네이밍: DB snake_case, Kotlin PascalCase, API kebab-case

FE 규칙

  • 컴포넌트 3-tier — shared/ui/(shadcn Primitive) → shared/{component}/(Composite) → shared/blocks/(Layout Block)
  • DESIGN.md 우선 — FE 디자인 작업 시 repo/worktree 루트에 DESIGN.md가 있으면 먼저 읽고 visual source of truth로 따른다. page-local visual system 금지, 반복 패턴은 shared/blocks로 올린다.
  • UI 우선순위 — shadcn/ui → Tailwind CSS → 커스텀 (shadcn 없는 경우만)
  • DaisyUI 레거시 클래스 사용 금지 — btn-, badge badge-, fieldset-label, modal-action, tabs-boxed, toggle toggle- → shadcn 컴포넌트로 대체 (docs/reference/fe-components.md)
  • RHF 패턴 — useForm + zodResolver 필수, raw useState 폼 금지 (docs/reference/frontend/rhf.md)
  • 제어 주체 분리 — React 렌더링 요소는 React(props/hooks)로만 제어, querySelector 금지
  • DOM 존재 시점 — 조건부 렌더링 게이트 안 요소는 useEffect 실행 시 없을 수 있다. usePageLoaded 사용
  • 검색엔진 차단 — robots.txt + <meta name="robots" content="noindex, nofollow">

BE 규칙

  • DDD 레이어 책임:
    • Controller: 얇게 유지, Service 호출만
    • Service: 유스케이스 조합, Entity 메서드 호출 (필드 직접 조작 금지)
    • Entity: 상태 변경 캡슐화 (메서드로만 변경)
  • @TransactionalEventListener(AFTER_COMMIT): @Transactional 내에서만 이벤트 발행
  • 권한 모델: Role은 사용자 분류용(동적 생성 가능), 권한 관리에 직접 사용하지 않음. Menu.permissions 기반 — 새 기능 추가 시 PermissionRegistrar + ProgramRegistrar 등록 → 메뉴에 할당
  • SOLID 원칙, 의존성 주입
  • SoftDeleteEntity / HardDeleteEntity 상속, Soft Delete (@SQLRestriction), @PreAuthorize
  • !! 사용 금지 — smart cast 불가능한 경우만 예외
  • 인증: INTERNAL + AUTH0, 역할: ADMIN/MANAGER/USER/GUEST
  • UUID v7, Envelope Encryption, JWT ES256

스킬 — 코드 작성 시 해당 영역 스킬 사용

  • FE: style-frontend → react-expert, typescript-pro, playwright-expert
  • BE: style-backend → kotlin-specialist, spring-boot-engineer
  • 인프라: style-infra → devops-engineer, monitoring-expert, secure-code-guardian, postgres-pro
  • 설계/리뷰: architecture-designer, api-designer, code-reviewer, test-master

라이브러리

  • 안정된 최신 릴리스 (RC/alpha/beta 제외), CVE 없는 버전
  • 버전은 backend/gradle/libs.versions.toml에서 일원 관리

문서 관리

  • CLAUDE.md: 100줄 이내, 수정 시 사용자 검토 후 반영
  • docs/*.md: 300줄 이내, 코드 예시 최소화
  • docs/ 문서 생성/수정 시 docs/reference/writing-guide.md를 먼저 읽고 따른다

상세: docs/ 참조