Claude Code에 질문할 때, 이런 상황에서 멈출 때가 있습니다.

「README에 대해 묻고 싶은데, 어떻게 지정해야 하지?」

파일명을 문장으로 써도 전달될 때가 있습니다. 하지만 같은 이름의 파일이 여러 개 있거나 폴더가 깊으면, Claude Code가 대상을 찾는 것부터 시작하게 됩니다. 그래서 오늘 사용할 것이 바로 @멘션입니다.

Claude Code의 입력란에서 @를 입력하면, 파일 경로 (File path) 후보가 표시됩니다. 후보 중에서 읽고 싶은 파일을 선택하고, 그대로 질문을 작성할 수 있습니다. 사람에게 자료를 건넬 때, "그 자료"라고 말하는 대신 눈앞의 한 장을 손가락으로 가리키는 느낌입니다.

이 기사에서 다루는 기능은 이 @ 파일 경로 멘션 (File path mention)뿐입니다. 설치부터 시작해서, 연습용 README.md를 지정하고, 한 문장의 설명을 받는 것까지 10분 만에 진행합니다.

먼저 중요한 점입니다.

@는 일반 터미널에 명령어로 입력하는 것이 아니라, claude를 실행한 후의 Claude Code 입력란에서 사용합니다. Claude Code 공식의 Interactive mode에서는 @는 File path mention으로 설명되어 있습니다. 입력하면 파일 경로의 오토컴플리트 (Autocomplete)가 실행됩니다.

여기서 나온 용어들을 먼저 풀어보겠습니다.

• CLI: 터미널에서 문자를 입력하여 조작하는 방식입니다. Claude Code는 claude라는 명령어로 실행할 수 있습니다.
• 파일 경로 (File path): 파일이 어디에 있는지 나타내는 "주소"입니다. 예를 들어 README.md나 src/app.js입니다.
• 오토컴플리트 (Autocomplete): 입력 도중에 후보를 표시하여 선택할 수 있게 하는 메커니즘입니다.
• 멘션 (Mention): 여기서는 질문 속에서 "이 파일입니다"라고 대상을 나타내는 입력 방법입니다.

즉 @ 멘션은 Claude Code에게 질문할 때, 읽어주길 바라는 파일의 주소를 후보에서 선택하기 위한 입구입니다.

@README.md 이 파일의 역할을 한 문장으로 설명해 주세요

이 예시의 @README.md 부분은 전부 직접 입력하기보다, @를 입력하여 표시된 후보에서 선택하는 것이 기본입니다. 후보를 선택한 후에 질문을 이어갑니다.

참고로, @를 붙였다고 해서 답변이 반드시 정확해지는 기능은 아닙니다. 대상 파일을 지정하기 쉽게 만드는 입력 기능입니다. 답변 내용은 마지막에 스스로 파일과 대조해 보는 것이 안심됩니다.

Claude Code는 필요에 따라 프로젝트 내의 파일을 찾아줍니다. 공식 Quickstart에도 프로젝트 파일을 필요에 따라 읽는다고 되어 있습니다. 따라서 매번 모든 것을 지정해야만 사용할 수 있는 것은 아닙니다.

그럼에도 @가 편리한 이유는, 질문의 대상이 정해져 있을 때 그 위치를 처음부터 전달할 수 있기 때문입니다.

예를 들어, 다음 두 가지를 비교해 보겠습니다.

설정 파일을 설명해 주세요

@config/app.json 이 설정 항목을 처음 접하는 사람을 위해 설명해 주세요

전자에서는 어떤 설정 파일인지 Claude Code가 찾아야 합니다. 후자에서는 대상을 먼저 좁힐 수 있습니다. 프로젝트 규모가 클수록 이 작은 지정이 "어떤 파일인가요?"라는 확인이나, 다른 파일을 읽고 돌아오는 왕복 과정을 줄여줍니다.

편리함의 정체는 화려한 자동화가 아닙니다. 질문의 시작 지점을 맞추는 것입니다.

여기서부터는 아직 Claude Code를 설치하지 않은 상태에서 진행합니다. 터미널을 열고 공식 Quickstart에 있는 Native Install을 실행합니다.

curl -fsSL https://claude.ai/install.sh | bash

WSL은 Windows 상에서 Linux 환경을 사용하는 메커니즘입니다. Windows의 PowerShell을 사용하는 경우에는 다음 명령어를 사용합니다.

irm https://claude.ai/install.ps1 | iex

