이 프로젝트를 분석해서 CLAUDE.md와 상세 문서를 한국어로 작성해주세요.
# 0. 전역 규칙 (모든 항목에 적용)
- 코드·설정·스키마에서 직접 확인한 내용만 적습니다. 확인할 수 없는 내용은 지어내지 말고 "확인 필요"로 표시합니다.
- 이 프로젝트에만 해당하는 사실만 적습니다. 모델이 이미 아는 일반론(예: "any를 쓰지 않는다", "N+1 쿼리를 피한다", "SQL 인젝션을 조심한다")은 이 프로젝트에서 특별히 강제되는 근거가 없으면 쓰지 않습니다.
- 규칙은 지켰는지 판정할 수 있게, "~하지 마라"보다 "~한다"로 쓰고, 이유를 한 줄 붙입니다.
- 나쁨: "깨끗한 코드를 작성한다", "fetch를 쓰지 마라"
- 좋음: "API 호출은 src/api/client.ts를 통해서만 한다. 토큰 갱신과 재시도가 거기에만 구현돼 있다."
- 이 프로젝트에 해당하지 않는 항목은 생략합니다. 빈 섹션이나 "해당 없음" 설명을 남기지 않습니다.
- 같은 내용을 여러 파일에 반복하지 않습니다. 한 곳에 쓰고 다른 곳에서는 파일 경로로 가리킵니다.
# 1. 산출물
## CLAUDE.md (150줄 이하)
다음 순서로 작성합니다.
1. 명령어 — 바로 실행 가능한 실제 명령어
2. 프로젝트 요약 — 무엇을 하는 제품인지 2~3문장
3. 아키텍처 요약 — 주요 디렉터리와 역할, 신규 코드를 둘 위치
4. 핵심 규칙 — 이 프로젝트 고유 규칙 10개 이내
5. 함정 — 코드만 봐서는 드러나지 않는 사실
6. 승인 필요 작업 — 진행 전 반드시 사용자에게 확인할 작업
7. 상세 문서 안내 — "어떤 작업을 할 때 어떤 파일을 읽는다" 형식
(예: "API를 추가·수정할 때는 .claude/docs/api-data.md를 먼저 읽는다")
@import 문법은 쓰지 않습니다. 세션 시작 시 전부 로딩되기 때문입니다.
## .claude/docs/ (상세 문서)
아래 파일 중 이 프로젝트에 해당하는 것만 만듭니다.
- overview.md — 제품·사용자·비즈니스 제약
- architecture.md — 구조, 계층, 데이터 흐름, 신규 코드 위치
- conventions.md — 코드·네이밍·파일 생성 규칙
- api-data.md — API 계층, 데이터 모델
- ui-copy.md — 디자인 시스템, 문구 규칙
- testing.md — 테스트·품질 기준, 완료 기준
- sensitive-areas.md — 민감 영역, 승인 필요 작업
- performance.md — 이 프로젝트의 성능 기준
# 2. 분석 항목
## 2-1. 명령어와 실행 환경
- 설치, 개발 서버, 빌드, 테스트, 단일 테스트 파일 실행, 타입 검사, 린트, 포맷 명령어
- 필요한 환경변수 이름과 용도 (값은 적지 않음), 예시 파일 위치
- 로컬에서 함께 띄워야 하는 서비스 (DB, 캐시, 메시지 큐 등)
- 적은 명령어는 실제로 실행해 보고, 동작한 것만 남깁니다. 실행할 수 없었던 명령어는 "확인 필요"로 표시합니다.
## 2-2. 프로젝트 개요
- 제품의 목적과 핵심 기능
- 주요 사용자
- 지켜야 하는 비즈니스 제약과 UX 금지 규칙
- 코드에서 확인되지 않는 내용(포지션, 향후 방향 등)은 "확인 필요"로 남깁니다.
## 2-3. 기술 스택
- 언어, 프레임워크와 정확한 버전 (lock 파일 기준)
- 스타일링, UI 라이브러리, 상태 관리, 테스트, 빌드 도구
- 백엔드·데이터 인프라
- 비슷한 역할의 라이브러리가 여러 개라면, 신규 코드에서 어느 쪽을 쓰는지
## 2-4. 아키텍처와 디렉터리
- 최상위 디렉터리의 역할과, 왜 그렇게 나뉘었는지
- 계층별 책임과 의존 방향 (모노레포라면 패키지 간 의존 규칙)
- 요청·데이터가 흐르는 경로
- 신규 기능 코드, 공통 컴포넌트·훅·유틸을 둘 위치
- 기존 파일을 고칠지 새로 만들지 판단하는 기준, 공통 로직으로 추출하는 시점
## 2-5. 코드 규칙
- 파일·컴포넌트·함수 네이밍
- 컴포넌트·모듈 작성 패턴 (대표 예시 파일 경로를 함께)
- 타입 규칙, import/export 규칙
- 에러 처리, 비동기 처리 방식
- 주석 규칙
- 규칙마다 실제로 그렇게 작성된 파일 경로를 근거로 붙입니다.
## 2-6. API와 데이터
- API 클라이언트 구성, 인증·인가 흐름
- 요청/응답 규격, 공통 타입 위치
- 에러 처리, 재시도, 캐싱, 버전 관리 방식
- API를 추가할 때 따르는 절차
- 주요 엔티티와 관계, 저장 구조, 생성·수정·삭제 흐름
- 데이터 검증·무결성 규칙, 마이그레이션 방식
## 2-7. UI와 문구 (프론트엔드가 있을 때만)
- 디자인 토큰 위치 (spacing, typography, color)
- 인터랙션 피드백, 반응형, 접근성 기준
- 문체, 문장 길이, 사용 금지 표현
- 브랜드·카피 가이드 문서가 있으면 경로를 적습니다.
## 2-8. 테스트와 완료 기준
- 반드시 테스트해야 하는 핵심 시나리오
- 신규 코드에 필요한 테스트 종류와 위치
- "작업 완료"로 판단하는 기준 (예: typecheck·lint·test 통과)
- 작업 절차: 관련 코드 탐색 → 기존 패턴 확인 → 영향 범위 분석 → 구현 → 테스트 → 검증
아래 자동화 테스트 규칙은 testing.md에 그대로 포함합니다. 0번의 "일반론 금지"에서 제외되는 예외입니다.
- 명령어·도구·경로는 이 프로젝트의 실제 값으로 바꿔 적습니다. (예: "unit test" → "pnpm test")
- 프로젝트에 해당 도구가 없으면(예: E2E 도구 미도입) 규칙을 지우지 말고 "확인 필요"로 표시합니다.
- [실행]·[실패 대응]·[보고] 규칙은 모든 작업에 적용되므로 CLAUDE.md 핵심 규칙에도 요약해 넣습니다.
[작성]
- PRD의 수용 기준(AC)을 테스트 가능한 조건으로 변환한다.
- 기능 구현 시 관련 단위 테스트와 필요한 통합 테스트를 함께 작성한다.
- 로그인, 권한, 핵심 사용자 흐름에는 E2E 테스트를 작성한다.
- 외부 서비스, 인증 정보, 테스트 데이터는 테스트 환경에 맞게 격리한다.
[실행]
- 구현 완료 후 lint, typecheck, unit test, build를 실행한다.
- 핵심 사용자 흐름에 영향을 주는 변경은 E2E 테스트도 실행한다.
[실패 대응]
- 테스트 실패 시 원인을 분석하고 코드를 수정한 뒤 재실행한다.
- 테스트를 통과시키기 위해 검증 조건을 임의로 약화하거나 테스트를 삭제하지 않는다.
[보고]
- 실행하지 않은 테스트는 통과했다고 보고하지 않는다.
- 최종 결과에 실행한 명령, 통과·실패 항목, 미검증 항목을 보고한다.
## 2-9. 민감 영역과 승인 필요 작업
- 인증·인가, 세션·토큰, 결제, 개인정보, 암호화, 보안 미들웨어 중 이 프로젝트에 있는 것과 그 위치
- 위 영역 중 수정 전 승인이 필요한 것
- 스키마, 공용 API 계약, 공용 인터페이스, 외부 서비스 변경처럼 되돌리기 어려운 작업
- 비밀값·민감 정보 처리 방식 (환경변수 로딩 위치, 로그 마스킹 등)
- 어떤 영역을 승인 대상으로 할지는 조직이 정하는 정책입니다. 코드에서 근거를 찾지 못하면 후보로만 제시하고 "확인 필요"로 표시합니다.
## 2-10. 성능
- 이 프로젝트에 이미 적용된 최적화 패턴과 위치 (메모이제이션, 지연 로딩, 캐시, 쿼리 최적화 등)
- 명시된 성능 기준 (번들 크기 예산, 응답 시간 목표 등). 없으면 지어내지 않습니다.
## 2-11. 함정
- 이름이나 구조만 보고는 오해하기 쉬운 것
(예: "user_v1 테이블은 읽기 전용", "날짜는 UTC로 저장하고 표시 직전에 KST로 변환")
- 레거시·폐기 예정 코드와 그 대체 경로
- 깨지기 쉬운 설정, 순서가 중요한 초기화
## 2-12. Git 규칙
- 브랜치, 커밋 메시지, PR 규칙 (설정 파일이나 기존 커밋에서 확인)
# 3. 마무리 보고
문서를 모두 작성한 뒤, 파일과 별도로 대화창에 다음을 보고합니다.
1. 생성한 파일 목록과 각 줄 수
2. 실행해 본 명령어와 결과 (성공·실패)
3. "확인 필요" 항목을 모은 질문 목록 — 제가 답하면 문서에 반영합니다
4. 문서 규칙 대신 린터·타입 검사·훅·CI로 강제하는 편이 나은 항목
5. 해당 없어서 생략한 항목과 그 이유 (한 줄씩)