하네스 엔지니어링
hooks · permissions · skill

Session 4 · 하네스 엔지니어링 — 규약으로 강제하기

hooks 이벤트 6종 · permissions allow/deny · Statusline · Custom Skill · Slash Command · hook·slash·skill 각 1개 직접 제작

강사 박수현 · 🚀 젠아이랩스(GenAI Labs)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a triangle with three vertices labeled 'Prompt', 'Context', and 'Harness'. The 'Harness' vertex is highlighted brightly, glowing with teal light, while the other two vertices are dimmer. Around the harness vertex, small icons float: a small gear labeled 'Hook', a lock labeled 'Permission', and a scroll labeled 'Skill'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

Session 4 · 하네스 엔지니어링 — 규약으로 강제하기

Claude Code 5계층 세팅 — 우선순위 순

확장 5계층 — 컨텍스트를 언제·얼마나 차지하는가

같은 5계층을 컨텍스트 점유 축으로 다시 세우면 "무엇을 넉넉히 두고 무엇을 아껴야 하는지" 가 보인다.

PART 1

하네스 엔지니어링이란 — 세 번째 축

하네스의 정의 · Claude Code 하네스 5개 개념 · 개인·프로젝트·로컬 3층 스코프.

세 축의 지도 — 프롬프트 · 컨텍스트 · 하네스

AI 코딩을 다루는 기술은 세 축으로 정리된다. 축마다 초점이 다르고, 뒤의 축이 앞의 축을 감싼다.

오늘 서 있는 자리는 가장 바깥 고리 — 셸 · Git · Docker · 테스트 · 브라우저 · DB · MCP 가 걸리는 실행 환경

하네스란 무엇인가 — 묶어서 함께 일하게 하는 장치

harness 는 원래 여러 장비를 하나로 묶어 함께 동작하게 하는 장치 를 뜻한다. 말 마구, 등반·작업용 안전벨트 하네스, 소프트웨어의 테스트 하네스 — 전부 같은 발상이다. AI 코딩의 하네스도 두 층위로 나눠 보면 정확해진다.

"Flask 할 일 앱 만들어줘" — 한 줄 뒤에 벌어지는 일

이 한 줄이 들어가면 실제로 일어나는 일을 펼쳐 보면, 사람이 준 몫과 하네스가 한 몫이 갈린다.

Claude Code 하네스 5개 개념 — 오늘 목차

스코프 5축 지도 — 파일별 위치 · 좁은 스코프가 이긴다

PART 2

Hooks — 세션 이벤트에 셸을 매다는 장치

훅의 정의 · 발동 카덴스 · 실습에서 다루는 이벤트 6종 (공식 30+ 중 실무 핵심) · JSON 구조 · 실전 예 2개 (lint · 커밋 게이트).

훅이란 — 세션 이벤트에 셸을 매다

📖 Claude Code Hooks: Complete Guide to All 12 Lifecycle Events

프롬프트 vs 훅 — 확률적 규칙 vs 결정론적 규칙

실습에서 다루는 훅 이벤트 6종 — 실무 핵심 6개 + 소수 확장

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a horizontal timeline arrow going from left to right, labeled 'Session Timeline'. Along the timeline, six luminous dots are placed with labels above them, in order from left to right: 'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Notification', 'Stop'. Each dot has a small line to a tiny icon representing its action (a magnifier for prompt, a shield for pretool, a wrench for posttool, a bell for notification, a stop sign for stop). Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

훅 이벤트 6종 — 세션 타임라인 위 어디에 붙는가

매 턴 실행 loop — 훅이 걸리는 자리를 한 장에

핵심 대비 — PreToolUse vs PostToolUse

훅 JSON 구조 — settings.json 아래 hooks 키

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

실전 훅 예 ① — 파일 수정 후 자동 lint

목표. Python 파일 수정 시 즉시 ruff lint · format. ~/.claude/settings.json (개인 스코프).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path' <<< \"$CLAUDE_HOOK_INPUT\"); if [[ \"$path\" == *.py ]]; then ruff check --fix \"$path\" && ruff format \"$path\"; fi"
          }
        ]
      }
    ]
  }
}

실전 훅 예 ② — 커밋 시 테스트 자동 실행 (PreToolUse)

목표. git commit 직전 pytest 실행, 실패 시 커밋 차단. <repo>/.claude/settings.json (프로젝트 · 팀 공유).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(jq -r '.tool_input.command' <<< \"$CLAUDE_HOOK_INPUT\"); if [[ \"$cmd\" == *'git commit'* ]]; then pytest -x --tb=short || exit 2; fi"
          }
        ]
      }
    ]
  }
}

Hook 실용 예 ③ — 위험 명령 사전 차단 (PreToolUse Bash)

목표. AWS 리소스 삭제 · 프로덕션 DB 파괴 명령을 Claude 가 실행하기 직전에 차단. Bash 도구에 훅을 걸어 외부 파이썬 검문 스크립트를 태운다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/danger_guard.py" }
        ]
      }
    ]
  }
}

