#claude.md

프로젝트를 분석하고 CLAUDE.md를 작성해주세요.
아래 10가지 핵심 항목을 분석한 뒤, 이를 기반으로 한국어로 문서를 작성해주세요. docs폴더에 각 섹션 별로 md파일을 생성해서 정리해주세요

#1. 프로젝트 개요: AI가 비즈니스 구조를 명확히 이해할 수 있도록 작성 (최우선)

반드시 포함할 핵심 내용:

• 제품의 핵심 포지션 및 목적
• 주요 사용자 대상
• 핵심 기능 및 향후 개선 방향
• 반드시 지켜야 하는 비즈니스 제약사항 및 UX 금지 규칙

전체 분량은 3~5개의 짧은 문단으로 간결하게 작성해주세요.

#2. 전체 기술 스택: AI가 잘못된 의존성이나 버전을 사용하지 않도록 명확히 작성

반드시 포함할 핵심 내용:

• 프레임워크 및 정확한 버전
• 사용 언어
• 전역 스타일링 방식
• 공통 UI 컴포넌트 라이브러리
• 상태 관리 도구
• 테스트 도구
• 빌드 및 번들링 도구
• 백엔드 및 데이터 처리 인프라

#3. 프로젝트 아키텍처 및 디렉토리 역할: AI가 저장소 구조를 이해할 수 있도록 작성

반드시 포함할 핵심 내용:

• 주요 최상위 디렉토리 역할
• 계층별 책임 분리 기준
• 전체 데이터 흐름 구조
• 관심사 분리 원칙
• 신규 기능 코드가 추가되어야 하는 위치

단순히 폴더 이름만 나열하지 말고, “왜 그렇게 구성되었는지”와 “어떤 규칙으로 사용하는지”를 중심으로 설명해주세요.

#4. 코드 작성 규칙: AI가 높은 품질의 코드를 생성할 수 있도록 작성

반드시 포함할 핵심 내용:

• 파일명 규칙
• 컴포넌트 작성 패턴
• TypeScript 강타입 규칙
• 단일 파일 최대 길이 제한
• import/export 규칙
• 전역 예외 처리 방식
• 주석 작성 규칙
• 비동기 요청 처리 방식

#5. UI 및 디자인 시스템: 프론트엔드 생산성을 높이기 위한 기준 작성

반드시 포함할 핵심 내용:

• 전체 UI 톤앤매너
• spacing 규칙
• typography 기준
• 인터랙션 피드백 방식
• 반응형 대응 규칙
• 접근성 지원 기준
• 컴포넌트 재사용 시 주의사항

#6. 문구 및 카피라이팅 규칙: 운영형/서비스형 프로젝트에서 필수

반드시 포함할 핵심 내용:

• 문체의 간결성 기준
• 문장 표현 방식
• 전문성 있는 톤 유지 규칙
• 문장 길이 기준
• 사용 금지 마케팅 표현 목록

가능하다면 내부 브랜드 문서 또는 카피 가이드 링크도 함께 첨부해주세요.

#7. 테스트 및 품질 기준: 얕은 구현과 저품질 결과 방지

반드시 포함할 핵심 내용:

• 반드시 테스트해야 하는 핵심 시나리오
• 신규 코드 작성 시 필수 테스트 규칙
• Lint 검사 기준
• 타입 검사 기준
• “작업 완료”로 판단하는 기준

#8. 파일 및 컴포넌트 생성 규칙: 중복 개발 및 저장소 혼잡 방지

반드시 포함할 핵심 내용:

• 신규 파일 생성 위치 규칙
• 기존 컴포넌트 수정 여부 판단 기준
• 공통 로직 추출 시점
• 전체 프로젝트 공통 네이밍 규칙

#9. 안전한 변경 규칙: 핵심 아키텍처 보호

반드시 포함할 핵심 내용:

• 공용 API 경로 임의 변경 금지
• 데이터베이스 스키마 무단 변경 금지
• 인증/권한 시스템 수정 금지
• 기존 버전과의 하위 호환 유지 규칙
• 대규모 구조 변경 시 사전 승인 필요 규칙

#10. 프로젝트 전용 명령어: AI가 즉시 작업 가능한 실행 환경 제공

Anthropic 공식 권장 방식에 맞춰 아래 내용을 포함해주세요.

반드시 포함할 핵심 내용:

• 로컬 개발 명령어
• 실행 명령어
• 빌드 명령어
• 검증 명령어
• 테스트 명령어

