# 다양한 접근 방식 모두 가능
claude "버그를 찾아서 수정해줘"
claude "TDD 방식으로 새 기능을 구현해줘"
claude "이 코드를 함수형 스타일로 리팩토링해줘"
claude "아키텍처를 분석하고 개선점을 제안해줘"

# Claude Code의 작업 과정을 실시간으로 확인
> 파일 탐색 중: src/components/
> 코드 분석 중: UserProfile.jsx
> 수정 사항 적용 중...
> 테스트 실행 중...

# 우리 프로젝트의 규칙
- 모든 컴포넌트는 함수형으로 작성
- 테스트 커버리지 80% 이상 유지
- 커밋 메시지는 conventional commits 따르기

# 프론트엔드부터 배포까지 한 번에
claude "사용자 인증 기능을 만들어줘. React 프론트엔드, Node.js 백엔드, PostgreSQL 데이터베이스, Docker 컨테이너화까지"

# Node.js 버전 확인
node --version

# npm 버전 확인
npm --version

# Git 설치 확인 (선택사항이지만 권장)
git --version

# Claude Code 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# Homebrew tap 추가
brew tap anthropic-ai/claude-code

# Claude Code 설치
brew install claude-code

# 설치 확인
claude --version

# 터미널 권한 설정 (필요한 경우)
# 시스템 환경설정 > 보안 및 개인정보 > 개인정보 > 전체 디스크 접근 권한
# Terminal.app 또는 사용 중인 터미널 앱 추가

# Spotlight 검색 제외 (선택사항)
# .claude-code 디렉토리를 Spotlight 검색에서 제외하여 성능 향상

# WSL 설치 (Ubuntu 22.04 LTS 기본 포함)
wsl --install

# 설치 후 시스템 재부팅

# WSL 2로 업그레이드
wsl --set-version Ubuntu 2

# 설치 상태 확인
wsl --status
wsl --list --verbose

# NVM 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 변경사항 적용
source ~/.bashrc

# Node.js 18 LTS 설치 및 사용
nvm install 18
nvm use 18

# 설치 확인
node --version
npm --version

# Claude Code 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# 시스템 패키지 업데이트
sudo apt update && sudo apt upgrade

# Node.js 설치 (아직 없는 경우)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs

# Claude Code 설치
sudo npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# 권한 설정 (필요한 경우)
sudo chmod +x /usr/local/bin/claude

# API 키 설정 명령어 실행
claude login

# 프롬프트가 나타나면 복사한 API 키를 붙여넣기
# (키를 입력할 때는 화면에 표시되지 않는 것이 정상입니다)

# 첫 인사 (Claude가 답변하면 성공!)
claude "안녕하세요, Claude! 처음 뵙겠습니다."

# 간단한 작업 요청해보기
claude "현재 시스템 정보를 알려주세요"

# 디렉토리 탐색해보기
claude "현재 폴더에 어떤 파일들이 있는지 보여주세요"

claude "package.json 파일을 읽고 요약해줘"

# 대화형 모드 시작
claude

# 이제 지속적으로 대화 가능
> 새로운 React 프로젝트를 시작하고 싶어
> TypeScript를 사용하고, 테스트 환경도 설정해줘
> Material-UI도 추가해줘

{
  "api_key": "sk-ant-...",              // API 인증 키
  "default_model": "claude-3-opus-20240229", // 기본 사용 모델
  "theme": "dark",                       // 인터페이스 테마 (dark/light)
  "editor": "vscode",                    // 선호 에디터
  "auto_commit": false,                  // 자동 커밋 여부
  "language": "ko",                      // 기본 언어 설정
  "permissions": {
    "file_write": true,                  // 파일 쓰기 권한
    "file_read": true,                   // 파일 읽기 권한
    "command_execution": true            // 명령 실행 권한
  }
}

# 모든 권한 부여 (개발 환경)
claude --allow-all

# 읽기 전용 모드 (코드 리뷰용)
claude --read-only

# 특정 권한만 부여
claude --allow-read --allow-write --deny-execute

# VSCode 통합
claude config set editor vscode

# Vim 통합
claude config set editor vim

# 에디터에서 직접 Claude Code 호출
# VSCode: Cmd+Shift+P > "Claude: Ask"

# HTTP 프록시 설정
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Claude Code 전용 프록시 설정
claude config set proxy http://proxy.company.com:8080

# 1단계: npm 전역 경로 확인
npm config get prefix

# 2단계: PATH에 추가 (bash/zsh)
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

# 3단계: 설치 확인
claude --version

# 방법 1: 권한 수정 (권장)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 방법 2: npx를 통한 실행 (임시 해결)
npx @anthropic-ai/claude-code

# 방법 3: npm 전역 디렉토리 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 1단계: 현재 상태 확인
claude status

# 2단계: 자동 재시도 간격 설정 (밀리초)
claude config set retry_delay 5000

# 3단계: 최대 재시도 횟수 설정
claude config set max_retries 3

# ⚠️ 임시 해결책 (보안 위험 있음)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# ✅ 권장 해결책: 회사 인증서 설치
# 1단계: IT 부서에서 인증서 파일 받기
# 2단계: npm에 인증서 등록
npm config set cafile /path/to/company-cert.pem

# 3단계: Claude Code 전용 설정
claude config set tls_verify true
claude config set ca_bundle /path/to/company-cert.pem

# 응답 캐싱 활성화
claude config set cache_enabled true

# 캐시 유지 시간 설정 (초 단위, 기본: 3600초 = 1시간)
claude config set cache_ttl 3600

# 캐시 크기 제한 설정 (MB 단위)
claude config set cache_max_size 100

# 큰 프로젝트의 경우 컨텍스트 확대
claude config set max_context_length 100000

# 작은 프로젝트나 빠른 응답이 필요한 경우
claude config set max_context_length 50000

# 현재 설정 확인
claude config get max_context_length

# 로컬 모드 활성화
claude config set local_mode true

# 로컬 모델 다운로드 (용량 주의: 수 GB)
claude download-model claude-instant

# 다운로드된 모델 확인
claude list-models --local

# 특정 모델로 실행
claude --model local:claude-instant "코드를 분석해줘"

# 1단계: 프로젝트 디렉토리 생성
mkdir hello-claude && cd hello-claude

# 2단계: Claude Code로 프로젝트 초기화
claude "Node.js로 간단한 Hello World 웹 서버를 만들어줘. 
포트 3000에서 실행되고, '/' 경로로 접속하면 'Hello from Claude Code!'를 
표시하도록 해줘. package.json과 README.md도 함께 만들어줘."

# 3단계: 생성된 파일 구조 확인
ls -la
# 예상 결과
# package.json  - 프로젝트 설정 파일
# server.js     - 웹 서버 메인 파일
# README.md     - 프로젝트 설명 문서

# 4단계: 의존성 설치
npm install

# 5단계: 서버 실행
npm start

# 6단계: 브라우저에서 테스트
# http://localhost:3000 접속하여 "Hello from Claude Code!" 메시지 확인

# 도움말 확인
claude help

# 대화형 튜토리얼 시작
claude tutorial

# 현재 설정 확인
claude config list

# 버전 정보 확인
claude --version

# 도움말 보기 - 사용 가능한 모든 명령어와 옵션 확인
claude --help
claude -h

# 버전 확인 - 현재 설치된 Claude Code 버전 확인
claude --version
claude -v

# 대화 기록 지우기 - 새로운 컨텍스트로 시작하고 싶을 때
claude --clear
claude -c

# 복잡한 작업을 위한 고성능 모델 사용
claude --model claude-3-opus "복잡한 알고리즘 구현해줘"

# 빠른 응답이 필요한 간단한 작업
claude -m claude-3-haiku "간단한 설명만 해줘"

# 균형잡힌 성능과 속도
claude -m claude-3-sonnet "코드 리뷰해줘"

# JSON 형식으로 구조화된 데이터 받기
claude --json "프로젝트 구조를 JSON으로 출력해줘"

# 마크다운 형식으로 문서 생성
claude --markdown "README 파일 내용을 마크다운으로 보여줘"

# 일반 텍스트 출력 (기본값)
claude --plain "간단한 설명을 텍스트로 보여줘"

# 기술적인 요청
claude "UserService 클래스에 이메일 검증 메서드를 추가해줘"

# 탐색적인 질문
claude "이 프로젝트에서 인증은 어떻게 처리되고 있어?"

# 창의적인 요청
claude "이 함수를 더 효율적으로 만들 수 있는 방법이 있을까?"

# 복합적인 작업
claude "버그를 찾아서 수정하고, 테스트도 작성한 다음, 커밋 메시지까지 만들어줘"

