Claude Code 상세 사용법 30: Deep Link로 런북에서 세션 열기 | DAKER 커뮤니티
Claude Code 상세 사용법 30: Deep Link로 런북에서 세션 열기
Claude Code 공식 deep links 문서는 claude-cli:// URL로 로컬 Claude Code 터미널 세션을 여는 방법을 설명한다. 2026년 6월 5일 기준 deep link는 Claude Code v2.1.91 이상이 필요하고, 링크를 클릭해도 곧바로 실행되지 않는다. 작업 디렉터리와 프롬프트 입력칸만 채우고, 사람이 읽은 뒤 Enter를 눌러야 시작된다.
위 SVG는 Mermaid 기반 URL 구성도를 DAKER 편집기용 이미지로 옮긴 것이다.
1. 링크는 실행 버튼이 아니다
deep link는 claude-cli://open으로 시작한다. q는 입력칸에 넣을 프롬프트, cwd는 절대 경로, repo는 GitHub owner/name 저장소 slug다. cwd와 repo를 같이 주면 cwd가 우선한다.
claude-cli://open?repo=acme/payments&q=review%20open%20PRs링크로 열린 세션에는 외부 링크에서 온 프롬프트라는 경고가 표시된다. 긴 프롬프트는 숨은 지시가 섞일 수 있으므로 전체를 스크롤해 확인해야 한다. permission rule, CLAUDE.md, trust prompt는 일반 세션과 똑같이 적용된다.
2. repo와 cwd를 다르게 쓴다
팀 런북, Slack 알림, 대시보드에는 repo가 보통 낫다. 각자가 다른 위치에 clone해도 Claude Code가 이전에 실행했던 로컬 경로를 찾아 열 수 있기 때문이다. 단, 해당 저장소에서 Claude Code를 한 번도 실행한 적이 없으면 홈 디렉터리로 열릴 수 있다.
표준 devcontainer나 VM처럼 모두 같은 절대 경로를 쓴다면 cwd가 더 예측 가능하다.
claude-cli://open?cwd=/workspaces/payments&q=Check%20failed%20tests3. 프롬프트는 URL encoding 한다
q 값은 URL encoding이 필요하고, 줄바꿈은 %0A로 넣는다. 실무에서는 링크를 손으로 만들기보다 작은 스크립트로 생성한다.
const prompt = `결제 API 배포 실패를 조사해줘.
최근 main 커밋, 실패한 CI job, rollback 필요성을 확인해.`;
const url = `claude-cli://open?repo=acme/payments&q=${encodeURIComponent(prompt)}`;
console.log(url);5,000자 제한을 넘기는 분석 지시는 링크에 넣지 말고 런북 본문에 두는 편이 낫다. 링크에는 “어디서 무엇을 시작할지”만 담는다.
두 번째 Mermaid 기반 흐름도는 장애 대응 런북에서 deep link를 쓰는 순서를 요약한다.
4. 렌더러 제한을 확인한다
GitHub Markdown은 claude-cli:// 같은 custom URL scheme을 clickable link로 유지하지 않을 수 있다. README, issue, wiki에서 링크가 사라지면 code block에 URL을 노출하고 브라우저 주소창에 붙여 넣게 안내한다. macOS에서는 open, Linux에서는 xdg-open, Windows PowerShell에서는 Start-Process로 열 수 있다.
open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"handler가 동작하지 않으면 그 머신에서 interactive claude 세션을 한 번 시작했다가 종료한다. 조직에서 이 기능을 막아야 하면 settings의 disableDeepLinkRegistration을 managed settings로 배포한다.
Senior takeaway: Deep Link는 agentic coding을 “좋은 프롬프트 복붙”에서 “운영 문서의 클릭 가능한 시작점”으로 바꾼다. 다만 실행은 항상 사람의 Enter 뒤에 일어나야 한다. 클로드 코드 런북은 링크보다 검토 문구, 저장소 경계, 권한 모드가 먼저다.
