byteforce

CPN 한국어 자습서 · Claude Code in Action

2 · 직접 해보기

컨텍스트 추가

Adding context

이 코스에서 꼭 가져가야 할 개념이 컨텍스트 관리입니다. 작업마다 Claude에게 필요한 정보는 딱 적당한 양이 있습니다. /init로 CLAUDE.md를 만들고, # 메모리 모드와 @ 파일 멘션으로 알맞은 컨텍스트를 짚어 줍니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · 강사

코드 에디터로 작은 프로젝트를 열고, npm run dev로 개발 서버를 띄웠습니다. localhost:3000으로 들어가면 앱이 도는 걸 볼 수 있습니다. 이제 Claude로 이 프로젝트에 약간의 작업을 해 볼 텐데, 그 전에 꼭 이해하고 가야 할 게 있습니다. 이 코스에서 여러분이 가져갔으면 하는 핵심은 바로 컨텍스트 관리입니다.

보통 프로젝트에는 파일이 수십, 수백 개씩 있고 각 파일에는 엄청난 양의 정보가 담겨 있습니다. Claude에게 질문이나 작업을 줄 때, Claude가 필요로 하는 정보에는 이상적인 양이 있습니다 — 질문에 답하거나 작업을 끝내기에 딱 충분한 만큼이요. 관련 없는 정보가 더해지기 시작하면 Claude의 효율은 떨어지기 시작합니다. 그래서 프로젝트 안에서 관련 있는 파일이나 문서로 Claude를 안내해 주는 게 정말 중요합니다. Claude Code는 손을 잡아 주지 않아도 잘 동작하지만, 약간의 안내만 해 주면 최상의 결과를 얻습니다.

프로젝트에서 Claude Code를 처음 쓸 때는 /init 명령을 꼭 실행하길 권합니다. 이 명령은 Claude가 코드베이스 전체를 깊이 살펴보게 합니다. 프로젝트의 목적, 전반적인 아키텍처, 관련 명령, 핵심 파일 등을 파악한 뒤, 그 결과를 요약해 CLAUDE.md라는 파일에 담습니다. 이 파일을 만들 때 권한을 물어보는데, 엔터로 수락하거나, 매번 묻는 게 번거롭다면 Shift+Tab을 눌러 Claude Code가 프로젝트에 자유롭게 파일을 쓰도록 허용할 수 있습니다.

생성된 CLAUDE.md를 열어 내용을 살펴보길 권합니다. 이 파일의 내용은 Claude에 보내는 모든 요청에 포함됩니다. 이 파일은 두 가지 목적이 있습니다. 첫째, Claude가 코드베이스를 더 잘 이해해 관련 코드를 빠르게 찾도록 돕습니다. 둘째, Claude에게 일반적인 지침을 줄 수 있는 자리이기도 합니다.

CLAUDE.md 파일은 여러 종류가 있습니다 — 프로젝트 수준, 로컬 수준, 머신 수준. 프로젝트 수준은 방금 /init으로 만든 것으로, 보통 Git 같은 소스 컨트롤에 커밋해 다른 엔지니어들과 공유하고 프로젝트별 지침을 전달합니다. 선택적으로 CLAUDE.local.md도 만들 수 있는데, 이건 커밋하지 않고 공유하지도 않으며 나만을 위한 개인 지침을 둡니다. 마지막으로 머신 전역 CLAUDE.md는 로컬에서 돌리는 모든 프로젝트에 적용됩니다.

