Claude 원정대(송곳 만들기)

하네스 엔지니어링이란 개념을 클로드 코드를 통해 설명하는 글이에요

AI 접근법의 발전

최근 몇 달간 AI얘기로 떠들썩했었죠? 프롬프트 엔지니어링 -> 컨텍스트 엔지니어링 -> 하네스 엔지니어링 순으로 관심이 이동된 걸로 기억합니다.

프롬프트 엔지니어링은 AI에게 한 번의 요청으로 어떻게 원하는 결과를 얻을 수 있을까? 가 중점이었다면

컨텍스트 엔지니어링은 AI에게 어떤 데이터를 넣어야 더 좋은 결과가 나올 것인지, 어떻게 AI가 실행 중에 필요한 정보를 찾아서 쓸 수 있게 할지가 중점이었습니다.

하네스 엔지니어링은 AI가 어떤 제약과 흐름 속에서 작업을 수행할지, 그리고 툴 호출이나 실패 처리까지 포함한 실행 방식을 통제하는 환경을 다루는 개념입니다.

세 가지가 성격이 다르죠? 위 두개는 AI가 어떻게 생각하고 어떤 정보를 바탕으로 답할지를 다룬다면, 하네스는 이 모델이 어떤 환경 속에서 실행될지를 다뤄요

 

따라서 세 가지를 발전 과정으로 보는 것이 아닌, AI의 작업 환경이 확장된다는 개념으로 이해하는 것이 적절합니다.

하네스 엔지니어링

AI에 목줄 채우기

그 중 저는 하네스 엔지니어링에 집중해서 글을 작성했습니다. 최근 가장 많은 관심을 받은 이 하네스라는 용어를 제가 정확히 이해하지 못했거든요.

 

harness(마구)라는 단어 그대로, 비결정성이 있는 AI의 동작을 일정한 제약과 흐름 안으로 통제하는 방법입니다. 단순히 위험한 영역에 대한 권한을 제한하는 것을 넘어서, 실행 흐름과 도구 사용까지 제어하여 사용자가 기대하는 방향으로 결과를 낼 수 있게 됩니다.

"솔직히 그거, 원래 있던 개념 있어보이게 말한 거 아니야?"

러한 환경 조성은 프로젝트를 시작하기 전에 사람이 미리 정의해두던 과정과 크게 다르지 않습니다. 단지 대상이 사람에서 AI로 바뀐 것일 뿐이니까요

 

그렇지만 공학에서 용어는 단순한 이름이 아니라, 문제를 바라보는 관점을 정리하는 도구라고 생각합니다. 모든 개념이 새롭게 만들어지는 것은 아니지만, 특정한 문제를 명확하게 다루기 위해 새로운 이름이 붙는 경우는 많습니다.

 

하네스 엔지니어링이라는 용어 역시 AI를 하나의 시스템 구성 요소로 보고, 이를 어떻게 통제하고 실행할 것인지에 대한 문제를 명확히 드러내기 위해 등장했습니다.

 

그렇다면 왜 지금 이 개념이 주목받고 있는지, 그리고 기존 방식과 무엇이 다른지 살펴볼까요?

하네스를 사용하지 않는다면

하네스가 없는 상황에서 AI의 실수

프롬프트나 컨텍스트만으로 작업을 구성할 때는, 한 번의 요청과 응답에 많은 것을 의존하게 됩니다. 이러한 방식에서는 결과가 기대와 어긋났을 때, 사람이 직접 다시 요청을 구성하거나 수정해야 하니까요.

 

반면 하네스를 도입하면, 작업이 하나의 고정된 흐름으로 검증을 수행하고, 실패 시 자동으로 수정이나 재시도가 이루어지는 구조를 만들 수 있습니다. 이로서 결과의 품질을 일정 수준 이상 유지되도록 만들 수 있게 됩니다.

 

만약 하네스를 사용하지 않는다면 어떻게 될까요?

 