Hook 실용 예 ③ — ~/.claude/hooks/danger_guard.py

#!/usr/bin/env python3
import json, sys, re

cmd = json.load(sys.stdin).get("tool_input", {}).get("command", "")
DANGER = [
    r"\brm\s+-rf\s+/",
    r"\bterminate-instances\b",
    r"\bDROP\s+(TABLE|DATABASE)\b",
    r"\bkubectl\s+delete\s+ns\b",
]
for pat in DANGER:
    if re.search(pat, cmd, re.I):
        print(f"차단: 위험 명령 감지 → {pat}", file=sys.stderr)
        sys.exit(2)
sys.exit(0)

Hook 실용 예 ④ — 커밋 전 스테이지 쓰레기 검사

목표. git commit 을 감지하면 스테이지된 diff 를 훑어 API 키 · "TODO remove" · 디버그 print 등 커밋되면 안 될 것들을 잡아낸다.

~/.claude/hooks/commit_scan.py.

#!/usr/bin/env python3
import json, sys, subprocess, re

cmd = json.load(sys.stdin).get("tool_input", {}).get("command", "")
if "git commit" not in cmd:
    sys.exit(0)
diff = subprocess.run(["git", "diff", "--cached"], capture_output=True, text=True).stdout
PATTERNS = {
    "OpenAI key":  r"sk-[A-Za-z0-9]{20,}",
    "AWS key":     r"AKIA[0-9A-Z]{16}",
    "TODO remove": r"TODO.*remove",
    "print debug": r"^\+\s*print\(.+debug",
}
hits = [n for n, p in PATTERNS.items() if re.search(p, diff, re.M)]
if hits:
    print(f"차단: 스테이지에 {', '.join(hits)} 흔적", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

Hook 실용 예 ⑤ — 긴 작업 완료 알림 (Stop)

목표. 응답을 마치는 순간 데스크톱 알림. 긴 작업을 맡겨 두고 다른 일을 하다 알림을 받는다 — 체감 효과가 가장 큰 훅.

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/notify.sh" } ] }
    ]
  }
}

~/.claude/hooks/notify.sh — OS 분기.

#!/usr/bin/env bash
title="Claude Code"; msg="응답 완료"
case "$(uname -s)" in
  Darwin) osascript -e "display notification \"$msg\" with title \"$title\"" ;;
  Linux)  notify-send "$title" "$msg" ;;
  MINGW*|MSYS*|CYGWIN*)
    powershell -Command "[reflection.assembly]::LoadWithPartialName('System.Windows.Forms'); \
      [System.Windows.Forms.MessageBox]::Show('$msg','$title')" ;;
esac

Hook 실용 예 ⑤ — 완료 알림 · 왜 유용한가 · 확장

PART 3

Permissions — allow · deny 리스트로 사전 차단

훅이 "이벤트 반응" 이라면 permissions 는 "규칙 리스트로 사전 차단" · 세밀 문법 · 팀 규약 3원칙 · 프로젝트 초안 템플릿.

Permissions 세 축 — allow · deny · ask

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log:*)",
      "Bash(pytest:*)",
      "Read(./src/**)",
      "WebFetch(domain:docs.python.org)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(gh pr create:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "WebFetch(domain:*.internal.company.com)"
    ]
  }
}

Permissions 문법·원칙 — Tool(spec) · deny → ask → allow

세밀 제어 — Bash · WebFetch · MCP · Read/Edit/Write

팀 규약 3원칙 — permissions 로 팀 안전선 긋기

프로젝트 permissions 실전 템플릿 — <repo>/.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(git status)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git branch:*)",
      "Bash(ls:*)", "Bash(cat:*)", "Bash(pytest:*)", "Bash(ruff:*)",
      "Read(./**)", "Edit(./src/**)", "Edit(./tests/**)",
      "WebFetch(domain:docs.python.org)", "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(rm -rf:*)", "Bash(sudo:*)", "Bash(curl:*)", "Bash(wget:*)",
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Edit(./.env)", "Edit(./.env.*)"
    ]
  }
}

PART 4

Statusline · Custom Skill · Slash Command

하단 상태표시줄 커스터마이즈 · 자율 발동 skill · 명시 호출 slash · 개인 규약 자동화 4선.

Statusline — 하단 상태표시줄 · settings.json

Statusline 은 세션 하단에 뜨는 상태 줄. 기본은 디렉토리·git 브랜치·모델명. 스크립트로 원하는 정보를 붙일 수 있다.

~/.claude/settings.json 등록.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Statusline 스크립트 — ~/.claude/statusline.sh

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(echo "$input" | jq -r '.workspace.current_dir' | sed "s|$HOME|~|")
branch=$(git -C "$(echo "$input" | jq -r '.workspace.current_dir')" branch --show-current 2>/dev/null)
echo "[$model] $dir ${branch:+@$branch}"

Custom Skill — SKILL.md 스켈레톤 · 자율 발동

Custom Skill 은 재사용 지시 묶음. 마크다운 한 장에 "이런 상황에 이렇게 처리" 를 담아 두면 Claude 가 해당 상황에서 자율 발동 한다.

