[Claude Code 스킬] @ 파일 참조 — 검색 대신 콕 집어 컨텍스트에 넣기 | DAKER 커뮤니티

무엇

@는 프롬프트 안에서 파일·디렉토리·MCP 리소스를 이름으로 '지목'해 그 내용을 곧바로 컨텍스트에 넣는 문법입니다. Claude가 grep으로 프로젝트를 뒤져 파일을 찾아 읽는 과정을 건너뛰고, 손가락으로 책장의 정확한 페이지를 짚어 보여주는 것과 같습니다. @만 입력하면 자동완성 메뉴가 떠 Tab으로 경로를 채웁니다.

언제 쓰나

• 고칠 파일을 이미 알 때 — Claude가 헤매며 탐색 토큰을 쓰기 전에 바로 지목.

• 서로 얽힌 여러 파일을 한 번에 보여줄 때(로그인 로직 + 미들웨어 + 타입 정의).

• 내용 말고 디렉토리 '구조'만 빠르게 파악시키고 싶을 때.

• 연결된 MCP 서버의 리소스(이슈·DB 스키마·문서)를 대화로 끌어올 때.

사용법

# 파일 한 개 — @ 입력 후 Tab 자동완성
> @src/auth/login.ts 이 로그인 흐름에 2단계 인증을 추가해줘

# 여러 파일을 앞에 모아 지목(요청 전에 컨텍스트부터)
> 결제 처리를 리팩터링하려고 해. 관련 파일:
@src/services/payment.ts    (핵심 로직)
@src/api/stripe.ts          (결제사 연동)
@src/models/Transaction.ts  (데이터 모델)

# 디렉토리 — 내용이 아니라 파일 '목록'을 넣어줌
> @src/components/ 구조부터 파악해줘

# MCP 리소스 — @서버:프로토콜://리소스
> @github:issue://123 을 분석하고 @postgres:schema://users 와 비교해줘

팁

• 요청보다 먼저 지목하라. "@파일 → 무엇을 해줘" 순서가 "무엇을 해줘(알아서 찾아)"보다 정확합니다. 모델이 추측으로 탐색하지 않기 때문입니다.

• @는 핀셋, 자동탐색은 그물. 핀셋이 빠르고 토큰도 아끼지만 무엇을 집을지 모를 땐 자연어로 맡기는 게 낫습니다. 작업이 바뀌면 /clear로 묵은 참조를 비워 혼선을 막습니다.

출처

• Claude Code Docs — Best practices: code.claude.com/docs/en/best-practices

• MCPcat — Reference Files with @ in Claude Code: mcpcat.io/guides/reference-other-files

• Steve Kinney — Referencing Files and Resources in Claude Code: stevekinney.com/courses/ai-development/referencing-files-in-claude-code