[TIL][Claude Code] Claude Code 초기 세팅 #1 - 처음 쓰는 사람이 놓치는 것들

Claude Code 를 설치해서 claude 쳐서 대화하는 건 다들 알고 있다

나는 꿈돌이가 알려준 튜토리얼대로 세팅하고 편하게 했는데

초기 세팅을 모르고 그냥 사용하는 칭구들이 많아서 내용을 정리한다

1. CLAUDE.md - "나는 이렇게 일해" 를 한 번만 써두는 파일

프로젝트 루트에 CLAUDE.md 파일을 두면 Claude Code 가 매 대화 시작할 때 자동으로 읽는다

즉, 매번 "나 React 프로젝트야, TypeScript 쓰고, pnpm 쓰고..." 안 해도 된다

만드는 법

# 방법 1: Claude 한테 시키기 (추천)
cd /your/project
claude
> /init
# Claude 가 프로젝트 구조 분석해서 초안 만들어줌

# 방법 2: 직접 만들기
touch CLAUDE.md

뭘 써야 하나

처음엔 이 정도면 충분하다:

# 프로젝트 개요
- React + TypeScript 프로젝트
- 패키지 매니저: pnpm
- Node 20

# 주요 명령어
- `pnpm dev` - 개발 서버
- `pnpm test` - 테스트
- `pnpm build` - 빌드

# 코드 스타일
- 함수형 컴포넌트만
- Zustand 으로 상태 관리

# 폴더 구조
- src/components/ - UI 컴포넌트
- src/hooks/ - 커스텀 훅
- src/api/ - API 호출

포인트는 Claude 가 프로젝트 맥락을 파악하는 데 필요한 것만 쓰는 거다

장황한 설명 필요 없고 핵심만

편집할 때

claude
> /memory
# 에디터가 열림 → 바로 수정 가능

2. CLAUDE.md 는 여러 개 둘 수 있다

이거 처음에 몰랐는데 꽤 유용하다

