프롬프트와 컨텍스트를 잘 챙겨도, AI가 여러 단계의 일을 자율적으로 처리하는 단계에서는 또 다른 문제가 생깁니다. AI에게 어떤 도구를 쥐어줄지, 어디까지 허용할지, 실수했을 때 어떻게 되돌아오게 할지까지 미리 깔아둬야 합니다. 이 전체 환경 설계를 하네스 엔지니어링이라고 부릅니다.

1. 하네스 엔지니어링이란

업계에서 점차 자리잡은 정의는 단순합니다.

에이전트 = LLM + 하네스

LLM이 두뇌라면, 하네스는 두뇌가 일할 책상, 공구함, 안전 장비, 작업 절차 같은 주변 환경 전체입니다. 모델이 무엇을 할지 결정한다면, 하네스는 모델이 무엇을 볼 수 있는지, 어떤 도구를 쓸 수 있는지, 실수했을 때 어떻게 되돌아오는지를 결정합니다.

2026년 2월, OpenAI는 다섯 달 동안 3~7명의 팀이 100만 줄짜리 제품을 만들었는데 사람이 직접 친 코드는 0줄 이었다는 실험 결과를 공개했습니다. 핵심 철학은 한 문장이었습니다.

"Humans steer. Agents execute." 인간은 방향을 잡고, 에이전트가 실행한다.

HashiCorp 공동창립자 Mitchell Hashimoto는 같은 정신을 이렇게 표현했습니다.

"에이전트가 실수하는 걸 발견할 때마다, 그 실수를 다시는 못 하도록 해결책을 환경에 끼워 넣는다."

개별 실수를 손으로 고치지 않고, 그 실수가 구조적으로 일어날 수 없도록 환경을 손본다는 발상입니다.

2. 직접 해보기

하네스라는 단어는 코딩 분야에서 시작됐지만 원리는 어디에나 적용됩니다. AI에게 참조할 자료, 지켜야 할 규칙, 다 쓴 뒤 스스로 점검할 체크리스트 를 한 번에 줘보는 실습입니다. 코딩이 아닌 추리 소설 집필을 예시로 잡았는데, 코드든 보고서든 디자인 가이드든 발상은 그대로입니다. 채팅 탭에서 진행합니다.

2.1 설계 없이 요청한 경우

새 대화를 열고 아래 한 줄을 입력해보세요.

추리 소설 4장을 써줘.

읽을 만한 글이 나오긴 합니다. 그런데 다시 실행하면 주인공 성격이 미묘하게 바뀌고, 1인칭이 됐다 3인칭이 됐다 하고, 갑자기 톤이 달라지기도 합니다. 매번 결과가 흔들립니다.

2.2 하네스를 같이 넣은 경우

이번엔 아래 프롬프트를 통째로 붙여 넣어보세요. 설정집, 문체 규칙, 자체 점검 항목까지 들어 있는 작은 하네스입니다.

당신은 한국 추리 소설 작가 에이전트입니다. 아래의 설정집, 문체 규칙,
검증 체크리스트를 반드시 따라 4장을 집필하세요.

## 캐릭터 설정집 (Story Bible)
주인공 - 서하진 (38세, 여성)
- 직업: 퇴직 형사, 현재 사설 탐정
- 성격: 냉소적이지만 약자에게 약함, 유머는 건조한 자기비하 스타일
- 말투: 짧은 문장, 감탄사 거의 없음, 독백이 많음
- 트라우마: 5년 전 미제 사건, 이것이 퇴직의 원인
- 절대 하지 않는 것: 거짓말, 술, 사건 현장에서 뛰기(무릎 부상)

피해자 - 윤재호 (45세, 남성)
- 직업: IT 스타트업 대표
- 사망 상황: 자택 서재에서 발견, 외상 없음
- 비밀: 회사 자금 횡령 의혹 (경찰은 아직 모름)

## 문체 가드레일
- 시점: 서하진 1인칭 시점만 사용
- 문장: 한 문장 40자 이내 권장, 80자 초과 금지
- 금지 표현: "갑자기", "그런데", "사실은"
- 분위기: 건조하고 절제된 하드보일드, 감정 묘사는 행동으로만 표현
- 복선: 각 장마다 최소 1개의 복선 삽입 (장 끝에 [복선 메모]로 표시)

