Claude Code Hooks vs Agent 차이점 – 자동 경비 시스템과 전문가 호출 뭐가 다를까

저도 처음엔 헷갈렸어요

Claude Code를 쓰다 보면 이런 용어들이 나와요.

Agents, Skills, Hooks, Rules…

“이거 다 뭐가 다른 거야?”

저도 똑같은 의문을 가졌어요. 특히 Hooks랑 Agent가 제일 헷갈리더라고요.

둘 다 뭔가 자동으로 실행되는 것 같은데… 뭐가 다른 걸까?

오늘은 이 두 개념의 결정적인 차이를 실제 설정 예시와 함께 설명해볼게요.

2026년 1월 현재, Claude Code는 2025년 2월 출시 이후 약 1년이 지났고, Hooks와 Subagents 기능은 2025년 7월에 추가되었어요.

---

🎯 이 글에서 다룰 내용

핵심 질문: Claude Code에서 Hooks와 Agent는 언제 쓰는 게 맞을까?

• Hooks vs Agent 핵심 차이 – 실행 시점, 트리거, 용도
• PreToolUse / PostToolUse – 뭔 소린지 쉽게 설명
• 실제 설정 방법 – settings.json 예시
• 언제 뭘 써야 하는지 판단 기준

---

🔥 핵심 차이: 자동 경비 vs 전문가 호출

여러분 이거 경험 있죠?

회사에 보안 시스템이랑 외부 컨설턴트가 따로 있잖아요.

보안 시스템 = 24시간 자동 감시, 문 열리면 알아서 알림 외부 컨설턴트 = 필요할 때 “도와주세요” 하고 불러야 옴

Claude Code에서 Hooks는 보안 시스템, Agent는 외부 컨설턴트예요.

비교표로 보면 확실해요

구분	Hooks	Agent
실행 시점	🤖 자동 (이벤트 발생 시)	👆 수동 (사용자가 호출 시)
트리거	도구 사용 전/후	@agent-name 명령
실행 주체	Shell 스크립트	LLM (Claude)
용도	검증, 차단, 포맷팅, 로깅	복잡한 워크플로우 수행
비유	🚨 자동 경비 시스템	👨‍🔧 전문가 호출

---

⚡ Hooks: 백그라운드에서 알아서 도는 녀석

Hooks가 뭐냐면요

Hooks는 “특정 상황에서 자동으로 뭔가 실행되게” 만드는 거예요.

Git Hooks 아시죠? 커밋하면 알아서 린트 돌리는 거요.

Claude Code Hooks도 똑같아요.

“파일 저장하면 자동으로 포맷팅해” “민감 파일 건드리면 자동으로 막아”

사용자가 뭔가 하지 않아도 백그라운드에서 돌아가요.

PreToolUse vs PostToolUse

여기서 또 혼란스러운 게 나와요.

PreToolUse랑 PostToolUse가 뭔데?

쉽게 말할게요.

타입	실행 시점	용도
PreToolUse	도구 실행 전	차단, 검증, 권한 체크
PostToolUse	도구 실행 후	포맷팅, 로깅, 정리

PreToolUse는 경비원이 문 앞에서 “신분증 보여주세요” 하는 거예요. PostToolUse는 청소부가 퇴근 후 정리하는 거예요.

실제 예시로 보면

사용자: "이 파일 저장해"
  ↓
[PreToolUse Hook] - ".env 파일이네? 민감 파일! 차단!"
  ↓ (차단되면 여기서 끝)
[Write 도구 실행] - 파일 저장
  ↓
[PostToolUse Hook] - "console.log 있나 체크... 3개 발견! 경고!"

자동으로요. 사용자가 뭘 안 해도요.

---

👨‍💼 Agent: 불러야 오는 전문가

Agent가 뭐냐면요

Agent는 **”특정 분야 전문가 AI”**예요.

하나의 Claude에게 모든 걸 시키는 게 아니라, 업무별로 전문 에이전트를 만들어 두는 거예요.

@code-reviewer  → 코드 리뷰 전문가
@planner        → 기획/계획 전문가
@security       → 보안 전문가
@blog-pipeline  → 블로그 작성 전문가

근데 중요한 건요.

에이전트는 불러야 와요.

사용자: "@code-reviewer 이 PR 봐줘"
  ↓
Claude가 code-reviewer 역할로 전환
  ↓
상세 코드 리뷰 수행
  ↓
결과 반환

Hooks랑 다르게 사용자가 명시적으로 호출해야 해요.

Agent 예시 파일

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior code reviewer...

이런 식으로 .claude/agents/ 폴더에 만들어두면, 필요할 때 @code-reviewer로 부를 수 있어요.

---

🛠️ Hooks 설정하는 법

settings.json 위치

Hooks는 settings.json 파일에서 설정해요.

위치가 3개예요:

위치	적용 범위
~/.claude/settings.json	모든 프로젝트 (글로벌)
.claude/settings.json	이 프로젝트만 (커밋 가능)
.claude/settings.local.json	이 프로젝트만 (커밋 안 함)

PostToolUse 예시: 파일 저장 후 알림

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] 파일 작성 완료'"
          }
        ]
      }
    ]
  }
}

이러면 파일 저장될 때마다 터미널에 [Hook] 파일 작성 완료가 뜨는 거예요.

