SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
542ba40fa37a73a92560ac986acc2b75da4d2c90
sam-docs/dev/guides/sam-hotkey-manager.md
김보곤 8323cb41a6 docs: [guides] SAM Hotkey Manager 기술문서 추가 
- AutoHotkey v2 기반 Claude Code CLI 프롬프트 단축키 도구
- 설치, 키 바인딩, 편집기 GUI, 자동 시작, 향후 개선 방향 포함
2026-03-18 14:13:09 +09:00

7.6 KiB
Raw Blame History

SAM Hotkey Manager — Claude Code CLI 프롬프트 단축키

작성일: 2026-03-18 상태: 운영 중 버전: v1.1 요구사항: AutoHotkey v2.0+, Windows (WSL 환경에서 Windows 측 실행)

1. 개요

1.1 목적

Claude Code CLI에서 반복적으로 입력하는 프롬프트(트리거 워드, 작업 요청)를 단축키로 빠르게 입력하는 자동화 도구.

1.2 해결하는 문제

  • 매번 동일한 프롬프트를 수동 타이핑하는 비효율
  • 오타로 인한 트리거 워드 미인식
  • 자주 쓰는 프롬프트를 기억해야 하는 인지 부담

1.3 핵심 동작

단축키 입력 → 기존 CLI 입력 지우기(Ctrl+U) → 프롬프트 붙여넣기(Ctrl+V) → 사용자가 Enter

2. 파일 구조

sam/hotkey/
├── sam-hotkey.ahk    ← AHK v2 메인 스크립트 (단축키 + GUI 편집기)
└── prompts.cfg       ← 프롬프트 설정 파일 (UTF-8, 슬롯번호=프롬프트)

3. 설치

3.1 AutoHotkey v2 설치

# WSL에서 winget으로 설치
winget.exe install AutoHotkey.AutoHotkey --accept-package-agreements

3.2 자동 시작 설정

~/.bashrc에 다음이 등록되어 있다. 터미널(Claude Code) 시작 시 AHK가 자동 실행되며, 이미 실행 중이면 건너뛴다:

# SAM Hotkey Manager 자동 시작 (이미 실행 중이면 건너뜀)
if ! tasklist.exe 2>/dev/null | grep -qi "AutoHotkey"; then
    powershell.exe -Command "Start-Process '\\\\wsl.localhost\\Ubuntu\\home\\aweso\\sam\\hotkey\\sam-hotkey.ahk'" &>/dev/null 2>&1 &
fi

3.3 수동 실행

# WSL에서 실행
powershell.exe -Command "Start-Process '\\\\wsl.localhost\\Ubuntu\\home\\aweso\\sam\\hotkey\\sam-hotkey.ahk'"

또는 Windows 탐색기에서 \\wsl.localhost\Ubuntu\home\aweso\sam\hotkey\sam-hotkey.ahk 더블클릭.

4. 단축키 바인딩

4.1 키 조합 설계 원칙

순위 조합 용도 선정 이유
1순위 CapsLock + 숫자 자주 사용 (슬롯 1~10) 충돌 최소, 누르기 편함
2순위 Ctrl+Shift + 숫자 보조 (슬롯 11~20) IDE/터미널 충돌 적음

CapsLock은 modifier로 전환되어 단독으로는 동작하지 않는다. 대소문자 전환은 Shift+CapsLock으로 대체.

4.2 전체 단축키 목록

단축키 동작
CapsLock + 1~9, 0 슬롯 1~10 프롬프트 입력 (Enter 안 침)
CapsLock + Shift + 1~9, 0 슬롯 1~10 프롬프트 입력 + Enter 자동 전송
Ctrl+Shift + 1~9, 0 슬롯 11~20 프롬프트 입력 (Enter 안 침)
CapsLock + F12 편집기 GUI 열기
Ctrl+Shift + F12 단축키 일시 중지/재개 토글
Shift + CapsLock 원래 CapsLock 대소문자 전환

4.3 입력 동작 상세

  1. Ctrl+U 전송 → 현재 CLI 입력 줄 전체 삭제
  2. 클립보드 백업 → 프롬프트를 클립보드에 복사
  3. Ctrl+V 전송 → 프롬프트 붙여넣기
  4. 클립보드 원래 내용으로 복원
  5. 피드백 툴팁 표시 (2초 후 자동 사라짐)

기본 동작은 Enter를 치지 않는다. 사용자가 내용을 확인/수정 후 직접 Enter를 누른다.

5. 기본 프롬프트 구성

5.1 슬롯 1~10 (CapsLock + 숫자, 자주 사용)

