Claude Code - 기존 프로젝트 분석

Claude Code로 기존 프로젝트 분석하는 방법

Step 1 — 프로젝트 폴더에서 Claude Code 시작

터미널에서 프로젝트 폴더로 이동 후 실행합니다.

cd 내프로젝트폴더
claude

### Step 2 — 코드베이스 분석 요청

Claude Code는 agentic search를 사용해서 프로젝트 구조와 의존성을 자동으로 파악합니다. 
수동으로 파일을 선택하지 않아도 됩니다. 

자주 쓰는 분석 프롬프트들이에요:

# 전체 구조 파악
Give me a high-level overview of this codebase

# 특정 기능 찾기
Where is the user authentication logic?

# 의존성 분석
What are the main dependencies and how are they used?

# 특정 파일 분석
Explain what this file does: @src/api/routes.ts

### Step 3 — Plan Mode로 안전하게 탐색

Plan Mode는 읽기 전용 작업으로 코드베이스를 분석하고 계획을 세우는 모드입니다. 
코드를 수정하지 않고 탐색만 할 때 특히 유용합니다. 

# Plan Mode 진입 (Shift + Tab 또는 프롬프트에 직접)
Let's analyze this project in plan mode before making any changes

### Step 4 — /init 으로 CLAUDE.md 자동 생성
/init

이 명령어 하나로 Claude가 코드베이스를 탐색하고 프로젝트에 맞는 CLAUDE.md 파일을 자동으로 생성해 줍니다. 이미 CLAUDE.md가 있는 프로젝트라면 현재 파일을 검토하고 개선점을 제안해 줍니다.

CLAUDE.md는 반드시 만들어야 하나요?

필수는 아니지만, 만들면 차원이 달라집니다.

CLAUDE.md는 Claude가 매 대화에 자동으로 불러오는 프로젝트 설정 파일입니다. 프로젝트 구조, 코딩 표준, 선호하는 워크플로우를 항상 알고 있는 상태로 만들어줍니다. 

CLAUDE.md가 없으면 생기는 문제

CLAUDE.md가 없으면 매 대화마다 같은 아키텍처 결정, 테스트 요구사항, 코딩 스타일을 반복해서 설명해야 합니다. 코드베이스가 커질수록 이 문제가 심각해집니다. 

CLAUDE.md가 있으면 달라지는 것들

빌드 명령어나 린트 명령어를 매번 코드베이스에서 찾을 필요 없이 항상 인지하고 있습니다. 편집 전에 실행할 코드(Prettier 등)나 편집 후 실행할 타입 체크 같은 훅도 자동으로 적용됩니다. 

CLAUDE.md 기본 구조 예시

markdown

## 프로젝트 개요
FastAPI 기반 사용자 인증 REST API

## 주요 디렉토리
- `app/models/` — DB 모델
- `app/api/`    — 라우트 핸들러
- `app/core/`   — 설정 및 유틸리티

## 코딩 규칙
- 모든 함수에 타입 힌트 필수
- 테스트는 pytest 사용
- PEP 8, 한 줄 최대 100자

## 자주 쓰는 명령어
uvicorn app.main:app --reload   # 개발 서버
pytest tests/ -v                # 테스트 실행

CLAUDE.md를 작성하다 보면 부수 효과로 내 프로젝트에 대한 이해도 자체가 높아집니다. AI만을 위한 파일이 아니라 신규 팀원 온보딩 문서로도 그대로 활용할 수 있습니다.

한마디로 — CLAUDE.md는 Claude한테 주는 입사 첫날 온보딩 문서입니다. 없어도 일은 하지만, 있으면 매번 처음 만난 사람처럼 설명 안 해도 되는 거죠.