# 단일 파일 읽기
claude "package.json 파일을 읽어줘"

# 여러 파일 동시에 읽기
claude "모든 설정 파일들(config로 시작하는)을 읽고 요약해줘"

# 특정 부분만 읽기
claude "app.js 파일에서 라우터 설정 부분만 보여줘"

# 파일 비교
claude "개발 환경과 프로덕션 환경 설정 파일을 비교해줘"

# 함수 분석
claude "calculateTotalPrice 함수가 어떻게 동작하는지 설명해줘"

# 의존성 분석
claude "이 프로젝트가 사용하는 주요 라이브러리들과 용도를 설명해줘"

# 아키텍처 분석
claude "이 프로젝트의 전체적인 아키텍처를 다이어그램으로 설명해줘"

# 보안 취약점 검사
claude "보안상 문제가 될 수 있는 코드가 있는지 검사해줘"

# 기본적인 파일 생성
claude "utils 폴더에 날짜 관련 유틸리티 함수들을 만들어줘"

# 템플릿 기반 생성
claude "Express 라우터 템플릿으로 user 라우터를 만들어줘"

# 테스트 파일 자동 생성
claude "UserService에 대한 Jest 테스트 파일을 만들어줘"

# 문서 생성
claude "API 엔드포인트 문서를 Swagger 형식으로 만들어줘"

# ES5를 ES6+ 문법으로 업그레이드
claude "모든 var를 const나 let으로 바꿔줘. 재할당되는 변수만 let을 사용해"

# 콜백을 async/await로 변환
claude "콜백 기반 코드를 async/await 패턴으로 변경해줘"

# 문자열 연결을 템플릿 리터럴로
claude "문자열 연결 연산자(+)를 템플릿 리터럴로 바꿔줘"

# 긴 함수 분리
claude "이 함수가 50줄이 넘는데, 논리적 단위로 분리해서 가독성을 높여줘"

# 중복 코드 제거
claude "중복되는 코드를 찾아서 재사용 가능한 함수로 추출해줘"

# 조건문 단순화
claude "복잡한 if-else 체인을 early return 패턴이나 switch문으로 개선해줘"

# 에러 처리 추가
claude "이 API 호출 함수에 적절한 에러 처리와 재시도 로직을 추가해줘"

# 로딩 상태 관리
claude "이 컴포넌트에 로딩, 성공, 에러 상태를 관리하는 로직을 추가해줘"

# 유효성 검사 추가
claude "사용자 입력 폼에 실시간 유효성 검사를 추가해줘"

# 잠재적 오류 찾기
claude "null/undefined 참조 오류가 발생할 수 있는 부분을 찾아서 옵셔널 체이닝으로 수정해줘"

# 메모리 누수 방지
claude "이벤트 리스너나 타이머가 제대로 정리되지 않는 부분을 찾아서 수정해줘"

# 경쟁 조건 해결
claude "비동기 작업에서 경쟁 조건이 발생할 수 있는 부분을 찾아서 수정해줘"

# 포매팅
claude "프로젝트 전체를 Prettier 규칙에 맞게 포매팅해줘"

# 네이밍 컨벤션
claude "camelCase를 snake_case로 변경해줘"

# 주석 추가
claude "복잡한 로직에 설명 주석을 추가해줘"

# 타입 추가
claude "JavaScript 파일에 TypeScript 타입을 추가해줘"

# 단위 테스트
claude "calculateDiscount 함수에 대한 단위 테스트를 작성해줘"

# 통합 테스트
claude "사용자 등록 API에 대한 통합 테스트를 작성해줘"

# 엣지 케이스
claude "이 함수의 엣지 케이스를 찾아서 테스트를 추가해줘"

# 테스트 커버리지
claude "테스트 커버리지를 확인하고 누락된 부분에 테스트를 추가해줘"

claude "이 오류 메시지가 무엇을 의미하는지 설명하고 해결 방법을 제시해줘
TypeError: Cannot read property 'name' of undefined"

claude "문제가 발생하는 것 같은 부분에 디버그 로그를 추가해줘"

claude "이 함수의 실행 흐름을 단계별로 추적할 수 있도록 코드를 수정해줘"

claude "이 코드의 성능 병목 지점을 찾아서 최적화해줘"

# 대화형 디버깅 시작
claude

> 서버가 시작되지 않아. 포트 3000에서 이미 사용 중이라는 오류가 나와.
< 포트 3000을 사용하는 프로세스를 확인해보겠습니다. 다음 명령을 실행해드릴게요
  lsof -i :3000

> 확인했더니 이전에 실행한 node 프로세스가 PID 12345로 실행 중이야.
< 해당 프로세스를 안전하게 종료하고, 향후 이런 문제를 방지하는 스크립트를 만들어드리겠습니다.
  1. 프로세스 종료 스크립트 생성
  2. package.json에 재시작 스크립트 추가
  3. graceful shutdown 코드 구현

> 좋아, 진행해줘. 그리고 왜 서버가 제대로 종료되지 않았는지도 알고 싶어.
< 서버 코드를 분석해보니 다음과 같은 문제들을 발견했습니다.
  1. SIGTERM 시그널 핸들러가 없어서 프로세스가 강제 종료됨
  2. 활성 연결이 정리되지 않고 있음
  3. 데이터베이스 연결 풀이 닫히지 않음
  
  이제 이 문제들을 하나씩 해결해드리겠습니다...

claude

> 서버가 며칠 동안 실행되면 메모리 사용량이 계속 증가해. 메모리 누수가 있는 것 같아.
< 메모리 누수를 추적하기 위해 다음 단계로 진행하겠습니다.
  1. 현재 코드에서 메모리 누수 가능성이 있는 패턴 검색
  2. 메모리 프로파일링 도구 설정
  3. 의심되는 코드 영역에 모니터링 추가

> 어떤 패턴들이 위험한가?
< 다음과 같은 패턴들을 발견했습니다.
  - 이벤트 리스너가 제거되지 않는 곳 3개
  - 전역 변수에 계속 데이터가 추가되는 캐시
  - 순환 참조가 있는 객체 구조
  각각 수정 방법을 보여드릴까요?

# 상태 확인
claude "git 상태를 확인하고 변경사항을 요약해줘"

# 스테이징
claude "수정된 파일 중 테스트 관련 파일만 스테이징해줘"

# 커밋
claude "의미 있는 커밋 메시지를 작성해서 커밋해줘"

# 브랜치 관리
claude "새로운 기능을 위한 브랜치를 만들고 체크아웃해줘"

# 대화형 리베이스
claude "최근 3개 커밋을 정리해서 하나로 합쳐줘"

# 충돌 해결
claude "머지 충돌을 해결해줘. 두 변경사항을 모두 유지하는 방향으로"

# 히스토리 분석
claude "이 버그가 언제 도입됐는지 git bisect로 찾아줘"

# 체리픽
claude "hotfix 브랜치의 버그 수정 커밋만 main으로 체리픽해줘"

# PR 생성
claude "이 기능에 대한 Pull Request를 생성해줘. 
변경사항을 요약하고, 테스트 방법도 포함해줘"

# 코드 리뷰 대응
claude "리뷰어가 지적한 사항들을 수정하고 답변을 작성해줘"

# PR 템플릿 활용
claude "프로젝트의 PR 템플릿에 맞춰서 설명을 작성해줘"

# Claude Code 템플릿 디렉토리 생성
mkdir -p ~/.claude-templates/{components,features,tests,docs}

# 컴포넌트 생성 템플릿
cat > ~/.claude-templates/components/react-component.txt << 'EOF'
새로운 React 컴포넌트를 만들어줘
- 컴포넌트 이름: [COMPONENT_NAME]
- 함수형 컴포넌트로 작성
- TypeScript 사용
- Props 인터페이스 정의
- 기본 스타일 포함
- 스토리북 스토리 파일도 생성
- 유닛 테스트 파일 포함
EOF

# 사용 예시
COMPONENT_NAME="UserProfile" envsubst < ~/.claude-templates/components/react-component.txt | claude

# API 라우트 생성 템플릿
cat > ~/.claude-templates/features/api-endpoint.txt << 'EOF'
새로운 REST API 엔드포인트를 만들어줘
- 리소스: [RESOURCE_NAME]
- CRUD 작업 모두 포함
- Express.js 라우터 사용
- 입력 검증 미들웨어
- 에러 핸들링
- Swagger 문서 주석
- 통합 테스트 포함
EOF

