faq-shortcuts가 반복 프롬프트를 프로젝트별 명령어로 바꾼다

cli-faq-shortcuts는 코딩 에이전트에 반복해서 입력한 요청을 기록에서 찾아 /sent나 /project billing 같은 짧은 명령으로 바꾸는 Agent Skill이다. Claude Code, Codex, Cursor에서 쓸 수 있으며, 기록을 읽어 반복 요청과 횟수를 보여준 뒤 사용자가 고른 요청을 프로젝트별 바로가기로 만든다.

• 한 실제 프로젝트에서는 표현이 달랐던 반복 요청을 의도별로 묶었을 때 가장 많이 나온 요청이 230회 입력됐다. 사용자가 바로가기로 만들 항목을 선택한다.
• 추출기는 기록을 에이전트에 보여주기 전에 API 키, 토큰, 비밀번호 등을 [REDACTED]로 바꾼다.
• 추출기는 표준 라이브러리만 사용하는 Python 스크립트로, 패키지·API 키·네트워크 연결이 필요 없다. 요청을 의도별로 묶는 일은 코딩 에이전트가 한다.

저장소에는 24초 데모 영상 보기 또는 다운로드와 v1.3.0 변경 사항이 있다. 데모는 합성 데이터로 작업 흐름을 보여주며, 실제 에이전트 녹화 영상은 아니다.

설치와 시작

macOS와 Linux에서는 git, Python 3.9 이상이 필요하다. 다음 명령으로 설치한다.

git clone https://github.com/kishormorol/cli-faq-shortcuts ~/.agents/skills/faq-shortcuts
mkdir -p ~/.claude/skills && ln -sfn ~/.agents/skills/faq-shortcuts ~/.claude/skills/faq-shortcuts

프로젝트를 Claude Code, Codex 또는 Cursor에서 새 세션으로 연 다음, “이 프로젝트에서 내가 뭘 계속 요청하지?”라고 묻거나 Claude Code에서 /faq-shortcuts를 입력한다. 반복 요청과 입력 횟수가 표로 나오면 바로가기로 만들 항목을 고른다.

저장소 이름은 cli-faq-shortcuts, 설치되는 스킬 이름은 faq-shortcuts다. Windows 설치 방법은 Windows 안내에 있다.

명령과 바로가기

Claude Code에서는 프로젝트 안에서 다음과 같이 실행할 수 있다.

# inside your project, in Claude Code
/faq-shortcuts # find your repeated asks and propose shortcuts
/faq-shortcuts --since 2026-06-01 # only look at recent history
/faq-shortcuts --source codex # only what you asked Codex

에이전트 없이 추출기만 실행해도 된다. 이 방식에서는 데이터가 컴퓨터 밖으로 나가지 않는다.

# the extractor on its own: no agent, nothing leaves your machine
E=~/.agents/skills/faq-shortcuts/scripts/extract_asks.py
python3 "$E" . # matching prompts, oldest first
python3 "$E" . --since 2026-09-01 | wc -l # how many since September
python3 "$E" . --format jsonl # structured records for your own scripts
python3 "$E" . | awk -F'\t' 'split($3,w," ")>=4 {print tolower($3)}' \
 | sort | uniq -c | sort -rn | head # your most repeated exact requests

마지막 명령은 문구가 정확히 일치하는 요청만 세기 때문에 횟수를 실제보다 적게 잡는다. 한 실제 프로젝트에서 정확히 일치하는 최다 요청은 14회였지만, 표현과 상관없이 의도별로 묶으면 가장 많이 나온 요청은 230회였다. /faq-shortcuts에서 에이전트가 이 묶음 작업을 맡는다.

반복 요청을 짧은 명령으로 바꾸는 예는 다음과 같다.

