하네스 엔지니어링 입문 가이드: AI 에이전트 시대에 사람이 하는 일
하네스 엔지니어링은 AI 에이전트가 쓸 자료와 도구, 작업 범위, 검사와 실패 처리 방법을 설계하는 일입니다. 태그 분류 예시로 원자료와 규칙을 만들고 잘못된 결과를 고친 뒤 다시 확인하는 과정을 익힙니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
AI 에이전트에게 일을 맡기면 생기는 일
AI에게 블로그의 태그 기능을 추가해 달라고 했는데 기존에 쓰지 않던 데이터베이스를 설치하려 한다고 해 보겠습니다. 태그는 글의 주제를 표시하는 이름이고 데이터베이스는 자료를 저장하고 찾는 시스템입니다. 기능 이름은 전달했지만, 콘텐츠를 어디에 보관하고 어떤 방식으로 수정해야 하는지는 충분히 알려 주지 않은 상황입니다.
AI 에이전트는 도구를 사용해 파일을 읽고 수정하며 작업을 진행하는 시스템입니다. 요청을 수행할 기능이 있어도 프로젝트의 규칙이나 완료 조건을 놓칠 수 있습니다.
하네스 엔지니어링(Harness Engineering)은 에이전트가 사용할 작업 환경과 규칙, 실행 및 검증 절차를 설계하는 일입니다. 위 예시라면 콘텐츠 저장 방식과 수정할 경로를 안내하고, 새 의존성 설치 권한을 정하고, 태그 기능이 작동하는지 확인할 검사를 준비합니다. 의존성은 프로젝트가 작동하는 데 필요한 외부 코드나 도구입니다. 조직 단위의 업무 변화는 AX 뜻과 DX 차이에서 따로 다룹니다.
프롬프트, 컨텍스트와 함께 설계합니다
비슷한 용어는 발전 순서로 외우기보다 각각 무엇을 정하는지 구분하는 편이 이해하기 쉽습니다.
| 용어 | 주로 정하는 것 | 태그 기능을 추가하는 예 |
|---|---|---|
| 프롬프트 엔지니어링 | 요청과 지시의 내용 | 태그가 없는 글을 어떻게 표시할지 설명 |
| 컨텍스트 엔지니어링 | 모델에 제공할 정보와 관리 방법 | 관련 소스 파일과 데이터 형식, 필요한 대화 내용을 제공 |
| 하네스 엔지니어링 | 도구와 실행 환경, 권한, 검증과 실패 처리 | 수정 경로와 명령 실행 권한을 정하고 테스트 결과를 확인 |
이 구분은 설명을 위한 것으로 실제 작업에서는 서로 겹칩니다. 하네스를 마련했다고 좋은 지시나 필요한 자료가 더 이상 필요하지 않은 것은 아닙니다. 바이브코딩은 코드보다 실행 결과에 의존하는 개발 방식을 가리키므로 이 표의 다음 단계로 볼 수 없습니다.
실제 개발 사례에서 확인할 점
OpenAI는 2026년 2월 11일 공개한 하네스 엔지니어링 사례에서 에이전트가 작업할 환경과 검증 과정을 설계한 경험을 소개했습니다. 마틴 파울러 사이트에 실린 Birgitta Böckeler의 관련 글도 코딩 에이전트 사용자의 관점에서 이 주제를 다룹니다.
이 글에서는 두 자료를 참고해 프로젝트에 적용할 항목을 정리합니다. 특정 팀의 성공 사례가 다른 프로젝트의 품질이나 작업 시간을 그대로 보장하는 것은 아닙니다. 규칙을 적은 뒤 에이전트가 실제로 읽었는지, 검사가 필요한 오류를 잡는지 확인해야 합니다.
하네스 엔지니어링의 뜻과 네 가지 구성
하네스(Harness)는 원래 말에 씌우는 마구를 뜻하는 영어 단어이고, 동사로는 강한 힘을 다스려 쓸모 있게 쓴다는 뜻입니다. AI에서는 에이전트를 감싸는 작업 환경, 규칙, 확인과 수정 체계를 모두 가리킵니다. 모델 자체가 아니라 모델이 사용할 도구와 자료, 실행 및 확인 절차를 설계하는 일입니다.
| 구성 요소 | 하는 일 | 실제 예시 |
|---|---|---|
| 환경 | 에이전트가 읽고 쓸 수 있는 범위와 도구를 정합니다 | 프로젝트 폴더 구조, 개발 도구 설정, 쓸 수 있는 명령 |
| 규칙 | 지켜야 할 방식과 금지할 것을 적어 둡니다 | 코딩 규칙, 쓸 수 있는 라이브러리 목록, 글쓰기 기준 |
| 확인과 수정 | 결과를 검사하고 실패 내용을 바탕으로 수정합니다 | 테스트 자동 실행, 빌드 확인, 문장 검사기 |
| 기록과 관찰 | 무엇이 어디서 잘못됐는지 나중에 찾을 수 있게 남깁니다 | 작업 로그, 오류 추적, 변경 기록 |
다섯 가지 원칙
앞의 사례를 참고해 처음 적용할 때 확인할 항목을 다섯 가지로 정리했습니다. 아래는 이 글의 적용 제안입니다.
1. 범위를 정해 줍니다
"알아서 해 주세요"라고만 하면 에이전트가 맡긴 범위를 넘어 파일을 지우거나, 엉뚱한 라이브러리를 설치하거나, 의도하지 않은 곳의 코드를 바꿀 수 있습니다. 수정 가능한 경로와 실행해도 되는 명령을 구체적으로 정합니다.
실무에서는 CLAUDE.md나 AGENTS.md 같은 프로젝트 규칙 파일에 "TypeScript만 사용, 새 파일을 만들기 전에 기존 파일부터 확인, 태그는 이 목록에서만 선택"처럼 적어 둡니다. 문서는 작업 지침이며 실제 접근 권한을 제한하지는 않습니다. 파일 접근이나 명령 실행을 막아야 한다면 실행 도구의 권한 설정도 함께 적용합니다.
2. 우리 쪽 사정을 알려 줍니다
에이전트에게 필요한 프로젝트 규칙과 구조가 전달됐는지 확인합니다. 폴더 구조, 이름 짓는 방식, 자주 쓰는 명령을 문서로 남겨 두면 에이전트가 그 문서를 읽고 맞춰 일합니다. 프로젝트 사용 설명 파일인 README.md, 설계 문서, 프로그램 사이의 요청과 응답 형식을 정한 API 명세가 이 역할을 합니다.
3. 결과를 자동으로 확인합니다
에이전트가 코드를 짰다고 끝이 아닙니다. 반복해서 확인할 항목 중 기계가 판단할 수 있는 것은 자동 검사로 만들 수 있습니다. 코드 작업에서는 특정 입력에 예상 결과가 나오는지 보는 테스트, 작성 규칙을 확인하는 린터, 값의 종류를 확인하는 타입 검사, 실행하거나 배포할 형태로 만드는 빌드 등이 쓰입니다. 모든 작업에 네 가지를 전부 요구하기보다 변경한 기능에 필요한 검사를 고릅니다. 검사가 통과해도 그 검사가 다루지 않은 오류는 남을 수 있습니다. 예를 들어 금지 표현 검색만으로 문장의 뜻이 자연스러운지 판단할 수는 없습니다.
4. 스스로 고치게 합니다
검사에서 문제가 나오면 오류 메시지를 에이전트에게 다시 넘겨 고치게 하는 흐름을 만들어 둡니다. 수정 후에는 같은 검사를 다시 실행해 오류가 해결됐는지 확인합니다. 같은 검사에서 계속 실패하거나 요청 범위를 벗어나는 수정이 필요하면 반복을 멈추고 원인을 확인하도록 정합니다. 재시도 횟수와 비용 한도는 작업에 맞게 정하며 성공할 때까지 무한히 반복하지 않습니다.
5. 마지막 판단은 사람이 합니다
이 글에서는 중요한 변경의 최종 판단을 사람이 맡는 구성을 제안합니다. 실제 운영에서는 어떤 변경을 자동 처리하고 어디서 사람이 확인할지 위험과 업무 조건에 맞춰 정합니다. 예를 들어 배포나 권한 변경은 담당자의 검토를 거치도록 구성할 수 있습니다. 필요한 경우 코드 변경 요청(Pull Request)에 승인 조건을 설정합니다. 에이전트가 만든 결과물을 같은 에이전트에게 검수시키면 문제를 놓치기 쉬운 이유는 AI 자기 검수의 한계에 따로 적었습니다.
하네스 엔지니어링 예시: 준이아빠블로그의 구성
준이아빠블로그는 클로드 코드로 만들고 운영합니다. 처음에는 "이거 만들어 줘"라고 말하는 것으로 충분했지만, 글과 기능이 늘면서 결과가 들쭉날쭉해졌습니다. 그래서 다음과 같은 구조를 만들었습니다. 아래에서 /로 끝나는 이름은 폴더이고, 안쪽으로 들여 쓴 항목은 그 폴더 안에 있다는 뜻입니다. 이 그림은 기존 구성을 설명하며 그대로 복사해 새로 만들 필요는 없습니다.
hongblog/
├── CLAUDE.md ← 프로젝트 전체 규칙과 구조
├── .claude/
│ ├── references/ ← 글쓰기 핵심 지침 같은 기준 문서
│ └── skills/ ← 글쓰기, 썸네일, 검수 같은 반복 절차
├── content/ ← 글과 강의 원고
├── src/ ← 사이트 코드
└── scripts/ ← 제목, 요약, 빌드 검사 스크립트| 사람이 만든 것 | 하는 일 |
|---|---|
CLAUDE.md | 프로젝트 지침으로 읽도록 둔 파일. 태그 목록, 날짜 규칙, 배포 절차를 적어 둡니다 |
| 글쓰기 핵심 지침 | 문체와 구성의 단일 기준. 글을 작성하고 검수할 때 참조합니다 |
| 스킬 | 글쓰기, 썸네일 만들기, 검수 같은 반복 절차를 단계별로 적어 둡니다 |
| 검사 스크립트 | 번역투와 금지 표현, 제목 길이, 요약 규칙을 자동으로 검사합니다 |
| 사람의 최종 확인 | 사실 확인과 전문 읽기를 거친 뒤 배포를 승인합니다 |
이 구조에서는 조사, 초안, 검색용 제목과 설명 같은 메타데이터, 퀴즈 작성과 검수 절차를 문서로 관리합니다. 스킬은 반복 작업의 지침과 필요한 자료를 묶은 것이며, 파일을 만들어 두는 것만으로 모든 요청에서 자동 실행되지는 않습니다. 검사 스크립트가 통과해도 사실관계나 문장 흐름까지 검증된 것은 아닙니다. 별도로 출처를 확인하고 전문을 읽어야 합니다.
도구가 바뀌어도 원칙은 남습니다
AI 코딩 도구는 커서, 리플릿, 클로드 코드, 깃허브 코파일럿, 코덱스, 제미나이 CLI처럼 계속 늘어나고 이름도 자주 바뀝니다. 하나하나 사용법을 익히다 보면 따라가기 벅찹니다.
하네스 엔지니어링의 관점에서 보면 도구가 바뀌어도 원칙은 같습니다. 범위와 자료, 검사와 실패 처리, 사람이 판단할 지점을 정하는 방식은 여러 도구에 적용할 수 있습니다. 규칙 파일 이름과 자동으로 읽는 범위는 도구마다 다를 수 있습니다. 기존 규칙을 옮길 때는 해당 도구가 실제로 읽는 위치와 적용 범위를 확인합니다.
하네스 엔지니어링에는 작업을 나누고 기준을 문서로 적는 일뿐 아니라 검사와 실행 환경을 구현하는 일도 포함됩니다. 준이아빠블로그를 운영하며 하는 일도 대부분 문서 작성, 구조 설계, 결과 확인입니다. 기획자와 마케터도 업무 조건과 검토 기준을 정하는 데 참여할 수 있습니다. 실행 도구나 검사 프로그램을 만들 때는 개발 작업이 필요할 수 있습니다.
자주 묻는 질문
하네스 엔지니어링이 뭔가요?
AI 에이전트를 감싸는 작업 환경과 규칙, 확인과 수정 체계를 설계하는 일입니다. 하네스는 원래 말에 씌우는 마구를 뜻하는 말이고, 동사로는 강한 힘을 다스려 쓸모 있게 쓴다는 뜻입니다. 모델 자체를 바꾸는 대신 사용할 도구와 실행 절차를 정하는 일입니다.
프롬프트 엔지니어링과 무엇이 다른가요?
다루는 범위가 다릅니다. 프롬프트는 요청과 지시를 어떻게 구성할지의 문제이고, 하네스는 에이전트가 어떤 자료를 볼 수 있고 어디까지 고칠 수 있으며 결과를 누가 어떻게 확인하는지까지 정합니다. 요청 문장이 아니라 작업 환경을 설계하는 일에 가깝습니다.
개발자가 아니어도 할 수 있나요?
할 수 있습니다. 범위를 정하고 확인 단계를 두는 일은 코드를 짜는 능력보다 업무를 나누는 능력에 가깝습니다. 어떤 자료만 쓰게 할지, 어디서 사람이 한 번 확인할지를 정하는 것부터가 하네스 설계입니다.
작은 자료로 확인과 수정 흐름을 연습합니다
처음부터 코드 프로젝트를 만들 필요는 없습니다. 아래는 실제 블로그의 태그 체계와 관계없는 가상 자료입니다. 메모 앱에서 직접 대조하거나 이미 쓰는 AI 대화에 자료와 기준을 함께 전달할 수 있습니다. 여기서는 자동 실행 환경을 설치하지 않고 하네스의 확인 절차를 설계합니다.
[원자료]
A: AI로 여행 계획을 만드는 방법
B: 광고 클릭률을 계산하는 방법
[요청]
두 글을 분류하고 ID, 제목, 태그 세 열의 표로 출력합니다.
[분류 기준]
허용 태그: AI, 마케팅, 미분류
AI 사용법은 AI, 광고 지표는 마케팅으로 분류합니다.
어느 쪽인지 원자료에서 판단할 수 없거나 두 기준이 겹치면 미분류로 둡니다.
글 ID와 제목을 유지하고 태그 한 개만 붙입니다.
원자료를 수정하거나 프로그램을 설치하지 않습니다.글 ID는 A와 B처럼 각 글을 구분하는 표시입니다. 다음 결과를 받았다고 가정합니다.
| ID | 제목 | 태그 |
|---|---|---|
| A | AI로 여행 계획을 만드는 방법 | 여행 |
| B | 광고 클릭률을 계산하는 방법 | 마케팅 |
먼저 A와 B가 빠지거나 추가되지 않았는지, 제목이 유지됐는지 확인합니다. 그다음 허용 태그와 분류 기준을 대조합니다. A의 ‘여행’은 허용 목록에 없으며 이 예시의 기준에서는 AI가 맞습니다. B는 마케팅으로 맞게 분류됐습니다.
AI에 수정을 요청한다면 “A의 태그 여행은 허용 목록에 없습니다. AI 사용법이라는 기준에 따라 고치고 ID와 제목은 유지해 주세요”처럼 어긋난 조건을 짚습니다. 수정 후 A만 보지 않고 두 행의 ID, 제목, 태그를 모두 다시 확인합니다. A는 AI, B는 마케팅이어야 합니다.
이번에는 검사 자체의 한계도 확인합니다. A를 마케팅으로 잘못 분류해도 ‘태그가 허용 목록 안에 있는지’만 검사하면 통과합니다. 허용 목록 검사와 내용에 맞는 분류 검사는 다른 것입니다. 자동 검사를 붙인다면 무엇을 검사했고 무엇을 검사하지 않았는지 나눠 기록합니다. 예를 들어 A가 마케팅인 결과는 ‘허용 목록: 통과, 내용 분류: 불일치’로 적습니다. 태그가 AI로 고쳐진 뒤 두 항목을 다시 대조해야 합니다.
혼자 반복할 때는 원자료에 C: 주말 산책 준비물을 추가하고 요청도 ‘세 글을 분류’로 바꿉니다. 이 제목만으로는 AI 사용법이나 광고 지표라고 볼 수 없으므로 C의 태그는 미분류가 됩니다. A와 B의 기존 결과가 유지되는지도 함께 확인합니다.
연습을 실제 작업으로 옮기는 방법
방금 연습에서는 원자료, 작업 규칙, 결과 대조, 수정 후 재확인을 따로 정했습니다. 이것을 반복 가능한 실행 환경으로 만들려면 필요한 도구와 권한, 검사 실행 및 기록 방식을 연결해야 합니다. 대화에 기준을 붙여 넣은 것만으로 완성된 자동화 시스템이 되지는 않습니다.
처음에는 다음 세 가지를 작은 작업 하나에 적용합니다.
- 원자료와 기준을 한곳에 정리합니다. 무엇을 바꾸고 무엇을 유지할지 적고 AI가 그 자료를 실제로 읽었는지 확인합니다. 지원되는 프로젝트 규칙 파일을 사용할 때는 해당 도구의 파일 위치와 적용 범위를 따릅니다.
- 오류 하나를 잡는 확인 방법을 만듭니다. 위 예시에서는 허용 태그 목록과 결과를 대조합니다. 반복이 많아지면 자동 검사로 옮기되 알려진 잘못된 값이 실제로 걸리는지 시험합니다.
- 실패 후 행동과 완료 기준을 정합니다. 무엇을 고칠지, 언제 중단할지, 수정 후 어떤 항목을 다시 볼지 적습니다. 실행하지 않은 검사는 통과가 아니라 미실행으로 남깁니다.
개인 학습이라면 직접 원자료와 결과를 대조하는 작은 작업부터 시작해도 됩니다. 검사 프로그램이나 권한 제한을 구현해야 하는 단계에서는 도구 문서나 개발 지원이 필요할 수 있습니다.
Sources:
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
하네스 엔지니어링에서 '하네스(Harness)'가 의미하는 것은 무엇인가요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.
이 글이 도움이 되었나요?
도구에 상관없이 통하는 에이전트 원리와 설계 규칙을 정리했습니다
- 1AI 에이전트(AI Agent) 뜻과 챗봇, 워크플로의 차이
- 2에이전트 루프와 도구 호출(Tool Calling) 원리
- 3AGENTS.md와 CLAUDE.md(에이전트 지침 파일) 뜻과 작성법
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.