하네스 엔지니어링 뜻과 방법, 프롬프트 대신 규칙을 강제하는 법

하네스 엔지니어링은 AI 에이전트가 사람이 만든 규칙과 검사 장치 안에서만 일하도록 환경을 짜는 방법입니다. 이 글은 YC CEO 게리 탄이 공개한 gstack 사례로 그 뜻과 원칙을 정리하고, 클로드 코드에서 첫 장치를 실제로 거는 설정 예시까지 붙였습니다. 프롬프트를 아무리 다듬어도 AI가 같은 실수를 반복한다면 읽어 볼 만합니다.

하네스 엔지니어링이 나온 배경

"프롬프트를 잘 써야 한다"는 조언은 이제 그만 듣자는 이야기로 시작하는 영상입니다. 채널은 마일드코드, 16분 남짓. Y Combinator CEO 게리 탄이 공개한 오픈소스를 사례로 들어, 상위 사용자들이 실제로 무엇을 만들고 있는지를 설명합니다. 여기서 하네스(harness)는 원래 말에 채우는 마구를 뜻하는 말로, AI라는 힘센 말을 원하는 방향으로 끌고 가는 장치 전체를 가리킵니다.

아래 사례, 수치, 판단은 영상 화자가 말한 내용입니다. 영상 후반부는 화자 본인의 유료 강의 홍보이고, 해당 대목은 본문에서 따로 표시했습니다.

상위 0.1~1%는 프롬프트를 다듬지 않는다

출발점은 이렇습니다. 지금까지 우리는 "프롬프트를 잘 써야 한다", "질문을 잘해야 한다"는 쪽으로만 접근해 왔다는 것.

그런데 상위 0.1~1% 사용자는 그렇게 바이브 코딩(코드를 직접 읽지 않고 AI에게 말로 시켜 프로그램을 만드는 방식)하지 않는다는 게 화자의 주장입니다. 그들이 하는 건 다릅니다. 하네스를 설계하고 루프를 만들어서, AI 에이전트(스스로 여러 단계를 나눠 일하는 AI)가 의도와 목적에 맞게 스스로 판단해 최고의 결과를 내도록 환경을 짭니다.

그래서 첫 권유는 단순합니다. 프롬프트를 넣어 놓고 AI가 일하는 걸 지켜보고만 있지 말라는 것.

게리 탄의 gstack, 하네스 엔지니어링 사례

Y Combinator는 세계 최고의 실리콘밸리 투자사이자 액셀러레이터(초기 스타트업을 뽑아 키우는 회사)이고, 이전 대표는 지금 오픈AI를 이끄는 샘 올트먼이었다고 화자는 소개합니다.

현 CEO 게리 탄의 이력도 짚습니다. 스탠퍼드 컴퓨터공학을 나와 팔란티어에서 일했고, 블로그 서비스 Posterous를 창업해 트위터에 엑시트(회사를 팔아 투자금을 회수)했습니다.

그 게리 탄이 자기가 직접 만들어 쓰는 워크플로를 깃허브에 오픈소스로 공개했고, 깃허브 스타 10만 개가 넘으며 세계적으로 바이럴이 됐다는 설명입니다. 이 스타 수치는 화자 발화 기준이고, 영상에서 측정 시점이나 출처를 밝히지는 않습니다.

저장소 이름은 gstack입니다. 깃허브나 검색창에 "garry tan gstack"을 치면 찾을 수 있습니다.

23개 역할로 짜인 에이전트 팀

게리 탄이 미리 설계해 둔 건 프롬프트가 아니라 역할이었다는 게 화자의 설명입니다.

• CEO: 제품 전체를 총괄하고 다른 에이전트를 관리
• 엔지니어링 매니저: 아키텍처를 설계하고 감독
• 마케터: 제품의 홍보와 판매를 책임짐

이런 식으로 총 23개 역할의 에이전트 팀을 구성했다고 합니다. 영상에서 이름과 함께 언급된 역할은 위 세 개와 리뷰어 역할인 /review이고, 나머지 스무 개의 목록은 나오지 않습니다.

그리고 이 역할들이 생각, 계획, 제작, 상호 리뷰, 테스트, 배포, 회고의 사이클을 돌도록 루프가 설계돼 있다는 것.

여기서 실천 제안이 나옵니다. 프롬프트 고민에 쓰던 시간을 잠시 내려놓고, "우리 팀에서 누가 어떤 책임과 역할로 일할지"부터 정의하라는 겁니다.

부탁이 아니라 강제하는 결정론적 장치

역할을 나눴다고 해서 항상 의도대로 지켜지지는 않습니다. 화자도 이걸 인정하고 다음 층으로 넘어갑니다. 더 시스템적이고 결정론적인 장치가 필요하다는 거죠. 결정론적이라는 말은 같은 상황이면 매번 똑같이 동작한다는 뜻입니다. AI의 판단처럼 그때그때 달라지지 않습니다.

