클로드 코드 자동화: 훅과 예약으로 손 떼기

여기까지 만든 CLAUDE.md도, 스킬도, 서브에이전트도 전부 공통점이 하나 있습니다. 전부 내가 뭔가를 입력해야 시작됩니다. 세션을 열어야 CLAUDE.md가 읽히고, 슬래시 명령을 쳐야 스킬이 돌고, 위임을 요청해야 서브에이전트가 움직입니다. 자동이라는 말이 붙었지만 결국 시작 버튼은 늘 사람 몫이었던 셈입니다. 지난 레슨에서 일을 나눠 맡기는 데까지 왔다면, 오늘은 그 시작 버튼 자체를 내려놓는 차례입니다. 자동화가 급해서 오셨다면 이 레슨만 보셔도 됩니다. "훅"이라는 이름보다 자동화라는 결과로 이 레슨을 찾아오신 분이 많으실 텐데, 그 이유는 레슨 1에서 이미 짚었으니 여기서는 결과로 바로 들어가겠습니다.

훅 (Hook)

훅은 Claude Code(클로드 코드) 생애주기의 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령이다. 파일을 편집한 뒤, 세션을 새로 열 때, 알림을 보낼 때처럼 정해진 이벤트가 일어나면 실행되므로, Claude(클로드)가 그때그때 판단해서 실행할지 말지 정하는 대신 특정 동작이 항상 일어나게 만든다.

훅이란: 이벤트에 맞춰 도는 명령

공식 문서에 등록된 훅 이벤트는 30가지가 넘습니다. 전부 외울 필요는 없고, 자주 쓰이는 몇 가지만 감을 잡아두면 됩니다.

이 이름들은 릴리스마다 늘어나거나 바뀔 수 있는 영역입니다. 이 레슨은 2026년 8월 22일 기준 공식 문서로 확인한 목록이니, 오래된 시점에 읽으신다면 공식 문서에서 최신 이벤트 목록을 다시 확인해 주세요.

훅을 어디에 등록하느냐에 따라 범위가 갈립니다. CLAUDE.md, 스킬 위치 규칙과 결이 같습니다.

각 이벤트 아래에는 matcher로 범위를 더 좁힐 수 있습니다. 예를 들어 PostToolUse에 matcher: "Edit|Write"를 넣으면 파일을 편집하는 도구를 쓸 때만 훅이 돌고, Bash나 Read를 쓸 때는 조용합니다.

훅 하나 걸어보기

이 블로그가 쓰는 저장소의 .claude/settings.json에는 실제로 SessionStart 훅이 걸려 있습니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "node scripts/handoff.mjs --hook", "timeout": 15 },
          { "type": "command", "command": "node scripts/i18n-sync.mjs --changed --hook", "timeout": 20 }
        ]
      }
    ]
  }
}

matcher가 비어 있어서 세션을 새로 열 때, 이어서 열 때, /clear나 /compact를 할 때까지 SessionStart가 발동하는 모든 경우에 두 스크립트가 함께 돕니다. 하나는 다른 작업 폴더에서 이 저장소로 남겨둔 인수인계 메모가 있는지 확인하는 것이고, 다른 하나는 한국어판과 영어판 글이 구조적으로 어긋나지 않았는지 점검하는 것입니다. 둘 다 파일을 고치는 게 아니라 확인만 하는 훅이라, 잘못 실행돼도 뭔가가 지워지거나 망가지지 않습니다.

처음 걸어보는 훅은 이렇게 안전한 자리에서 시작하는 편이 낫습니다. 공식 문서의 첫 실습도 비슷합니다. Claude가 입력을 기다릴 때 데스크톱 알림을 받는 훅입니다. ~/.claude/settings.json(개인 설정이라 다른 프로젝트에는 영향이 없습니다)을 열어 이렇게 추가합니다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"클로드코드가 입력을 기다립니다\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

맥 기준 예시이고, 윈도우와 리눅스는 각각 다른 알림 명령을 씁니다. 정확한 명령은 아래 Sources의 공식 문서에 플랫폼별로 정리되어 있습니다.

예약이란: 정한 시각에 도는 자동화

훅이 "어떤 일이 일어날 때"라면 예약은 "정한 시각에"입니다. Claude Code는 예약을 세 가지 방식으로 제공하고, 셋의 조건이 서로 다릅니다. 표의 간격·조건 값은 2026년 8월 기준입니다.

이 트랙의 관통 시나리오처럼 매달 1일 오전 9시에 리포트 초안을 자동으로 띄우고 싶다면 클라우드 루틴이 맞습니다. 컴퓨터를 꺼둬도 Anthropic 쪽 클라우드에서 대신 돌기 때문입니다. 터미널에서 /schedule을 입력하고 자연어로 설명하면 됩니다.

/schedule 매달 1일 오전 9시에 report-researcher와 monthly-report-draft로 리포트 초안 만들기