• “이번 주 가입자가 몇 명이지? 테스트 계정은 빼고”는 /signups가 된다.
• “뉴스레터가 실제로 발송됐나? 모두에게 도착했나?”는 /sent가 된다.
• “결제 시스템 이전은 어떻게 됐지? 막힌 부분은?”은 /project billing이 된다.
• “신규 고객 CSV를 추가하되 이미 있는 고객은 건너뛰어”는 /import new.csv가 된다.

각 바로가기는 프로젝트의 .claude/skills/<name>/SKILL.md에 저장되는 작은 파일이다. 예를 들어 /sent는 기존 이메일 상태 확인 스크립트를 가리키고, 발송만 요청하는 바로가기가 아니라 보고만 하며 재발송하지 말라고 명시할 수 있다. 바로가기는 프로젝트에서 이미 쓰는 스크립트와 쿼리를 연결하고, 해당 작업에서 이미 발생한 실수도 기록한다. 예시에서는 에이전트가 앞서 “보냈다”고 한 메시지를 믿는 대신 발송 기록을 확인하며, 공유 받은편지함에 ‘전달됨’으로 표시돼도 누군가 읽었다는 뜻은 아니라고 주의를 준다. 쓰기나 발송을 수행하는 작업은 먼저 미리보기를 보여주고 사용자의 승인을 기다린다.

작동 방식과 지원 범위

스킬은 프로젝트의 Claude Code와 Codex 기록에서 사용자가 직접 입력한 프롬프트를 모은다. 하위 에이전트 대화와 스크립트 실행은 사용자가 직접 입력한 것이 아니므로 제외한다. 에이전트는 표현이 다른 요청을 의도별로 묶고 횟수를 센 다음, 이미 존재하는 바로가기와 프로젝트의 도구를 살핀다. 이어 바로가기, 대체할 요청, 요청 횟수를 표로 제안하고 사용자가 고른 항목을 .claude/skills/에 SKILL.md로 만든다. 파일은 .agents/skills/에 연결되어 세 에이전트가 불러올 수 있고, 팀도 사용할 수 있도록 저장소에 커밋된다. 마지막으로 각 바로가기와 이를 대체하는 문장을 CLAUDE.md 또는 AGENTS.md의 표에 기록한다.

Codex는 ~/.agents/skills/에서 스킬을 읽고, Claude Code는 연결된 ~/.claude/skills/에서 읽는다. Cursor는 두 위치를 모두 읽는다. 업데이트하려면 다음 명령을 실행한 뒤 새 에이전트 세션을 시작한다.

git -C ~/.agents/skills/faq-shortcuts pull --ff-only

삭제할 때는 다음 명령을 사용한다.

rm ~/.claude/skills/faq-shortcuts && rm -rf ~/.agents/skills/faq-shortcuts

Claude Code만 쓰는 경우에는 플러그인으로 설치할 수도 있다.

/plugin marketplace add kishormorol/cli-faq-shortcuts /plugin install faq-shortcuts@cli-faq-shortcuts

이 경우 명령은 /faq-shortcuts:faq-shortcuts이며, “이 프로젝트에서 내가 뭘 계속 요청하지?”라고 물어도 된다. Codex와 Cursor는 Claude Code 플러그인을 읽지 않으므로 빠른 설치 방법을 사용해야 한다.

Windows에서는 git과 Python 3.9 이상을 설치한 뒤 PowerShell에서 다음 명령을 실행한다. 심볼릭 링크 대신 디렉터리 연결(junction)을 만들어 관리자 권한이나 Developer Mode가 필요하지 않다.

git clone https://github.com/kishormorol/cli-faq-shortcuts "$env:USERPROFILE\.agents\skills\faq-shortcuts"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\faq-shortcuts" -Target "$env:USERPROFILE\.agents\skills\faq-shortcuts"

추출기는 python3가 아니라 python 또는 py로 실행한다.

python "$env:USERPROFILE\.agents\skills\faq-shortcuts\scripts\extract_asks.py" . | Select-Object -First 10

업데이트 명령은 다음과 같다. 실행한 뒤 새 세션을 시작한다.

git -C "$env:USERPROFILE\.agents\skills\faq-shortcuts" pull --ff-only