설치되었는지 확인합니다.

claude --version

정상이라면 버전 번호와 (Claude Code)가 표시됩니다. 필자의 환경에서는 다음을 확인했습니다.

2.1.220 (Claude Code)

버전 번호는 업데이트에 따라 변경됩니다. 같은 숫자가 아니더라도 claude --version

에러 없이 Claude Code의 버전이 표시된다면 괜찮습니다.

처음에는 다음 명령어로 실행합니다.

claude

처음 사용할 때는 브라우저 로그인 안내가 표시됩니다. 공식 Quickstart에 따르면, Claude Code를 사용하려면 대상 Claude 플랜, Claude Console 계정, 또는 대응하는 클라우드 프로바이더(Cloud Provider)를 통한 액세스가 필요합니다. 화면의 안내에 따라 인증해 주세요.

로그인, 2단계 인증, 조직 권한 확인이 나타나는 경우, 내용을 직접 확인하며 진행하면 됩니다. 인증 정보를 기사의 코드 예시나 채팅에 붙여넣을 필요는 없습니다.

갑자기 업무 프로젝트를 사용하면 불안해지기 쉬우므로, 우선 연습용 폴더를 만듭니다. 다음 명령어를 위에서부터 순서대로 복사하세요.

mkdir claude-at-practice
cd claude-at-practice
printf '# Sample App\n\nCSV를 읽어 월간 보고서를 만드는 연습용 앱입니다.\n' > README.md

생성되었는지 확인합니다.

ls

Windows PowerShell에서도 ls를 사용하여 목록을 표시할 수 있습니다. README.md가 보이면 준비 완료입니다.

이 폴더에서 Claude Code를 실행합니다.

claude

이후부터는 일반적인 터미널 명령어가 아니라, Claude Code의 입력란에서 조작합니다.

• 입력란에 @를 한 글자 입력합니다.
• 표시된 파일 경로 후보 중에서 README.md를 선택합니다.
• 선택한 파일명 뒤에 질문을 이어갑니다.

완성된 형태는 다음과 같습니다.

@README.md 이 파일의 역할을 한 문장으로 설명해 주세요

전송하여 "CSV를 읽어 월간 보고서를 만드는 연습용 앱에 대한 설명입니다"와 같이 README 내용에 부합하는 한 문장이 돌아온다면 성공입니다.

확인할 것은 세 가지만 있으면 됩니다.

• @를 입력했을 때 파일 경로 후보가 나왔는가
• 후보 중에서 README.md를 선택할 수 있었는가
• README에 작성한 내용에 따른 설명이 돌아왔는가

이것으로 첫 번째 파일을 직접 지정할 수 있었습니다. 거창한 설정은 필요 없습니다. 우선 이 작은 성공만으로도 충분합니다.

동작 확인에 대하여:

claude --version은 필자의 환경에서 실행 완료했습니다. @를 사용하는 대화 부분은 필자의 환경에서 동작을 확인하지 않았으며, 공식 Interactive mode의 사양을 바탕으로 합니다.

기본 형태는 "@로 대상을 선택 + 해당 파일에 대해 요청하기"입니다. 기능을 늘리지 않고 질문만 바꾸면 계속해서 활용할 수 있습니다.

@README.md 이 프로젝트를 처음 접하는 사람이 가장 먼저 알아야 할 전제 조건 3가지를 들어주세요

@config/app.json 각 설정 항목이 무엇을 변경하는지, 값을 변경하지 말고 설명해 주세요

@tests/login.test.js 이 테스트가 확인하고 있는 성공 조건과 실패 조건을 나누어 주세요

모두 @의 역할은 동일합니다. 대상을 선택하는 것까지는 인간이 결정하고, 읽고 정리하는 것은 Claude Code에게 맡기는 것입니다. 이렇게 역할을 분담하면 "다른 파일을 보고 있었다"는 식의 재작업을 줄이기 쉽습니다.

파일을 수정하기를 원하지 않을 때는 요청문에 "변경하지 말고 설명해 주세요"라고 적어두면 목적을 전달하기 쉽습니다. 다만, 실제로 어떤 조작이 허용되는지는 Claude Code의 권한 설정과도 관련이 있습니다. 이 기사에서는 @에만 집중하기 위해 권한 설정의 상세한 내용까지 다루지는 않겠습니다.

먼저 다음 사항을 순서대로 확인하세요.

