Claude Code 입문: 터미널 인터페이스와 컨텍스트 최적화로 AI 개발 효율 3배 높이기

Claude를 처음 프로젝트에 붙여봤다가 엉뚱한 답변을 받은 적 있다면, 이 글이 정확히 그 이유와 해결책을 설명한다. CLAUDE.md 하나, 슬래시 명령어 몇 개만 제대로 써도 체감 속도가 달라진다.

---

CLAUDE.md: 프로젝트 내비게이션 구축

Claude를 처음 띄우면 내 프로젝트 구조를 전혀 모른다. 폴더가 어떻게 나뉘어 있는지, 테스트는 어떻게 돌리는지, 코딩 컨벤션은 무엇인지 — 전부 맥락 없는 상태에서 시작한다.

해결책은 단순하다. 프로젝트 루트에 CLAUDE.md 파일을 만들면 된다.

# 프로젝트 개요
Node.js 기반 REST API 서버. Express + PostgreSQL.

# 폴더 구조
src/
  routes/    # 라우터 정의
  services/  # 비즈니스 로직
  models/    # DB 모델
tests/       # Jest 기반 테스트

# 테스트 실행
npm test              # 전체
npm test -- --watch   # 변경 감지 모드

# 코딩 컨벤션
- async/await 사용 (콜백 금지)
- 에러는 반드시 try/catch로 처리
- 함수명 camelCase, 파일명 kebab-case

이 파일 하나로 Claude가 답변을 뱉기 전에 이미 구조를 파악하고 들어온다. 실제로 테스트해보니, CLAUDE.md 없을 때는 "테스트 파일이 어디 있나요?" 같은 되묻기가 빈번했는데, 파일을 추가하고 나서는 바로 npm test 명령어를 정확히 제안했다.

CLAUDE.md는 전역(홈 디렉토리)과 로컬(프로젝트 루트) 두 곳에 둘 수 있다. 전역에는 개인 선호 스타일을, 로컬에는 프로젝트 특화 정보를 분리해서 관리하면 깔끔하다.

---

터미널 인터페이스: 키보드만으로 전체 코드베이스 조작

Claude Code는 GUI가 없다. 터미널 하나가 전부다. 처음엔 불편해 보이지만, 익숙해지면 마우스를 안 쓴다는 게 오히려 속도를 높인다.

기본 호출 방법:

# 현재 디렉토리 구조 설명 요청
claude "Explain the current directory structure"

# 특정 파일 분석
claude "src/services/auth.js 파일에서 보안 취약점 찾아줘"

# 대화형 모드 진입
claude

대화형 모드로 들어가면 프롬프트가 > 로 바뀐다. 이 상태에서 자연어로 지시를 내리면 Claude가 파일을 직접 읽고, 수정하고, 명령어를 실행한다.

> user.js 파일에 이메일 중복 검사 로직 추가해줘
> 방금 수정한 내용 테스트 코드도 작성해줘
> git diff로 변경 사항 보여줘

명령 한 줄이 파일 편집, 테스트 작성, diff 확인까지 이어진다. 손이 키보드에서 떠나지 않는다.

---

컨텍스트 윈도우: 기억력 한계를 설계로 극복

Claude가 한 번에 읽을 수 있는 코드 양은 무한하지 않다. 토큰 한도를 넘기면 속도가 느려지고, 앞쪽 내용이 밀려나기 시작한다.

실제로 마주친 문제:

# 이렇게 하면 안 된다 — node_modules까지 컨텍스트에 들어감
claude "전체 프로젝트 분석해줘"

node_modules가 3만 개 파일이면, Claude가 그걸 다 훑으려다 응답 시간이 30초를 넘긴다.

해결책은 두 가지다.

1. .claudeignore 또는 .gitignore 활용

# .gitignore (Claude도 이 파일을 존중한다)
node_modules/
dist/
.env
*.log
coverage/

2. 범위를 좁혀서 질문

# 전체 X → 범위 지정 O
claude "src/services 폴더만 분석해줘"
claude "auth 관련 파일들에서 버그 찾아줘"

방식	컨텍스트 사용량	응답 속도
전체 프로젝트 요청	과부하	느림
범위 지정 요청	최적	빠름
핵심 파일만 명시	최소	가장 빠름

---

슬래시 명령어: 대화 흐름을 리셋하는 단축키

대화가 길어지면 Claude가 초반 맥락을 잊기 시작한다. 20번 넘게 주고받은 대화에서 "아까 말한 함수 수정해줘" 같은 요청이 엉뚱하게 처리된다면 이미 컨텍스트가 흐릿해진 것이다.

자주 쓰는 슬래시 명령어:

/compact   # 지금까지 대화를 핵심만 요약해서 압축
/clear     # 대화 초기화 (새 작업 시작 시)
/help      # 사용 가능한 명령어 전체 목록
/model     # 사용 중인 모델 확인 및 변경

/compact는 특히 유용하다. 긴 디버깅 세션에서 여러 파일을 오가다 보면 대화가 50줄을 넘는다. 이때 /compact를 치면 핵심 결정 사항만 남기고 나머지를 압축한다. 응답 속도가 눈에 띄게 빨라진다.

---

마무리

CLAUDE.md로 프로젝트 맥락을 심고, 컨텍스트 범위를 좁히고, /compact로 주기적으로 대화를 정리하는 것 — 이 세 가지 습관이 Claude Code 활용의 80%를 결정한다.

다음 글에서는 Claude Code의 권한 관리와 자율 실행 모드(--dangerously-skip-permissions)를 어떤 상황에서, 어떻게 안전하게 쓰는지 다룬다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 입문
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독