위치	용도	git 에 올라감?
~/.claude/CLAUDE.md	모든 프로젝트 공통	X (개인용)
./CLAUDE.md	이 프로젝트 규칙	O (팀 공유)
./CLAUDE.local.md	내 개인 설정	X (자동 gitignore)
./.claude/rules/*.md	주제별 규칙 분리	O (팀 공유)

실전 활용

# 모든 프로젝트에서 한국어로 답변받기
echo "모든 응답은 한국어로 작성한다" > ~/.claude/CLAUDE.md

# 이 프로젝트에서만 적용할 내 개인 설정
echo "커밋 메시지는 Conventional Commits 형식으로" > ./CLAUDE.local.md

~/.claude/CLAUDE.md 에 개인 취향을 넣어두면 어떤 프로젝트 열어도 적용된다

나는 여기에 "한국어로 답변", "코드 스타일 규칙" 같은 것들을 넣어뒀다

프로젝트가 크면 rules 폴더로 분리

.claude/
├── CLAUDE.md           # 프로젝트 개요만
└── rules/
    ├── code-style.md   # 코드 스타일
    ├── testing.md      # 테스트 규칙
    └── git.md          # 커밋/브랜치 규칙

CLAUDE.md 하나가 200줄 넘어가면 분리하는 게 낫다

3. @ 참조 - 파일을 대화에 끌어오기

기본

# 파일 참조
> @src/auth/login.ts 이 코드 리뷰해줘

# 여러 파일
> @src/api/user.ts 랑 @src/types/user.d.ts 타입 불일치 확인해줘

# 디렉토리 (구조만 보여줌)
> @src/components 여기 구조 좀 설명해줘

팁: Tab 자동완성

@ 입력 후 Tab 키 누르면 파일 경로 자동완성된다

경로 외울 필요 없다

CLAUDE.md 안에서도 @ 가 된다

# CLAUDE.md
아키텍처 상세는 @docs/architecture.md 참고
테스트 컨벤션은 @tests/README.md 참고

CLAUDE.md 를 짧게 유지하면서 상세 문서를 연결하는 방법이다

최대 5단계까지 중첩 참조 가능

4. 세션 관리 - 맥락을 잃지 않는 법

세션 이름 붙이기

claude
> /rename auth-refactor

나중에 이어하기

# 이름으로 복원
claude --resume auth-refactor

# 최근 세션 이어하기
claude -c

리팩토링 같은 큰 작업은 하루에 안 끝난다

# 월요일: 시작
claude
> /rename api-migration
> Axios 에서 fetch 로 마이그레이션하자
# ... 점심 ...

# 화요일: 이어서
claude --resume api-migration
> 어디까지 했지?
# Claude 가 전체 맥락 기억하고 있음

세션 이름 안 붙이면 나중에 찾기 어렵다

5. 모델 전환

# 대화 중 모델 변경
> /model

상황	모델	이유
아키텍처 설계, 복잡한 리팩토링	Opus	추론 최고
일반 코딩	Sonnet	속도/품질 밸런스
단순 질문, 포맷 변환	Haiku	빠르고 쌈

Pro Plan 으로 Opus 두어번 돌리면 토큰이 끝나 버린다

간단한 건 Haiku 로 돌리는 습관을 들이면 좋다

6. 자주 쓰는 슬래시 명령어

명령어	하는 일	언제 씀
/init	CLAUDE.md 자동 생성	프로젝트 첫 세팅
/memory	CLAUDE.md 편집	규칙 추가/수정
/compact	대화 압축	컨텍스트 길어졌을 때
/cost	토큰 사용량 확인	비용 체크
/context	컨텍스트 시각화	남은 공간 확인
/clear	대화 초기화	주제 바꿀 때
/model	모델 전환	Opus ↔ Sonnet ↔ Haiku

7. Plan Mode - 코드 쓰기 전에 계획부터

Claude 한테 바로 "이거 만들어" 하면 의도와 다른 방향으로 갈 수 있다

Plan Mode 는 먼저 분석만 하고, 계획 세우고, 내가 승인하면 그때 코드 작성하는 모드다

사용법

# Shift+Tab 으로 모드 전환 (입력창에서)
# Plan ↔ Act 토글

# 또는 시작할 때 지정
claude --permission-mode plan

흐름

[Plan Mode]
> OAuth2 구글 로그인 추가하고 싶어

Claude: 코드 분석 중...
→ 기존 auth 구조 파악
→ 수정할 파일 목록
→ 단계별 구현 계획

나: 좋아 진행해

[Act Mode 전환]
→ 계획대로 코드 작성

복잡한 작업일수록 Plan Mode 가 실수를 줄여준다

8. 권한 설정 - 매번 "허용하시겠습니까?" 안 뜨게

.claude/settings.json 에 자주 쓰는 명령어를 허용해두면 된다

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

npm test 같은 안전한 명령은 물어보지 않고 바로 실행

rm -rf 같은 위험한 건 차단

9. 컨텍스트 관리

Claude Code 도 컨텍스트 윈도우가 있다

대화가 길어지면 앞부분을 잊기 시작한다

/compact - 대화 압축

> /compact
# 지금까지 대화를 요약해서 컨텍스트 확보

/context - 남은 공간 확인

> /context
# 시각적으로 컨텍스트 사용량 보여줌

체감 상 대화 20~30턴 넘어가면 /compact 한 번 해주는 게 좋다

📋 Claude Code 첫 세팅 순서

1. claude 설치 (npm install -g @anthropic-ai/claude-code)
2. /init 으로 CLAUDE.md 생성
3. ~/.claude/CLAUDE.md 에 개인 공통 규칙 추가
4. .claude/settings.json 에 자주 쓰는 명령어 허용
5. /rename 으로 세션 이름 짓는 습관 들이기
6. /compact 를 대화하면서 적절하게 잘 사용하기 

🎯 결론

Claude Code 는 그냥 사용만 해도 좋지만

CLAUDE.md + 세션 관리 + 권한 설정을 하고 사용하면 더 좋다

특히 CLAUDE.md 는 한 번 잘 써두면 매번 반복 설명하는 시간을 아껴준다