Claude Code 딥링크 — 클릭해도 실행은 안 되고, 깃허브에서는 링크가 사라집니다

장애 대응 문서에 "여기를 누르면 그 저장소에서 진단 프롬프트가 열립니다"라고 링크 하나를 걸어둘 수 있다면 어떨까요. 공식 문서에 그 기능이 있습니다. 전용 주소 형식을 쓰는데, 누르면 새 터미널이 열리고 프롬프트까지 채워진 상태로 뜹니다. 저는 보안이 먼저 걱정됐는데, 문서가 그 지점을 정면으로 다루고 있었습니다 — 링크는 아무것도 실행하지 않습니다. 대신 깃허브에 붙이면 링크 자체가 사라집니다.

📌 30초 요약

• 링크는 폴더를 고르고 프롬프트를 채우기만 합니다. 엔터를 누르기 전엔 모델로 아무것도 안 갑니다.
• 외부 링크에서 온 프롬프트라고 경고선이 뜹니다. 보내거나 지울 때까지 안 사라집니다.
• 1,000자를 넘으면 글자 수까지 알려주고 전문을 스크롤해서 보라고 합니다. 이유가 명확합니다.
• 깃허브는 이 주소 형식을 지워버립니다. README·이슈·PR·위키 전부요.
• 눌러도 아무 일이 없다면 등록이 안 된 것입니다. 설치 명령이 아니라 첫 프롬프트를 보낼 때 등록됩니다.
• 윈도우는 어느 터미널이 열릴지 순서가 고정돼 있습니다.

클릭하면 무슨 일이 일어나나

원리는 메일 주소 링크와 같습니다. 전용 주소 형식을 운영체제에 등록해 두고, 그걸 만나면 해당 프로그램을 띄우는 방식이죠. 순서는 넷입니다 — 브라우저가 주소를 운영체제에 넘기고, 운영체제가 Claude Code를 띄우고, 링크가 지정한 폴더에서 새 터미널이 열리고, 프롬프트가 입력창에 채워집니다. 링크는 어디에 있든 상관없지만 세션은 항상 클릭한 그 컴퓨터에서 열립니다.

# 형태는 이렇습니다 (경로는 하나만 허용)
claude-cli://open?cwd=/절대/경로&prompt=진단해줘

# 사람마다 클론 위치가 다르면 저장소 슬러그로
claude-cli://open?repo=소유자/저장소&prompt=최근 배포 실패 원인 찾아줘

문서가 든 용례가 실용적입니다 — 장애 대응 문서의 한 단계, 모니터링 알림이나 대시보드에서 특정 지표 조사 프롬프트로, README나 위키에서 신입 온보딩 프롬프트로, CI 실패 알림에서 실패한 작업 이름을 미리 채워서.

링크는 아무것도 실행하지 않습니다

"모르는 사람이 만든 링크를 누르면 내 컴퓨터에서 뭐가 도는 거 아닌가" — 당연한 걱정이고, 문서가 먼저 답합니다. 딥링크는 스스로 아무것도 실행하지 않습니다. 하는 일은 폴더를 고르고 입력창을 채우는 것뿐이고, 믿을 수 없는 페이지에서 눌러도 그 프롬프트는 여전히 불활성입니다. 내가 읽고 엔터를 눌러야 비로소 모델에 갑니다.

🔍 1,000자 넘는 프롬프트에는 경고가 하나 더 붙습니다

세션이 열리면 입력창 아래에 "외부 링크에서 온 프롬프트"라는 경고선이 뜨고, 보내거나 지울 때까지 계속 남아 있습니다. 여기에 조건이 하나 더 있는데 — 1,000자를 넘으면 글자 수를 함께 표시하고 "엔터 전에 스크롤해서 전문을 확인하라"고 안내합니다. 이유를 문서가 그대로 적어놨습니다. 긴 프롬프트는 지시를 화면 밖으로 밀어낼 수 있기 때문입니다. 앞부분만 읽고 엔터를 누르면 아래에 뭐가 더 붙어 있는지 모른 채 보내게 되는 거죠. 링크 클릭이 위험한 게 아니라 "다 읽었다고 착각하는 것"이 위험하다는 정확한 진단입니다. 참고로 권한 규칙과 프로젝트 지시, 폴더 신뢰 확인은 평소 세션과 똑같이 적용됩니다.

