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

하네스 엔지니어링이 나온 배경
"프롬프트를 잘 써야 한다"는 조언만으로는 AI가 같은 실수를 되풀이하는 걸 막지 못합니다. 하네스 엔지니어링은 거기서 출발합니다. 하네스(harness)는 원래 말에 채우는 마구를 뜻하는 말입니다. 여기서는 AI라는 힘센 말을 원하는 방향으로 끌고 가는 장치 전체를 가리킵니다.
상위 0.1~1%는 프롬프트를 다듬지 않는다
지금까지 AI 활용은 "프롬프트를 잘 써야 한다", "질문을 잘해야 한다"는 쪽으로만 흘러왔습니다.
상위 0.1~1% 사용자는 그런 식으로 바이브 코딩(코드를 직접 읽지 않고 AI에게 말로 시켜 프로그램을 만드는 방식)을 하지 않는다는 견해가 있습니다. 그들이 하는 일은 다릅니다. 하네스를 설계하고 루프를 만들어서, AI 에이전트(스스로 여러 단계를 나눠 일하는 AI)가 의도와 목적에 맞게 스스로 판단해 최고의 결과를 내도록 환경을 짭니다.
그래서 첫 권유는 단순합니다. 프롬프트를 넣어 놓고 AI가 일하는 걸 지켜보고만 있지 마세요.
게리 탄의 gstack, 하네스 엔지니어링 사례
Y Combinator는 실리콘밸리를 대표하는 투자사이자 액셀러레이터(초기 스타트업을 뽑아 키우는 회사)입니다. 이전 대표는 지금 오픈AI를 이끄는 샘 올트먼이었습니다.
현 CEO 게리 탄은 스탠퍼드 컴퓨터공학을 나와 팔란티어에서 일했고, 블로그 서비스 Posterous를 창업해 트위터에 엑시트(회사를 팔아 투자금을 회수)했습니다.
게리 탄은 자기가 직접 만들어 쓰는 워크플로를 깃허브에 오픈소스로 공개했습니다. 깃허브 스타가 10만 개를 넘기며 세계적으로 퍼졌습니다.
저장소 이름은 gstack입니다. 깃허브나 검색창에 "garry tan gstack"을 치면 찾을 수 있습니다.
23개 역할로 짜인 에이전트 팀
gstack에 미리 설계돼 있는 건 프롬프트가 아니라 역할입니다.
- 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개 넘게 만들었더니 불필요한 규칙, "좀비처럼 남은" 규칙이 늘었다는 사례가 있습니다. 모델과 도구가 발전하면서 더 이상 필요 없어진 하네스도 많아집니다.
실제로 쓰이는 장치 세 가지
유료 서비스를 혼자 운영하는 경우를 생각해 보면 이 장치들이 왜 필요한지 분명해집니다. 기능 하나 깨지는 게 곧 장애이고, 장애는 매출로 직결됩니다.
1. 완료의 정의를 검사기로 바꾼다
AI가 "다 됐다"고 하는 말을 믿지 않고, 검사가 통과해야 완료로 판정합니다. 클로드 코드가 일을 끝내려는 순간에 검사가 돌고, 통과하지 못하면 그 턴 자체가 끝나지 않게 만듭니다.
2. 데이터는 부탁이 아니라 차단으로 막는다
흔한 사고는 이렇습니다. 유저 테이블에 컬럼을 추가했는데 기존 데이터에는 그 컬럼이 없어서, 앱이 없는 칸을 찾다가 멈춥니다.
매번 말로 부탁하는 대신 커밋(코드 변경을 저장하는 단위) 순간마다 검사가 자동으로 돌게 만듭니다. DB 변경이 필요한데 변경 커맨드 이력이 없으면 코드 저장 자체가 안 되게 합니다.
한 운영 사례에서는 이 방식으로 100번이 훨씬 넘는 DB 구조 변경을 사고 한 번 없이 치렀습니다.
3. 잘못된 코드가 배포되지 못하게 막는다
어젯밤엔 잘됐는데 아침에 열어 보니 서비스가 죽어 있는 일, 다들 겪어 봤을 겁니다. 해법은 자동 검사가 통과해야 배포가 가능하게 만드는 것입니다.
첫 장치를 클로드 코드에 거는 법
위 세 장치를 클로드 코드와 git, 깃허브에서 거는 일반적인 방법입니다. 내 프로젝트에 맞게 경로와 명령을 바꿔서 씁니다.
준비: 설정 파일 위치 알기
클로드 코드의 훅은 프로젝트 폴더 안 .claude/settings.json 파일에 적습니다. 이 파일이 없으면 새로 만듭니다. 어떤 훅이 걸려 있는지는 클로드 코드 입력창에 /hooks
장치 1: 폴더 통째 삭제 명령 막기
클로드가 터미널 명령(Bash)을 실행하기 직전에 스크립트를 돌리는 PreToolUse 훅입니다. 먼저 .claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh" }
]
}
]
}
}
그다음 .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
터미널에서 chmod +x .claude/hooks/block-rm.shexit 2로 끝나면 클로드 코드는 그 명령을 실행하지 않고, 이유 문장을 클로드에게 돌려줍니다. jq(JSON을 읽는 작은 프로그램)가 없으면 맥에서는 brew install jq
장치 2: 검사가 통과해야 일이 끝나게 하기
클로드가 답을 끝내려는 순간 도는 Stop 훅입니다. 위 설정 파일의 "hooks" 안에 "Stop" 항목을 하나 더 넣습니다.
"Stop": [
{
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests.sh" }
]
}
]
.claude/hooks/run-tests.shnpm test 자리는 내 프로젝트의 검사 명령으로 바꿉니다.
#!/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
검사가 실패하면 클로드는 턴을 끝내지 못하고 실패 내용을 받아 다시 고칩니다. stop_hook_active 확인 줄은 무한 반복을 막는 안전장치입니다. 이 줄이 있으면 한 번 되돌려 보낸 뒤에는 멈춥니다.
장치 3: DB 변경 이력 없이 커밋 못 하게 하기
이건 클로드 코드가 아니라 git(코드 변경 기록 도구)의 훅으로 겁니다. 프로젝트 폴더의 .git/hooks/pre-commit 파일에 적습니다. 아래는 Prisma라는 DB 도구를 쓰는 프로젝트를 가정한 예시입니다. 경로는 내 프로젝트에 맞게 바꿉니다.
#!/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
chmod +x .git/hooks/pre-commit
배포 막기: 검사 통과를 필수로
깃허브를 쓴다면 저장소 화면의 Settings, Branches(또는 Rules)로 가서 main 브랜치에 규칙을 추가합니다. "Require status checks to pass before merging"을 켜고 자동 검사 작업을 고르면, 검사가 통과하지 않은 코드는 main에 합쳐지지 않습니다.
검증이 필요한 지점 세 곳
어디에 하네스를 걸지 고르는 기준입니다.
- AI가 "다 됐다"는데 열어 보면 깨져 있을 때: 고쳐야 할 건 프롬프트가 아니라 완료의 정의입니다. 무엇이 통과하면 완료인지를 먼저 정해 둡니다. 위의 장치 2가 여기에 해당합니다.
- 절대 일어나면 안 되는 일이 있을 때: 지우면 안 되는 걸 지우거나 손대면 안 될 데이터를 건드리는 일은, 부탁으로 두면 언젠가 반드시 뚫립니다. 실행 자체가 안 되게 막습니다. 장치 1과 3이 여기에 해당합니다.
- 매번 똑같은 잔소리를 반복하게 될 때: 말로 반복하지 말고 역할로 넘깁니다. gstack의 리뷰 스킬이 딱 그 구조입니다.
원칙 하나가 더 붙습니다. 모델이 좋아져서 더 이상 필요 없어진 장치는 주기적으로 걷어냅니다. Anthropic도 새 모델을 내면서 자체 하네스를 줄였습니다.
하네스 엔지니어링 실천 목록
- 프롬프트를 잘 쓰려고만 애쓰지 말 것. 상위 사용자는 AI가 일할 역할과 순서의 시스템을 먼저 설계합니다.
- 프롬프트를 넣고 AI가 일하는 걸 지켜보고만 있지 말 것.
- 역할과 책임부터 정의할 것. 누가 어떤 책임으로 일할지를 먼저 정합니다.
- 말로 부탁하던 명령 하나를 어길 수 없는 방어 장치로 바꿔 볼 것. 반복하는데 잘 안 지켜지는 것 하나부터.
- 완료의 정의를 바꿀 것. "AI가 다 됐다고 한 것"이 아니라 "검사기가 통과한 것"이 완료입니다.
- 절대 일어나면 안 되는 일은 실행 자체가 안 되게 막을 것.
- 반복되는 잔소리는 역할로 넘길 것.
- 하네스를 한 번에 완성하려 하지 말 것. 실수를 보면서 하나씩 붙입니다.
- 검증 루프 없이 루프를 돌리지 말 것.
- 꼭 필요한 시스템만 남기고, 필요 없어진 장치는 주기적으로 걷어낼 것.
- 커뮤니티 스킬과 플러그인을 그대로 가져다 쓰지 말 것. 왜 만들었는지를 배워 옵니다.
- 유행어는 배척하지도, 극단적으로 말하지도 말 것.
두 가지는 도구 이름 없이도 오늘 바로 적용할 수 있습니다. 규칙을 프롬프트에 적어 두고 지켜지길 바라는 대신 어길 수 없게 만드는 쪽으로 생각을 옮기는 것, 그리고 붙이는 것만큼 걷어내는 것도 설계라는 점입니다.
자주 묻는 질문
하네스 엔지니어링이란 무엇인가요?
AI 에이전트가 사람이 만든 규칙, 검사, 차단 장치 안에서만 일하도록 환경을 설계하는 방법입니다. AI가 실수를 하면 프롬프트로 부탁하는 대신 그 실수를 다시는 못 하게 시스템을 고쳐 둡니다. 이 이름은 개발자 미첼 하시모토가 정리했습니다.
프롬프트 엔지니어링과 무엇이 다른가요?
프롬프트 엔지니어링은 질문과 지시문을 잘 쓰는 데 집중합니다. 하네스 엔지니어링은 AI가 지시를 어겨도 결과가 망가지지 않도록 역할 분담, 자동 검사, 명령 차단 같은 장치를 바깥에 둡니다. 둘 중 하나를 버리라는 게 아니라, 본질에서 쓸 것을 건지면 됩니다.
클로드 코드에서 위험한 명령을 막으려면 어떻게 하나요?
프로젝트의 .claude/settings.jsonPreToolUse 훅을 등록하고, 실행하려는 명령을 검사하는 스크립트를 연결합니다. 스크립트가 exit 2
gstack을 그대로 설치해서 쓰면 되나요?
그대로 쓰기보다는 배워서 다시 만드는 편이 낫습니다. 게리 탄의 장치는 그의 문제를 풀려고 만든 것이라, 왜 그렇게 만들었는지를 익혀 내 문제에 맞게 고쳐야 합니다. 장치가 많을수록 토큰 비용도 늘어납니다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