하네스 엔지니어링

부탁 vs 강제,
무엇이 다른가?

프롬프트 엔지니어링은 에이전트에게 "이렇게 해줘"라고 부탁하는 것이고, 하네스 엔지니어링은 규칙을 어기면 도구 자체가 실행되지 않도록 만드는 것입니다.

책 챕터 작성에
워크플로 강제 걸기

"아웃라인 없이 초안 작성 불가"라는 규칙을 Hook으로 구현합니다. Claude가 아무리 시도해도, outline.md가 없으면 draft.md를 쓸 수 없습니다.

규칙을 코드로 만들기

#!/bin/bash

# stdin으로 들어오는 JSON 파싱
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

# draft.md 작성 시도를 감지
if [[ ("$TOOL_NAME" == "Write" || \
      "$TOOL_NAME" == "Edit") && \
     "$FILE_PATH" == *"/draft.md" ]]; then

  # 같은 폴더에서 outline.md 확인
  CHAPTER_DIR=$(dirname "$FILE_PATH")
  OUTLINE="$CHAPTER_DIR/outline.md"

  if [[ ! -f "$OUTLINE" ]]; then
    echo "⛔ outline.md가 없습니다."
    echo "   아웃라인을 먼저 작성해주세요."
    exit 2  # ← 도구 실행 차단!
  fi
fi

exit 0  # ← 통과

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "command",
          "command": "bash .claude/hooks/require-outline.sh"
        }
      ]
    }
  ]
}

문체 윤문도
Hook으로 강제할 수 있다

아웃라인 검사는 "파일이 있냐 없냐"라서 bash로 충분했지만, 문법 교정이나 문체 일관성은 자연어 판단이 필요합니다. 이럴 때 prompt 타입 Hook을 쓰면 됩니다.

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "방금 작성된 파일이 draft.md라면,
다음 문체 규칙을 위반했는지 검사하세요:

1. '~합니다/~됩니다'만 반복하는 딱딱한 문어체 금지
   → '~거든요', '~더라고요', '~예요' 같은 구어체 사용
2. 'XXX의 장점:' 뒤에 불릿 리스트 나열 금지
   → 자연어로 흐름을 이어갈 것
3. '또한', '뿐만 아니라', '이를 통해' 같은 AI 표현 금지

위반이 있으면 구체적 위치와 수정 제안을 반환하세요.
위반이 없으면 'approve'를 반환하세요."
        }
      ]
    }
  ]
}

세 가지 신호만 기억하세요

Hook이 작동하는 순간

Claude는 어떻게 반응할까?

Hook이 차단하면 Claude는 피드백 메시지를 읽고 스스로 우회 경로를 찾습니다.

outline.md는 draft.md가 아니므로 Hook에 걸리지 않아 자유롭게 생성됩니다.

코드가 어려우면?
자연어로 Hook을 만들 수 있다

bash 스크립트나 settings.json 문법이 낯설어도 걱정 없습니다. Claude Code에게 자연어로 Hook을 설계해달라고 요청하면 됩니다.