---
name: korean-comment-cleaner
description: >
  Python·JavaScript·TypeScript 코드의 한글 주석을 정리한다.
  띄어쓰기·문장 부호 통일, 오래된 TODO 정리, 중복 주석 제거.
  코드에 한글 주석이 섞여 있을 때 자동 발동.
---

# korean-comment-cleaner

## 발동 조건
- 사용자가 "한글 주석 정리" 를 요청
- Edit·Write 로 수정하는 파일에 한글 주석이 다수 포함

## 처리 규칙
1. **띄어쓰기** — 조사 앞은 붙이고, 관형·명사 사이는 띄운다.
2. **문장 부호** — `.` 은 문장 끝에만, 목록은 `-` 로 통일.
3. **TODO** — `TODO:` 뒤 6개월 이상 오래된 것은 로그로 옮기고 제거.
4. **중복** — 같은 함수 안 같은 뜻 주석 2개 이상이면 하나로 합친다.

## 안전 규칙
- 주석의 **의미** 를 바꾸지 않는다. 표현만 정리.
- 라이선스 헤더 · 저작권 문구는 건드리지 않는다.
- 수정 결과는 diff 로 사용자에게 먼저 보인다.

Skill 스켈레톤 3요소 · 파일 배치 · 스코프

~/.claude/skills/
└── korean-comment-cleaner/
    ├── SKILL.md          # 필수
    ├── example.py        # 선택
    └── glossary.md       # 선택

📖 Claude Code · Extend Claude with skills · Anthropic · How to create custom skills

Slash Command — ~/.claude/commands/<name>.md

Slash command 는 사용자가 명시 호출하는 재사용 프롬프트. skill 과 달리 자율 발동하지 않아 예측 가능성이 필요할 때 유리. 최소 예 ~/.claude/commands/summarize.md (/summarize).

---
description: 현재 리포의 최근 커밋 5개를 3줄로 요약
allowed-tools:
  - Bash(git log:*)
  - Read(./**)
---

다음을 실행한다:

1. `git log --oneline -5` 로 최근 5개 커밋 확인.
2. 각 커밋의 diff 를 훑고, 무엇을 바꿨는지 한 줄로 요약.
3. 전체를 **3줄** 로 압축해 응답. 첫 줄은 주제, 나머지 두 줄은 근거.

한국어로 답한다.

📖 Claude Code Slash Commands (2026)

개인 규약 자동화 4선 — 네 개념 조합 실전

PART 5

미니 실습 — hook · slash · skill 각 1개

참여자 각자가 자기 홈에 hook · slash · skill 각 1개를 만들고 동작을 확인한다. 순서대로 진행. 실패해도 다음으로 넘어가고 마지막에 트러블슈팅.

실습 ① — 개인 hook

목표. 커밋 직전 자동 게이트(테스트·lint), 실패 시 차단.

단계.

mkdir -p ~/.claude
touch ~/.claude/settings.json

PART 2 의 훅 JSON (PreToolUse · matcher: "Bash" · git commit 감지 시 pytest) 을 ~/.claude/settings.json 에 병합. pytest 를 자기 리포의 lint · 테스트 명령으로 교체 가능. 세션 재시작 후 리포에서 > git commit -m "test" 시도.

실습 ② — 개인 slash command

목표. /status 호출 시 리포 상태·최근 커밋·브랜치·미커밋 파일을 3줄 요약.

mkdir -p ~/.claude/commands

~/.claude/commands/status.md.

---
description: 현재 리포의 상태를 3줄로 요약
allowed-tools:
  - Bash(git status)
  - Bash(git log:*)
  - Bash(git branch:*)
---

`git branch --show-current` · `git status --short` · `git log --oneline -3` 을 실행한다.
결과를 **정확히 3줄** 로 요약: 1줄 브랜치·미커밋 파일 수, 2줄 최근 커밋 3개 주제,
3줄 다음 액션 한 문장. 한국어로 답한다.

실습 ③ — 개인 skill

목표. korean-comment-cleaner skill 을 만들어 한글 주석 정리 요청 시 자율 발동.

단계.

mkdir -p ~/.claude/skills/korean-comment-cleaner

PART 4 의 SKILL.md 를 그대로 위 폴더에 저장. 세션에서 다음을 입력.

> src/main.py 의 한글 주석을 정리해줘

실습 정리 · 체크리스트

PART 6

정리 — 한 문장 결론

프롬프트 · 컨텍스트 · 하네스 세 축 — 오늘의 한 문장.

마무리 — 한 문장으로

"매 세션 반복하는 손을 규약으로 옮기는 것 — 그게 하네스다."

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a bold triangle with three vertices labeled 'Prompt', 'Context', and 'Harness'. All three vertices glow equally bright with teal and purple light, connected by luminous edges forming a solid shape. In the center of the triangle, a small keyboard icon with the text 'settings.json' sits as the foundation. A subtitle at the bottom reads 'Three Axes of Vibe Coding'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."