Skip to content

11장. 훅과 화면 맞춤 ​

필수 이 단계를 따라가려면 꼭 읽으세요.

한 줄 요약: 훅(Hook)은 정해진 순간마다 Claude Code가 직접 돌리는 명령입니다. AI의 판단에 맡기지 않으니, 꼭 일어나야 할 일에 씁니다.

이 장의 화면은 2026년 11월 6일 리눅스에서 Claude Code 2.1.318로 실행한 결과입니다.

파일이 바뀔 때마다 기록을 남기는 훅을 만들어 봅니다. 화면 아래 상태 줄과 답변 말투도 내게 맞춥니다.

훅이란 ​

훅은 내가 정해 둔 셸 명령입니다. Claude Code가 정해진 시점마다 그 명령을 실행합니다. 그래서 Claude가 "기억하고 해 주기"를 바랄 필요가 없습니다.[1]

8장의 CLAUDE.md와 나란히 놓고 보면 차이가 보입니다.

  • 아쉬운 예: CLAUDE.md에 "파일을 바꾸면 변경기록.txt에 한 줄 남겨 줘"라고 적는다. 지키는 쪽은 Claude입니다. 빠뜨릴 수 있습니다.
  • 나은 예: 같은 일을 훅으로 만든다. 지키는 쪽은 Claude Code입니다. 파일을 바꾼 뒤마다 명령이 실행됩니다.

매번 반드시 일어나야 하는 일에는 훅을 쓰세요.[2] 그렇다고 규칙을 전부 훅으로 옮길 필요는 없습니다. 말투나 문서 형식 같은 규칙은 CLAUDE.md로 충분합니다. 훅은 "빠지면 곤란한 일"에만 쓰세요.

확인 퀴즈

파일이 바뀔 때마다 기록을 꼭 남기고 싶습니다. CLAUDE.md에 적는 것보다 훅이 나은 까닭은 무엇일까요?

변경기록 훅 만들기 ​

훅은 설정 파일에 hooks 칸을 추가해서 만듭니다.[3] 이 장에서는 프로젝트 설정 파일 .claude/settings.json에 넣습니다. 7장의 거부 규칙이 든 그 파일입니다.

손으로 고치면 쉼표 하나로 틀리기 쉽습니다. 그래서 파일 전체를 한 번에 덮어씁니다. 7장의 거부 규칙도 아래 내용 안에 그대로 있으니 사라지지 않습니다.

/exit로 나와 터미널의 연습 폴더에서 아래를 통째로 붙여 넣습니다. 붙여 넣은 뒤 아직 실행되지 않았으면 Enter를 한 번 더 누르세요.

낯선 칸 이름이 여럿 나오지만 지금 다 알 필요는 없습니다. 큰 덩어리는 셋입니다.

  • permissions: 7장에서 만든 거부 규칙
  • hooks: 이번에 만드는 변경기록 훅
  • statusLine: 화면 아래 상태 줄

자세한 뜻은 상자 바로 아래에서 하나씩 풉니다.

bash
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "deny": ["Read(./비밀/**)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "date '+%F %T 파일이 바뀌었습니다' >> 변경기록.txt" }
        ]
      }
    ]
  },
  "statusLine": { "type": "command", "command": "echo 모퉁이 카페 정리 중" }
}
EOF

Windows PowerShell은 notepad .claude\settings.json으로 메모장을 엽니다. 원래 내용을 지우고 위 상자에서 cat으로 시작하는 줄과 EOF 줄을 뺀 사이만 넣습니다. Ctrl + S로 저장하고 닫습니다. 이 방법은 실행해 보지 않았습니다.

