컨텍스트 추가하기

Claude Code에 컨텍스트 추가하기

코드 에디터로 프로젝트를 열어 두고, npm run dev로 개발 서버를 시작합니다. 브라우저에서 localhost:3000으로 이동하면 애플리케이션이 동작하는 것을 볼 수 있습니다. 이제 이 프로젝트에 Claude를 활용해 약간의 작업을 해볼 텐데, 그 전에 Claude를 사용할 때 정말 중요한 한 가지를 짚고 넘어가고 싶습니다. 바로 컨텍스트 관리(context management) 입니다.

이 강의를 통해 이 개념을 확실히 이해하고 가시기를 바랍니다.

왜 컨텍스트 관리가 중요한가

일반적인 프로젝트에는 수십 개에서 수백 개의 파일이 있고, 각 파일은 엄청난 양의 정보를 담고 있습니다. 우리가 Claude에게 질문을 던지거나 작업을 맡길 때, Claude가 필요로 하는 이상적인 정보의 양이 존재합니다. 여러분의 질문에 답하거나 작업을 완수하는 데 딱 충분한 만큼이죠.

여기에 관련 없는 정보를 추가하기 시작하면, Claude의 효율성은 떨어지기 시작합니다.

따라서 Claude에게 프로젝트 내의 관련 파일이나 문서를 구체적으로 안내해주는 것이 매우 중요합니다. 별도의 안내가 없어도 Claude Code는 분명 잘 동작하지만, 약간의 가이드만 더해도 Claude는 최상의 결과를 내줍니다. 지금부터 Claude에게 최선의 컨텍스트를 제공하는 다양한 팁을 알려드리겠습니다.

/init 명령어로 시작하기

먼저 에디터에서 터미널을 열고 claude 명령어를 실행해 Claude Code를 시작합니다.

새로운 프로젝트에서 Claude Code를 처음 실행할 때는 /init 명령어를 꼭 실행하길 강력히 권장합니다.

/init 명령어를 실행하면 Claude가 코드베이스 전체를 깊이 살펴봅니다. 프로젝트의 목적, 전반적인 아키텍처, 관련 명령어, 핵심 파일 등을 파악한 뒤, 그 결과를 요약해 CLAUDE.md 라는 파일에 정리해줍니다.

Claude가 CLAUDE.md 파일을 생성할 때는 권한을 요청합니다. Enter를 눌러 승인할 수도 있고, 매번 파일 쓰기 요청마다 권한을 부여하고 싶지 않다면 Shift + Tab을 눌러(모드 전환) Claude Code가 프로젝트 내에서 자유롭게 파일을 작성하도록 허용할 수도 있습니다.

생성된 CLAUDE.md 파일을 열어 내용을 살펴보시기를 권장합니다. 앞서 말씀드렸듯이, 이 파일의 내용은 Claude로 보내는 모든 요청에 포함됩니다. 이 파일에는 두 가지 목적이 있습니다.

1. Claude가 여러분의 코드베이스를 더 잘 이해하도록 도와 관련 코드를 빠르게 찾을 수 있게 합니다.

2. 여러분이 Claude에게 일반적인 가이드를 줄 수 있는 장소 역할을 합니다.

CLAUDE.md 파일의 세 가지 레벨

Claude Code가 활용하는 CLAUDE.md 파일에는 여러 종류가 있습니다.

• 프로젝트 레벨: 방금 /init으로 생성한 파일입니다. 일반적으로 Git과 같은 소스 컨트롤에 커밋해 다른 엔지니어들과 공유하며, 프로젝트별 지시 사항을 Claude에 전달합니다.

• 로컬 레벨 (CLAUDE.local.md): 선택적으로 만들 수 있으며, 커밋하지 않고 다른 엔지니어와도 공유하지 않습니다. 오직 자신만을 위한 개인 지시 사항을 여기에 넣을 수 있습니다.