# 버그 수정 워크플로우 템플릿
cat > ~/.claude-templates/features/bugfix.txt << 'EOF'
다음 버그를 수정해줘
1. 먼저 관련된 코드를 찾아서 분석해줘
2. 버그의 근본 원인을 설명해줘
3. 수정 방안을 제시하고 구현해줘
4. 재발 방지를 위한 테스트를 추가해줘
5. 수정사항을 커밋 메시지와 함께 정리해줘

버그 설명: [BUG_DESCRIPTION]
EOF

# 대화형 모드로 시작
claude

> 이제부터 레거시 코드를 최신 아키텍처로 마이그레이션할 거야
< 알겠습니다. 먼저 현재 코드베이스를 분석하고 마이그레이션 계획을 수립하겠습니다.

> 1단계: 현재 아키텍처를 분석하고 문제점을 파악해줘
< 분석 결과
  - 모놀리식 구조로 모듈 간 결합도가 높음
  - 클래스 기반 컴포넌트 사용 (React 16.2)
  - 상태 관리가 prop drilling으로 복잡함
  - 테스트 커버리지 30%
  
  주요 개선 필요 영역을 식별했습니다. 계속 진행할까요?

> 2단계: 마이그레이션 로드맵을 만들어줘
< 단계별 마이그레이션 로드맵
  Phase 1: 인프라 현대화 (1-2주)
  - 빌드 도구를 Webpack에서 Vite로 마이그레이션
  - TypeScript 도입
  
  Phase 2: 컴포넌트 현대화 (3-4주)
  - 클래스 컴포넌트를 함수형으로 전환
  - Custom Hooks로 로직 추출
  
  Phase 3: 상태 관리 개선 (1주)
  - Context API 또는 Zustand 도입
  
  Phase 4: 테스트 강화 (1주)
  - 테스트 커버리지 80% 목표

> 좋아, Phase 1부터 시작하자. 먼저 Vite 마이그레이션을 진행해줘
< Phase 1 시작: Vite 마이그레이션을 단계별로 진행하겠습니다...

# CLAUDE.md
## 코드 스타일

- 모든 함수는 화살표 함수로 작성
- 세미콜론 항상 사용
- 들여쓰기는 2칸

## Git 커밋 규칙
- feat: 새로운 기능 추가
- fix: 버그 수정
- docs: 문서 수정
- style: 코드 포매팅 (기능 변경 없음)
- refactor: 코드 리팩토링 (기능 변경 없음)
- test: 테스트 추가 또는 수정
- chore: 빌드 프로세스 또는 보조 도구 변경

## 커밋 메시지 형식
<type>(<scope>): <subject>

예시
feat(auth): 소셜 로그인 기능 추가
fix(api): 사용자 조회 시 null 참조 오류 수정

## 도메인 용어
- SKU (Stock Keeping Unit): 재고 관리 단위
  - 예: "SHOE-NIKE-AF1-WHT-42" (나이키 에어포스1 흰색 42사이즈)
- PDP (Product Detail Page): 상품 상세 페이지
  - 주요 컴포넌트: 이미지 갤러리, 가격 정보, 재고 상태, 리뷰
- CAC (Customer Acquisition Cost): 고객 획득 비용
  - 계산식: 총 마케팅 비용 / 신규 고객 수

## 비즈니스 규칙
- 재고가 5개 이하일 때 "품절 임박" 표시
- 신규 회원은 첫 구매 시 10% 할인 자동 적용
- 50,000원 이상 구매 시 무료 배송

# README.md (사람을 위한 문서)
## 프로젝트 소개
이 프로젝트는 전자상거래 플랫폼입니다.

## 설치 방법

1. 저장소를 클론합니다.
2. `npm install` 실행
3. `npm start`로 서버 시작

---

# CLAUDE.md (Claude Code를 위한 문서)
## 프로젝트 아키텍처
- 패턴: MVC + Repository Pattern
- 프론트엔드: React 18 + TypeScript
- 백엔드: Node.js + Express
- 데이터베이스: PostgreSQL + Redis

## 코드 생성 규칙
- 모든 API 응답은 ResponseDto로 래핑
- 에러는 CustomError 클래스 사용
- 비동기 함수는 반드시 try-catch 포함

# CLAUDE.md

## 프로젝트 구조

### 디렉토리 구조

## 아키텍처 패턴

### 상태 관리
- Redux Toolkit 사용
- 각 기능별로 slice 파일 생성
- RTK Query로 API 상태 관리

### 컴포넌트 구조
```typescript
// 모든 컴포넌트는 다음 구조를 따름
interface ComponentProps {
  // props 정의
}

export const ComponentName: React.FC<ComponentProps> = (props) => {
  // 훅은 최상단에
  // 로직
  // JSX 반환
}

## 코딩 스타일

### TypeScript/JavaScript
- 함수명: camelCase
- 컴포넌트명: PascalCase  
- 상수: UPPER_SNAKE_CASE
- 파일명: kebab-case.ts

### 명명 규칙 예시
```typescript
// 좋은 예
const getUserData = async (userId: string) => { }
const MAX_RETRY_COUNT = 3;
export const UserProfile: React.FC = () => { }

// 피해야 할 예
const get_user_data = async (userid) => { }
const maxretrycount = 3;
export const userprofile = () => { }
```

```mermaid
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%%
flowchart TD
    A["Import 순서"] --> B["1. React 관련<br/>React, useState, useEffect"]
    B --> C["2. 외부 라이브러리<br/>axios, lodash, moment"]
    C --> D["3. 내부 모듈<br/>@/constants, @/services"]
    D --> E["4. 상대 경로 import<br/>../components, ./utils"]
    E --> F["5. 스타일 파일<br/>CSS, SCSS 파일"]
    
    classDef importStyle fill:#f1f5f9,stroke:#475569,stroke-width:2px,color:#1e293b
    classDef rootStyle fill:#e2e8f0,stroke:#334155,stroke-width:3px,color:#1e293b
    
    class A rootStyle
    class B,C,D,E,F importStyle
```

### Import 순서

```typescript
import React, { useState, useEffect } from 'react';
import { useSelector } from 'react-redux';
import axios from 'axios';

import { API_ENDPOINTS } from '@/constants';
import { UserService } from '@/services';

import { Button } from '../components';
import './styles.css';
```

## 코드 품질 기준

```mermaid
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f8fafc", "primaryTextColor": "#1e293b", "primaryBorderColor": "#e2e8f0", "lineColor": "#94a3b8", "secondaryColor": "#f1f5f9", "tertiaryColor": "#e2e8f0"}}}%%
graph TB
    subgraph rules ["함수 작성 규칙"]
        A["한 가지 일만 수행<br/>Single Responsibility"]
        B["함수 길이 50줄 이하<br/>가독성 향상"]
        C["매개변수 3개 이하<br/>복잡성 감소"]
        D["복잡도 10 이하<br/>Cyclomatic Complexity"]
    end
    
    classDef ruleStyle fill:#e2e8f0,stroke:#334155,stroke-width:2px,color:#1e293b
    
    class A,B,C,D ruleStyle

// 모든 비동기 함수는 try-catch 사용
try {
  const data = await fetchData();
  return { success: true, data };
} catch (error) {
  console.error('Error fetching data:', error);
  return { success: false, error: error.message };
}

/**
 * 사용자 인증 토큰을 검증합니다.
 * @param token - JWT 토큰
 * @returns 토큰이 유효한지 여부
 */
const validateToken = (token: string): boolean => {
  // TODO(#123): 토큰 만료 시간 검증 로직 추가
  return jwt.verify(token, SECRET_KEY);
}

## 개발 환경

### 필수 도구
- Node.js 18.0 이상
- pnpm 8.0 이상 (npm 대신 사용)
- VS Code + 추천 확장 프로그램

### 초기 설정 스크립트
# 의존성 설치
pnpm install

# 환경 변수 설정
cp .env.example .env

# 데이터베이스 마이그레이션
pnpm db:migrate

# 개발 서버 시작
pnpm dev

## 코드 리뷰 가이드라인

### PR 작성 규칙
1. 제목: `[타입] 간단한 설명`
2. 본문 필수 포함 사항
   - 변경 사항 요약
   - 관련 이슈 번호
   - 테스트 방법
   - 스크린샷 (UI 변경 시)

### 리뷰 체크리스트
- [ ] 코드가 프로젝트 컨벤션을 따르는가?
- [ ] 테스트가 충분히 작성되었는가?
- [ ] 성능 영향은 고려되었는가?
- [ ] 보안 취약점은 없는가?
- [ ] 문서는 업데이트되었는가?

### 머지 기준
- 최소 1명의 승인 필요
- 모든 CI 체크 통과
- 충돌 해결 완료

### 브랜치 전략

