Claude Code Prompt Improver 소개
Claude Code Prompt Improver는 Anthropic의 Claude Code 환경에서 사용자의 모호한 요청(User Prompt)을 명확하게 만들어주는 Claude Code의 훅(hook) 기반 도구입니다. 사용자가 Claude Code에 불명확한 요청을 할 때, Claude Code는 이러한 요청을 이해하기 위해 추가적인 토큰을 소비하거나 잘못된 방향으로 동작하는 경우들이 있습니다. 이 프로젝트는 이렇게 사용자의 불분명하거나 애매한 명령을 자동으로 분석하고, 필요한 경우 추가적인 질문을 통해 명확한 요청으로 개선하는 것을 목표로 합니다.
즉, 개발자가 “버그를 고쳐줘” 같은 추상적인 요청을 하더라도 Claude가 자동으로 “어떤 버그를 의미하나요?”와 같은 구체적인 질문을 되묻고, 이후 명확한 문맥을 바탕으로 작업을 수행하도록 도와줍니다.
특히, Claude Code Prompt Improver의 주요한 특징은 자동 개입의 빈도와 투명성에 있습니다. Claude Code Prompt Improver는 다음과 같은 원칙을 따릅니다:
- “사용자 의도를 신뢰하라” - 가능한 한 개입하지 않음
- “필요할 때만 질문하라” - 불분명한 경우에만 질문 수행
- “대화 맥락을 존중하라” - 이전 대화 내역을 반영해 중복 질문 방지
Claude Code Prompt Improver는 Claude Code 2.0.22 이상 버전에서 사용 가능한 AskUserQuestion 도구를 활용하며, 사용자 입력을 Anthropic에 전달하기 전에 사전 평가를 수행하는 방식으로 동작합니다. 이렇게 하면 사용자는 여러 번의 질문과 답변을 주고받는 과정을 줄이고, 처음부터 정확한 결과를 얻을 수 있습니다.
이 프로젝트가 중요한 이유는 명확하지 않은 요청이 Claude의 코드 이해력과 응답 품질에 큰 영향을 미친다는 점에 있습니다. 일반적으로 코드 AI는 요청이 불분명할 경우, 불완전한 추론을 수행하거나 잘못된 방향으로 작업을 진행하기 쉽습니다. Claude Code Prompt Improver는 이러한 문제를 자동으로 완화함으로써 생산성 향상과 품질 안정성을 모두 달성할 수 있도록 설계되었습니다.
Claude Code의 훅(Hook) 기능 소개
Claude Code Hook은 Claude Code가 제공하는 기능 중 하나로, Claude Code 실행 흐름 중 특정 시점에 자동으로 실행되는 사용자 정의 쉘 명령(command) 입니다. 즉, 단순히 LLM의 추론 결과에 의존하지 않고, 사용자가 직접 정한 규칙과 동작을 시스템 수준에서 강제할 수 있는 기능입니다.
훅(Hook)은 Claude Code의 “자동화된 트리거”처럼 작동하여, 특정 이벤트가 발생했을 때 정해진 스크립트나 명령이 항상 실행되도록 보장합니다. 이 덕분에 Claude Code의 동작을 더 일관적이고 예측 가능하게 제어할 수 있습니다.
예를 들어, 아래와 같은 상황에서 Hook을 활용할 수 있습니다:
- Claude가 코드를 실행하려 할 때마다 특정 포맷터(prettier, gofmt)를 자동 실행
- Claude가 파일을 수정할 때마다 변경 내용을 로깅
- 민감한 디렉터리(예:
prod/,.env) 파일 수정 방지 - Claude가 사용자 입력을 기다릴 때 데스크톱 알림 전송
이러한 훅(Hook)은 특정한 상황에서 자동적으로 실행(trigger)됩니다. Claude Code가 제공하는 훅 이벤트는 다음과 같습니다:
| Hook 이벤트 | 실행 시점 | 설명 |
|---|---|---|
| PreToolUse | Claude가 어떤 도구(예: Bash, Edit, Search)를 사용하기 전에 | 실행을 차단하거나 수정할 수 있음 |
| PostToolUse | Claude가 도구 실행을 마친 후 | 후처리(포맷팅, 로그 작성 등)에 활용 |
| UserPromptSubmit | 사용자가 프롬프트를 입력했을 때 | 프롬프트를 가공하거나 평가 가능 |
| Notification | Claude가 알림을 보낼 때 | 데스크톱 알림, 메시징 연동 등 |
| Stop | Claude의 응답이 완료될 때 | 세션 종료 처리 등 |
| SubagentStop | Claude의 하위 작업(subagent)이 끝났을 때 | 병렬 작업 모니터링용 |
| PreCompact | Claude가 세션 데이터를 정리하기 전 | 캐시 백업 등에 사용 가능 |
| SessionStart / SessionEnd | 세션이 시작되거나 종료될 때 | 초기화, 리소스 해제 등의 자동화에 활용 |
Claude Code Prompt Improver의 설계 철학 및 내부 구조
Claude Code Prompt Improver는 다음의 다섯 가지 원칙에 따라 설계되었습니다:
- 최소 개입 – 대부분의 명령은 그대로 통과시킴
- 사용자 의도 신뢰 – 모호할 때만 질문 수행
- 대화 맥락 활용 – 동일한 질문을 반복하지 않음
- 최대 6개 질문 제한 – 복잡한 경우에도 간결하게
- 투명한 작동 – Claude Code의 판단 과정을 대화 내에서 표시
이로 인해 Claude Code는 더욱 인간적인 인터랙션을 제공하며, 대화형 개발 환경에서 신뢰할 수 있는 파트너처럼 동작하게 됩니다.
\
sequenceDiagram
participant User
participant Hook
participant Claude
participant Project
User->>Hook: "fix the bug"
Hook->>Claude: Wrapped with evaluation instructions (~300 tokens)
Claude->>Claude: Evaluate using conversation history
alt Vague prompt
Claude->>Claude: Create research plan (TodoWrite)
Claude->>Project: Execute research (codebase, web, docs)
Project-->>Claude: Context
Claude->>User: Ask grounded questions (1-6)
User->>Claude: Answer
Claude->>Claude: Execute original request with answers
else Clear prompt
Claude->>Claude: Proceed immediately
end
Claude Code Prompt Improver는 내부적으로 Claude Code의 훅(Hook) 기능을 사용합니다. 즉, “Claude Code가 사용자의 프롬프트를 바로 실행하기 전에 한 번 점검하고 정리해주는 자동 통역관” 역할을 합니다.
Claude Code Prompt Improver는 다음과 같이 두 부분으로 나뉘어 실행됩니다:
-
훅(Hook )(
improve-prompt.py): 이 부분은 사용자 입력을 가로채어 판단 및 가공하는 프리필터입니다. 즉, 사용자가 Claude Code에 명령을 입력하게 되면, UserPromptSubmit 이벤트가 발생하며improve-prompt.py파일이 실행됩니다.improve-prompt.py파일은 다음과 같이 동작합니다:- stdin/stdout을 통한 JSON 통신 으로 Claude Code와 데이터를 주고 받습니다.
- 사용자가 입력한 프롬프트에
*,/,#등과 같은 특정 접두어(Prefix)가 붙은 명령은 즉시 통과시킵니다. 이 때,/는/help등과 같은 슬래시 명령어로 사용되기 때문이며,#은 노트 또는 메모리에 저장하기 위해 사용하기 때문입니다. 그 외*이 붙어있으면 평가를 건너뜁니다. - 그 외 명령은 약 300토큰 정도의, '이 명령이 불분명하면 먼저 질문을 해라' 라는 지시를 포함한 메타 프롬프트로 구성된 “평가 지침(evaluation instructions)”을 추가로 감싸 Claude Code에 전달합니다.
-
Main Claude Code Session: Claude Code 본체가 실제 코드 분석 및 실행을 수행하는 세션입니다. 여기에서는 이전 단계에서 개선한 프롬프트를 처리합니다. 핵심 포인트는 “대화 맥락(conversation history)”을 사용해 판단한다는 것입니다.
이 과정은 아래와 같이 동작합니다:┌──────────────────────────────────────────┐ │ Claude Main Session Workflow │ ├──────────────────────────────────────────┤ │ 1. Evaluate clarity using conversation │ │ → 이전 대화 기록을 참고하여 명확도 판단 │ │ │ │ 2. If vague → Create Research Plan │ │ → "TodoWrite" 형태로 조사 계획 수립 │ │ │ │ 3. Execute Research │ │ → 코드베이스, 문서, 웹 검색 등 수행 │ │ │ │ 4. Ask Clarifying Questions (1~6개) │ │ → AskUserQuestion 도구로 사용자 질의 │ │ │ │ 5. Execute Original Request │ │ → 명확해진 정보로 최종 요청 수행 │ └──────────────────────────────────────────┘
Claude Code Prompt Improver 설치 및 설정
Claude Code Prompt Improver를 사용하기 위해서는 Claude Code 버전 2.0.22 이상이 설치되어 있어야 합니다. 또한, AskUserQuestion 도구가 활성화되어 있어야 합니다.
현재 Claude Code의 플러그인 훅(UserPromptSubmit) 시스템에는 실행 버그가 존재하기 때문에, 아래와 같은 방식으로 Claude Code Prompt Improver의 설치 및 설정 과정이 필요합니다.
-
GitHub 저장소로부터 훅(Hook) 파일을 복사합니다:
cp scripts/improve-prompt.py ~/.claude/hooks/ chmod +x ~/.claude/hooks/improve-prompt.py -
Claude Code의 설정 파일(
~/.claude/settings.json)을 열고, 아래와 같이 사용자 프롬프트 입력 시 훅이 동작하도록 내용을 추가합니다:{ "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "python3 ~/.claude/hooks/improve-prompt.py" } ] } ] } }
위와 같이 설정하고, 실행 중인 Claude Code가 존재한다면 재실행한 뒤부터는 Claude Code에 사용자 프롬프트가 입력될 때마다 해당 훅이 자동으로 프롬프트를 검사하고, 필요 시 개선 과정을 거칩니다.
Claude Code Prompt Improver 사용 예시
다음은 일반적인 사용 예시입니다. 예를 들어, 다음과 같이 Claude Code에 명령을 실행했다고 가정해보면,
claude "fix the bug"
claude "add tests"
위와 같은 프롬프트를 서버로 전달하기 전, Claude Code Prompt Improver는 내부적으로 “이 프롬프트가 명확한가?”를 평가하고, 필요할 경우 이를 더 개선하기 위해 사용자에게 추가적인 질문을 생성합니다.
예를 들어, 사용자가 "fix the error"와 같은 질문을 했다면 다음과 같이 되묻습니다:
어떤 오류를 수정해야 하나요?
○ src/components/Map.tsx의 TypeError (최근 변경 사항)
○ src/services/osmService.ts의 API timeout
○ 기타 (오류 메시지 입력)
사용자가 위 선택지 중 하나를 선택하면 Claude Code는 이를 반영하여 코드를 수정하도록 요청합니다.
만약, 사용자가 아래와 같은 방식으로 명확한 프롬프트를 입력했다면,
$ claude "Fix TypeError in src/components/Map.tsx line 127 where mapboxgl.Map constructor is missing container option"
Claude Code Prompt Improver는 추가 질문 없이 바로 작업을 진행합니다.
라이선스
Claude Code Prompt Improver 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다. 상업적 사용, 수정, 재배포 모두 허용됩니다.
Claude Code Prompt Improver 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 