diff --git a/.gitignore b/.gitignore
index c2065bc..72c96fc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,3 +35,6 @@ out/
 
 ### VS Code ###
 .vscode/
+
+### Local only ###
+gradle.properties
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6e9cc72
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md - alist API 프로젝트
+
+## 프로젝트 개요
+- **프로젝트명**: alist API
+- **그룹**: com.alist
+- **포트**: 8106
+- **빌드 결과물**: `api.jar`
+
+## 기술 스택
+- **Java**: 21
+- **Framework**: Spring Boot 3.5.10
+- **빌드 도구**: Gradle
+- **DB**: MariaDB
+- **ORM**: MyBatis (mapper XML: `classpath:mapper/**/*.xml`)
+- **인증**: JWT (jjwt 0.11.5) + Spring Security
+- **API 문서**: Swagger (springdoc-openapi 2.6.0)
+- **기타**: Lombok, Validation, Actuator, log4jdbc
+
+## 패키지 구조
+```
+com.alist.api
+├── common
+│   ├── response/     # ApiResponse, ApiResponseCode
+│   └── utils/        # 공통 유틸리티
+├── config
+│   ├── jwt/          # JWT 필터, 핸들러, Provider
+│   ├── exception/    # GlobalExceptionHandler
+│   ├── properties/   # JwtProperties 등
+│   ├── SecurityConfig.java
+│   └── OpenApiConfig.java
+└── modules
+    └── {도메인}/     # Controller, Service, Mapper, DTO
+```
+
+## 프로파일
+| 프로파일 | 설명 |
+|---------|------|
+| `local` | 로컬 개발 환경 |
+| `pjt` | 프로젝트(운영) 환경 |
+
+## 보안 구조
+- **Swagger**: `/v3/api-docs/**`, `/swagger-ui/**` → HTTP Basic 인증 (InMemory)
+- **API**: JWT Bearer 토큰 인증 (Stateless)
+- **공개 경로**: `/`, `/actuator/health`, `/auth/**`, `/api/user/signup`
+
+## 빌드 및 실행
+```bash
+# 빌드
+./gradlew bootJar
+
+# 로컬 실행
+./gradlew bootRun --args='--spring.profiles.active=local'
+
+# JAR 실행
+java -jar build/libs/api.jar --spring.profiles.active=local
+```
+
+## Swagger 접속
+- URL: `http://localhost:8106/swagger-ui.html`
+- 인증: `swagger.login.id` / `swagger.login.password` (환경별 yaml에 설정)
+
+## 코드 작성 규칙
+- 응답은 `ApiResponse<T>` 래퍼 사용
+- 응답 코드는 `ApiResponseCode` enum 사용
+- MyBatis Mapper XML은 `src/main/resources/mapper/` 하위에 작성
+- 카멜케이스 자동 변환 활성화 (`map-underscore-to-camel-case: true`)
+- 새 모듈은 `modules/{도메인}/` 하위에 Controller, Service, Mapper, DTO 구성
+
+## CI/CD
+- **Jenkins**: `Jenkinsfile.pjt`
+- **Docker**: `Dockerfile`
+- **배포 스크립트**: `deploy/` 디렉토리