자동화 및 편의 기능 활용: Hooks & Commands로 Claude Code 업그레이드하기

프롬프트로 "제발 포맷팅 좀 해줘"라고 애원하는 시대는 끝났다. 이제는 시스템 레벨에서 강제할 때다. 이 글에서는 Claude Code를 나만의 강력한 개발 도구로 개조하는 Hooks와 Commands의 활용법을 소개한다.

1. 핵심 철학: "설득하지 말고, 강제하라" (From Hope to Guarantee)

문제: 프롬프트로 "코드 수정 후에는 꼭 포맷팅을 해줘"라고 말해도, 컨텍스트가 길어지거나 모델이 지치면(instruction drift) 지시를 어길 때가 있다. AI는 확률적으로 작동하기 때문이다.
해결: Hooks는 시스템 레벨에서 쉘 명령어를 실행하므로 결정론적(Deterministic)이다. AI의 '의지'와 상관없이 무조건 실행된다. 이것이 바로 "희망(Hope)을 보장(Guarantee)으로 바꾸는 기술"이다.

2. Hooks: 시스템 레벨의 자동화 및 안전장치

Hooks는 특정 이벤트(도구 사용 전/후, 세션 시작 등)에 트리거되는 스크립트다.

A. 주요 이벤트 및 활용 사례

이벤트	실행 시점	주요 활용 사례	비고
PreToolUse	도구 실행 직전	보안 검사, 명령어 수정, 위험한 명령 차단	유일하게 실행을 차단(Block) 가능
PostToolUse	도구 실행 직후	자동 포맷팅(Prettier), 린트(Lint), 테스트 실행	결과값 검증에 유용
UserPromptSubmit	프롬프트 제출 시	동적 컨텍스트 주입(Git 브랜치 정보 등), 스킬 강제 활성화	프롬프트 증강(Augmentation)
SessionStart	세션 시작 시	환경 변수 설정, 가상 환경(venv) 활성화	작업 환경 초기화

B. 필수 Hook 레시피 (복사/붙여넣기용 코드)

1) 보안: `.env` 및 비밀 파일 읽기 원천 차단 (`PreToolUse`)

Claude Code가 실수로 비밀 키를 읽는 것을 시스템적으로 막는다.

설정 예시:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/block-secrets.py" }]
    }]
  }
}

스크립트가 exit code 2를 반환하면 Claude Code는 해당 파일 접근이 불가능하다는 에러를 받고 포기한다.

2) 포맷팅: 코드 수정 후 자동 Prettier 실행 (`PostToolUse`)

AI가 코드를 짤 때 스타일을 신경 쓰지 않게 하여 토큰을 아끼고, 수정 후 기계적으로 정렬한다.

설정 예시:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE_PATH\"" }]
    }]
  }
}

3) 토큰 절약: 테스트 출력 요약 (RTK)

npm test나 cargo test의 출력이 수백 줄에 달하면 토큰이 낭비된다. PreToolUse 훅을 사용하여 명령어를 가로채고, rtk 같은 프록시 도구로 출력을 요약(성공 시 "30 tests passed" 한 줄만 출력)하여 Claude Code에게 전달하면 토큰을 89%까지 절약할 수 있다.

3. Custom Slash Commands: 반복 업무의 '단축키'

자주 사용하는 긴 프롬프트를 /command 형태의 단축어로 저장한다.

A. 구조 및 위치

위치: .claude/commands/ 폴더에 마크다운(my-cmd.md) 파일로 저장
구성: Frontmatter(설정) + Prompt(지시 내용)

B. 강력한 기능들

매개변수 주입 ($ARGUMENTS):
- 예: /fix-issue 123이라고 치면 $ARGUMENTS 자리에 123이 들어간다.
- 활용: "GitHub 이슈 #123 내용을 가져와서 코드 수정해"
인라인 Bash 실행 (!):
- 프롬프트 중간에 !git status를 넣으면, 현재 깃 상태를 실행한 결과값이 프롬프트에 자동으로 박힌다. 동적인 컨텍스트를 제공할 때 강력하다.
- 예: "현재 !git diff 내용을 보고 커밋 메시지를 작성해줘"

C. 추천 커맨드 리스트

/pr: 코드 스타일 정리, 테스트 실행, PR 본문 작성까지 한 번에 수행
/review: "시니어 개발자 페르소나"로 현재 변경 사항의 보안/성능 취약점 점검
/onboard: 프로젝트 구조와 핵심 규칙을 요약해서 CLAUDE.md를 갱신하거나 새 팀원(AI)에게 설명

4. Skills vs Commands: 언제 무엇을 써야 하나?

이 둘은 비슷해 보이지만 사용 주체가 다르다.

구분	Slash Commands (명령어)	Skills (스킬)
호출 주체	사용자가 직접 입력 (`/test`)	Claude Code가 상황에 맞춰 알아서 사용
사용 시점	내가 원할 때, 명시적인 작업	도메인 지식이 필요할 때, 암묵적인 지원
예시	배포하기, PR 생성하기, 리포트 작성	"이 프로젝트의 API 에러 핸들링 규칙", "보안 가이드라인"
전략	자주 쓰는 워크플로우 자동화용	AI에게 가르쳐야 할 배경지식/절차 주입용

Note: 최신 버전에서는 기술적으로 스키마가 통합되었으나, 사용성 측면에서 '명시적 호출(Command)'과 '자동 호출(Skill)'로 구분하는 것이 정신건강에 좋다.

5. 모니터링 및 상태 표시줄 (Status Bar)

터미널 하단에 실시간 정보를 띄워 비용과 상태를 관리한다.

/statusline 명령어: 기본 제공 명령어로 상태 표시줄을 커스터마이징할 수 있다.
외부 도구 (ccusage, claude-dashboard):
- ccusage를 활용하면 현재 세션의 비용($), 남은 토큰 양, 5시간 제한 리셋까지 남은 시간 등을 한 줄로 깔끔하게 볼 수 있다.
- "내가 지금 얼마를 쓰고 있는지" 실시간으로 보여주어 무의식적인 토큰 낭비를 막는 심리적 효과가 크다.

📝 요약 테이블 (Copy & Paste용)

Hooks는 법이다: 프롬프트로 "제발 비밀파일 읽지 마"라고 애원하지 말고, Hook으로 물리적으로 차단하라. (exit code 2)
커맨드로 시간 단축: 매번 치는 긴 프롬프트는 .claude/commands/에 저장하고 /로 호출하라. ($ARGUMENTS 활용)
Bash 출력 다이어트: npm test 같은 시끄러운 명령어는 Hook을 통해 에러 메시지만 필터링해서 보여주면 토큰을 90% 아낄 수 있다.
스킬 vs 커맨드: 내가 시키고 싶으면 커맨드, 알아서 하길 원하면 스킬.
대시보드 장착: /statusline이나 ccusage로 돈 나가는 속도를 눈으로 확인하라.