정의는 이렇습니다. 반드시 지켜야 할 규칙을 프롬프트에 적는 "부탁"으로 두지 말고, 아예 어길 수 없게 시스템으로 강제하는 것.

다만 균형에 대한 단서가 붙습니다. 모든 걸 기계적으로 만들 수는 없고 그래서도 안 됩니다. 그렇게 하면 지금 AI 모델 성능의 절반도 못 쓰게 된다는 겁니다.

gstack에서 본 두 가지 대비 사례가 이 균형을 보여 줍니다.

판단을 맡기는 쪽 (부탁)

CEO 스킬은 이런 문장으로 시작한다고 합니다. "CEO는 단순히 부하 에이전트들의 계획에 도장이나 찍어 주려고 존재하는 게 아니다." AI에게 직접 사고하고 추론해서 판단해 달라고 부탁하는 쪽입니다.

강제하는 쪽 (시스템)

위험한 명령을 막는 스킬은 성격이 완전히 다릅니다. AI가 터미널 명령을 실행하기 전에 스크립트가 먼저 돌아서, 폴더를 통째로 지우는 명령이면 그 자리에서 잡아 버리는 훅(hook, 특정 순간에 자동으로 끼어들어 실행되는 스크립트)이라는 설명입니다.

그리고 화자가 의외였다고 말하는 대목. 게리 탄이 밝힌 속도의 비결은 화려한 에이전트 역할이나 스킬이 아니라 테스트와 검증을 하는 시스템 계층이었다는 겁니다.

그래서 권하는 첫걸음은 작습니다. 말로 부탁하던 명령 하나를 절대 어길 수 없는 방어 장치로 바꿔 보라는 것. 매번 반복하는데도 잘 안 지켜지는 명령, 그거 하나부터 시작하면 됩니다.

전제도 분명합니다. 게리 탄도 처음부터 다 갖추고 시작한 게 아닙니다. 하네스는 한 번에 설계하고 끝내는 게 아니라, AI가 하는 실수와 반복 작업을 보면서 하나씩 붙여 가는 것입니다.

하네스 엔지니어링의 뜻

화자의 정의는 한 줄입니다. AI 에이전트가 우리가 만든 시스템 안에서 작업하게 만드는 것.

이름의 출처도 나옵니다. 올해 초 개발자 미첼 하시모토(Mitchell Hashimoto, HashiCorp 공동창업자)가 이 이름으로 정리했다는 것입니다.

의도는 복잡하지 않습니다. AI가 실수하는 걸 발견하면, 다시는 그 실수를 못 하게 환경 자체를 고쳐 둔다. 화자가 가진 규칙 파일과 자동 검사 도구도 전부 "AI가 특정 실수를 반복한다"는 문제를 하나씩 막으려고 추가된 것들이라고 합니다.

루프 엔지니어링, 검사하는 루프를 옆에 둔다

두 번째 용어입니다. 핵심은 실제로 코드를 짜서 서비스를 만드는 메인 루프 옆에 검사를 하는 루프를 두는 것.

이 이름은 올해 6월 개발자 애디 오스마니(Addy Osmani)가 붙였다고 화자는 말합니다.

클로드 코드를 만든 Anthropic도 "코드를 쓰는 루프에는 코드를 검사하는 루프가 필요하다"고 말한다는 인용이 이어집니다. 배경 논리는 이렇습니다. 사람이 코드를 직접 검수하는 게 사실상 불가능해졌으니, 사람이 검수하던 자리를 AI로 대체하자는 발상입니다.

화자 본인의 경험이 여기 붙습니다. 작년까지는 클로드 코드가 10분 만에 짠 코드를 세 시간씩 눈으로 검수했다고 해요. 지속 가능한 방법이 아니었다는 겁니다.

gstack도 지난달 검증 루프를 붙였다고 합니다. 통과 조건이 충족될 때까지 AI가 일을 끝내지 못하고 스스로 문제를 파악해 수정하는 구조이고, "이런 검증 루프 없이는 루프를 돌리지 말라"는 메시지도 함께 있었다는 설명입니다.

남이 만든 세팅을 그대로 쓰지 말라

이 영상에서 가장 여러 번 반복되는 경고입니다.

화자의 선언은 이렇습니다. "저는 남이 만들어 둔 세팅을 찾아다니지 않습니다." 참고하고 영감은 얻지만, 게리 탄의 장치 목록은 그의 경험과 취향으로 만들어진 것이라 내 문제를 해결해 주지 않는다는 거예요.

유행어를 대하는 태도도 한마디 합니다. 프롬프트 엔지니어링, 하네스 엔지니어링, 루프 엔지니어링처럼 새 이름이 계속 나오는데, "이건 유행이야" 하고 배척하지도 말고 "프롬프트는 끝났다" 식으로 극단적으로 말하지도 말라는 것. 본질에서 무엇을 건질지만 보면 됩니다.