• 일반 셸이 아니라, claude 실행 후의 입력란에서 @를 입력하고 있는가
• claude를 실행한 폴더에 목적 파일이 있는가
• 파일명의 철자가 맞는가
• claude --version이 정상적으로 표시되는가

이번 연습의 경우, Claude Code를 일단 종료한 후 다음 두 줄로 위치를 확인할 수 있습니다.

pwd
ls

Windows PowerShell에서는 pwd와 ls를 모두 사용할 수 있습니다. claude-at-practice 안에 README.md가 보이는 상태에서 다시 한번 claude를 실행합니다.

README.md가 여러 개 있는 프로젝트에서는 후보로 표시되는 경로를 보고 폴더를 포함하여 선택합니다.

@docs/README.md 이 문서의 대상 독자를 한 문장으로 설명해 주세요

파일명뿐만 아니라, docs/와 같이 중간 경로를 확인하는 것이 포인트입니다.

네. 후보에서 파일을 선택한 후, 바로 목적을 작성합니다. 단순히 "설명해 줘"라고 하기보다 길이, 대상 독자, 변경해도 되는지 여부를 덧붙이면 원하는 결과에 가까워지기 쉽습니다.

@README.md 내용은 변경하지 말고, 설정(Setup) 절차만 5줄 이내로 요약해 주세요

이 글의 성공 조건은 파일을 하나 선택하는 것까지입니다. 처음부터 범위를 넓히기보다, 파일 1개로 후보 표시와 질문의 흐름을 확인하는 것이 막히는 부분을 찾기에 더 쉽기 때문입니다.

아니요. 비밀키(Secret Key), 액세스 토큰(Access Token), 비밀번호, 개인정보, 고객 데이터가 포함된 파일은 지정하지 마세요. .env라는 이름의 파일에는 인증 정보가 들어있는 경우가 많으므로, 내용을 확인할 수 없는 상태에서 예시로 사용하지 않는 것이 안전합니다.

회사나 팀에서 사용하는 경우에는 조직의 데이터 이용 규칙도 먼저 확인해야 합니다. "기술적으로 선택할 수 있는 것"과 "보내도 되는 것"은 별개의 판단입니다.

이 기능은 편리하지만, 언제나 필수적인 것은 아닙니다.

예를 들어, 파일이 몇 개 없는 연습용 프로젝트에서 "이 프로젝트는 무엇을 하는 것인가요?"라고 묻는다면, Claude Code의 자동 탐색(Auto-exploration)만으로도 충분할 때가 있습니다. 질문의 대상을 아직 모르는 상태에서 우선 전체를 조사해 주길 바라는 상황에서도, 먼저 파일 1개로 좁히면 시야를 좁힐 가능성이 있습니다.

구분 방법은 간단합니다.

• 대상 파일이 정해져 있다 → @로 지정한다
• 대상 파일 내에서 찾아주길 원한다 → 목적을 문장으로 전달하고 탐색을 맡긴다

또 다른 한계는, @로 올바른 파일을 선택했더라도 질문이 모호하면 답변도 넓어지기 쉽다는 점입니다. "누구를 위해", "무엇을", "어느 정도 길이로", "변경할지 말지"를 한마디 덧붙이면 재작업을 줄일 수 있습니다.

Claude Code의 @ 멘션은 입력창에서 파일 경로 후보를 표시하여 질문 대상을 선택하기 쉽게 만드는 기능입니다.

사용법은 3단계 동작이었습니다.

• claude를 실행한다
• 입력창에서 @를 입력하고 파일 후보에서 선택한다
• 해당 파일에 대해 질문한다

처음부터 거대한 코드베이스(Codebase)에서 시도할 필요는 없습니다. 오늘 10분 핸즈온(Hands-on)을 통해 README.md를 하나 지정하고, 한 문장의 설명이 돌아온다면 그것만으로도 첫 번째 성공입니다.

다음 단계는 평소 사용하는 프로젝트의 README.md를 딱 한 번 @로 지정하고, "처음 참여하는 사람이 헷갈릴 만한 점을 한 가지만 들어주세요"라고 물어보는 것입니다. 실행 후에 일어나는 변화는, 대상 파일을 찾는 단계가 아니라 그 내용에 대해 생각하는 단계부터 대화가 시작된다는 작은 변화입니다.

최종 확인일: 2026-08-03

생성형 AI 활용 엔지니어 & 세 아이의 아빠. AI × 개발의 실전 지식을 매일 발신하고 있습니다. 자세한 내용은 X에서 동일한 이름으로 찾아보세요.