프롬프트와 컨텍스트를 잘 챙겨도, 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 나 API 문서가 같은 자리입니다
• 문체 가드레일 이 하지 말아야 할 것의 경계를 정합니다. 코딩으로 치면 린터 규칙입니다
• 검증 체크리스트 가 AI가 스스로 다시 보는 루프가 됩니다. 코딩으로 치면 테스트 실행이 같은 역할입니다

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

4. Claude Code와 하네스

이 책의 나머지 챕터에서 사용할 Claude Code도 본질적으로 하나의 하네스입니다.

• CLAUDE.md: 프로젝트의 설정집과 문체 가드레일 역할
• Skills, Subagents, Plugins: 도구와 가드레일을 늘리는 장치
• 슬래시 명령어, Hooks: 작업 절차와 피드백 루프

위 추리 소설 실습에서 채팅창에 통째로 붙여 넣었던 내용을, Claude Code에서는 폴더에 파일로 깔아두는 형태로 영구화합니다. 이후 5~11장에서 그 구체적인 사용법을 다룹니다.

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

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

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

여기에 들어가서 ZIP 파일로 다운로드 받은 다음 그 폴더를 Claude Code에서 열어보세요. 그리고 안에 있는 파일을 하나씩 클릭해서 열어보세요. 어떤 구성으로 되어있는지 살펴보시면 됩니다. 이 하네스를 가지고 '2박 3일 바이브 코딩 랜딩 페이지 만들어줘.'와 '1달간 진행하는 제주 워케이션 랜딩 페이지를 만들어줘.'를 각각 요청해보았습니다. 결과가 어떤지 비교해보세요.