사용자 지정 지침의 예를 보여 드리겠습니다. Claude가 주석을 너무 자주 단다고 해 봅시다. CLAUDE.md를 고쳐 해결할 수 있습니다. 파일을 직접 수정해도 되지만, 지름길로 Claude Code에서 파운드(#) 기호를 입력하면 메모리 모드로 들어갑니다. 그러면 CLAUDE.md 파일 중 하나를 똑똑하게 편집할 수 있습니다. '주석을 너무 자주 달지 마라' 같은 요청을 넣고, 프로젝트 CLAUDE.md에 추가하겠다고 지정하면 Claude가 그 지침을 파일에 알맞게 병합해 줍니다.

이제 대화에 특정 컨텍스트를 끌어오는 법을 알아봅니다. 이 프로젝트의 인증 시스템이 어떻게 동작하는지 알고 싶다고 합시다. 그냥 Claude에게 물어보면 코드베이스를 뒤져 관련 파일을 찾아 줍니다 — 동작은 하지만 시간이 좀 걸립니다. 대신 관련 파일을 이미 알고 있다면 앳(@) 문자로 멘션할 수 있습니다. 파일을 멘션하면 그 내용이 Claude 요청에 자동으로 포함됩니다. Claude를 특정 방향으로 가리키는 아주 좋은 기법입니다.

같은 문법으로 CLAUDE.md 안에서도 파일을 멘션할 수 있습니다. 예를 들어 Prisma 폴더에 schema.prisma 파일이 있는데, 여기에는 이 프로젝트의 SQLite 데이터베이스에 저장되는 모든 테이블과 레코드 유형의 정의가 들어 있습니다. 너무 중요하고 여러 곳과 관련된 정보라, 이 파일을 CLAUDE.md 안에서 멘션해 둘 수 있습니다. # 으로 메모리 모드에 들어가 그 schema 파일을 멘션하면서 '데이터 구조를 이해해야 할 때면 언제든 이 파일을 참고하라'고 적어 둡니다. 이렇게 파일을 멘션해 두면 그 내용이 요청에 자동으로 포함되므로, '유저는 어떤 속성을 갖는지' 물어도 Claude가 schema 파일을 다시 읽지 않고 바로 답할 수 있습니다.

이 장에서 배우는 것What you'll learn

약 5분
1

작업마다 필요한 컨텍스트는 딱 적당한 양이 있다

2

관련 없는 정보가 늘면 Claude 효율은 떨어진다

3

/init → 코드베이스 분석 후 CLAUDE.md 생성

4

CLAUDE.md는 프로젝트 · 로컬 · 머신 세 수준

5

# 메모리 모드로 CLAUDE.md를 똑똑하게 편집

6

@로 파일 멘션 → 그 내용이 요청에 자동 포함

먼저 짚고 갈 용어
컨텍스트(context)
Claude가 작업을 위해 보는 정보. 너무 많아도(잡음) 효율이 떨어진다 — 알맞게 짚어 주는 게 핵심.
/init
코드베이스를 분석해 목적·구조·핵심 파일을 요약하고 CLAUDE.md로 저장하는 명령.
CLAUDE.md
모든 요청에 포함되는 안내 파일. 코드베이스 이해를 돕고 일반 지침을 담는다.
# (메모리 모드)
Claude Code에서 # 입력 시 진입. CLAUDE.md를 똑똑하게 편집한다.
@ (파일 멘션)
@경로로 파일을 가리키면 그 내용이 요청에 자동 포함된다.

컨텍스트 관리가 핵심

Just enough context

프로젝트에는 파일이 수십·수백 개. 작업마다 Claude에게 필요한 정보는 딱 적당한 양이 있습니다. 관련 없는 정보가 늘면 효율은 오히려 떨어집니다. 그래서 관련 파일·문서로 Claude를 안내해 주는 게 중요합니다.

컨텍스트 양 데모 · 슬라이더를 움직여 보세요
너무 적음딱 적당너무 많음(잡음)

최적 · 효율 최고

필요한 만큼만 — 질문에 답하기 딱 충분한 정보일 때 Claude가 가장 잘 동작합니다.

/init 과 CLAUDE.md

/init & CLAUDE.md

프로젝트에서 처음 쓸 때 /init을 실행하면, Claude가 코드베이스를 분석해 그 요약을 CLAUDE.md에 담습니다. 이 파일은 모든 요청에 포함되어, 코드베이스 이해를 돕고 일반 지침을 전달하는 두 역할을 합니다.

터미널 · /init 으로 CLAUDE.md 생성
# 프로젝트에서 Claude Code를 처음 쓸 때
> /init

# Claude가 코드베이스를 분석 → 목적·구조·핵심 파일을 요약
# 결과를 CLAUDE.md 로 저장 (생성 시 권한 확인: Enter 수락 / Shift+Tab 자동 허용)

CLAUDE.md는 세 수준으로 나뉩니다. 어디에 두는지에 따라 적용 범위와 공유 여부가 달라집니다.

PROJECT

CLAUDE.md

/init으로 생성. 보통 Git에 커밋해 팀과 공유하는 프로젝트 지침.

LOCAL

CLAUDE.local.md

커밋·공유 안 함. 나만을 위한 개인 지침을 둔다.

MACHINE

~/.claude/CLAUDE.md

머신 전역. 모든 프로젝트에 적용되는 지침.

# 메모리 모드 & @ 파일 멘션

Memory mode & @-mentions

지침을 더하고 싶을 때 파일을 직접 고쳐도 되지만, #를 입력해 메모리 모드로 들어가면 CLAUDE.md를 똑똑하게 편집할 수 있습니다.

메모리 모드 · CLAUDE.md에 지침 병합
# # 입력 → 메모리 모드. CLAUDE.md 를 똑똑하게 편집
# 주석을 너무 자주 달지 마세요

# → 어느 CLAUDE.md에 넣을지 고르면(프로젝트 등) 알맞게 병합됨

대화에 특정 컨텍스트를 끌어오려면 @로 파일을 멘션합니다. 멘션한 파일의 내용이 요청에 자동으로 포함되어, Claude를 정확한 방향으로 가리킬 수 있습니다.

@ 파일 멘션 · 대화 + CLAUDE.md
# @ 로 파일 멘션 → 그 내용이 요청에 자동 포함
> 인증 시스템이 어떻게 동작하나요? @src/auth/session.ts

# CLAUDE.md 안에서도 같은 문법으로 멘션 가능 (메모리 모드에서):
# 데이터 구조를 이해해야 할 땐 항상 @prisma/schema.prisma 를 참고하세요
왜 유용할까

schema.prisma처럼 중요한 파일을 CLAUDE.md에서 멘션해 두면, "유저는 어떤 속성을 갖나요?" 같은 질문에 Claude가 파일을 다시 읽지 않고 바로 답합니다.

정리 & 점검

Recap & check
핵심 정리
  • 작업마다 딱 적당한 컨텍스트가 있다 — 잡음이 늘면 효율은 떨어진다.
  • /init → 코드베이스 분석 후 CLAUDE.md 생성. 모든 요청에 포함된다.
  • CLAUDE.md는 프로젝트(커밋·공유) · 로컬(개인) · 머신(전역) 세 수준.
  • # 메모리 모드로 CLAUDE.md를 똑똑하게 편집한다.
  • @로 파일을 멘션하면 그 내용이 요청에 자동 포함된다.

Q1프로젝트에서 Claude Code를 처음 쓸 때 권장되는, 코드베이스를 분석해 CLAUDE.md를 만드는 명령은?

Q2대화에 특정 파일의 내용을 자동으로 포함시키는 방법은?

Q3팀과 공유하지 않고 나만을 위한 개인 지침을 두는 파일은?

MEMBER SESSION REQUIRED · REGISTRATION IS FREE

여기부터는 등록한 분에게 열립니다.

전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 16개 레슨을 끝까지 읽을 수 있습니다.

등록하고 이어서 읽기

이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.