체계적인 Git 브랜치 관리를 위한 전략과 규칙을 정의합니다. Git Flow를 기반으로 한 실용적인 브랜치 전략을 소개합니다.

## Git 브랜치 전략

### 브랜치 명명 규칙
- feature/기능명: 새 기능 개발
- fix/이슈번호: 버그 수정
- hotfix/설명: 긴급 수정
- refactor/대상: 리팩토링

### 브랜치 플로우
main
  ├── develop
  │     ├── feature/user-auth
  │     ├── feature/payment
  │     └── fix/123
  └── hotfix/critical-bug

### 머지 전략
- feature → develop: Squash merge
- develop → main: Merge commit
- hotfix → main: Cherry-pick

# E-Commerce Project Guidelines for Claude Code

## 프로젝트 개요
대규모 전자상거래 플랫폼 (일 100만 MAU)

## 핵심 기술 스택
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- State: Zustand + React Query
- Backend: Node.js, Express, PostgreSQL
- Infrastructure: AWS, Docker, K8s

## 도메인 지식

### 비즈니스 용어
- SKU: Stock Keeping Unit (재고 관리 코드)
- GMV: Gross Merchandise Volume (총 거래액)
- AOV: Average Order Value (평균 주문 금액)
- Cart Abandonment: 장바구니 이탈

### 핵심 도메인 모델
```typescript
interface Product {
  id: string;
  sku: string;
  name: string;
  price: Money;
  inventory: Inventory;
  category: Category;
}

interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  status: OrderStatus;
  payment: Payment;
  shipping: Shipping;
}
```

## 성능 요구사항
- 페이지 로드: 3초 이내
- API 응답: 200ms 이내
- 99.9% 가용성

## 보안 규칙
- 모든 사용자 입력 검증
- SQL Injection 방지
- XSS 방지
- 민감 정보 암호화

## 테스트 전략
- 단위 테스트: 80% 커버리지
- 통합 테스트: 핵심 플로우
- E2E 테스트: 구매 플로우

## 배포 프로세스
1. feature 브랜치에서 개발
2. PR 생성 및 리뷰
3. develop 브랜치 머지
4. 스테이징 자동 배포
5. QA 검증
6. 프로덕션 배포 (승인 필요)

## Claude Code 특별 지침
- 성능을 항상 고려하여 코드 작성
- 확장 가능한 아키텍처 유지
- 마이크로서비스 경계 준수
- 비동기 처리 우선
- 에러 로깅 필수

# CLAUDE.md

## 🚨 중요 규칙 (항상 준수)
- 절대 main 브랜치에 직접 푸시 금지
- 모든 API 키는 환경 변수로
- 테스트 없는 코드 커밋 금지

## 📋 일반 가이드라인
- 가능하면 함수형 프로그래밍
- 주석은 최소화, 코드로 설명

## 💡 권장사항
- 새로운 라이브러리 도입 전 팀 논의
- 성능 최적화는 측정 후 진행 

# CLAUDE.md 업데이트 시 Claude Code에게 알리기
claude "CLAUDE.md 파일이 업데이트되었어. 
새로운 규칙들을 확인하고 요약해줘"

# 월간 CLAUDE.md 리뷰
claude "지난 한 달간 우리 팀의 개발 패턴을 분석해서
CLAUDE.md에서 개선이 필요한 부분을 찾아줘"

# 규칙 효과성 분석
claude "현재 CLAUDE.md 규칙들이 실제로 잘 지켜지고 있는지
코드베이스를 분석해서 준수율을 보고해줘"

# 새로운 규칙 제안
claude "최근 발생한 버그들을 분석해서
예방할 수 있는 새로운 규칙을 제안해줘"

# Vite를 사용한 React 프로젝트 생성
claude "Vite로 새로운 React TypeScript 프로젝트를 만들어줘. 
Tailwind CSS, React Router, React Query를 포함하고,
폴더 구조도 모범 사례에 따라 설정해줘"

# 기본 컴포넌트 생성
claude "UserProfile 컴포넌트를 만들어줘. 
프로필 이미지, 이름, 소개를 표시하고,
편집 모드를 지원해야 해. 
Storybook 스토리와 테스트 코드도 함께 작성해줘"

# 고급 데이터 테이블 컴포넌트
claude "DataTable 컴포넌트를 만들어줘.
- 정렬, 필터링, 페이지네이션 지원
- 선택 가능한 행과 대량 작업
- 가상 스크롤링으로 성능 최적화
- TypeScript 제네릭으로 타입 안전성 보장
- 접근성(a11y) 준수"

# 복잡한 폼 컴포넌트
claude "MultiStepForm 컴포넌트를 만들어줘.
- React Hook Form과 Zod 검증 통합
- 단계별 진행 표시와 네비게이션
- 자동 저장과 임시 저장 기능
- 오류 상태 처리와 사용자 피드백
- 각 단계별 조건부 필드 표시"

# 인증 상태 관리
claude "사용자 인증 상태를 전역으로 관리하는 
Context와 커스텀 훅을 만들어줘.
로그인, 로그아웃, 토큰 갱신 기능이 필요해"

# 복잡한 비즈니스 로직 상태 관리
claude "전자상거래 장바구니 상태 관리를 구현해줘.
- Zustand로 상태 저장소 구성
- 상품 추가/제거/수량 변경 로직
- 할인 쿠폰 적용과 가격 계산
- 로컬스토리지 동기화
- 비관적/낙관적 업데이트 처리"

# 서버 상태와 캐싱
claude "React Query를 활용한 서버 상태 관리를 설정해줘.
- API 응답 캐싱 전략
- 백그라운드 리페칭과 스테일 타임 설정
- 무한 스크롤 데이터 페칭
- 에러 재시도 로직과 오프라인 지원"

# 리렌더링 최적화
claude "이 컴포넌트의 불필요한 리렌더링을 방지하도록 
React.memo, useMemo, useCallback을 적용해줘"

# 코드 스플리팅과 지연 로딩
claude "이 애플리케이션에 코드 스플리팅을 적용해줘.
- 라우트 레벨 지연 로딩
- 무거운 컴포넌트의 동적 임포트
- 라이브러리 번들 분리
- 로딩 스피너와 에러 바운더리 추가"

# 대용량 리스트 최적화
claude "10,000개 아이템을 효율적으로 렌더링하는 
가상 스크롤 컴포넌트를 구현해줘.
- react-window 라이브러리 활용
- 동적 아이템 높이 지원
- 무한 스크롤과 페이지네이션 통합"

# 이미지 최적화
claude "이미지 갤러리의 성능을 최적화해줘.
- 지연 로딩과 프리로딩 전략
- WebP 포맷 지원과 폴백
- 이미지 압축과 리사이징
- Progressive loading 구현"

# 종합적인 블로그 시스템
claude "Next.js 14 App Router로 블로그를 만들어줘.
동적 라우팅, 메타데이터 최적화, 
그리고 ISR(Incremental Static Regeneration)을 활용해줘"

# 다국어 지원과 국제화
claude "Next.js에서 다국어 지원을 구현해줘.
- i18n 라우팅 설정
- 서버 컴포넌트에서 번역 처리
- 동적 번역 로딩과 폴백
- SEO 최적화를 위한 hreflang 태그"

# 복잡한 인증 시스템
claude "NextAuth.js로 다중 인증 제공자를 지원하는 시스템을 구현해줘.
- OAuth (Google, GitHub), 이메일, 자격증명 로그인
- 역할 기반 접근 제어 (RBAC)
- 세션 관리와 보안 강화
- API 라우트 보호 미들웨어"

claude "이 페이지를 Server Component로 리팩토링해줘.
데이터 페칭은 서버에서, 인터랙션은 Client Component로 분리해줘"

claude "RESTful API를 Next.js API routes로 구현해줘.
미들웨어로 인증을 처리하고, Zod로 요청 검증을 추가해줘"

# React/Next.js Project Guidelines

## 컴포넌트 규칙
- 함수형 컴포넌트만 사용
- Props는 인터페이스로 정의
- 컴포넌트당 하나의 파일

## 상태 관리
- 로컬 상태: useState
- 서버 상태: React Query (TanStack Query)
- 전역 상태: Zustand

## 폴더 구조

# 기본 REST API 서버
claude "Express.js로 확장 가능한 REST API 서버를 만들어줘.
계층화된 아키텍처(Controller-Service-Repository)를 사용하고,
TypeScript, JWT 인증, 에러 핸들링, 로깅을 포함해줘"

# 마이크로서비스 패턴
claude "Express로 마이크로서비스 아키텍처를 구현해줘.
- 서비스 간 통신 (HTTP/gRPC)
- API Gateway 패턴
- 서비스 디스커버리와 로드 밸런싱
- 분산 로깅과 트레이싱
- Circuit Breaker 패턴"