낯선 말을 하나씩 풀어 볼게요. 마지막의 statusLine 칸은 뒤의 「상태 줄」 절에서 봅니다.

  • PostToolUse: Claude가 도구를 쓴 뒤라는 뜻입니다. 이미 끝난 일을 되돌리지는 못합니다. 도구를 쓰기 전에 끼어들어 막을 수 있는 시점은 PreToolUse입니다.[4]
  • matcher: 어떤 도구에 반응할지 정합니다. Write|Edit는 파일을 만드는 도구와 고치는 도구입니다. 여기서 |는 "또는"이라는 뜻입니다. Claude가 셸 명령으로 바꾼 파일에는 이 훅이 반응하지 않습니다.
  • command: 실행할 명령입니다. 지금 날짜·시각과 문장을 변경기록.txt 끝에 덧붙입니다. 명령을 조각으로 나눠 보면 이렇습니다.
    • date: 지금 날짜와 시각을 찍는 명령입니다.
    • '+%F %T 파일이 바뀌었습니다': 찍을 모양입니다. %F 자리에 날짜(2026-11-06), %T 자리에 시각(11:19:11)이 들어갑니다.
    • >> 변경기록.txt: 결과를 그 파일 끝에 덧붙입니다. 10장의 >는 파일을 덮어쓰고, >>는 뒤에 이어 씁니다. 파일이 없으면 새로 만듭니다.

덮어쓰는 대신 Claude에게 말로 부탁해도 됩니다.[5] 내 프로젝트처럼 설정이 이미 들어 있는 파일이라면 이 방법이 낫습니다. .claude 폴더는 특별히 지키는 곳이라 이때 허락 창이 뜰 수 있습니다.[6]

text
.claude/settings.json 에 훅을 추가해 줘. Claude가 Write나 Edit 도구를 쓴 뒤마다 아래 명령이 돌게 해 줘. 이미 있는 내용은 지우지 마.
date '+%F %T 파일이 바뀌었습니다' >> 변경기록.txt

이미 hooks 칸이 있다면 통째로 바꾸지 말고 그 안에 하나 더 넣습니다.[7] Windows에서는 이 훅을 실행해 보지 않았습니다. date 명령은 bash 형식이라 그대로 실행되지 않을 수 있습니다. 그럴 때는 Claude에게 내 환경에 맞는 명령으로 바꿔 달라고 부탁하세요.

이제 시험합니다. claude를 켜고 이렇게 보냅니다.

text
notes 폴더에 훅시험.md 를 만들고 "훅 시험" 한 줄만 적어 줘.

끝나면 ! cat 변경기록.txt를 칩니다. 실제로 돌렸을 때는 이렇게 한 줄이 남았습니다.

text
2026-11-06 11:19:11 파일이 바뀌었습니다

전체 설정 파일은 11장-settings.json.txt에서 볼 수 있습니다.

확인 퀴즈

훅 설정의 `PostToolUse`는 언제를 뜻할까요?

훅 확인하기 ​

훅이 등록됐는지는 세션에서 /hooks를 쳐서 봅니다.[8] 이 화면은 보기 전용입니다. 여기서 훅을 만들거나 고칠 수는 없습니다. 화면이 직접 그렇게 말합니다.

text
  Hooks
  1 hook on 1 event

  This menu is read-only. To add or change a hook, edit settings.json or ask Claude. Learn more

    PostToolUse  after tool execution
  ❯ [Project] date '+%F %T 파일이 바뀌었습니다' >> 변경기록.txt   Write|Edit · command

    All events

  Enter to view · Esc to close

훅이 실행되지 않으면 먼저 스스로 물어보세요. /hooks에 보이나? PostToolUse 아래에 있나?[8:1] 그래도 없다면 설정 파일의 문법을 봅니다. 설정 파일에는 끝에 남는 쉼표와 주석을 쓸 수 없습니다.[9] 앞의 상자를 다시 덮어쓰면 가장 빠릅니다.

확인 퀴즈

`/hooks` 화면과 설정 파일에 대해 맞는 말은 무엇일까요?

남이 준 폴더의 훅 ​

내가 직접 만든 연습 폴더라면 위험이 낮습니다. 조심할 것은 남에게 받은 폴더입니다.

남이 준 폴더에는 남이 적어 둔 훅이 들어 있을 수 있습니다.[10] claude -p로 실행하면 내가 신뢰한다고 답한 적 없는 폴더에서도 그 훅이 실행됩니다.[11] 그러니 그 훅은 내 컴퓨터에서 내 계정으로 실행된다고 보는 편이 안전합니다. 받은 폴더는 Claude를 켜기 전에 설정 파일부터 읽어 보세요. 이 권고는 공식 문서의 문장이 아니라 이 가이드의 판단입니다.

bash
cat .claude/settings.json