위 사진은 하네스를 사용하지 않을 때 AI가 실수하던 예시인데요, 브랜치 전략으로 main 브랜치에 push 금지 규칙을 지시했지만, 작업을 하며 지시 사항이 밀려나가 접근하지 못하게 되고 admin 권한으로 밀어버린 상황이었습니다.

 

이렇게 하네스라는 작업 지침이 없다면 AI모델이 사용자의 예상 내에 결과를 벗어나는 작업을 하게 됩니다.

클로드 코드의 hooks

하네스를 떠올렸을 때 가장 먼저 눈에 띄는 요소는 제약이었습니다. 하네스는 언제 어떤 모델을 호출할지 어떤 흐름으로 작업을 진행할지, 실패시 어떻게 처리할지 등 여러 요소가 합쳐진 구조이지만 제약과 통제에 관련된 부분은 비교적 직관적으로 이해하기 쉬워 이 부분을 중심으로 살펴보았습니다.

 

보통 저희가 프로젝트를 할 때, 컨벤션을 정하게 되는데 아래와 같이 두 가지의 컨벤션이 있다고 생각해보겠습니다.

1. any 타입 금지
2. 이벤트를 다루는 함수는 handle 을 붙이기

1번의 경우는 tsconfig 로 코드내에서 강제할 수 있는 컨벤션이지만, 2번은 사람이 직접 코드를 보고 해당 함수가 이벤트를 다루는지 판단해야 합니다.

이러한 두 컨벤션을 AI에게 지키게하여 프로그램을 작성하게 한다면 우리는 어떤 방식으로 통제를 시켜야 할까요?

통제의 기준

클로드 코드에서는 hooks 를 통해 프로그램이 실행되는 특정 시점마다 원하는 검사를 할 수 있게 지원합니다 .

 

hook 은 크게 두 가지로 구분됩니다.

- 강제적 통제: 명령어 쉘(.sh)을 통해 실행을 중단시키거나 제어

- 지침 기반 통제: 컨텍스트(context)를 통해 클로드가 스스로 판단할 수 있도록 유도

 

any 타입 사용 여부처럼 명확하게 검사 가능한 조건은 스크립트를 통해 실행을 중단시키는 방식으로 처리할 수 있습니다.

이벤트를 다루는 함수처럼 의미를 기반으로 판단해야 하는 규칙은 모델이 해당 규칙을 인식하고 스스로 판단하도록 컨텍스트를 주입해야 합니다.

Hooks: settings.json 예시

스크립트 방식과 지침기반 방식의 예시를 보여드리겠습니다.

1. 스크립트 방식에서의 예시

아까 예시 1번을 검사하는 로직의 예를 간단하게 보여드리겠습니다.

클로드코드의 에이전트 루프가 실행되기 전의 이벤트(PreToolUse)에서 차단하는 코드입니다.

// .claude/settings.json 
{
  "hooks": {
    "PreToolUse": [    // 루프 중 어느 이벤트에서 시작할 지 (밑에서 설명)
      {
        "matcher": "Edit|Write",   // 수정 또는 작성에서 실행
        "hooks": [
          {
            "type": "command",  // 쉘을 시작할 때
            "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/check_any.sh\"",
             // 실제 검사 로직 스크립트의 위치
            "timeout": 30  // 30초안에 안 끝나면 실패
          }
        ]
      }
    ]
  }
}

위와 같은 setting.json으로 아래의 쉘 스크립트를 실행합니다.

#!/bin/bash
# .claude/hooks/check_any.sh

# TypeScript 타입 체크 실행 (실제 파일 생성 없이 체크만 수행)
npm run type-check # 내부적으로 tsc --noEmit 실행 가정

if [ $? -ne 0 ]; then
  echo "타입 체크에 실패했습니다. any 타입 사용 혹은 타입 오류를 해결하세요." >&2
  exit 2  # exit 2: Claude에게 에러 메시지를 전달하고 작업을 차단
fi