실제 사례도 있습니다. 그렇게 해본 사람이 gstack 이슈 게시판(저장소에 질문과 문제를 올리는 곳)에 글을 올렸다고 해요. "남의 세팅은 그대로 가져다 쓰는 게 아니라, 영감을 받고 내가 직접 다시 만들어 쓰는 게 맞겠다"는 내용이었다고 합니다.

화자 자신도 클로드 코드를 처음 쓸 때 남들이 좋다는 플러그인과 스킬을 여러 개 깔았는데, 자신에게 맞지 않는 게 많았다고 털어놓습니다.

이유를 설명하는 대목에서 Anthropic을 다시 인용합니다. 하네스의 모든 구성 요소에는 "모델이 혼자 하지 못하는 게 뭔지"에 대한 가정이 들어 있고, 그 가정은 모델이 좋아지면 금방 낡아 버린다는 것.

그래서 커뮤니티 스킬과 플러그인은 그대로 쓰지 말고, 왜 만들었는지, 어떤 문제를 어떻게 풀었는지를 배워 오라는 게 결론입니다. 직접 만들고 직접 유지보수할 수 있어야 한다고요.

하네스에도 비용이 든다

인용된 것은 Anthropic의 포스팅, 오래 가는 소프트웨어를 위한 하네스 디자인에 관한 글입니다. 제목과 주소는 영상에 나오지 않습니다.

요지는 이렇습니다. 하네스는 성능만 올려 주는 장치가 아니라, 많이 붙을수록 토큰(AI가 읽고 쓰는 글자 단위, 곧 사용료) 비용이 늘어난다는 것. 그래서 붙이는 것만큼 필수적인 시스템만 남기는 것도 설계 원칙이 됩니다.

화자의 경험도 같은 방향입니다. 프로젝트 규칙을 20개 넘게 만들었더니 불필요한 규칙, "좀비처럼 남은" 규칙이 늘었다는 거예요. 모델과 도구가 발전하면서 더 이상 필요 없어진 하네스도 많아졌고요.

화자가 직접 걸어 둔 장치 세 가지

이 대목은 화자가 자기 강의 교재를 화면에 띄워 놓고 설명하는 구간에서 나옵니다. 그는 시리즈 B AI 스타트업의 풀스택 프로덕트 엔지니어이고, 개인 서비스 "엣지링크"를 혼자 운영한다고 밝힙니다. 유료 서비스라 기능 하나 깨지는 게 곧 장애이고 매출로 직결된다는 것이 이 장치들을 만든 동기입니다.

1. 완료의 정의를 검사기로 바꾼다

AI가 "다 됐다"고 하는 말을 믿지 않고, 검사가 통과해야 완료로 판정합니다. 그의 구현은 클로드 코드가 일을 끝내려는 순간에 검사가 돌고, 통과하지 못하면 그 턴 자체가 끝나지 않는 형태입니다.

2. 데이터는 부탁이 아니라 차단으로 막는다

문제 상황은 이렇습니다. 유저 테이블에 컬럼을 추가했는데 기존 데이터에는 그 컬럼이 없어서, 앱이 없는 칸을 찾다가 멈추는 경우.

매번 말로 부탁하는 대신 커밋(코드 변경을 저장하는 단위) 순간마다 검사가 자동으로 돌게 만들었고, DB 변경이 필요한데 변경 커맨드 이력이 없으면 코드 저장 자체가 안 되게 했다고 합니다.

그 결과로 100번이 훨씬 넘는 DB 구조 변경을 사고 한 번 없이 운영했다는 것이 화자의 주장입니다. 영상 안에 이를 뒷받침하는 기록이나 화면은 제시되지 않습니다.

3. 잘못된 코드가 배포되지 못하게 막는다

증상은 다들 겪어 봤을 겁니다. 어젯밤엔 잘됐는데 아침에 열어 보니 서비스가 죽어 있는 것. 그의 구현은 자동 검사가 통과해야 배포가 가능하게 만드는 쪽입니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm[[:space:]]+-[a-zA-Z]*(rf|fr)'; then
  echo "폴더 통째 삭제 명령은 막혀 있습니다: $cmd" >&2
  exit 2
fi
exit 0

"Stop": [
  {
    "hooks": [
      { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests.sh" }
    ]
  }
]

#!/bin/bash
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
if ! npm test > /tmp/test.log 2>&1; then
  echo "테스트가 실패했습니다. 원인을 찾아 고친 뒤에 끝내세요." >&2
  tail -n 30 /tmp/test.log >&2
  exit 2
fi
exit 0

#!/bin/sh
changed=$(git diff --cached --name-only)
if echo "$changed" | grep -q '^prisma/schema.prisma$'; then
  if ! echo "$changed" | grep -q '^prisma/migrations/'; then
    echo "DB 구조를 바꿨는데 마이그레이션 파일이 없습니다. 커밋을 막습니다." >&2
    exit 1
  fi
fi
exit 0

출처: youtube.com/…