깃허브에서는 링크가 사라집니다

실무에서 제일 먼저 부딪힐 대목입니다. 링크를 보여주는 쪽이 이 주소 형식을 허용해야 하는데, 깃허브는 안 합니다. 일반 웹 주소만 허용하고 나머지는 지웁니다 — README도, 이슈도, PR도, 위키도요.

결과가 고약합니다. 링크를 걸어두면 글자만 남고 링크는 사라지며, 주소 자체도 안 보입니다. 읽는 사람은 "여기를 클릭"이라는 밋밋한 글자만 보게 되죠. 문서가 제시하는 회피법은 단순합니다 — 코드블록에 넣어서 주소를 보이게 하고, 읽는 사람이 복사해 주소창에 붙여넣게 하는 것입니다. 링크로는 못 만들어도 주소를 감추지는 않게 되는 셈입니다.

눌렀는데 아무 일이 없다면

가장 흔한 원인이 등록이 안 된 것입니다. 그런데 등록 시점이 좀 특이합니다 — 설치 명령이 따로 없고, 대화형 세션에서 첫 프롬프트를 보내는 순간 등록됩니다. 문서가 못을 박는데, 세션을 켰다가 프롬프트 없이 끄면 등록되지 않습니다. 그러니 새 컴퓨터라면 아무거나 한 번 물어보고 나오면 됩니다.

운영체제	등록되는 곳	어느 터미널이 열리나
맥	사용자 응용 프로그램 폴더에 전용 앱	가장 최근에 쓴 터미널을 기억해 재사용
리눅스	사용자 응용 프로그램 디렉터리의 실행 항목	환경변수 지정값 우선, 없으면 시스템 기본값
윈도우	현재 사용자 레지스트리	순서 고정 — 윈도우 터미널, 파워셸, 명령 프롬프트

🪟 윈도우만 선택권이 없습니다

표의 마지막 줄이 국내 독자에게는 제일 실질적입니다. 맥은 내가 마지막에 쓴 터미널을 기억하고, 리눅스는 환경변수로 지정할 수 있는데, 윈도우는 순서가 고정입니다 — 윈도우 터미널이 있으면 그것, 없으면 파워셸, 그것도 없으면 명령 프롬프트. 문서의 해결책도 "윈도우 터미널을 설치하라" 한 줄뿐입니다. 그리고 WSL이나 컨테이너에서는 링크를 여는 도구 자체가 빠져 있는 경우가 흔합니다 — 최소 이미지에는 잘 안 들어가거든요. 패키지를 따로 설치해야 하고, 설치한 뒤에도 데스크톱 환경이 없으면 넘겨줄 곳이 없어 여전히 안 열립니다.

🧾 정직하게 — 이 글의 한계

• 링크를 만들어 눌러보지는 않았습니다. 공식 문서를 정리한 것이라, 경고선이 실제로 어떻게 보이는지·1,000자 안내가 어떤 문구인지는 제가 확인한 게 아닙니다.
• 주소 형식과 파라미터 이름은 원문 표기가 정확합니다. 본문에서는 읽기 쉽게 우리말을 섞었으니, 실제로 만들 때는 문서를 보고 그대로 쓰세요.
• 깃허브 외의 플랫폼은 확인 못 했습니다. 문서가 이름을 든 건 깃허브뿐이라, 다른 위키나 협업 도구가 어떻게 처리하는지는 제가 잰 범위에 없습니다.
• "실행하지 않는다"는 설계상의 보장입니다. 그래도 모르는 출처의 프롬프트는 읽고 지우는 편이 낫다는 게 제 생각입니다.

🗺️ AI 지출 전체 지도