exit 0  # 통과 시 작업 계속 허용

ts에서 제공하는 타입 검사를 직접 실행하도록 강제하고 실패 했을 때와 성공했을 때의 흐름을 정의할 수 있게 됩니다.

 

exit 2 를 보시면 통과를 못했을 시, 클로드에게 &2(err message)의 메세지가 클로드에게 전달되어 원인을 인식하게합니다.

이러한 스크립트 방식은 프리터나 린터를 사용하는 것과 같이 물리적으로 차단이 되는 환경을 조성할 수 있습니다.

2. 지침기반 방식에서의 예시

클로드가 컨벤션을 지키게 하기 위해 세션 시작이나 프롬프트 제출전에 규칙을 주입하거나, 코드 작성이 끝난 후 검사할 수 있도록 마지막에 주입하게됩니다.

세션이나 프롬프트 시작마다 규칙을 주입하는 것은 세션이 길어지면 지침이 밀려날 수 있기 때문에 컨벤션의 중요도를 고민해보고 어느 시점에 주입할 지 결정하면 좋겠습니다.
(매번 주입하면 좋겠지만 토큰소모량도 증가하고, 앞선 컨텍스트들이 밀려나 참조를 못하게 됩니다)

아래는 프롬프트 종료하고 검사를 시키고 알아서 고치게 할 수 있는 훅의 예시입니다.

// .claude/settings.json
{
  "hooks": {
    "Stop": [     // 발동 이벤트 시점
      {
        "hooks": [
          {
            "type": "prompt",  // 아깐 쉘이었지만 이번엔 모델에게 텍스트 전달
            "prompt": "작성된 코드에서 이벤트 처리 함수가 'handle' 접두어 없이 'on'으로 시작하는 경우가 있으면 알려주고 수정해줘. $ARGUMENTS"
            // 모델에게 텍스트를 직접 전달 
          }
        ]
      }
    ]
  }
}

작업 종료 시, 마지막으로 점검할 수 있게합니다. 세션이 끝날 때 명확하게 지시하여 작성한 코드를 다시 검사하게 유도하지만 모델이 규칙을 잘못 판단하거나 놓칠 가능성이 생깁니다.

훅의 이벤트 종류

클로드 공식 문서에서 알려주는 훅의 라이프 사이클입니다.

관련 문서를 보면 어마어마한 숫자의 이벤트가 있지만 필요할 때 찾아보면 되니, 크게 세가지로만 설명하려고 합니다.

 

1. 세션 단위: 세션이 시작되거나 끝날 때 한 번 실행시작과 끝의 SessionStart, SessionEnd

 

2. 턴 단위: 사용자가 프롬프트를 보내거나 Claude가 응답을 마칠 때마다 실행

UserPromptSubmit : 프롬프트 제출 시, Stop : 클로드 답변 이후

 

3. 툴 호출 단위: 클로드가 도구를 호출할 때마다 실행

- 여기서 도구란? 파일 읽기나 수정, 명령어 등 실행할 때 (matcher 로 체크 Edit, Write)

PreToolUse : 도구 실행 전 이벤트

PostToolUse : 도구 실행 성공 이후 이벤트

 

이러한 훅 라이프 사이클을 보면 클로드 코드가 작업하는 부분 중 어느 시점에 개입할 수 있을 지 결정할 수 있습니다.

CLAUDE.md

클로드 코드에서는 세션이 시작될 때 CLAUDE.md라는 파일의 내용이 기본 컨텍스트로 주입됩니다.이 덕분에 CLAUDE.md는 프로젝트 전반에서 항상 참고되는 일종의 기본 지침서로 사용하게 됩니다.

 

처음에 이를 설명하지 않은 이유는, CLAUDE.md 자체보다 실제로 어떻게 통제하고 개입하는지가 더 중요하다고 생각했기 때문입니다. 다만 어느 정도 클로드를 사용해본 사람이라면 “컨벤션이나 룰을 CLAUDE.md에 넣어두면 되는 것 아닌가?”라는 의문이 들 것 같은데요.

 

