# 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 설치

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

### 3.2 자동 시작 설정

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

```bash
# 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 수동 실행

```bash
# 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
