AGENT.md, CLAUDE.md, Skills 완전 활용 가이드: AI 코딩 어시스턴트 마스터하기

my-project/
  CLAUDE.md          # 프로젝트 전체 설정
  src/
    CLAUDE.md        # src 디렉토리 특화 설정
    components/
      CLAUDE.md      # 컴포넌트 특화 설정
  backend/
    CLAUDE.md        # 백엔드 특화 설정

# Project Overview

프로젝트 목적, 기술 스택, 아키텍처 개요

# Tech Stack

- Language: TypeScript 5.x
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Testing Library

# Project Structure

src/
app/ # Next.js App Router
components/ # React components
lib/ # Utility functions
types/ # TypeScript types

# Coding Standards

- 함수 최대 50줄
- 타입 any 사용 금지
- 모든 함수에 JSDoc 필수
- 컴포넌트는 named export만 사용

# Testing Requirements

- 모든 유틸 함수: 단위 테스트 필수
- API 라우트: 통합 테스트 필수
- 커버리지 80% 이상

# Git Conventions

- Conventional Commits 준수
- PR당 200줄 이하

# Forbidden Patterns

- console.log 프로덕션 코드에 금지
- any 타입 금지
- 하드코딩된 URL 금지

# Project Structure

src/
app/ # Next.js App Router - 페이지 및 레이아웃
(auth)/ # 인증 필요 라우트 그룹
(public)/ # 공개 라우트 그룹
api/ # API Route Handlers
components/ # 재사용 가능한 React 컴포넌트
ui/ # shadcn/ui 기반 기본 UI 컴포넌트
features/ # 기능별 컴포넌트 (auth, dashboard 등)
lib/ # 순수 유틸리티 함수 (프레임워크 의존성 없음)
hooks/ # 커스텀 React Hooks
stores/ # Zustand 상태 관리
types/ # TypeScript 타입 정의
server/ # 서버 전용 코드 (DB, 외부 API 등)

# Forbidden Patterns

## 타입 관련

- `any` 타입 사용 금지 → `unknown` 또는 구체적 타입 사용
- `@ts-ignore` 사용 금지 → 타입 오류의 근본 원인 해결
- `as any` 타입 캐스팅 금지

## 코드 품질

- `console.log`, `console.debug` 프로덕션 코드에 금지 → logger 사용
- TODO 주석 없이 코드 완성하지 않기 (TODO는 이슈 링크 필수)
- 매직 넘버 금지 → 명명된 상수로 추출

## 아키텍처

- 컴포넌트에서 직접 fetch 호출 금지 → custom hook 또는 server action 사용
- 클라이언트 컴포넌트에서 DB 직접 쿼리 금지
- 하드코딩된 URL 금지 → 환경 변수 사용

## 보안

- 사용자 입력 직접 SQL에 삽입 금지 → Prisma ORM 사용
- 클라이언트에 시크릿 키 노출 금지
- 인증 없이 관리자 API 엔드포인트 생성 금지

## 성능

- useEffect 내 무한 루프 유발 의존성 배열 오류 주의
- 큰 데이터셋을 클라이언트 사이드에서 필터링 금지 → DB 레벨 필터링

# Before Creating New Code

새 코드를 작성하기 전에 항상 다음을 확인하라:

1. `src/lib/` 에 이미 구현된 유틸리티가 있는지
2. `src/hooks/` 에 유사한 커스텀 훅이 있는지
3. `src/components/ui/` 에 재사용 가능한 컴포넌트가 있는지
4. `src/server/` 에 재사용 가능한 서버 액션이 있는지

중복 구현은 코드베이스의 유지보수성을 심각하게 저하시킨다.

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    performance-check.md

현재 staged 변경사항을 분석하고 Conventional Commits 형식으로
커밋 메시지를 작성해줘. 한국어로 작성.

형식:
type(scope): subject

body (선택, 변경 이유와 영향 설명)

footer (선택, Breaking Change 또는 이슈 번호)

type 선택 기준:

- feat: 새 기능 추가
- fix: 버그 수정
- refactor: 기능 변경 없는 코드 개선
- test: 테스트 추가/수정
- docs: 문서 변경
- chore: 빌드/설정 변경
- perf: 성능 개선

scope는 변경된 모듈/컴포넌트명 사용.
subject는 50자 이하, 명령형으로 작성.

현재 브랜치의 변경사항을 분석해서 PR 설명을 작성해줘.

## 변경 요약

- (bullet points로 핵심 변경사항 나열)

## 변경 이유

(왜 이 변경이 필요한지 설명)

## 테스트 방법

- [ ] (검증 방법 체크리스트)

## 스크린샷

(UI 변경이 있는 경우 스크린샷 필요 여부 표시)

## 참고 사항

(리뷰어가 알아야 할 특이사항)

선택된 코드에 대한 단위 테스트를 작성해줘.
Vitest + Testing Library 사용.

다음을 포함할 것:

1. 정상 케이스 (happy path)
2. 경계값 테스트
3. 에러 케이스 (예외 처리)
4. 엣지 케이스 (null, undefined, 빈 배열 등)