## 플롯 뼈대
- 2장: 사건 의뢰, 윤재호의 아내가 서하진을 찾아옴
- 3장: 현장 조사, 서재에서 단서 발견 (경찰이 놓친 것)
- 4장: 첫 번째 용의자, 공동 창업자 인터뷰, 알리바이에 구멍

## 일관성 검증 (각 장 집필 후 수행)
각 장을 쓴 후, 아래 항목을 ✅/❌로 자체 검증하세요:
- [ ] 서하진이 설정과 다른 행동을 하지 않았는가? (거짓말, 술, 뛰기)
- [ ] 1인칭 시점이 깨지지 않았는가?
- [ ] 금지 표현을 사용하지 않았는가?
- [ ] 80자 초과 문장이 없는가?
- [ ] 복선이 최소 1개 포함되었는가?
❌가 있으면 해당 부분을 수정한 후 다시 검증하세요.

3. 무엇을 관찰해야 하나

두 결과를 나란히 놓고 비교해보면 세 가지가 보입니다.

• 설정집(Story Bible) 이 참조할 지식 역할을 합니다. 바이브 코딩으로 치면 CLAUDE.md 나 프로젝트 지침이 같은 자리입니다
• 문체 가드레일 이 하지 말아야 할 것의 경계를 정합니다. 바이브 코딩으로 치면 "가격은 지어내지 마" 같은 규칙입니다
• 검증 체크리스트 가 AI가 스스로 다시 보는 루프가 됩니다. 바이브 코딩으로 치면 3장에서 만든 page-review Skill이 같은 역할입니다

이게 하네스 엔지니어링입니다. AI에게 "잘 해줘"라고 부탁하는 게 아니라, AI가 어쩔 수 없이 잘하게 되는 환경을 미리 짜두는 일입니다. 소설이든 코드든 보고서든 마케팅 자료든 원리는 그대로 작동합니다.

4. Claude Desktop과 하네스

이 책의 나머지 장에서 사용할 Claude Desktop도 본질적으로 하나의 하네스입니다. 3장에서 만난 것들을 위 세 역할에 대응시키면 아래와 같습니다.

위 추리 소설 실습에서 채팅창에 통째로 붙여 넣었던 내용을, Claude Desktop에서는 폴더에 파일로 깔아두거나 계정에 저장해 두는 형태로 영구화합니다. 매번 붙여 넣지 않아도 됩니다.

이 책의 검토 루프(10장)가 하네스와 만나는 지점이 있습니다. 검토에서 같은 실수가 두 번 걸리면, 그것을 사람이 또 고치는 대신 하네스에 올립니다. 문구를 지어내는 실수가 반복되면 CLAUDE.md에 "지어내지 마"를 넣고, 폰에서 깨지는 실수가 반복되면 page-review Skill에 항목을 더합니다. 검토는 결과물을 고치는 일이고, 하네스는 다음 결과물이 처음부터 그렇게 나오지 않게 하는 일입니다.

세 절을 모두 따라오셨다면 프롬프트 → 컨텍스트 → 하네스 로 단계가 넓어지는 흐름을 한 번 손으로 체험하신 셈입니다. 다음 장부터는 본격적인 바이브 코딩 실습으로 들어갑니다.

5. 하네스 엔지니어링 체험하기

위니브에서 랜딩 페이지를 만들 때 쓰는 하네스를 공개해 두었습니다.

• https://github.com/weniv/landing-harness-student

여기에 들어가서 초록색 Code 버튼을 누르고 Download ZIP으로 내려받은 다음, 압축을 풀어 바탕화면에 두세요. 그 폴더를 Code 탭에서 폴더 선택으로 지정하고, 안에 있는 파일을 하나씩 열어보세요. 메모장으로 열어도 되고, Code 탭에 "이 폴더의 파일들이 각각 무슨 역할인지 설명해줘"라고 물어봐도 됩니다. 어떤 구성으로 되어있는지 살펴보시면 됩니다. 설정집 역할을 하는 파일, 규칙 역할을 하는 파일, 검토 역할을 하는 파일이 보일 것입니다.

이 하네스를 가지고 '2박 3일 바이브 코딩 랜딩 페이지 만들어줘.'와 '1달간 진행하는 제주 워케이션 랜딩 페이지를 만들어줘.'를 각각 요청해보았습니다. 한 줄짜리 요청인데도 결과가 어떤지 비교해보세요. 한 줄로 끝날 수 있는 이유는 나머지가 폴더 안에 이미 깔려 있기 때문입니다.