# 고성능 API 서버
claude "대용량 트래픽을 처리하는 Express API를 만들어줘.
- 클러스터링과 워커 프로세스 관리
- Redis를 활용한 세션과 캐싱
- 요청 제한과 DDoS 방어
- 데이터베이스 커넥션 풀링
- APM 모니터링 통합"

# GraphQL API 서버
claude "Express에 GraphQL을 통합한 API 서버를 만들어줘.
- Apollo Server 설정
- 스키마 stitching과 federation
- DataLoader를 활용한 N+1 쿼리 방지
- 인증과 권한 부여
- 쿼리 복잡도 제한"

claude "사용자 관리를 위한 RESTful API를 설계해줘.
CRUD 작업, 페이지네이션, 필터링, 정렬을 지원하고,
OpenAPI(Swagger) 문서도 자동 생성되도록 해줘"

claude "Prisma ORM을 사용해서 User, Post, Comment 모델을 만들어줘.
관계 설정, 마이그레이션, 시드 데이터도 포함해줘"

claude "JWT 기반 인증 시스템을 구현해줘.
액세스 토큰과 리프레시 토큰을 사용하고,
역할 기반 접근 제어(RBAC)도 추가해줘"

claude "이 모놀리식 앱을 마이크로서비스로 분해해줘.
User Service, Product Service, Order Service로 나누고,
API Gateway와 서비스 간 통신 방법도 설계해줘"

# Node.js/Express API Guidelines

## API 설계 원칙
- RESTful 원칙 준수
- 일관된 응답 형식
- 적절한 HTTP 상태 코드 사용

## 응답 형식
```json
{
  "success": true,
  "data": {},
  "message": "Success",
  "timestamp": "2024-01-01T00:00:00Z"
}

claude "전자상거래를 위한 Django 모델을 설계해줘.
Product, Category, Order, User 모델과 관계를 정의하고,
Admin 인터페이스도 커스터마이징해줘"

claude "Product 모델에 대한 ViewSet과 Serializer를 만들어줘.
필터링, 검색, 정렬을 지원하고,
중첩된 관계도 효율적으로 처리해줘"

claude "Celery를 사용해서 이메일 발송과 
이미지 처리를 비동기로 처리하도록 설정해줘"

# Django Project Guidelines

## 앱 구조
- 기능별로 앱 분리
- 앱당 최대 10개 모델
- 순환 의존성 금지

## 모델 설계
- 모든 모델에 created_at, updated_at
- soft delete 사용 (is_deleted 필드)
- 관계는 명시적으로 정의

## API 설계
- ViewSet 사용 권장
- 커스텀 액션은 @action 데코레이터
- 페이지네이션 기본 20개

## 테스트
- 모델, 뷰, 시리얼라이저 각각 테스트
- Factory Boy로 테스트 데이터 생성
- 커버리지 80% 이상

claude "Expo로 크로스 플랫폼 모바일 앱을 만들어줘.
네비게이션, 상태 관리, 네이티브 기능 접근을 설정하고,
iOS와 Android 스타일 차이도 처리해줘"

claude "React Navigation으로 복잡한 네비게이션을 구현해줘.
Tab Navigator, Stack Navigator, Drawer를 조합하고,
딥링킹도 설정해줘"

claude "카메라와 위치 정보에 접근하는 기능을 구현해줘.
권한 요청 처리와 에러 핸들링도 포함해줘"

claude "Flutter로 Material Design 앱을 만들어줘.
다국어 지원, 다크 모드, 반응형 레이아웃을 포함하고,
Clean Architecture 패턴을 적용해줘"

# Mobile App Guidelines

## 아키텍처
- MVVM 패턴 사용
- 비즈니스 로직은 ViewModel에
- View는 상태만 표시

## 성능
- 리스트는 가상화 필수
- 이미지 최적화 및 캐싱
- 애니메이션 60fps 유지

## 플랫폼별 처리
```javascript
Platform.select({
  ios: { /* iOS 스타일 */ },
  android: { /* Android 스타일 */ }
})

claude "머신러닝 프로젝트를 위한 Jupyter 환경을 설정해줘.
데이터 분석, 시각화, 모델 학습 파이프라인을 구축하고,
실험 추적도 설정해줘"

# 기본 데이터 전처리
claude "이 CSV 데이터를 분석하고 전처리해줘.
결측치 처리, 이상치 탐지, 특성 엔지니어링을 수행하고,
각 단계를 시각화해줘"

# 고급 특성 엔지니어링
claude "시계열 데이터의 특성 엔지니어링을 구현해줘.
- 시간 기반 특성 생성 (lag, rolling window)
- 계절성과 트렌드 분해
- Fourier 변환을 통한 주기 특성
- 스케일링과 정규화 파이프라인
- 범주형 변수 인코딩 전략"

# 대용량 데이터 처리
claude "Dask를 활용한 대용량 데이터 전처리 파이프라인을 만들어줘.
- 청크 단위 병렬 처리
- 메모리 효율적인 데이터 로딩
- 분산 컴퓨팅 환경 설정
- 진행 상황 모니터링"

# AutoML과 모델 비교
claude "여러 머신러닝 모델을 비교 평가해줘.
교차 검증, 하이퍼파라미터 튜닝을 수행하고,
결과를 표로 정리해줘"

# 딥러닝 모델 개발
claude "PyTorch로 이미지 분류 모델을 구현해줘.
- 전이학습 (Transfer Learning) 활용
- 데이터 증강과 정규화
- 학습률 스케줄링과 조기 종료
- 모델 체크포인트와 재개 기능
- TensorBoard 시각화"

# MLflow 실험 추적
claude "MLflow를 활용한 실험 추적 시스템을 구축해줘.
- 모델 메트릭과 파라미터 로깅
- 아티팩트 버전 관리
- 모델 레지스트리 설정
- A/B 테스트 프레임워크
- 실험 비교 대시보드"

# API 서빙
claude "학습된 모델을 FastAPI로 서빙하는 API를 만들어줘.
입력 검증, 예측, 모니터링 기능을 포함해줘"

# 실시간 예측 시스템
claude "Kafka와 Redis를 활용한 실시간 ML 파이프라인을 구축해줘.
- 스트리밍 데이터 전처리
- 실시간 특성 저장소
- 배치와 온라인 예측 통합
- 모델 성능 모니터링
- 자동 재학습 트리거"

# 컨테이너 배포
claude "Docker와 Kubernetes로 ML 모델을 배포해줘.
- 멀티 스테이지 Docker 빌드
- GPU 지원 컨테이너
- 오토스케일링 설정
- 헬스체크와 로그 수집
- CI/CD 파이프라인 통합"

# 모델 모니터링
claude "프로덕션 ML 모델 모니터링 시스템을 구축해줘.
- 데이터 드리프트 탐지
- 모델 성능 저하 알림
- 편향성 모니터링
- 설명 가능한 AI 대시보드
- 사고 대응 플레이북"

# Data Science Project Guidelines

## 프로젝트 구조

# 새 프로젝트 시작 시
claude "이 프로젝트의 구조와 사용된 기술 스택을 분석해줘.
주요 파일들의 역할과 데이터 흐름을 설명해줘"

# 기존 코드 개선
claude "이 코드를 리팩토링해줘. 
먼저 테스트를 작성해서 동작을 보장한 후,
단계별로 개선해줘"

# 문서 생성
claude "프로젝트의 README.md를 업데이트해줘.
설치 방법, 사용법, API 문서, 기여 가이드를 포함해줘"

# 성능 분석
claude "이 애플리케이션의 성능을 프로파일링하고,
병목 지점을 찾아서 최적화 방안을 제시해줘"

# 1. 의존성 및 아키텍처 분석
claude "이 Express 앱의 핵심 기능과 구조를 분석해줘.
- 의존성 트리와 순환 참조 확인
- 비즈니스 크리티컬 모듈 식별
- 테스트 커버리지 평가
- 성능 병목 지점 파악"

# 2. 상세한 마이그레이션 로드맵
claude "이 앱을 Fastify로 마이그레이션하는 계획을 세워줘.
- Strangler Fig 패턴 적용
- 단계별 롤백 계획
- 성능 벤치마크 설정
- 팀 교육 일정 포함
- 리스크 평가와 완화 전략"

# 3. 점진적 마이그레이션 실행
claude "인증 모듈부터 Fastify로 마이그레이션해줘.
- 트래픽 스플리팅 구현
- 모니터링과 알림 설정
- 데이터 일관성 보장
- 자동화된 테스트 스위트
- 성능 회귀 감지"