클릭 한 번으로 세션이 열린다는 건 그만큼 쉽게 토큰이 나가기 시작한다는 뜻이기도 합니다. 팀 문서에 링크를 여러 개 심어두면 특히요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 사람마다 클론 위치가 다른데 어떻게 하나요?

절대 경로 대신 저장소 이름으로 지정하면 됩니다. 동작 방식이 재미있는데 — 내가 그 저장소에서 Claude를 실행할 때마다 경로가 기록되고, 링크가 도착하면 가장 최근에 작업한 위치를 엽니다. 여러 클론과 작업방을 따로 추적하고요. 두 가지는 알아두세요 — 한 번도 실행해 본 적 없는 클론은 못 찾아서 홈 폴더가 열리고, 브랜치는 바꾸지 않습니다. 지금 그 폴더가 놓인 상태 그대로 열립니다. 어느 경로가 선택됐는지는 맨 위 인사말에 표시되니 확인하고 시작하시면 됩니다.

Q. 아예 등록되지 않게 막을 수 있나요?

설정 파일에 등록 차단 항목을 넣으면 됩니다. 회사에서 전 직원에게 강제하려면 관리 설정 쪽에 넣어야 하고, 그러면 사용자가 되돌릴 수 없습니다. 등록 위치가 전부 사용자 수준이라는 점도 참고할 만합니다 — 시스템 전역을 건드리지 않으니, 정 불안하면 해당 위치를 직접 지워도 됩니다. 어느 파일에 무엇을 적는지는 설정 파일 지도에 정리해 뒀습니다.

Q. 터미널 말고 편집기에서 열 수는 없나요?

됩니다. 편집기 확장이 자기 주소 형식을 따로 등록해서, 그쪽 주소를 쓰면 터미널 창 대신 편집기 안의 탭으로 열립니다. 팀이 편집기를 통일해 쓴다면 이쪽이 자연스럽겠죠. 참고로 링크를 눌렀는데 아무 반응이 없을 때는 등록 여부부터 보시고, 그래도 안 되면 설정 쪽 문제일 수 있습니다 — 설정이 안 먹힐 때 증상별로 갈라본 글이 도움이 될 겁니다.

🔁 같은 위험을 다른 기능에서도 같은 방식으로 막습니다 (8월 17일 추가)

이 글에서 1,000자를 넘는 프롬프트에는 글자 수를 표시하고 전문을 스크롤해 확인하라고 안내한다는 걸 짚었습니다. 이유는 긴 내용이 지시를 화면 밖으로 밀어낼 수 있어서였죠. 같은 설계가 전혀 다른 기능에서 한 번 더 나옵니다 — 플러그인을 배포할 때 쓰는 명령 문자열에는 인쇄 가능한 문자만, 최대 500자, 공백 네 칸 이상 연속 금지라는 조건이 붙습니다. 문서가 밝힌 이유가 똑같습니다 — "사용자가 수락할 명령 전체를 검토할 수 있도록." 공백을 길게 넣어 뒤쪽 내용을 화면 밖으로 밀어내는 수법을 막는 것이죠. 승인 절차가 형식이 되지 않게 하는 같은 원칙이 두 기능에 나란히 들어가 있습니다. 배포 쪽 규칙은 마켓플레이스를 정리한 글에 있습니다.

✨ 오늘 확인한 것 정리

링크 하나로 그 저장소에서, 그 프롬프트가 채워진 채로 세션이 열립니다. 남이 만든 링크를 눌러도 엔터 전엔 아무것도 실행되지 않고, 외부에서 온 프롬프트라는 경고선이 붙습니다 — 1,000자를 넘으면 "지시가 화면 밖으로 밀릴 수 있다"며 전문 확인을 요구하고요. 다만 깃허브에 붙이면 링크가 사라지니 코드블록에 주소를 넣으세요. 그리고 첫 프롬프트를 보내야 등록됩니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/deep-links. 주소 형식과 파라미터 이름은 원문 표기를 확인하세요.

※ 플랫폼별 처리와 터미널 선택 규칙은 버전·환경에 따라 달라질 수 있습니다.