삭제할 때는 rmdir로 연결을 지운다. 이 명령은 연결 대상 폴더를 삭제하지 않는다. 그다음 복제본을 제거한다.

cmd /c rmdir "$env:USERPROFILE\.claude\skills\faq-shortcuts"
Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\faq-shortcuts"

읽는 기록과 추출기 옵션

• Claude Code는 최근 30일 기록인 ~/.claude/projects/<project>/*.jsonl과 이전 프롬프트가 담긴 ~/.claude/history.jsonl을 읽는다.
• Codex는 세션이 실행된 폴더를 기준으로 일치하는 ~/.codex/sessions/ 기록을 읽는다. 대체 경로로 $CODEX_HOME을 사용할 수 있다.
• Cursor는 macOS의 ~/Library/Application Support, Windows의 %APPDATA%, Linux의 ~/.config 아래에 있는 Cursor/User/globalStorage/state.vscdb를 읽는다. 채팅이 실행된 폴더를 기준으로 일치시킨다. 작업 폴더를 열지 않은 채팅은 제외된다.

에이전트 없이 추출 결과를 확인할 수 있다.

python3 ~/.agents/skills/faq-shortcuts/scripts/extract_asks.py ~/my-project | head

출력은 date<TAB>source<TAB>prompt 형식이다. --source claude, --source codex, --source cursor로 한 도구의 기록만 읽고, --since 2026-01-01로 그 날짜보다 오래된 프롬프트를 제외할 수 있다. 전체 옵션은 다음과 같다.

python scripts/extract_asks.py [project_dir] [--source all|claude|codex|cursor]                               [--since YYYY-MM-DD] [--max-len N] [--min-words N]                               [--format tsv|jsonl] [--no-redact]

• project_dir는 기본적으로 현재 디렉터리다. 기록에 저장된 프로젝트 폴더와 정확히 일치하는 항목을 찾는다.
• --source의 기본값은 all이다. 지원 도구 하나 또는 세 도구 모두의 기록을 읽는다.
• --since는 기본적으로 날짜 제한이 없다. 지정한 UTC 날짜와 그 이후를 포함하며 날짜를 알 수 없는 프롬프트는 제외한다.
• --max-len의 기본값은 400이다. 공백 정리 전에 이 양의 문자 수보다 긴 프롬프트를 건너뛴다.
• --min-words의 기본값은 1이다. 지정한 단어 수보다 짧은 프롬프트를 제외한다. 3으로 설정하면 “ok”, “yes”, “push” 같은 답을 건너뛰며 스킬은 이 설정을 사용한다.
• --no-redact는 기본적으로 꺼져 있다. 이 옵션을 쓰면 붙여 넣은 비밀정보를 입력한 그대로 출력한다.
• --format의 기본값은 tsv다. 탭으로 구분한 줄 또는 줄마다 JSON 객체 하나를 출력한다.

JSONL 기록에는 date, source, prompt 필드가 있다. 두 출력 형식 모두 프롬프트 안의 연속된 공백을 하나로 합친다. 날짜는 YYYY-MM-DD이며 알 수 없으면 빈 문자열이다. 날짜가 없는 기록은 정렬할 때 앞에 온다. 집계와 진단 메시지는 표준 오류(stderr)로 출력하므로 표준 출력(stdout)을 파이프라인에 사용할 수 있다. 반환 코드는 기록 소스가 사용 가능하면(필터에 맞는 결과가 없어도) 0, 사용할 수 있는 소스가 없으면 1, 잘못된 인수가 있으면 2다.

한계와 문제 해결

이 도구가 보여주는 것은 컴퓨터에 아직 남아 있는 기록이며 완전한 활동 로그가 아니다. 400자를 넘는 프롬프트, 주입된 문맥, 비대화형 실행은 기본적으로 제외된다. 보통 더 긴 요청을 입력한다면 --max-len을 높인다. 프로젝트는 폴더 경로로 일치시키며 하위 폴더와 다른 작업 트리를 재귀적으로 포함하지 않는다. 프로젝트를 옮겨도 이전 기록에 저장된 경로는 바뀌지 않는다. Cursor의 저장 형식은 문서화되지 않아 바뀔 수 있고, 작업 공간이나 저장소가 기록되지 않은 채팅은 프로젝트에 연결할 수 없다. 형식이 잘못된 기록은 건너뛰며, 유효하지 않은 타임스탬프는 날짜 미상으로 처리한다.

문제가 생기면 다음을 확인한다.

• 에이전트가 /faq-shortcuts를 모르면 새 세션을 시작한다. 스킬은 세션 시작 때 불러온다. ls ~/.claude/skills/faq-shortcuts/SKILL.md로 파일이 있는지 확인한다.
• checked, nothing for this folder (…)가 나오면 실제 작업했던 프로젝트 폴더에서 실행한다. 기록은 폴더별로 저장되므로 하위 폴더는 다른 프로젝트로 취급된다.
• Claude Code가 python3 …extract_asks.py 실행을 허용할지 묻는다면 허용한다. 스크립트는 ~/.claude(그리고 Codex, Cursor)의 기록을 읽고 네트워크 연결을 하지 않는다. 헤드리스 실행(claude -p)에서는 이 질문에 답할 수 없으므로 --add-dir ~/.claude --allowedTools "Bash(python3:*)"를 전달한다.
• 프롬프트가 너무 적게 나오면 실제로 작업했던 프로젝트 폴더에서 실행했는지 확인한다. 폴더를 열지 않은 Cursor 채팅은 프로젝트에 연결되지 않아 건너뛴다.
• fatal: destination path … already exists가 나오면 이미 설치된 것이다. 업데이트 명령을 실행한다.
• --since 뒤에 결과가 없으면 날짜와 프로젝트 폴더를 확인한다. 일치하는 프롬프트가 없는 것은 성공적인 빈 결과이므로 날짜 옵션 없이 다시 시도할 수 있다.
• could not read session history가 나오면 파일 권한을 확인하고 다른 도구를 지정하는 --source 옵션을 시도한다. 사용 가능한 다른 소스에서는 결과가 나올 수 있다.
• 기억하는 요청이 빠졌다면 긴 프롬프트가 기본적으로 제외됐을 수 있으므로 --max-len 2000을 시도한다.

개인정보와 안전

추출기는 로컬 파일만 읽고 네트워크 연결을 하지 않는다. 출력 전에 Anthropic, OpenAI, GitHub, Slack, AWS, Google, Hugging Face, Stripe, Resend, Supabase, Kaggle의 API 키와 JWT, bearer 토큰, password= 형식의 값, postgresql://user:pass@host 같은 URL 속 비밀번호, Discord·Slack 웹훅, 대소문자와 숫자가 섞인 30자 이상의 일반 토큰을 [REDACTED]로 바꾼다. 패턴으로 탐지하므로 완벽한 보장이 아니라 안전망으로 봐야 한다. 프롬프트에는 이름과 이메일이 남아 있을 수도 있다. 스킬은 목록을 저장소가 아닌 임시 폴더에 기록하고, 에이전트는 사용자가 보여준 다른 파일과 같은 방식으로 그 목록을 읽는다.

에이전트는 프롬프트를 설정된 모델 제공업체로 보낼 수 있다. 민감한 기록을 쓰기 전에 에이전트 설정을 확인해야 한다. 원본 기록, 추출 결과 또는 Cursor 데이터베이스를 공개 이슈에 첨부하지 말고, 버그 재현에는 지어낸 프롬프트를 사용한다. 생성된 바로가기는 커밋하기 전에 검토해야 한다.

기여와 변경 사항은 기여 안내와 변경 기록에서 확인할 수 있다. Windows 설치와 추출은 Linux, macOS와 함께 CI에서 다룬다. 라이선스는 Apache-2.0이다.