테스트 네이밍: "should [expected behavior] when [condition]" 형식
Mock은 최소화하고 실제 구현에 가깝게 작성.

이 코드를 리뷰해줘. 다음 관점에서 분석하고
각 항목별로 심각도(Critical/Major/Minor)를 표시해줘:

1. 버그 가능성
   - 논리 오류, 엣지 케이스 미처리, 경쟁 조건 등

2. 보안 취약점
   - 인증/인가 오류, 인젝션 취약점, 민감 정보 노출 등

3. 성능 문제
   - 불필요한 렌더링, N+1 쿼리, 메모리 누수 등

4. 가독성 개선점
   - 복잡한 로직, 불명확한 변수명, 중복 코드 등

5. 테스트 가능성
   - 의존성 주입, 순수 함수 여부, Mock 용이성 등

각 지적사항에는 개선 코드 예시를 포함해줘.

이 코드의 JSDoc 문서를 작성해줘.

각 함수/클래스/타입에 대해:

- @description: 기능 설명 (2-3문장)
- @param: 각 파라미터의 타입, 설명, 예시값
- @returns: 반환값 타입과 설명
- @throws: 발생할 수 있는 예외
- @example: 실제 사용 예시 코드

복잡한 비즈니스 로직이 있는 경우 알고리즘 설명도 포함.

이 코드를 리팩토링해줘.

목표:

- 중복 제거 (DRY 원칙)
- 가독성 향상 (복잡도 감소)
- SOLID 원칙 적용
- 테스트 가능성 향상

제약:

- 기존 기능은 변경하지 말 것
- 퍼블릭 API(함수 시그니처, 모듈 인터페이스)는 유지할 것
- 점진적으로 리팩토링 (한 번에 너무 많이 바꾸지 않음)

리팩토링 전/후를 비교해서 보여주고 각 변경의 이유를 설명해줘.

이 코드의 보안 취약점을 OWASP Top 10 기준으로 점검해줘.

특히 확인할 것:

1. Injection (SQL, Command, XSS)
2. 인증/인가 오류
3. 민감 데이터 노출
4. 보안 설정 오류
5. 알려진 취약점 있는 컴포넌트 사용

각 취약점에 대해:

- 위험도 (High/Medium/Low)
- 공격 시나리오 설명
- 수정 방법과 코드 예시

이 코드의 성능 문제를 분석해줘.

확인 항목:

1. 알고리즘 복잡도 (시간/공간)
2. 불필요한 재연산 (메모이제이션 가능 여부)
3. 데이터베이스 쿼리 최적화 (N+1, 인덱스 활용)
4. 네트워크 요청 최적화 (배칭, 캐싱)
5. 렌더링 최적화 (React 컴포넌트의 경우)

각 문제에 대해 개선 예시 코드를 포함해줘.

# E-Commerce Platform

## Overview

B2C 이커머스 플랫폼. 고객 쇼핑, 주문 관리, 관리자 대시보드로 구성.
MAU 50만, 일 주문 5천건 처리.

## Tech Stack

- Next.js 15 (App Router, RSC)
- TypeScript 5.x (strict mode)
- PostgreSQL 16 + Prisma ORM
- Redis (세션, 캐시)
- Stripe (결제)
- Vercel (배포)

## Domain Model

- User: 고객 계정, 다중 배송지 지원
- Product: SKU 기반 재고 관리, 카테고리 트리
- Order: Draft → Pending → Confirmed → Shipped → Delivered → Cancelled
- Cart: Redis 기반, 미로그인 사용자도 지원 (세션 기반)

## Architecture Rules

- 서버 컴포넌트에서 DB 직접 쿼리 (Prisma)
- 클라이언트에서 API 호출은 /api 라우트를 통해
- 복잡한 비즈니스 로직은 src/server/services/ 에 위치
- 결제 관련 코드는 반드시 서버 사이드에서만

## Forbidden

- 클라이언트 컴포넌트에서 Prisma 직접 사용
- 결제 금액 클라이언트에서 계산 (반드시 서버에서)
- any 타입
- 하드코딩된 가격/할인율

# Order Service

## Overview

주문 처리 마이크로서비스. gRPC 내부 통신, REST 외부 노출.
초당 500 TPS 처리 목표.

## Tech Stack

- Go 1.23
- Fiber (HTTP), gRPC (내부 통신)
- PostgreSQL + sqlc (타입 세이프 쿼리)
- Redis (분산 잠금, 캐시)
- OpenTelemetry (분산 추적)

## Code Style

- 에러는 반드시 상위로 전파 (errors.Wrap 사용)
- 모든 DB 쿼리는 컨텍스트 포함 (ctx 파라미터 필수)
- 로그는 zerolog 구조화 로그만 사용
- 인터페이스 먼저 정의, 구현 나중에

## Project Layout (Standard Go Layout)

cmd/ # main 패키지
internal/ # 외부 공개 안 되는 코드
domain/ # 도메인 모델 및 인터페이스
service/ # 비즈니스 로직
repository/ # DB 접근 레이어
handler/ # HTTP/gRPC 핸들러
pkg/ # 외부 공개 가능한 유틸리티

