docs: [guides] SAM Hotkey Manager 기술문서 추가

- AutoHotkey v2 기반 Claude Code CLI 프롬프트 단축키 도구 - 설치, 키 바인딩, 편집기 GUI, 자동 시작, 향후 개선 방향 포함
2026-03-18 14:13:09 +09:00
parent f49db028eb
commit 8323cb41a6
2 changed files with 227 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -223,6 +223,7 @@ DB 도메인별:
 | [claude-code-btw-guide.md](dev/guides/claude-code-btw-guide.md) | Claude Code /btw 사이드 질문 기능 가이드 |
 | [tenant-email-integration-guide.md](dev/guides/tenant-email-integration-guide.md) | 테넌트 이메일 연동 (SMTP 프리셋, MNG 관리 화면, 연결 테스트) |
 | [performance-report-excel-export.md](dev/guides/performance-report-excel-export.md) | 실적신고 확정건 엑셀 Export (건기원 양식, PhpSpreadsheet, 셀 병합) |
+| [sam-hotkey-manager.md](dev/guides/sam-hotkey-manager.md) | SAM Hotkey Manager — Claude Code CLI 프롬프트 단축키 자동화 (AHK v2) |

 ---

--- a/dev/guides/sam-hotkey-manager.md
+++ b/dev/guides/sam-hotkey-manager.md
@@ -0,0 +1,226 @@
+# 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