Hook과 Skill 그리고 Rule에 관해서

"코드 고치면 테스트도 같이 돌려줘"라고 적어뒀는데 테스트 없이 끝난 작업을 받아본 적이 있습니다. 지시를 안 읽은 걸까요? 아닙니다. 그 지시를 어디에 적었느냐의 문제였습니다.

에이전트를 설정하는 방법에는 크게 Rule, Skill, Hook 세 가지가 있습니다. 셋 다 "에이전트가 이렇게 동작했으면 좋겠다"를 적는 자리라 비슷해 보이지만 성격이 전혀 다릅니다. 어떤 건 참고 사항이고, 어떤 건 필요할 때만 꺼내 보는 매뉴얼이며, 어떤 건 조건이 맞으면 무조건 실행되는 장치입니다. 이 차이를 모르면 반드시 지켜져야 할 규칙을 참고 사항 자리에 적어두고 지켜지길 기대하게 됩니다.

이 글에서는 셋을 하나씩 짚고, 나란히 놓고 비교한 뒤, 어떤 상황에 무엇을 쓸지 정리합니다.

Rule — 항상 지켜야 하는 기준

Rule은 에이전트가 작업 전반에서 계속 따라야 하는 기본 규칙과 제약조건입니다. 프로젝트의 기준선을 적어두는 자리라고 보면 됩니다.

여기 들어가는 내용은 이렇습니다.

• 사용하는 언어와 프레임워크
• 프로젝트의 디렉터리 구조
• 코딩 컨벤션과 패키지 관리자
• 금지된 작업
• 테스트 및 검증 기준
• 파일별 또는 디렉터리별 작업 규칙
• 결과 보고 형식

실제로 쓰면 이런 모양이 됩니다.

# Project Rules

- 패키지 관리자는 pnpm을 사용한다.
- 기존 테스트 코드는 삭제하지 않는다.
- 자동 생성 파일은 직접 수정하지 않는다.
- API 응답은 공통 응답 형식을 따른다.
- 코드 수정 후 관련 테스트를 실행한다.

Claude Code는 주로 CLAUDE.md나 별도 Rule 파일을, Codex는 AGENTS.md를 씁니다.

Rule은 특정 작업의 절차라기보다 작업하는 내내 참고하는 상시 지침에 가깝습니다. 그래서 Rule에 "테스트를 실행하라"고 써도 Rule 자체가 테스트 명령을 실행하지는 않습니다. LLM에 전달되는 지침이라 에이전트가 읽고 해석해서 따라야 합니다. 서두에서 말한 "테스트가 빠진 작업"이 바로 여기서 나옵니다. 반드시 실행돼야 하는 검사나 차단 절차라면 Rule이 아니라 Hook의 몫입니다.

Rule은 에이전트가 작업 전반에서 지켜야 할 프로젝트 규칙과 제약조건을 정의한 기본 지침입니다.

Rule이 적용되는 시점

Rule은 세션이나 프로젝트 작업이 시작될 때 로드됩니다.

에이전트 실행
↓
전역 Rule 확인
↓
프로젝트 Rule 확인
↓
현재 작업 경로에 적용되는 Rule 확인
↓
사용자 요청 처리

경로별 Rule을 지원하는 환경이라면 특정 디렉터리나 파일을 건드릴 때만 해당 Rule이 추가로 붙습니다.

프로젝트 공통 Rule
- pnpm 사용
- TypeScript strict 모드 준수

backend 디렉터리 Rule
- 모든 입력값 검증
- 트랜잭션 처리 기준 준수

frontend 디렉터리 Rule
- 공통 UI 컴포넌트 우선 사용
- 직접적인 DOM 조작 금지

전체 프로젝트에 걸어도 되고 특정 경로에만 한정해도 됩니다.

Skill — 작업을 수행하는 절차

Skill은 특정 작업을 일관된 순서와 기준으로 처리하도록 정의해둔, 재사용 가능한 작업 매뉴얼입니다.

여기에는 작업 수행 순서, 판단 기준, 사용할 도구, 참고 자료, 검증 방법, 결과 출력 형식, 실패 시 대응 방법을 적습니다.

Skill 자체가 별도의 에이전트로 실행되지는 않습니다. 메인 에이전트나 서브에이전트가 Skill을 읽고 그 절차대로 움직입니다. 적용되는 경로는 두 갈래입니다. 사용자가 직접 지정해 호출하거나, 현재 작업이 Skill의 설명과 맞아떨어질 때 에이전트가 알아서 고릅니다.

작업 내용과 절차는 목적에 맞게 자유롭게 쓰면 됩니다. 다만 Skill로 인식되려면 SKILL.md 파일, 디렉터리 구조, 이름과 설명 같은 필수 메타데이터 규격은 지켜야 합니다.

Skill은 점진적으로 로드됩니다.