CLAUDE.md는 세션 시작 시 한 번 적용되는 반면, Hooks는 세션 시작, 프롬프트 실행 전, 작업 완료 후 등 다양한 시점에서 개입할 수 있습니다. 이 차이 때문에 Hooks를 통해 더 세밀한 통제가 가능해지고, 그리고 AI의 안으로 주입되는 Claude.md와 다르게 Hooks는 AI의 밖에서 제어를 하는 외부 장치이기 때문에 강력한 통제가 가능해집니다.

RULES.md

그럼 rules 와 hooks에서 컨텍스트를 주입하는 것이 똑같다고 느껴질 수 있다고 생각합니다.

컨텍스트의 정보를 모델에게 주입한다는 점에서 동일한 부분이 있지만 서로 잘하는 것이 다르다고 생각하시면 좋겠습니다.

 

hooks가 잘하는 건 동적인 상황에서 이벤트기반으로 흐름 제어를 할 수 있는 거라고 생각합니다.

파일이 바꼈을 때, 실시간의 데이터베이스를 가져오고 싶을 때, 외부 MCP에서 데이터가 도착했을 때 이렇게 동적으로 어느 시점에 행동을 결정할 수 있습니다.

rules는 실행 흐름을 제어한다기 보단 AI에게 미리 정보를 주입하는 역할을 합니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙

- 모든 API 엔드포인트는 입력 검증을 포함해야 합니다
- 표준 오류 응답 형식을 사용합니다
- OpenAPI 문서 주석을 포함합니다

해당 규칙 마크다운 파일을 만들었을 때 클로드 코드는 파일을 읽을 때, rules 디렉토리 아래의 path들을 검사하고 만들어놓은 규칙을 적용하여 작업을 시작할 수 있습니다.

 

물론 컨텍스트기 때문에 강제성이 없지만 hooks보다 토큰이 적게들고(외부 프로세스에서 제어) 설정도 단순하고, 자연어로 작성되어 모델의 판단에 따라 사용할 수 있다는 점으로 더 많이 사용되곤 합니다.

 

그래서 모델을 설득해야한다면 rules, 통제해야한다면 hooks로 결정하면 됩니다.

추가) HOOKS는 클로드 코드만 가능한가요?

hooks는 클로드 코드의 특징이라고 할 수 있는 부분인데요. 물론 다른 AI 에이전트 프레임워크에서도 훅이 있습니다

 

클로드 코드의 hooks는 다양한 이벤트를 지원하고 ( Claude:28개, Codex: 6개)

MCP와 연결했을 때의 이벤트까지 지원하여 에이전틱 워크플로우(여러 AI가 협력하여 목표를 해결)를 지원합니다.

Codex의 공식 문서

그렇다고 클로드가 더 뛰어나다는 얘기가 아니라 각자 집중하는 방향이 다르다고 할 수 있습니다. 코덱스는 훅보다는 샌드박스를 주로 사용하고, 실행 환경의 경계를 강하게하여 작업 범위를 격리 시키는 방법으로 제어합니다.

마무리

하네스를 설명하기 위해 하네스의 일부분의 기능인 hooks 를 집중적으로 설명했습니다.

 

처음 하네스에 대해 얻은 인상은 다른 모델을 써도 같은 결과를 뽑아내는 법인줄 알았는데, 모델의 성능이나 자체를 무시할 수 있는 수준은 아니었습니다. 그냥 모델의 작업 결과를 검증하여 불확실성한 AI를 일정한 범위로 통제할 뿐이었습니다.

 

그리고 어떻게 통제를 잘 시킬가에 대한 고민은 AI의 활용 능력보다는 어떻게 프로젝트를 잘 설계할 것인가가 중요하다고 느꼈습니다.

---

공식 문서 링크

- https://code.claude.com/docs/en/hooks

- https://developers.openai.com/codex/hooks