# 4. 복잡한 프론트엔드 마이그레이션
claude "React 클래스 컴포넌트를 함수형으로 마이그레이션해줘.
- 생명주기를 훅으로 변환
- 상태 관리 현대화
- 코드 분할과 지연 로딩 적용
- TypeScript 타입 안전성 강화
- 성능 최적화 기회 식별"

# 5. 데이터베이스 마이그레이션
claude "MySQL에서 PostgreSQL로 마이그레이션 계획을 세워줘.
- 스키마 변환과 데이터 타입 매핑
- 무중단 데이터 이전 전략
- 쿼리 최적화와 성능 튜닝
- 백업과 복구 절차
- 검증과 테스트 계획"

# 성능 지표 모니터링
claude "마이그레이션 전후 성능 비교 대시보드를 만들어줘.
- 응답 시간과 처리량 비교
- 메모리 사용량과 CPU 효율성
- 번들 크기와 로딩 시간
- 사용자 경험 메트릭 (LCP, FID, CLS)
- 개발자 생산성 지표"

# 품질 지표 추적
claude "코드 품질 개선 사항을 추적하는 시스템을 구축해줘.
- 테스트 커버리지 변화
- 코드 복잡도 감소
- 보안 취약점 해결
- 기술 부채 감소
- 팀 만족도 조사"

# 기본 TypeScript 프로젝트 설정
claude "엄격한 타입 체크를 사용하는 TypeScript 프로젝트를 설정해줘.
tsconfig.json을 최적화하고, ESLint와 Prettier도 TypeScript에 맞게 구성해줘"

# 대규모 모노레포 설정
claude "대규모 TypeScript 모노레포를 설정해줘.
- Nx 워크스페이스 구성
- 프로젝트 간 의존성 관리
- 공유 라이브러리 빌드 시스템
- 컨시스턴트 코드 스타일 적용
- 사이클릭 의존성 감지"

# 마이크로프론트엔드 아키텍처
claude "TypeScript 마이크로프론트엔드 아키텍처를 구성해줘.
- Module Federation 설정
- 런타임 타입 안전성 보장
- 사이드카 로딩과 버전 관리
- 공유 상태 및 이벤트 처리
- 테스트 전략과 목 설정"

{
  "compilerOptions": {
    // 최신 자바스크립트 표준 지원
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    
    // 최대 타입 안전성
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true,
    
    // 추가 엄격성 옵션
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    
    // 모든 타입 및 내보내기
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "isolatedModules": true,
    
    // 성능 최적화
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    
    // 경로 매핑
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/utils/*": ["./src/utils/*"],
      "@/types/*": ["./src/types/*"]
    }
  },
  "include": [
    "src/**/*",
    "types/**/*",
    "tests/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "coverage"
  ]
}

# Branded Types로 비즈니스 규칙 적용
claude "Branded Types를 사용해서 비즈니스 로직 안전성을 보장해줘.
- UserId, Email, PhoneNumber 등 도메인 타입 정의
- 런타임 검증 함수와 연동
- API 응답 타입 안전성 보장
- 데이터베이스 스키마와 동기화"

# Conditional Types로 API 타입 자동 생성
claude "Conditional Types를 활용해서 OpenAPI 스키마에서 
TypeScript 타입을 자동 생성하는 시스템을 만들어줘.
- Path Parameter와 Query Parameter 타입 추론
- Response 타입 자동 매핑
- HTTP Status Code별 타입 구분
- 에러 타입 유니온 생성"

# Template Literal Types로 DSL 구현
claude "Template Literal Types를 사용해서 타입 안전한 DSL을 만들어줘.
- CSS-in-JS 타입 체크
- SQL 쿼리 빌더 타입 안전성
- Event Name 자동 완성
- i18n 키 유효성 검사"

# 점진적 타입 로딩
claude "대규모 프로젝트의 TypeScript 컴파일 성능을 최적화해줘.
- Project References로 점진적 빌드
- Type-only imports 활용
- 사용하지 않는 타입 제거
- 동적 import로 타입 로딩 최적화
- Watch mode 성능 튜닝"

# 런타임 타입 검증 최적화
claude "런타임 타입 검증을 성능에 영향 없이 구현해줘.
- Zod로 런타임 스키마 검증
- Type Guards 최적화
- 비동기 검증 배칭
- 캐시 전략과 메모이제이션
- 에러 바운더리와 로깅"

### 타입 안전성 극대화

**1. 고급 타입 활용**

```bash
claude "이 JavaScript 코드를 TypeScript로 마이그레이션해줘.
유니온 타입, 제네릭, 조건부 타입을 활용해서
타입 안전성을 최대한 확보해줘"

claude "이 함수의 반환 타입이 너무 넓게 추론되고 있어.
타입 가드와 const assertion을 사용해서 더 정확한 타입을 추론하도록 해줘"

claude "API 응답을 Zod 스키마로 검증하는 시스템을 만들어줘.
타입스크립트 타입도 자동으로 생성되도록 해줘"

claude "이 명령형 코드를 함수형 스타일로 리팩토링해줘.
불변성을 유지하고, 순수 함수를 사용하며,
함수 조합으로 로직을 구성해줘"

claude "여러 API 호출을 효율적으로 처리하도록 최적화해줘.
Promise.all, Promise.allSettled를 적절히 사용하고,
에러 처리와 재시도 로직도 추가해줘"

# TypeScript/JavaScript Guidelines

## 타입 정의 규칙
- 인터페이스 > 타입 별칭 (확장 가능한 경우)
- any 사용 금지 (unknown 사용)
- 명시적 반환 타입 선호

## 비동기 처리
```typescript
// 좋은 예
const fetchData = async (): Promise<Result<Data, Error>> => {
  try {
    const data = await api.get('/data');
    return { ok: true, value: data };
  } catch (error) {
    return { ok: false, error };
  }
};

# 기본 Python 프로젝트 설정
claude "Python 패키지 구조를 모범 사례에 따라 설정해줘.
pyproject.toml, 가상 환경, 타입 힌트, 
그리고 테스트 설정을 포함해줘"

# 대규모 FastAPI 애플리케이션
claude "FastAPI로 엔터프라이즈급 API 서버를 구축해줘.
- 비동기 데이터베이스 연동 (SQLAlchemy 2.0)
- Pydantic v2로 데이터 검증
- OAuth2/JWT 인증 시스템
- 마이크로서비스 아키텍처 대비
- 모니터링과 로깅 시스템"

# 데이터 엔지니어링 파이프라인
claude "Apache Airflow로 대용량 데이터 파이프라인을 구축해줘.
- ETL 워크플로우 자동화
- Pandas/Polars 성능 최적화
- 대용량 데이터 비동기 처리
- 에러 복구와 재시도 로직
- 모니터링과 알림 시스템"

# 머신러닝 프로덕션 시스템
claude "MLOps 파이프라인을 Python으로 구축해줘.
- MLflow로 실험 추적과 모델 버전 관리
- Celery로 비동기 매치 학습
- FastAPI로 모델 서빙 API
- 실시간 모델 모니터링
- A/B 테스트 프레임워크"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "enterprise-python-app"
version = "0.1.0"
description = "Enterprise-grade Python application"
authors = ["Team <team@company.com>"]
readme = "README.md"
packages = [{include = "app", from = "src"}]

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.104.0"
uvicorn = {extras = ["standard"], version = "^0.24.0"}
sqlalchemy = "^2.0.0"
alembic = "^1.12.0"
pydantic = "^2.5.0"
celery = "^5.3.0"
redis = "^5.0.0"
structlog = "^23.2.0"
prometheus-client = "^0.19.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
pytest-asyncio = "^0.21.0"
pytest-cov = "^4.1.0"
mypy = "^1.7.0"
black = "^23.11.0"
ruff = "^0.1.0"
pre-commit = "^3.5.0"

# 마이크로서비스 도구
locust = "^2.17.0"  # 로드 테스트
opentelemetry-api = "^1.21.0"  # 분산 추적
jinja2 = "^3.1.0"  # 템플릿 엔진

# 코드 품질 도구
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
disallow_untyped_decorators = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_no_return = true
warn_unreachable = true
strict_equality = true

[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'
extend-exclude = '''
^/(
  (
      \.eggs
    | \.git
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
  )/
)
'''

[tool.ruff]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings  
    "F",   # pyflakes
    "I",   # isort
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "UP",  # pyupgrade
    "N",   # pep8-naming
    "S",   # bandit
]
ignore = [
    "E501",  # line too long
    "B008",  # do not perform function calls in argument defaults
    "S101",  # use of assert
]
line-length = 88
target-version = "py311"

