AX 팁 14 — 프롬프트 낱말로 skill 미리 알리기

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • skill

Claude Code 에서 프롬프트를 보낼 때마다 UserPromptSubmit 훅이 입력 속 낱말을 사전과 대조해서, 맞는 skill 이름 하나를 「먼저 읽을 것」이라는 한 줄로 모델에게 붙여 주면 됩니다. 핵심은 많이 알리지 않는 것입니다. 한 번에 skill 하나만, 그리고 흔한 낱말 하나만으로는 알리지 않는 규칙을 두면 알림이 소음이 되지 않습니다. 이 글은 컴팩트 요약을 이름별 기록으로 남긴 지난 편에 이은 연재 열네 번째 편입니다.

모니터 옆 메모를 보며 도구를 고르는 남성 AI 생성 이미지

왜 skill 이 있는데도 모델이 안 읽을까?

규칙을 skill 파일로 잘 정리해 두어도, 모델은 지금 하는 일에 그 skill 이 필요한지 스스로 알아채지 못할 때가 많습니다. 「쿼리 좀 고쳐 줘」라고만 말했는데 SQL 작성 규칙 파일은 열리지 않은 채 코드가 나오는 식입니다.

처음에는 규칙 본문을 항상 읽히는 파일에 계속 늘렸습니다. 그러자 매 호출마다 읽는 글이 커지고, 정작 지금 필요한 줄은 묻혔습니다. 항상 켜 두는 규칙과, 필요할 때만 꺼내는 규칙을 나누어야 했습니다.

시도: 낱말 사전을 훅에 넣으면 어떻게 될까?

훅은 프롬프트가 모델에 가기 전에 한 번 끼어들 수 있습니다. 거기서 「이 낱말이 있으면 이 skill」이라는 사전을 대보고, 맞으면 추가 문맥으로 한 줄을 붙이게 했습니다.

처음 버전은 맞는 skill 을 최대 3개까지 알렸습니다. 결과는 나빴습니다. 「테이블」이나 「step」처럼 일상적인 낱말에도 알림이 붙어서, 관계없는 규칙을 읽느라 오히려 일이 느려졌습니다.

막힌 점: 흔한 낱말이 알림을 망치는 건 어떻게 막았을까?

두 가지로 줄였습니다. 먼저 알리는 개수 상한을 1로 낮췄습니다. 여러 skill 이 걸리면 낱말이 길고 많이 겹친 쪽 하나만 남깁니다. 다음으로 약한 낱말 목록을 따로 두었습니다. 약한 낱말은 혼자 걸리면 무시하고, 두 개 이상 겹치거나 강한 낱말이 같이 있을 때만 인정합니다.

짧은 영문 낱말은 단어 경계로만 맞춥니다. 그렇지 않으면 job 이 다른 단어 속 글자에 걸립니다. 2026-11-07 기준으로 사전은 skill 19개, 낱말 228개이고, 약한 (skill, 낱말) 짝은 17개, 알림 상한은 1입니다.

바꾼 방법: 코드는 어떻게 생겼을까?

점수 계산의 핵심은 이 몇 줄입니다. 강한 낱말이 하나도 없고 걸린 낱말이 하나뿐이면 건너뜁니다.

strong = [kw for kw in matched if (skill, kw) not in WEAK_TRIGGERS]
if not strong and len(matched) < 2:
    continue
score = sum(len(kw) for kw in matched) + (100 if strong else 0)
scored.append((score, skill))
scored.sort(key=lambda item: -item[0])
top = [skill for _, skill in scored[:MAX_SKILLS]]

처음 시작한다면 아래 정도의 작은 훅으로 충분합니다. 사전만 자기 skill 이름에 맞게 바꾸면 됩니다.