Claude가 반복 주기와 저장소, 프롬프트를 되물은 뒤 계정에 저장합니다. 공식 문서는 클라우드 루틴이 아직 연구 미리보기 상태라 동작과 제한이 바뀔 수 있다고 밝히고, 권한 모드 선택기나 실행 중 승인 프롬프트 없이 완전히 자율적으로 실행된다고도 설명합니다. /schedule이 명령어 목록에 안 뜬다면 API 키나 조직 인증으로 로그인한 상태일 수 있습니다. claude.ai 구독 계정으로 로그인해야 이 명령이 나타납니다.

리포트 초안이 참고하는 자료가 저장소가 아니라 내 컴퓨터 안의 파일이라면 사정이 다릅니다. 클라우드 루틴은 매번 저장소를 새로 복제해서 실행하므로 로컬 파일에는 손을 대지 못합니다. 이럴 때는 데스크톱 앱의 예약 작업을 씁니다. 사이드바의 Routines에서 Local을 선택하면 내 컴퓨터에서 직접 도는 예약 작업을 만들 수 있고, 최소 간격도 1분까지 줄일 수 있습니다. 다만 데스크톱 앱이 열려 있고 컴퓨터가 깨어 있을 때만 실행됩니다. 컴퓨터가 잠들어 있던 사이에 놓친 실행은 앱이 다시 켜질 때 지난 7일 안에서 가장 최근 것 딱 한 번만 따라잡습니다 (2026년 8월 기준). 매일 도는 작업을 엿새 놓쳤다면 깨어난 순간 한 번만 도는 식입니다.

지금 열린 세션 안에서 몇 분 간격으로만 짧게 반복하고 싶다면 /loop가 더 가볍습니다. 세션이 열려 있는 동안만 돌고 세션을 닫으면 함께 끝나지만, 만료 전이라면 --resume으로 이어서 세션을 열었을 때 그대로 복원됩니다. 세 방식 중 무엇을 고를지는 결국 두 질문으로 좁혀집니다. 컴퓨터가 꺼져 있어도 돌아야 하는가, 그리고 내 컴퓨터 안의 파일에 손을 대야 하는가입니다. 둘 다 그렇다는 조합은 없습니다.

자동으로 도는 것에는 안전장치가 필요하다

클라우드 루틴은 공식 문서가 스스로 이렇게 못박습니다. "완전한 Claude Code 클라우드 세션으로 자율적으로 실행됩니다. 권한 모드 선택기나 실행 중 승인 프롬프트가 없습니다." 사람이 없는 사이에 도는 대신, 그만큼 무엇을 시킬 수 있는지 미리 좁혀둬야 한다는 뜻입니다. 저장소는 루틴을 만들 때 직접 골라 추가하지만, 커넥터는 계정에 연결된 것 전부가 기본으로 포함됩니다. 공식 문서는 저장소든 커넥터든 루틴이 실제로 필요한 것만 남기고 나머지는 빼두라고 권합니다.

훅도 비슷한 함정이 있습니다. 권한 프롬프트를 자동으로 승인하는 PermissionRequest 훅을 만들 수도 있는데, matcher를 비워두거나 .*처럼 넓게 잡으면 파일 쓰기와 셸 명령을 포함한 모든 권한 프롬프트가 조용히 자동 승인됩니다. 공식 문서는 이 matcher를 가능한 한 좁게 유지하라고 명시적으로 경고합니다. 데스크톱 예약 작업의 "always allow" 방식도 마찬가지입니다. 한 번 승인해두면 다음 실행부터는 묻지 않고 그대로 실행되므로, 어떤 도구를 자동 승인해뒀는지 세부 정보 페이지에서 가끔 다시 확인할 필요가 있습니다.

그래서 원칙은 하나로 좁혀집니다. 초안까지는 자동화해도 되지만, 발행이나 전송, 결제처럼 되돌리기 어려운 마지막 한 걸음은 자동화하지 않습니다. 이 트랙의 관통 시나리오도 그렇게 설계돼 있습니다. 매달 1일에 자동으로 뜨는 건 리포트 초안이지, 고객사에 보내는 발송 메일이 아닙니다. 사람이 확인하고 마지막 버튼을 누르는 자리는 남겨두는 편이 안전합니다.

제 첫 자동화도 설정 파일의 훅이 아니라 스킬 안의 이어달리기였습니다. 콘텐츠 마케팅 준비를 스킬로 묶으면서, 한 단계가 끝나면 다음으로 넘어가고 중간에 어긋나면 앞 단계로 돌아가 다시 하게 이어 붙여서, 결과물이 나올 때까지 손대지 않고 돌게 만들었습니다. "무엇이 끝나면 무엇을 한다"는 발상 자체는 훅과 같습니다. 자리만 다를 뿐입니다.