슬롯 단축키 프롬프트 용도
1 CapsLock+1 sam/docs 문서 추가하고, 개발서버 푸시 문서+배포
2 CapsLock+2 운영서버 푸시 운영 배포 트리거
3 CapsLock+3 변경사항 확인하고 커밋해줘 커밋 요청
4 CapsLock+4 이관 이관 워크플로우 트리거
5 CapsLock+5 sam설명 프로젝트 컨텍스트 로드
6 CapsLock+6 방금 작성한 코드 리뷰해줘 코드 리뷰
7 CapsLock+7 이 코드에서 버그 찾아줘 버그 탐지
8 CapsLock+8 이 코드 리팩토링해줘 리팩토링
9 CapsLock+9 테스트 실행해줘 테스트
10 CapsLock+0 개발서버 로그 확인해줘 서버 진단

5.2 슬롯 11~20 (Ctrl+Shift + 숫자, 보조)

슬롯 단축키 프롬프트
11 Ctrl+Shift+1 보안 취약점 점검해줘
12 Ctrl+Shift+2 성능 최적화 포인트 찾아줘
13 Ctrl+Shift+3 코드 품질 검사해줘
14 Ctrl+Shift+4 마이그레이션 실행해줘
15 Ctrl+Shift+5 캐시 클리어해줘
16 Ctrl+Shift+6 이 기능 문서 작성해줘
17 Ctrl+Shift+7 이관 현황 확인
18 Ctrl+Shift+8 API 엔드포인트 목록 보여줘
19 Ctrl+Shift+9 코드 흐름 분석해줘
20 Ctrl+Shift+0 변경 이력 문서 작성해줘

6. 설정 파일 형식

prompts.cfg는 UTF-8 텍스트 파일이며, 슬롯번호=프롬프트 형식이다:

; 주석은 세미콜론으로 시작
1=개발서버 푸시
2=운영서버 푸시
3=변경사항 확인하고 커밋해줘
  • 슬롯 번호: 1~20 (정수)
  • ; 또는 #으로 시작하는 줄은 주석
  • 빈 줄은 무시
  • GUI 편집기에서 수정하면 자동 저장

7. 편집기 GUI

CapsLock+F12로 열리는 GUI 편집기 기능:

  • 20개 슬롯을 ListView로 표시 (슬롯 번호, 단축키, 프롬프트)
  • 행 클릭 → 하단 편집창에 프롬프트 로드
  • "저장" 버튼 → 해당 슬롯 수정 + 파일 즉시 저장
  • "모두 파일 저장" → 전체 설정을 prompts.cfg에 기록
  • "파일에서 다시 로드" → prompts.cfg를 다시 읽어 반영
  • Escape 또는 "닫기" 버튼으로 종료

8. 트레이 아이콘 메뉴

시스템 트레이에서 우클릭하면 다음 메뉴가 표시된다:

  • 편집기 열기 (CapsLock+F12)
  • 프롬프트 다시 로드
  • 일시 중지 (Ctrl+Shift+F12)
  • 종료

9. 기술 구현 상세

9.1 CapsLock modifier 전환

AHK v2의 & (커스텀 조합) 문법을 사용하여 CapsLock을 modifier 키로 전환한다. CapsLock 단독 입력은 무시되며, Shift+CapsLock으로 원래 대소문자 전환 기능을 유지한다.

9.2 한글 입력 처리

SendInput은 한글 입력이 불안정하므로, 클립보드 방식(Ctrl+V)을 사용한다:

클립보드 백업 → 프롬프트 복사 → ClipWait → Ctrl+V → 클립보드 복원

9.3 CLI 입력 줄 삭제

Claude Code CLI(터미널 기반)에서는 Ctrl+U가 현재 줄 전체를 삭제한다. Ctrl+A(전체 선택)나 Home+Shift+End는 동작하지 않는다.

9.4 중복 실행 방지

  • AHK 스크립트: #SingleInstance Force (재실행 시 기존 인스턴스 대체)
  • .bashrc: tasklist.exe로 프로세스 존재 여부 확인 후 조건부 실행

10. 향후 개선 방향

항목 설명 우선순위
프롬프트 검색 CapsLock+Space로 프롬프트 검색/필터 UI 열기 중
컨텍스트 감지 현재 작업 디렉토리에 따라 프롬프트 세트 자동 전환 중
프로필 지원 프로젝트별 prompts.cfg 분리 (api, mng, react) 하
히스토리 최근 사용한 프롬프트 기록 + 빈도 기반 재정렬 하
멀티라인 여러 줄 프롬프트 지원 (설정 파일에 \n 이스케이프) 하
변수 치환 프롬프트에 {date}, {branch} 등 동적 변수 삽입 하
Windows 시작프로그램 .bashrc 대신 Windows 시작 폴더에 바로가기 등록 하

관련 문서

  • CLAUDE.md 트리거 워드: 개발서버 푸시, 운영서버 푸시, 이관, sam설명

최종 업데이트: 2026-03-18