import json, sys
TRIGGERS = {"sql": ["쿼리", "join", "페이징"], "backend": ["controller", "jpa"]}
prompt = json.load(sys.stdin).get("prompt", "").lower()
hits = [s for s, kws in TRIGGERS.items() if any(k in prompt for k in kws)][:1]
if hits:
    msg = f"관련 skill: {hits[0]} — 작업 전에 먼저 읽을 것"
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": msg}}))
else:
    print("{}")

등록은 설정 파일에 훅 이벤트 하나를 추가하면 끝납니다.

{ "hooks": { "UserPromptSubmit": [ { "hooks": [
  { "type": "command", "command": "python3 ~/.claude/hooks/skill-hint.py" }
] } ] } }
프롬프트가 알림이 되기까지프롬프트 입력 (UserPromptSubmit 훅) → 사전과 낱말 대조; 사전과 낱말 대조 → 강한 낱말이 있거나 2개 이상 겹치나?; 강한 낱말이 있거나 2개 이상 겹치나? → 가장 점수 높은 skill 하나 고르기 (예); 강한 낱말이 있거나 2개 이상 겹치나? → 알리지 않고 통과 (아니오); 가장 점수 높은 skill 하나 고르기 → 한 줄 알림을 문맥에 붙이기예아니오프롬프트 입력(UserPromptSubmit훅)사전과 낱말 대조강한 낱말이 있거나 2개이상 겹치나?가장 점수 높은 skill하나 고르기알리지 않고 통과한 줄 알림을 문맥에붙이기
프롬프트가 알림이 되기까지 — 약한 낱말 하나만으로는 알리지 않는다

지금 하루는 어떻게 달라졌을까?

SQL 이나 백엔드 규칙처럼 파일로 나눈 규칙이 필요한 요청이면, 내가 skill 이름을 떠올리지 않아도 모델이 먼저 그 파일을 읽고 시작합니다. 항상 읽히는 파일은 짧게 유지할 수 있게 되었습니다.

규칙을 꺼내 쓰는 방식훅 도입 전: 규칙 본문을 항상 읽는 파일에 계속 추가, 필요한 skill 이름을 내가 직접 말해야 함, 읽는 글이 길어져 핵심이 묻힘 → 훅 도입 후: 필요한 skill 하나만 한 줄로 알림, 항상 읽는 파일은 짧게 유지, 알림이 어긋나면 사전만 고치면 됨훅 도입 전규칙 본문을 항상 읽는파일에 계속 추가필요한 skill 이름을내가 직접 말해야 함읽는 글이 길어져핵심이 묻힘훅 도입 후필요한 skill 하나만한 줄로 알림항상 읽는 파일은 짧게유지알림이 어긋나면사전만 고치면 됨
규칙을 꺼내 쓰는 방식

대가도 있습니다. 낱말 대조라서 뜻은 모릅니다. 「쿼리 줘」가 SQL 규칙이 아니라 단순 데이터 확인 요청일 때도 있어서, 어긋나는 낱말은 약한 목록으로 옮기며 계속 고쳐야 합니다.

자주 묻는 질문

훅이 알려 주면 모델이 그 skill 을 꼭 읽나요?

강제는 아닙니다. 추가 문맥으로 붙는 한 줄 안내라서, 모델이 따를 가능성을 높일 뿐입니다. 중요한 규칙은 훅 알림과 별개로 항상 읽히는 파일에도 한 줄 남겨 두는 편이 안전합니다.

알림 개수를 1보다 늘리면 안 되나요?

늘릴 수는 있지만 제 경우 3개일 때 관계없는 알림이 늘었습니다. 알림 상한은 설정값 하나이니 직접 바꿔 보면서 어긋나는 횟수를 세어 보는 방법을 권합니다.

영어 낱말이 엉뚱한 곳에 걸리면 어떻게 하나요?

짧은 영문 낱말은 앞뒤가 글자가 아닐 때만 맞게 하세요. 파이썬이라면 정규식의 단어 경계(\b)로 감싸면 됩니다.

사이트를 만들어볼까요?

무료 상담 받기