PreToolUse 예시: 민감 파일 보호

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$FILE_PATH\" | grep -qE '\\.env|secrets'; then echo '[Block] 민감 파일!'; exit 2; fi"
          }
        ]
      }
    ]
  }
}

여기서 exit 2가 중요해요.

exit 코드가 2면 Claude가 “아, 이거 못 하는구나” 알고 다른 방법을 찾아요.

matcher 패턴

패턴	의미
"Write"	Write 도구만
"Edit|Write"	Edit 또는 Write
"*"	모든 도구

---

🎯 언제 뭘 써야 할까?

이거 진짜 중요해요. 판단 기준 알려드릴게요.

Hooks 쓸 때

“매번 자동으로, 백그라운드에서, 내가 신경 안 써도”

• ✅ 코드 저장할 때마다 자동 포맷팅
• ✅ 특정 파일 수정 차단
• ✅ 작업 로그 자동 기록
• ✅ console.log 자동 경고

Agent 쓸 때

“이거 해줘! 하고 명시적으로 요청할 때”

• ✅ 코드 리뷰 해줘
• ✅ 기능 구현 계획 세워줘
• ✅ 블로그 글 써줘
• ✅ 보안 취약점 분석해줘

한 줄 정리

Hooks = “감시자/자동화” Agent = “전문가 호출”

---

💡 제가 실제로 쓰고 있는 설정

Hooks 설정

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "echo '[✅] 파일 저장됨'" }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "if echo \"$TOOL_INPUT\" | grep -qE '\\.env|secrets|api.key'; then echo '[🔒] 민감 파일 감지'; fi"
        }]
      }
    ]
  }
}

Agent 목록

@blog-pipeline    → 블로그 글 작성
@crypto-analyzer  → 코인 분석
@code-reviewer    → 코드 리뷰
@skill-creator    → 스킬 생성

둘 다 쓰고 있어요. 역할이 달라서요.

---

⚠️ 주의사항: Hooks가 안 될 때

솔직히 말할게요.

Hooks는 Claude Code 터미널에서만 동작해요.

Cursor, Windsurf, 다른 IDE에서 Claude 쓰면 Hooks 안 먹을 수 있어요.

왜냐면 Hooks는 Claude Code CLI 환경에서 도구 호출 시점을 가로채는 거라서요.

그래서 저는 이렇게 해요:

1. Hooks: Claude Code 터미널에서만 의존
2. Agent: 어디서든 @agent 호출로 사용

IDE 환경에서는 Agent 중심으로 쓰고, CLI 환경에서는 Hooks로 보완하는 전략이에요.

---

🤔 솔직한 마음

처음에 Hooks 설정할 때 “이게 진짜 되나?” 했어요.

근데 설정하고 파일 저장하니까 진짜 [✅] 파일 저장됨 뜨더라고요.

“오… 이거 되네?”

그때부터 좀 재밌어졌어요. “이걸로 뭘 자동화할 수 있을까?” 생각하게 됐거든요.

아직 초반이라 단순한 알림 정도만 쓰고 있는데, 나중에는 자동 테스트 실행이랑 커밋 전 검증도 추가해보려고요.

불안하진 않아요. 롤백도 쉬우니까요. hooks 블록만 지우면 끝이에요.

---

🎯 앞으로 제가 할 것들

이번 주

• [ ] PostToolUse에 자동 lint 추가
• [ ] git 관련 파일 수정 시 경고 Hook

이번 달

• [ ] 테스트 자동 실행 Hook
• [ ] 커밋 전 검증 Hook
• [ ] code-reviewer Agent 강화

---

❓ 자주 묻는 질문 (FAQ)

Q1. Hooks랑 Agent 둘 다 써야 해요?

A: 상황에 따라요. 자동화가 필요하면 Hooks, 복잡한 작업 위임이 필요하면 Agent. 저는 둘 다 씁니다.

Q2. Hooks가 안 되는데요?

A: Claude Code CLI 환경인지 확인하세요. 다른 IDE (Cursor 등)에서는 안 될 수 있어요.

Q3. PreToolUse에서 exit 2가 뭐예요?

A: 도구 실행을 차단하는 신호예요. exit 2 하면 Claude가 “이거 못 한다” 알고 다른 방법을 찾아요.

Q4. Agent 만들려면 어떻게 해요?

A: .claude/agents/ 폴더에 마크다운 파일 만들고 frontmatter에 name, description, tools 쓰면 돼요.

Q5. 어디서부터 시작하면 좋을까요?

A: 일단 간단한 PostToolUse Hook (파일 저장 알림) 부터 시작하세요. 동작 확인하고 점점 늘려가면 돼요.

---

📚 참고 자료

• Claude Code 공식 문서 – Hooks
• Claude Code Hooks 설정 가이드
• everything-claude-code 레포지토리

---

📌 마무리

Hooks와 Agent, 이제 구분되시죠?

Hooks = 24시간 자동 경비 Agent = 필요할 때 부르는 전문가

둘 다 Claude Code를 강력하게 만들어주는 기능이에요.

근데 역할이 달라요. 그래서 둘 다 쓰는 게 맞아요.

저도 아직 Hooks는 초반 단계인데, 점점 늘려가면서 “이거 자동화하면 좋겠다” 싶은 것들 추가하고 있어요.

여러분도 일단 간단한 Hook 하나 설정해보세요.

파일 저장할 때 메시지 뜨는 거 보면 “오… 이거 되네?” 할 거예요.

궁금한 거 있으면 댓글 남겨주세요!