[tool.pytest.ini_options]
minversion = "7.0"
addopts = "-ra -q --cov=src --cov-report=term-missing --cov-report=html"
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
asyncio_mode = "auto"

# 고급 타입 힌트 패턴
claude "이 Python 코드에 고급 타입 힌트를 추가해줘.
- 제네릭과 프로토콜을 활용한 추상화
- Union과 Literal을 이용한 정확한 타입 정의
- TypeGuard로 런타임 타입 체크
- NewType으로 도메인 타입 생성
- mypy strict 모드 통과 보장"

# Pydantic v2 고급 기능
claude "Pydantic v2로 고급 데이터 검증 시스템을 구축해줘.
- Field validators와 model validators
- 비동기 검증자와 커스텀 시리얼라이저
- Discriminated Unions로 복잡한 데이터 구조
- JSON Schema 자동 생성
- 성능 최적화된 설정"

# 정적 분석 도구 통합
claude "Python 코드 품질을 위한 정적 분석 도구를 설정해줘.
- mypy + Pylance로 최대 타입 체크
- ruff로 빠른 린팅과 포매팅
- bandit으로 보안 취약점 검사
- vulture로 사용하지 않는 코드 탐지
- 전체 CI/CD 파이프라인 통합"

from typing import (
    AsyncGenerator, Awaitable, Callable, 
    Generic, Literal, Protocol, TypeGuard, 
    TypeVar, Union, overload
)
from dataclasses import dataclass
from pydantic import BaseModel, Field, field_validator
from datetime import datetime
from decimal import Decimal

# Domain Types with NewType
from typing import NewType
UserId = NewType('UserId', int)
Email = NewType('Email', str)
ProductId = NewType('ProductId', str)

# Protocol for dependency injection
class DatabaseProtocol(Protocol):
    async def execute(self, query: str) -> list[dict[str, any]]: ...
    async def fetch_one(self, query: str) -> dict[str, any] | None: ...

# Generic Repository Pattern
T = TypeVar('T', bound=BaseModel)

class Repository(Generic[T]):
    def __init__(self, db: DatabaseProtocol, model_class: type[T]) -> None:
        self._db = db
        self._model_class = model_class
    
    async def find_by_id(self, id_: int) -> T | None:
        result = await self._db.fetch_one(
            f"SELECT * FROM {self._model_class.__tablename__} WHERE id = {id_}"
        )
        return self._model_class(**result) if result else None