hooks와 statusLine 칸에 무슨 명령이 있는지 봅니다. 뜻을 모르겠으면 그 폴더 밖에서 채팅으로 물어보세요. 9장의 플러그인도 내 권한으로 코드를 실행할 수 있습니다.[12] 같은 마음으로 대하면 됩니다.

확인 퀴즈

남에게 받은 폴더를 처음 쓸 때 이 가이드가 권하는 행동은 무엇일까요?

상태 줄 ​

상태 줄(Status line)은 Claude Code 화면 아래쪽에 내가 정한 셸 스크립트의 출력을 보여 주는 줄입니다.[13] 설정 파일에 statusLine 칸을 넣으면 됩니다.[14] 앞에서 덮어쓴 설정에 이미 아래 줄이 들어 있습니다. 따로 고칠 것은 없습니다.

json
"statusLine": { "type": "command", "command": "echo 모퉁이 카페 정리 중" }

실제로 돌리니 입력창 아래에 이렇게 보였습니다.

text
  모퉁이 카페 정리 중

폴더 신뢰 창을 수락하기 전에는 상태 줄이 비어 있습니다.[15] 셸 명령을 돌리는 기능이라서 훅과 같은 신뢰 규칙을 따릅니다. 앞 절의 주의도 그대로 적용됩니다.

/statusline 뒤에 원하는 모양을 말로 적어 만드는 방법도 있습니다.[16] 이 기능은 이 가이드에서 실행해 보지 않았습니다.

확인 퀴즈

상태 줄이 비어 있습니다. 문서가 말하는 원인 하나는 무엇일까요?

출력 스타일과 테마 ​

처음부터 바꿀 필요는 없습니다. 필요할 때 꺼내 쓰세요. 이 둘은 이 가이드에서 실행해 보지 않았고, 공식 문서가 설명하는 내용입니다.

출력 스타일(Output style)은 한 세션의 모든 답변에서 역할·말투·형식을 정합니다. 예를 들어 Concise는 결과부터 말하고 서두와 요약을 줄입니다.[17]

text
/output-style Concise

테마는 색입니다. 화면 글자가 잘 안 보이면 /theme으로 터미널에 맞는 색을 고릅니다.[18]

확인 퀴즈

답변을 결과부터 짧게 받고 싶을 때 쓸 수 있는 명령은 무엇일까요?

직접 해 보기 ​

  1. /exit로 나와 터미널에서 설정 상자를 붙여 넣습니다.
  2. claude를 켜고 입력창 아래에 모퉁이 카페 정리 중이 보이는지 봅니다.
  3. /hooks를 쳐서 PostToolUse 아래에 보이는지 확인하고 Esc로 닫습니다.
  4. 훅시험 요청을 보낸 뒤 ! cat 변경기록.txt로 한 줄이 늘었는지 봅니다.

스스로 물어보세요. 훅이 정말 실행됐나? Claude의 답이 아니라 변경기록.txt를 직접 열어 보고 답하세요.

정리 ​

  • 훅은 Claude Code가 정해진 시점마다 돌리는 명령이다. 꼭 일어나야 할 일에 쓴다.
  • /hooks는 보기 전용이다. 만들고 고치는 곳은 설정 파일이다.
  • 설정 파일 JSON에는 끝 쉼표와 주석을 쓰지 않는다.
  • 남이 준 폴더는 켜기 전에 .claude/settings.json부터 읽는다(이 가이드의 판단).
  • 상태 줄, 출력 스타일, 테마는 필요할 때만 바꾼다.

용어 정리 ​

용어읽는 법한 줄 뜻
Hook훅정해진 시점마다 자동으로 실행되는 명령
PostToolUse포스트 툴 유즈도구를 쓴 뒤라는 시점
PreToolUse프리 툴 유즈도구를 쓰기 전이라는 시점
JSON제이슨설정 파일에 쓰는 글자 형식
Status line스테이터스 라인 (상태 줄)화면 아래에 내 명령의 출력을 보이는 줄
Output style아웃풋 스타일답변의 역할·말투·형식 묶음

이 장을 다 읽었나요?

기록은 이 브라우저에만 저장됩니다. 진행 현황은 전체 목차에서 볼 수 있어요.