• 글로벌 레벨: 머신 단위로 존재하는 파일로, 로컬에서 실행하는 모든 프로젝트에 적용되는 지시 사항을 담을 수 있습니다.

커스텀 지시 사항 추가하기: 메모리 모드

특별하거나 커스텀한 지시 사항을 Claude에게 주는 예시를 보여드리겠습니다. 예를 들어 현재 Claude가 코드에 주석을 너무 자주 추가한다고 가정해봅시다. 이런 경우 CLAUDE.md 파일을 업데이트해 해결할 수 있습니다. 이 때, CLAUDE.md 파일을 열어 직접 수정해도 되지만, 좀 더 편한 방법이 있습니다. Claude Code 안에서 # 기호를 입력하면 메모리 모드(memory mode) 로 진입합니다.

메모리 모드를 사용하면 CLAUDE.md 파일 중 하나를 지능적으로 편집할 수 있습니다. 예를 들어 "주석을 그렇게 자주 쓰지 마세요."라는 요청을 입력한 뒤, 이 지시 사항을 프로젝트 CLAUDE.md 파일에 추가하도록 지정하면, Claude가 해당 지시 사항을 프로젝트 CLAUDE.md 파일에 똑똑하게 병합해줍니다.

프로젝트 CLAUDE.md 파일을 열어 검색해보면 새 지시 사항이 실제로 추가된 것을 확인할 수 있습니다.

@ 멘션으로 특정 파일을 컨텍스트에 가져오기

CLAUDE.md 파일을 만들었으니, 이제 특정 컨텍스트를 대화에 끌어오는 방법을 알아봅시다. 예를 들어 이 프로젝트의 인증 시스템이 어떻게 동작하는지 더 잘 이해하고 싶다고 합시다. 그냥 Claude에게 '인증 시스템이 어떻게 동작하는지' 물어볼 수도 있습니다.

그러면 Claude가 코드베이스를 검색해 인증 시스템과 관련된 파일을 찾아낼 것입니다. 이 과정은 동작은 하지만, 약간의 시간이 걸립니다. 대안으로, 인증 시스템과 관련된 파일들이 무엇인지 이미 알고 있다면 @ 문자를 사용해 그 파일들을 멘션할 수 있습니다.

파일을 멘션하면, 해당 파일이 자동으로 Claude에 보내는 요청에 포함됩니다. 이는 Claude를 특정 방향으로 안내하는 아주 훌륭한 기법입니다.

CLAUDE.md 안에서 @ 멘션 활용하기

이 동일한 문법은 CLAUDE.md 안에서도 파일을 멘션하는 데 사용할 수 있습니다. 이게 왜 정말 유용한지 예시로 보여드리겠습니다. 이 프로젝트의 prisma 폴더 안에는 schema.prisma 파일이 있습니다. 이 파일은 프로젝트 정보를 저장하는 데 사용되는 SQLite 데이터베이스의 모든 테이블과 레코드 타입에 대한 완전한 정의를 담고 있습니다.

schema.prisma 파일에 있는 정보는 프로젝트에 중요하고 관련성이 높은 정보를 담고 있기 때문에, 이 파일을 CLAUDE.md 파일 안에서 멘션하자고 결정할 수도 있습니다. 방법은 다음과 같습니다.

1. 먼저 #를 입력해 메모리 모드로 진입합니다.

2. 해당 schema 파일을 멘션하면서, 데이터베이스 내 데이터의 구조를 이해해야 할 때마다 이 파일을 참조하도록 Claude에게 지시합니다.

업데이트가 완료되면 CLAUDE.md 파일을 열어 메모가 추가되었는지 확인합니다.

이렇게 파일을 멘션해두면, 그 파일의 내용이 자동으로 여러분이 Claude에 요청을 보낼 때마다 포함됩니다. 그래서 여러분이 user가 어떤 속성을 가지고 있는지 물어보면, Claude는 schema.prisma 파일을 따로 읽지 않고도 즉시 답변할 수 있습니다.