# Advanced Pydantic Models
class UserCreateRequest(BaseModel):
    email: Email = Field(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    name: str = Field(..., min_length=1, max_length=100)
    age: int = Field(..., ge=18, le=120)
    
    @field_validator('email')
    @classmethod
    def validate_email_domain(cls, v: str) -> str:
        allowed_domains = ['company.com', 'partner.com']
        domain = v.split('@')[1]
        if domain not in allowed_domains:
            raise ValueError(f'Email domain must be one of {allowed_domains}')
        return v

# Type Guards for runtime validation
def is_valid_user_id(value: any) -> TypeGuard[UserId]:
    return isinstance(value, int) and value > 0

# Discriminated Union for complex data structures
class SuccessResponse(BaseModel):
    status: Literal['success'] = 'success'
    data: dict[str, any]
    timestamp: datetime = Field(default_factory=datetime.now)

class ErrorResponse(BaseModel):
    status: Literal['error'] = 'error'
    message: str
    error_code: int
    timestamp: datetime = Field(default_factory=datetime.now)

APIResponse = Union[SuccessResponse, ErrorResponse]

# Async Context Manager with proper typing
class AsyncDatabaseTransaction:
    def __init__(self, db: DatabaseProtocol) -> None:
        self._db = db
        self._transaction: any = None
    
    async def __aenter__(self) -> DatabaseProtocol:
        self._transaction = await self._db.begin()
        return self._db
    
    async def __aexit__(self, exc_type: type[Exception] | None, 
                       exc_val: Exception | None, 
                       exc_tb: any) -> None:
        if exc_type is None:
            await self._transaction.commit()
        else:
            await self._transaction.rollback()

# 고성능 비동기 시스템
claude "대용량 비동기 처리 시스템을 구축해줘.
- asyncio + aiohttp로 대량 HTTP 요청 처리
- asyncpg로 비동기 데이터베이스 연동
- 비동기 컨텍스트 매니저와 세마포어
- 백프레셔와 서킷 관리
- 에러 전파와 로깅 전략"

# 메모리 최적화 전략
claude "Pandas/Polars로 대용량 데이터 처리를 최적화해줘.
- 청크 단위 스트리밍 처리
- 제너레이터와 이터레이터 최적화
- 메모리 매핑 파일과 파켓 형식
- 병렬 처리와 멀티프로세싱
- 가비지 컴렉션 최적화"

# Celery로 백그라운드 작업 처리
claude "Celery로 엔터프라이즈급 비동기 작업 시스템을 구축해줘.
- Redis Sentinel로 고가용성 브로커
- 동적 워커 스케일링
- 작업 우선순위와 라우팅
- 실패 처리와 재시도 전략
- 모니터링과 메트릭 수집"

# 성능 프로파일링과 병목 분석
claude "Python 애플리케이션의 성능 병목을 찾아서 최적화해줘.
- cProfile과 py-spy로 프로파일링
- 메모리 사용량 분석 (memory_profiler)
- 데이터베이스 쿼리 최적화
- 캐시 전략 및 메모이제이션
- JIT 컴파일러 (Numba) 활용"

import asyncio
import aiohttp
import asyncpg
from typing import AsyncIterator, AsyncContextManager
from contextlib import asynccontextmanager
import structlog
from dataclasses import dataclass
from datetime import datetime

# 비동기 데이터베이스 커넥션 풀
class AsyncDatabasePool:
    def __init__(self, dsn: str, min_size: int = 10, max_size: int = 100):
        self.dsn = dsn
        self.min_size = min_size
        self.max_size = max_size
        self.pool: asyncpg.Pool | None = None
        self.logger = structlog.get_logger()
    
    async def initialize(self) -> None:
        """È비동기 커넥션 풀 초기화"""
        self.pool = await asyncpg.create_pool(
            self.dsn,
            min_size=self.min_size,
            max_size=self.max_size,
            command_timeout=60
        )
        self.logger.info("Database pool initialized", 
                        min_size=self.min_size, max_size=self.max_size)
    
    @asynccontextmanager
    async def acquire(self) -> AsyncIterator[asyncpg.Connection]:
        """È커넥션 획득 및 자동 반납"""
        if not self.pool:
            raise RuntimeError("Pool not initialized")
        
        async with self.pool.acquire() as conn:
            try:
                yield conn
            except Exception as e:
                self.logger.error("Database operation failed", error=str(e))
                raise
    
    async def close(self) -> None:
        """È커넥션 풀 종료"""
        if self.pool:
            await self.pool.close()
            self.logger.info("Database pool closed")

# 비동기 HTTP 클라이언트 래퍼
class AsyncHTTPClient:
    def __init__(self, timeout: int = 30, max_connections: int = 100):
        self.timeout = aiohttp.ClientTimeout(total=timeout)
        self.connector = aiohttp.TCPConnector(
            limit=max_connections,
            limit_per_host=20,
            keepalive_timeout=30
        )
        self.session: aiohttp.ClientSession | None = None
        self.logger = structlog.get_logger()
    
    async def __aenter__(self) -> 'AsyncHTTPClient':
        self.session = aiohttp.ClientSession(
            timeout=self.timeout,
            connector=self.connector
        )
        return self
    
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
        if self.session:
            await self.session.close()
    
    async def get_multiple(self, urls: list[str], 
                          concurrency: int = 10) -> AsyncIterator[dict]:
        """È여러 URL을 동시에 요청하고 결과를 스트리밍"""
        semaphore = asyncio.Semaphore(concurrency)
        
        async def fetch_one(url: str) -> dict:
            async with semaphore:
                try:
                    async with self.session.get(url) as response:
                        data = await response.json()
                        return {"url": url, "status": response.status, "data": data}
                except Exception as e:
                    self.logger.error("HTTP request failed", url=url, error=str(e))
                    return {"url": url, "status": 500, "error": str(e)}
        
        # 비동기 제너레이터로 결과 스트리밍
        tasks = [fetch_one(url) for url in urls]
        for task in asyncio.as_completed(tasks):
            result = await task
            yield result

# 대용량 데이터 처리를 위한 제너레이터 패턴
async def process_large_dataset_chunks(
    query: str, 
    db_pool: AsyncDatabasePool,
    chunk_size: int = 10000
) -> AsyncIterator[list[dict]]:
    """È대용량 데이터셋을 청크 단위로 처리"""
    offset = 0
    
    while True:
        chunked_query = f"{query} LIMIT {chunk_size} OFFSET {offset}"
        
        async with db_pool.acquire() as conn:
            rows = await conn.fetch(chunked_query)
            
        if not rows:
            break
            
        # dict로 변환하여 리턴
        chunk = [dict(row) for row in rows]
        yield chunk
        
        offset += chunk_size
        
        # 내부 처리를 위한 비동기 지연
        await asyncio.sleep(0.01)

# 무제한 재시도와 지수 백오프
async def retry_with_exponential_backoff(
    func: Callable[[], Awaitable[T]],
    max_retries: int = 3,
    base_delay: float = 1.0,
    max_delay: float = 60.0
) -> T:
    """È지수 백오프와 함께 재시도"""
    logger = structlog.get_logger()
    
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                logger.error("Max retries exceeded", error=str(e))
                raise
            
            delay = min(base_delay * (2 ** attempt), max_delay)
            logger.warning(
                "Operation failed, retrying",
                attempt=attempt + 1,
                max_retries=max_retries,
                delay=delay,
                error=str(e)
            )
            await asyncio.sleep(delay)
    
    # 이 지점에 도달할 수 없음
    raise RuntimeError("Unexpected execution path")

# Enterprise Python Guidelines

## 프로젝트 구조

import structlog

logger = structlog.get_logger()

# 비즈니스 로직
logger.info(
    "User created successfully", 
    user_id=user.id,
    email=user.email,
    timestamp=datetime.now().isoformat()
)

# 에러 로깅
logger.error(
    "Database connection failed",
    error=str(e),
    retry_count=retry_count,
    max_retries=max_retries
)

# 기본 현대화 작업
claude "이 레거시 Java 8 코드를 Java 17+ 기능을 활용해서 현대화해줘.
- Records로 데이터 클래스 변환
- Pattern Matching으로 instanceof 간소화
- Text Blocks로 가독성 향상
- Optional로 null 안전성 강화
- Stream API로 컬렉션 처리 최적화"

# 대규모 시스템 마이그레이션
claude "모놀리식 Spring 애플리케이션을 마이크로서비스로 분해해줘.
- 도메인 경계 식별과 서비스 분리
- Spring Cloud Gateway로 API 게이트웨이 구성
- 분산 트랜잭션과 사가 패턴 적용
- 서비스 메시와 분산 추적 설정
- 데이터베이스 분리 전략"

# 성능 최적화
claude "Java 애플리케이션의 성능을 프로파일링하고 최적화해줘.
- JVM 튜닝과 GC 최적화
- 메모리 누수 탐지와 해결
- 스레드 풀 설정 최적화
- 데이터베이스 커넥션 풀링
- JIT 컴파일러 최적화"

# 복잡한 의존성 그래프 최적화
claude "Spring Boot 애플리케이션의 의존성 주입을 최적화해줘.
- Constructor injection으로 불변성 보장
- 순환 의존성 탐지와 해결
- Configuration Properties로 타입 안전한 설정
- Profile별 Bean 조건부 생성
- 테스트용 Test Configuration 분리"

# 멀티 모듈 프로젝트 설정
claude "대규모 Spring Boot 멀티 모듈 프로젝트를 설정해줘.
- 공통 모듈과 도메인별 모듈 분리
- 모듈 간 의존성 관리
- 통합 테스트와 단위 테스트 전략
- 빌드 최적화와 병렬 컴파일
- 도커 이미지 계층화"

# WebFlux 마이그레이션
claude "기존 Spring MVC REST API를 Spring WebFlux로 마이그레이션해줘.
- Mono와 Flux를 활용한 논블로킹 처리
- R2DBC로 반응형 데이터베이스 연동
- WebClient로 외부 API 호출 최적화
- 백프레셔 처리와 에러 복구
- 성능 벤치마크와 비교 분석"

# 하이브리드 아키텍처
claude "Spring MVC와 WebFlux를 혼합한 하이브리드 시스템을 구축해줘.
- CPU 집약적 작업은 MVC로 처리
- I/O 집약적 작업은 WebFlux로 처리
- 공통 보안 설정과 인증 처리
- 모니터링과 메트릭 통합
- 로드 밸런싱 전략"

# Java 코드베이스 점진적 Kotlin 전환
claude "기존 Java Spring Boot 프로젝트를 점진적으로 Kotlin으로 전환해줘.
- 새 기능은 Kotlin으로 작성
- data class로 DTO 간소화
- sealed class로 상태 관리
- extension functions로 유틸리티 함수 정리
- coroutines로 비동기 처리 개선"

# Kotlin DSL 활용
claude "Kotlin DSL을 활용해서 설정과 빌드 스크립트를 개선해줘.
- build.gradle.kts로 빌드 스크립트 타입 안전성 확보
- Spring Security DSL로 보안 설정 간소화
- 테스트 DSL로 가독성 높은 테스트 작성
- 도메인 특화 언어 구현"

// 타입 안전한 설정 관리
@ConfigurationProperties(prefix = "app")
data class AppProperties(
    val database: DatabaseProperties,
    val security: SecurityProperties,
    val features: FeatureFlags
) {
    data class DatabaseProperties(
        val url: String,
        val maxPoolSize: Int = 20,
        val connectionTimeout: Duration = Duration.ofSeconds(30)
    )
    
    data class SecurityProperties(
        val jwtSecret: String,
        val jwtExpiration: Duration = Duration.ofHours(24),
        val corsAllowedOrigins: List<String> = emptyList()
    )
    
    data class FeatureFlags(
        val enableNewPaymentSystem: Boolean = false,
        val enableAdvancedAnalytics: Boolean = false
    )
}

// 결과 타입으로 에러 처리
sealed class Result<out T> {
    data class Success<T>(val value: T) : Result<T>()
    data class Error(val exception: Throwable) : Result<Nothing>()
    
    inline fun <R> map(transform: (T) -> R): Result<R> = when (this) {
        is Success -> Success(transform(value))
        is Error -> this
    }
    
    inline fun <R> flatMap(transform: (T) -> Result<R>): Result<R> = when (this) {
        is Success -> transform(value)
        is Error -> this
    }
}

// 코루틴을 활용한 서비스 계층
@Service
class UserService(
    private val userRepository: UserRepository,
    private val emailService: EmailService,
    private val auditService: AuditService
) {
    suspend fun createUser(request: CreateUserRequest): Result<User> = runCatching {
        // 병렬 검증
        val (emailExists, usernameExists) = coroutineScope {
            val emailCheck = async { userRepository.existsByEmail(request.email) }
            val usernameCheck = async { userRepository.existsByUsername(request.username) }
            emailCheck.await() to usernameCheck.await()
        }
        
        when {
            emailExists -> throw UserAlreadyExistsException("Email already exists")
            usernameExists -> throw UserAlreadyExistsException("Username already exists")
        }
        
        val user = User(
            email = request.email,
            username = request.username,
            hashedPassword = hashPassword(request.password)
        )
        
        // 병렬 처리
        coroutineScope {
            val saveUser = async { userRepository.save(user) }
            val sendEmail = async { emailService.sendWelcomeEmail(user.email) }
            val audit = async { auditService.logUserCreation(user.id) }
            
            saveUser.await().also {
                sendEmail.await()
                audit.await()
            }
        }
    }.fold(
        onSuccess = { Result.Success(it) },
        onFailure = { Result.Error(it) }
    )
}

// Extension functions로 유틸리티 확장
fun String.isValidEmail(): Boolean = 
    matches("""^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$""".toRegex())

fun <T> List<T>.chunkedParallel(size: Int, block: suspend (List<T>) -> Unit) = runBlocking {
    chunked(size).map { chunk ->
        async { block(chunk) }
    }.awaitAll()
}

// 타입 안전한 쿼리 빌더
class UserQueryBuilder {
    private val criteria = mutableListOf<String>()
    private val parameters = mutableMapOf<String, Any>()
    
    fun byEmail(email: String) = apply {
        criteria.add("email = :email")
        parameters["email"] = email
    }
    
    fun byAgeRange(min: Int, max: Int) = apply {
        criteria.add("age BETWEEN :minAge AND :maxAge")
        parameters["minAge"] = min
        parameters["maxAge"] = max
    }
    
    fun activeOnly() = apply {
        criteria.add("active = true")
    }
    
    fun build(): Pair<String, Map<String, Any>> {
        val query = "SELECT * FROM users" + 
            if (criteria.isNotEmpty()) " WHERE " + criteria.joinToString(" AND ")
            else ""
        return query to parameters
    }
}