AI가 별도 질문 없이 바로 실행할 수 있도록 실제 사용 중인 명령어를 모두 작성해주세요.

#11. API 아키텍처 및 통신 규칙

AI가 API 계층을 안전하게 이해하고 수정할 수 있도록 분석해주세요.

반드시 포함할 핵심 내용:

• API 계층 구조
• API 클라이언트 구성 방식
• 인증 및 인가 흐름
• API 요청/응답 규격
• 에러 처리 방식
• Retry 정책
• 캐싱 전략
• API 버전 관리 정책
• 공통 Request/Response 타입 위치
• API 추가 시 따라야 하는 규칙
• 실제 코드 기반으로 작성해주세요.
• 추측하지 말고 확인된 내용만 기록해주세요.

#12. 데이터 모델 및 데이터 흐름

AI가 비즈니스 데이터를 정확하게 이해할 수 있도록 분석해주세요.

반드시 포함할 핵심 내용:

• 주요 엔티티 목록
• 엔티티 간 관계
• 데이터 저장 구조
• 데이터 생성/수정/삭제 흐름
• 주요 비즈니스 데이터 책임
• 데이터 검증 규칙
• 데이터 무결성 유지 방식
• 마이그레이션 전략
• 실제 스키마 기반 분석
• 확인되지 않은 내용은 "확인 필요"로 명시

#13. AI 작업 원칙 및 개발 워크플로우

이 프로젝트에서 AI Agent가 반드시 따라야 하는 작업 규칙을 작성해주세요.

반드시 포함할 핵심 내용:

#작업 원칙

• 기존 구현 패턴을 우선 따른다.
• 신규 라이브러리 추가 전 기존 대체 수단을 먼저 검토한다.
• 동일 기능을 중복 구현하지 않는다.
• 기존 컴포넌트 재사용을 우선한다.
• 기존 API를 우선 활용한다.
• any 사용을 금지한다.
• 타입 우회를 금지한다.
• 하드코딩을 금지한다.
• 임시 Mock 데이터 사용을 금지한다.
• TODO만 남기고 작업 종료하지 않는다.

#작업 절차

• 관련 코드 탐색
• 기존 패턴 확인
• 영향 범위 분석
• 구현
• 테스트 작성
• 타입 검사
• Lint 검사
• 문서 업데이트

#코드 수정 전 체크리스트

• 기존 유사 기능 존재 여부
• 공통 컴포넌트 활용 가능 여부
• 공통 훅 활용 가능 여부
• 공통 유틸 활용 가능 여부
• API 재사용 가능 여부

#14. 보안 및 민감 영역 보호 규칙

AI가 시스템 핵심 영역을 무분별하게 수정하지 않도록 작성해주세요.

반드시 포함할 핵심 내용:

#수정 금지 영역

• 인증(Authentication)
• 인가(Authorization)
• Session 처리
• JWT 처리
• OAuth 처리
• RBAC 정책
• 결제 로직
• 개인정보 처리 로직
• 암호화 로직
• 보안 미들웨어

#승인 필요 작업

다음 작업은 반드시 사전 승인 후 진행:

• 인증 방식 변경
• 권한 체계 변경
• DB 스키마 변경
• API Contract 변경
• 공용 인터페이스 변경
• 외부 서비스 교체

#보안 규칙

• Secret 하드코딩 금지
• 환경변수 우선 사용
• 민감 정보 로그 출력 금지
• 개인정보 저장 규칙 준수
• 보안 설정 임의 비활성화 금지

#15. 성능 및 최적화 기준

AI가 성능 저하를 유발하는 구현을 방지할 수 있도록 작성해주세요.

반드시 포함할 핵심 내용:

#프론트엔드 성능

• 불필요한 Re-render 방지
• Memoization 기준
• Lazy Loading 적용 기준
• 번들 크기 관리 정책
• 이미지 최적화 정책

#백엔드 성능

• N+1 Query 방지
• 불필요한 DB 호출 금지
• 캐싱 활용 기준
• 대용량 데이터 처리 기준
• API 응답 시간 기준

#공통 성능 규칙

• 중복 연산 방지
• 불필요한 네트워크 호출 금지
• 성능 저하 가능성이 있는 코드 작성 금지
• 기존 성능 최적화 패턴 유지
• 코드 리뷰 체크포인트

#성능 영향 여부

• 메모리 사용량 증가 여부
• 네트워크 호출 증가 여부
• 번들 크기 증가 여부
• 렌더링 비용 증가 여부