## Forbidden

- 패닉 사용 금지 (recover 없이)
- context.Background() 핸들러에서 직접 사용 금지
- 전역 상태 금지
- goroutine 누수 유발 패턴

# Payment Service

## Overview

결제 처리 서비스. PCI-DSS 준수 필수.
Kafka 이벤트 기반 비동기 처리.

## Tech Stack

- Java 21 (Virtual Threads 활용)
- Spring Boot 3.x
- Spring Data JPA + Hibernate
- Apache Kafka (이벤트 스트리밍)
- Vault (시크릿 관리)

## Architecture

Hexagonal Architecture (Ports & Adapters):

- domain/: 순수 도메인 모델 (의존성 없음)
- application/: 유즈케이스, 포트 인터페이스
- infrastructure/: 어댑터 (DB, Kafka, 외부 API)
- interfaces/: 컨트롤러, DTO

## Rules

- 도메인 레이어는 Spring 의존성 없음
- 모든 금액은 BigDecimal (double/float 절대 금지)
- 외부 결제 API 호출에는 Circuit Breaker 패턴 적용
- 보상 트랜잭션 패턴으로 분산 트랜잭션 처리

## Forbidden

- BigDecimal 대신 double로 금액 계산
- 결제 정보 로그 출력 (마스킹 없이)
- 동기 결제 API 호출 타임아웃 미설정

결제 처리 함수를 만들어줘

[배경] 이커머스 플랫폼에서 Stripe를 사용해 결제를 처리한다.
현재 src/server/services/payment.ts 파일에 결제 관련 로직이 있다.

[제약]
- 금액은 반드시 서버에서 계산 (클라이언트 입력 신뢰 안 함)
- 결제 실패 시 재시도는 최대 3회, 지수 백오프 사용
- 모든 결제 이벤트는 audit log 저장

[요청]
장바구니 체크아웃 시 Stripe Payment Intent를 생성하는
processCheckout 함수를 작성해줘. TypeScript, async/await 사용.

1단계: "사용자 인증 시스템의 데이터베이스 스키마를 설계해줘"
2단계: "이 스키마를 기반으로 Prisma 모델을 작성해줘"
3단계: "로그인 비즈니스 로직을 서비스 레이어에 구현해줘"
4단계: "이 서비스를 사용하는 API 라우트 핸들러를 만들어줘"
5단계: "각 레이어에 대한 테스트를 작성해줘"

우리 프로젝트는 이런 패턴으로 API 라우트를 작성해:

[예시]
export async function GET(req: NextRequest) {
  try {
    const session = await getServerSession(authOptions)
    if (!session) return unauthorized()

    const data = await getUserData(session.user.id)
    return ok(data)
  } catch (error) {
    logger.error('Failed to get user data', { error })
    return internalError()
  }
}

이 패턴으로 주문 목록을 가져오는 API 라우트를 작성해줘.

상품 검색 기능을 구현해줘.

절대 하지 말아야 할 것:
- 클라이언트 사이드에서 전체 데이터를 가져와 필터링 (성능 이슈)
- 검색어를 SQL에 직접 삽입 (인젝션 취약점)
- 검색 결과 캐싱 없이 매 요청마다 DB 풀스캔

다음 코드에 성능 문제가 있는지 분석해줘.
분석 전에 먼저:
1. 코드가 어떤 작업을 하는지 설명
2. 시간/공간 복잡도 분석
3. 잠재적 병목 지점 식별
4. 개선 방안 제시

순서로 진행해줘.

에러 발생 → 컨텍스트 수집 → AI에게 분석 요청 → 해결책 검증

컨텍스트 수집 체크리스트:
- 에러 메시지 전문 (스택 트레이스 포함)
- 에러 발생 시점의 입력값
- 최근 변경된 코드 (git diff)
- 관련 로그 (에러 전후 30줄)
- 환경 정보 (개발/스테이징/프로덕션)

AI에게 요청 시:
"위 에러가 발생했어. 가능한 원인을 3가지로 분석하고
각각의 디버깅 방법을 알려줘"

# 팀 AI 활용 가이드라인

## 허용 범위

- 코드 생성 및 리팩토링
- 테스트 코드 작성
- 문서화 및 주석
- 디버깅 지원
- 코드 리뷰 보조

## 항상 사람이 검토해야 하는 영역

- 보안 관련 코드 (인증, 인가, 암호화)
- 결제 및 금융 처리 로직
- 개인정보 처리 코드
- 아키텍처 수준의 결정

## AI 생성 코드 관리

- AI가 생성한 코드라도 커밋 전 반드시 이해하고 리뷰
- "AI가 만들어줬으니 맞겠지"는 금지
- 이해하지 못한 코드는 AI에게 설명을 요청

# 기본 작업 공간
git worktree add ../project-feature-a feature/payment-v2

# 두 번째 작업 공간 (다른 디렉토리에 다른 브랜치)
git worktree add ../project-feature-b feature/user-profile-v2

# 워크트리 목록 확인
git worktree list