에이전트 시작
↓
사용 가능한 Skill의 이름과 설명 확인
↓
현재 작업과 관련된 Skill 선택
↓
선택한 SKILL.md 본문 로드
↓
필요한 참고 자료와 스크립트 추가 로드

설치된 Skill 전부가 항상 입력 컨텍스트에 들어가지는 않는다는 뜻입니다. 대신 실제로 선택된 Skill은 읽어 들인 분량만큼 입력 토큰을 씁니다. 그래서 핵심 절차는 SKILL.md에 짧게 적고, 상세 설명이나 예시는 별도 참고 파일로 빼서 필요할 때만 읽게 만드는 편이 효율적입니다.

Skill은 특정 작업의 수행 방법을 표준화한 재사용 가능한 지침이며, 필요한 작업에서만 선택적으로 로드됩니다.

Skill 예시

Claude Code 기준으로 파일 위치는 이렇습니다.

.claude/skills/code-review/SKILL.md

---
name: code-review
description: 코드 변경사항의 버그와 테스트 누락을 검토할 때 사용한다.
---

1. 변경된 파일을 확인한다.
2. 논리 오류와 보안 문제를 찾는다.
3. 관련 테스트를 실행한다.
4. 문제를 심각도순으로 정리한다.
5. 파일 경로와 근거를 함께 제시한다.

직접 호출할 때는 이렇게 씁니다.

/code-review

호출되면 에이전트가 SKILL.md를 읽고 정의된 순서대로 코드 리뷰를 진행합니다.

Hook — 특정 시점에 자동 실행되는 장치

Hook은 에이전트 실행 도중 특정 이벤트가 발생했을 때 미리 정해둔 명령·검사·자동화 작업을 실행하는 기능입니다. 언제 실행할지와 무엇을 실행할지를 한 쌍으로 적습니다.

조건이 맞으면 이런 일들이 자동으로 일어납니다.

• 린트, 테스트, 코드 포매팅 실행
• 보안 검사와 로그 기록
• 알림 발송
• 위험한 명령 차단
• 도구 실행 허용 여부 판단
• 추가 컨텍스트 제공

Hook도 종류에 따라 동작 방식이 갈립니다.

• 명령형 — 셸 명령이나 스크립트를 자동 실행합니다.
• 검사형 — 도구 실행을 허용하거나 차단합니다.
• 프롬프트형 — 별도의 LLM 판단을 호출해 조건을 검사합니다.
• 에이전트형 — 별도 에이전트를 실행해 결과를 분석하거나 검증합니다.

명령형 Hook은 모델을 부르지 않으니 LLM 토큰을 거의 쓰지 않습니다. 토큰이 추가로 나가는 경우는 Hook 출력이 다음 모델 입력에 포함될 때, 프롬프트형이 모델을 호출할 때, 에이전트형이 별도 에이전트를 돌릴 때입니다.

Hook은 특정 이벤트가 발생했을 때 정해진 작업을 자동으로 실행하거나 작업의 진행 여부를 제어하는, 이벤트 기반 자동화 규칙입니다.

대표적인 Hook 실행 시점

Claude Code에서 쓰는 이벤트를 예로 들면 이렇습니다.

• SessionStart — 세션이 시작될 때
• UserPromptSubmit — 사용자가 프롬프트를 제출했을 때
• PreToolUse — 도구가 실행되기 직전
• PostToolUse — 도구가 성공적으로 실행된 직후
• PostToolUseFailure — 도구 실행에 실패한 직후
• SubagentStart — 서브에이전트가 시작될 때
• SubagentStop — 서브에이전트가 종료될 때
• Stop — 에이전트가 응답 또는 작업을 종료할 때

이벤트 이름과 지원 범위는 제품 및 버전에 따라 달라집니다.

Hook 예시

Claude Code 기준으로 파일 위치는 .claude/settings.json입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  }
}

이 설정은 Claude가 Edit이나 Write 도구로 파일을 수정할 때마다 npm run lint를 실행합니다.

Skill에 "파일 수정 후 린트를 실행하라"고 적으면 에이전트가 그 지침을 읽고 따라야 하지만 Hook으로 걸어두면 파일 수정 이벤트가 발생하는 순간 린트가 돕니다. 앞의 두 절과 이 절의 차이가 여기서 드러납니다.

한눈에 비교

한 줄로 줄이면 이렇게 됩니다.

Rule  = 무엇을 지켜야 하는가
Skill = 어떻게 작업해야 하는가
Hook  = 언제 무엇을 자동 실행해야 하는가

실행 순서

셋이 실제로 맞물리는 순서는 이렇습니다.