다음 장: 12장. 동시 작업과 원격

참고 자료 (18개)
  1. Claude Code 공식 문서, 「Automate actions with hooks」. "Hooks are user-defined shell commands." / "Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." code.claude.com (확인일 2026-11-06) ↩︎

  2. Claude Code 공식 문서, 「Output styles」. "For something that has to happen every time, such as formatting after each edit or blocking a command, use a hook." code.claude.com (확인일 2026-11-06) ↩︎

  3. Claude Code 공식 문서, 「Automate actions with hooks」. "To create a hook, add a hooks block to a settings file." code.claude.com (확인일 2026-11-06) ↩︎

  4. Claude Code 공식 문서, 「Automate actions with hooks」. "PostToolUse hooks can't undo actions since the tool has already executed." / "Before a tool call executes. Can block it" code.claude.com (확인일 2026-11-06) ↩︎

  5. Claude Code 공식 문서, 「Automate actions with hooks」. "You can also ask Claude to write the hook for you by describing what you want in the CLI." code.claude.com (확인일 2026-11-06) ↩︎

  6. .claude 폴더는 보호 경로라서 쓰기가 그냥 승인되지 않습니다. 수동 모드에서는 허락 창이 뜨고, 자동 모드에서는 행동을 미리 살피는 별도의 AI가 판단합니다. Claude Code 공식 문서, 「Choose a permission mode」. "Writes to a small set of paths are never auto-approved" / 표의 auto 행: "Routed to the classifier" code.claude.com (확인일 2026-11-06) ↩︎

  7. Claude Code 공식 문서, 「Automate actions with hooks」. "If your settings file already has a hooks key, add Notification as a sibling of the existing event keys rather than replacing the whole object." code.claude.com (확인일 2026-11-06) ↩︎

  8. Claude Code 공식 문서, 「Automate actions with hooks」. "Type /hooks at the Claude Code prompt to open the hooks browser." / "Run /hooks and confirm the hook appears under the correct event" code.claude.com (확인일 2026-11-06) ↩︎

  9. Claude Code 공식 문서, 「Automate actions with hooks」. "Verify your JSON is valid: trailing commas and comments aren't allowed" code.claude.com (확인일 2026-11-06) ↩︎

  10. Claude Code 공식 문서, 「Automate actions with hooks」. .claude/settings.json 행의 공유 여부 칸: "Yes, can be committed to the repo" code.claude.com (확인일 2026-11-06) ↩︎

  11. Claude Code 공식 문서, 「Run Claude Code programmatically」. "Without --bare, a -p session runs the hooks in a project's .claude/settings.json and connects the servers in its .mcp.json, even in a folder you've never trusted." code.claude.com (확인일 2026-11-06) ↩︎

  12. Claude Code 공식 문서, 「Plugins overview」. "Whatever the tier, a plugin you install can run code with your user privileges." code.claude.com (확인일 2026-11-06) ↩︎

  13. Claude Code 공식 문서, 「Customize your status line」. "The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure." code.claude.com (확인일 2026-11-06) ↩︎

  14. Claude Code 공식 문서, 「Customize your status line」. "Add a statusLine field to your user settings (~/.claude/settings.json, where ~ is your home directory) or project settings." code.claude.com (확인일 2026-11-06) ↩︎

  15. Claude Code 공식 문서, 「Customize your status line」. "Until you accept the workspace trust dialog, the status line stays blank." / "Because statusLine executes a shell command" code.claude.com (확인일 2026-11-06) ↩︎

  16. Claude Code 공식 문서, 「Customize your status line」. "The /statusline command accepts natural language instructions describing what you want displayed." code.claude.com (확인일 2026-11-06) ↩︎

  17. Claude Code 공식 문서, 「Output styles」. "An output style is a set of instructions that sets Claude's role, tone, and response format for every response in a session." / "Responses lead with the result and leave out preamble, narration, and recaps" code.claude.com (확인일 2026-11-06) ↩︎

  18. Claude Code 공식 문서, 「Configure your terminal for Claude Code」. "Use the /theme command, or the theme picker in /config, to choose a Claude Code theme that matches your terminal." code.claude.com (확인일 2026-11-06) ↩︎