Free

CLAUDE.md 완벽 가이드: Claude Code가 프로젝트를 진짜로 이해하게 만들기

명령어·아키텍처·금지 사항·파일 참조까지, 실제 Rails 프로젝트로 배우는 CLAUDE.md 작성 실전 가이드.

Claude Code를 열 때마다 완전히 처음부터 시작한다 — 이전 대화는 기억하지 못하고, 프로젝트가 무엇인지 모르며, 테스트 명령어가 rspec인지 pytest인지도, 절대 건드려선 안 되는 작업이 뭔지도 모른다.

CLAUDE.md가 이 문제를 해결한다. Claude에게 쓰는 영구적인 설명서로, 매 대화 시작 전에 자동으로 로드된다. 잘 작성된 CLAUDE.md 하나면 Claude가 바로 업무 모드로 진입한다 — 불필요한 질문도 없고, 기초적인 실수도 없다.

어디에 두는가

Claude Code는 계층형 CLAUDE.md 시스템을 지원하며 세 가지 레벨이 있다:

  • ~/.claude/CLAUDE.md: 글로벌 설정. 모든 프로젝트에 적용된다. "git을 자동으로 커밋하지 말 것", "한국어로 답변할 것" 같은 공통 설정을 둔다.
  • 프로젝트 루트 CLAUDE.md: 프로젝트 단위 설정. 가장 많이 쓰는 위치.
  • 하위 디렉토리 CLAUDE.md: 해당 디렉토리의 파일을 다룰 때만 로드된다. frontend/, api/, infra/에 각각 별도 설명을 두기에 적합.

여러 CLAUDE.md 파일은 겹쳐서 적용되며, 더 깊은 레벨일수록 구체적이다. 하위 파일이 상위를 덮어쓸 수 있다.

무엇을 쓰는가

프로젝트 개요

프로젝트가 무엇이고 어떤 기술을 쓰는지 한 단락으로 설명한다:

## Project Overview

**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.

- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)

버전 번호를 명시하는 것이 중요하다. Rails 8임을 알면 Rails 6 시대 방식을 제안하지 않는다. 데이터베이스가 4개임을 알면 마이그레이션에서 실수하지 않는다.

개발 명령어

CLAUDE.md에서 가장 직접적인 가치를 만드는 섹션이다. 명령어를 명확히 쓰지 않으면 Claude는 추측에 의존하는데 — 그리고 틀린다.

## Development Commands

### Running the Application
bin/dev                  # Start Rails server (port 3000) + Tailwind watcher
bin/rails server         # Start Rails server only

### Testing
bundle exec rspec                                      # Run all tests
bundle exec rspec spec/models                          # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42         # Run test at line 42

### Linting & Security
bin/rubocop              # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a           # Auto-correct offenses
bin/brakeman             # Security vulnerability scan

### Deployment (Kamal)
bin/kamal deploy         # Deploy to production
bin/kamal app logs       # View application logs
bin/kamal app console    # Remote Rails console

이 목록으로 Claude는 알게 된다: 테스트는 rails test가 아닌 bundle exec rspec; 배포는 Capistrano나 Fly.io가 아닌 Kamal; 린터는 Rails Omakase 프리셋으로 설정된 RuboCop. 쓰지 않으면 모두 추측에 맡긴다.

아키텍처 설명

아키텍처 설명의 목적은 코드에서 보이지 않는 결정을 문서화하는 것이다. 디렉토리 구조는 Claude가 읽을 수 있다. 왜 그렇게 구성했는지는 쓰지 않으면 모른다.

## Key Architectural Patterns

**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.

**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.

**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.

이 세 가지 정보로 Claude는 새 기능을 추가할 때 알게 된다: 비즈니스 로직을 컨트롤러에 쌓지 말 것; 권한 확인은 app/policies/에서 해당 policy를 찾을 것; 비동기 처리는 Solid Queue로 job을 만들 것.

도메인 모델을 기능별로 그룹화해서 나열하는 것도 가치 있다:

## Core Domain Models

**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)

Claude가 직접 app/models/를 스캔하는 것보다 효율적이고, 비즈니스 의미도 전달된다 — 예를 들어 400포인트가 VIP 기준이라는 건 코드만 봐서는 한눈에 파악하기 어렵다.

직관적이지 않은 설정

이런 정보가 가장 간과되기 쉽고, 보통 가장 중요하다:

## Important Configuration

**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.

**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false

**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.

이 세 가지는 모두 "안 쓰면 반드시 실수한다"는 정보다: 멀티 데이터베이스는 마이그레이션 대상을 명시해야 한다; Lexxy는 베타 gem으로 표준 ActionText와 동작이 다르다; Propshaft는 Sprockets와 다르게 동작한다.

금지 사항

가장 과소평가된 섹션이다. Claude에게 하면 안 되는 것을 명확히 알려주는 것이 사후에 수정하는 것보다 훨씬 효율적이다.

## Do Not

- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction

첫 번째 항목은 거의 모든 프로젝트에 들어가야 한다. 배포 명령어는 더욱 중요하다 — 잘못 실행된 bin/kamal deploy는 프로덕션에 직격한다.

다른 파일 참조하기

CLAUDE.md는 @로 다른 파일을 참조할 수 있다:

배포 설정 상세: @config/deploy.yml
데이터베이스 스키마: @db/schema.rb

Claude는 필요할 때 이 파일들을 읽는다. db/schema.rb는 Rails 프로젝트에서 데이터베이스 구조의 단일 출처로, Claude가 모델 필드를 추측하는 것보다 훨씬 정확하다.

흔한 실수

너무 많이 쓰기: CLAUDE.md는 컨텍스트 윈도우를 소비한다. README를 전부 붙여넣으면 Claude가 실제 코드를 처리할 공간이 줄어든다. Claude가 코드베이스 자체에서 읽어낼 수 없는 것만 써라.

모호한 지침: "좋은 코드를 써라"는 쓸모없다. 구체적으로: "컨트롤러에 비즈니스 로직을 직접 쓰지 말고 app/services/에 위임할 것".

업데이트 잊기: Sprockets에서 Propshaft로 전환하거나 Sidekiq에서 Solid Queue로 이전한 후 CLAUDE.md가 따라오지 않으면 Claude는 구식 가정으로 동작한다. CLAUDE.md 업데이트를 리팩토링 체크리스트에 포함시켜라.

코드 예시 쓰기: 예시는 컨텍스트를 소비하고, Claude는 예시보다 실제 코드를 더 정확하게 읽는다. 실제 파일을 @로 참조하라.

시작 템플릿 (Rails 프로젝트)

# [프로젝트명]

[한 문장 설명]

- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL

## Development Commands

bin/dev              # Start server
bundle exec rspec    # Run tests
bin/rubocop          # Lint
bin/kamal deploy     # Deploy (ask before running)

## Architecture

[Services / Jobs / Policies 역할 분담]
[도메인 모델을 기능별로 그룹화]

## Important Notes

[직관적이지 않은 설정, gem의 특수한 동작]

## Do Not

- Do NOT run git commit automatically
[기타 고위험 작업]

이 템플릿에서 시작해서 프로젝트 실정에 맞게 채워넣는다. 모든 걸 다룰 필요는 없다 — 핵심 정보 5개가 담긴 CLAUDE.md가 허풍으로 가득 찬 것보다 몇 배 가치 있다.