에이전트 세션 시작
↓
전역 및 프로젝트 설정 확인
↓
Rule 로드
- CLAUDE.md
- AGENTS.md
- 경로별 Rule
↓
SessionStart Hook 실행
↓
사용자 프롬프트 입력
↓
UserPromptSubmit Hook 실행
↓
Rule을 기준으로 사용자 요청 분석
↓
Skill 호출 여부 결정
- 사용자가 직접 호출
- 에이전트가 자동 선택
↓
선택한 SKILL.md와 참고 자료 로드
↓
Rule과 Skill을 바탕으로 작업 계획 수립
↓
도구 호출 시도
↓
PreToolUse Hook 실행
- 명령 검사
- 입력값 검사
- 위험한 작업 차단
↓
권한 확인
↓
도구 실행
- 파일 읽기
- 파일 수정
- 명령 실행
- 외부 시스템 호출
↓
PostToolUse 또는 PostToolUseFailure Hook 실행
- 린트
- 포매팅
- 테스트
- 오류 기록
↓
필요하면 계획 및 도구 실행 반복
↓
서브에이전트 사용 시
- SubagentStart Hook
- 서브에이전트 작업
- SubagentStop Hook
↓
작업 완료
↓
Stop Hook 실행
↓
최종 결과 반환

내부 순서는 제품과 버전에 따라 조금씩 다르지만 큰 그림은 Rule이 기본 조건을 깔고 Skill이 절차를 얹으며 Hook이 중간중간 개입하는 구조입니다.

우선순위와 강제력

셋은 같은 종류의 설정이 아니라서 하나의 우선순위로 줄 세우기 어렵습니다.

Rule과 Skill

둘 다 LLM에 전달되는 지침입니다. Rule은 기본으로 깔리는 프로젝트 지침이고 Skill은 특정 작업을 위해 추가되는 전문 지침입니다. 충돌하면 제품의 지침 계층, 적용 범위, 파일 위치, 구체성에 따라 처리됩니다.

Rule을 기본 작업 환경과 제약조건으로, Skill을 그 조건 안에서 수행할 구체적인 절차로 보면 이해가 쉽습니다. Skill이 Rule을 무조건 덮어쓰지는 않습니다. Rule에서 운영 DB 수정이 금지돼 있다면 Skill에 운영 DB를 수정하라는 절차가 있어도 그대로 실행하는 건 적절하지 않습니다.

Hook의 강제력

Hook은 프롬프트 지침이 아니라 실제 실행 과정에 개입합니다. 이런 상황을 생각해봅시다.

Rule:
운영 환경 파일을 수정하지 않는다.

Skill:
설정 파일을 수정하고 테스트한다.

Hook:
운영 환경 파일 수정 시 도구 실행을 차단한다.

에이전트가 Rule을 놓치거나 Skill을 잘못 해석해 운영 파일에 손을 대려 해도, PreToolUse Hook이 실행을 막으면 수정은 일어나지 않습니다. Rule과 Skill이 LLM이 따라야 하는 지침이라면 Hook은 실제 실행을 검사하고 차단하는 통제 장치입니다.

물론 Hook도 등록된 이벤트와 조건에 걸리는 작업만 통제합니다. 모든 상황에서 Rule과 Skill보다 우선하지는 않습니다.

한 작업에 셋을 겹쳐보면

"코드를 수정하고 테스트까지 수행한다"를 목표로 잡아봅시다.

프로젝트 전체에서 지켜야 하는 기본 규칙은 Rule입니다.

- 패키지 관리자는 pnpm을 사용한다.
- 기존 테스트를 삭제하지 않는다.
- 관련 없는 파일은 수정하지 않는다.

작업을 어떤 순서로 처리할지는 Skill이 정합니다.

1. 변경 대상 파일을 확인한다.
2. 문제의 원인을 분석한다.
3. 최소 범위로 코드를 수정한다.
4. 관련 테스트를 실행한다.
5. 변경사항과 테스트 결과를 보고한다.

실행 과정에서 검사와 명령을 자동으로 끼워 넣는 건 Hook입니다.

파일 수정 전
→ 보호 대상 파일인지 검사

파일 수정 후
→ 포매터와 린트 실행

작업 종료 전
→ 테스트 실행 여부 검사

Rule로 제약조건을 깔고, Skill로 절차를 정하고, Hook으로 실행을 검사하는 3단 구조가 완성됩니다.

무엇을 어디에 쓸까

마무리

Rule, Skill, Hook은 서로를 대체하는 기능이 아닙니다. Rule은 에이전트의 기본 행동 기준을 제공하고, Skill은 특정 작업의 수행 방식을 표준화하며, Hook은 실제 실행 과정에서 자동화와 통제를 맡습니다. 셋을 겹쳐 쓰면 기준 → 절차 → 검사로 이어지는 안정적인 작업 환경이 만들어집니다.

기준을 나누는 방법은 간단합니다. 항상 참고해야 하는 기준은 Rule에 적고, 반복되는 작업 절차는 Skill로 빼고, 반드시 실행되거나 차단돼야 하는 동작은 Hook으로 구현합니다. 서두의 "테스트를 안 돌린 에이전트"는 Rule에 적을 내용을 Hook에 적었어야 하는 문제였습니다.