하네스 엔지니어링
이 글의 목차
- 반복되는 실패 하나에서 시작하기
- 프롬프트만으로 부족한 순간
- 하네스를 식당으로 비유하기
- 프롬프트, 루프, 그래프, 하네스의 차이
- 하네스의 7요소
- 산출물 계약이란 무엇인가
- Codex 프로젝트의 작은 하네스 예시
- Agent, Skill, Orchestrator를 쉽게 구분하기
- 하네스 설계 Phase 0부터 7까지
- 좋은 하네스는 자유와 제약을 다르게 배치한다
- 검증을 작성자와 분리하기
- 재실행 가능성을 설계하기
- 관찰 가능성: 무슨 일이 있었는지 볼 수 있어야 한다
- 자주 하는 실패
- 작은 하네스부터 시작하는 방법
- 실습: 블로그 글 한 편의 작업 환경 만들기
- 체크리스트
- 정리
- 참고
반복되는 실패 하나에서 시작하기
AI에게 글 작성을 맡길 때마다 출처가 빠진다고 하자. 다음에는 출처를 적을 파일과 검토 기준을 준비하고, 출처가 없으면 게시 단계로 넘어가지 않게 만들 수 있다. 이것이 작은 하네스의 시작이다.
Agent, Skill, Orchestrator라는 이름보다 누가 무엇을 만들고 다음 단계가 무엇을 확인하는지 먼저 적자. 파일 구조는 이 작업 순서를 재사용하고 기록하기 위한 수단이다. 단일 에이전트가 같은 절차를 수행하는 구성도 가능하다.
자동차의 엔진이 아무리 좋아도 바퀴, 브레이크, 계기판, 안전벨트 없이 목적지까지 안전하게 갈 수 없다. AI 모델도 비슷하다. 모델은 판단하는 엔진이지만, 실제 일을 끝내려면 자료를 읽는 방법, 사용할 도구, 작업 공간, 권한, 테스트, 기록, 실패 복구가 필요하다.
이처럼 모델이 실제 환경에서 일하도록 둘러싼 실행 시스템을 하네스(Harness)라고 부른다. 하네스 엔지니어링은 AI가 덜 추측하고, 더 안전하게, 더 반복 가능하게 일하도록 이 환경을 설계하고 개선하는 일이다.
프롬프트만으로 부족한 순간
다음 프롬프트를 생각해 보자.
이 저장소의 로그인 버그를 찾아 고치고 배포해 줘.
모델이 이 문장을 잘 이해해도 다음이 없으면 실행할 수 없다.
- 저장소 파일을 읽고 수정할 도구
- 명령을 실행할 안전한 컴퓨터 환경
- 프로젝트 구조와 코딩 규칙
- 버그를 재현하는 방법
- 테스트와 빌드 명령
- Git 브랜치와 배포 절차
- 비밀 값에 대한 접근 정책
- 배포 전 사람 승인 규칙
- 실패했을 때 되돌리거나 재개하는 방법
좋은 프롬프트는 하네스의 한 부분이지 하네스 전체가 아니다.
하네스를 식당으로 비유하기
모델 요리사
프롬프트 주문서
컨텍스트 레시피와 식재료 정보
도구 칼, 불, 오븐
환경 주방
권한 사용할 수 있는 창고와 잠금장치
워크플로 조리 순서
테스트 맛과 위생 검사
로그 주문·조리 기록
사람 승인 알레르기·고가 메뉴 최종 확인
훌륭한 요리사에게 “맛있게 만들어 줘”라고 해도 재료가 어디 있는지 모르고 오븐이 고장 났다면 결과가 나오지 않는다. 반대로 주방이 잘 정리되어 있으면 주문이 조금 달라져도 일정한 품질로 반복할 수 있다.
프롬프트, 루프, 그래프, 하네스의 차이
| 개념 | 중심 질문 | 범위 |
|---|---|---|
| 프롬프트 | 무엇을 어떻게 요청할까? | 한 번의 지시와 출력 |
| 컨텍스트 | 판단에 무엇을 보여 줄까? | 모델이 보는 정보 |
| 루프 | 어떤 행동을 반복하고 언제 멈출까? | 모델·도구의 반복 |
| 그래프 | 단계와 분기를 어떻게 연결할까? | 업무의 실행 경로 |
| 하네스 | 이 모든 것이 실제 환경에서 안전하게 작동하려면 무엇이 필요할까? | 도구, 환경, 권한, 기록, 검증, 복구 전체 |
그래프는 하네스 안의 실행 제어 방식이 될 수 있다. 하네스는 그래프뿐 아니라 그 그래프가 사용할 파일 시스템, 도구, 정책, 테스트, 관찰 가능성까지 포함한다.
하네스의 7요소
1. 목표: 무엇을 완성해야 하는가
최종 산출물과 완료 조건을 정한다.
산출물: 기술 블로그 글 1편
완료 조건:
- 초보자가 이해할 수 있는 용어 설명
- 공식 출처 2개 이상 확인
- Jekyll 빌드 성공
- 공개 페이지에서 본문 확인
“최대한 잘해라”가 아니라 결과와 검증 방법을 함께 정의한다.
2. 컨텍스트: 무엇을 먼저 읽어야 하는가
- 프로젝트 안내 문서
- 관련 소스 파일
- 이전 결정 기록
- 공식 문서와 최신 상태
- 사용자 취향과 금지 조건
처음부터 모든 파일을 읽게 하지 않고, 작업 종류에 따라 관련 자료를 찾는 경로를 제공한다.
3. 도구: 어떤 손과 발을 줄 것인가
- 파일 검색과 읽기
- 안전한 파일 수정
- 테스트와 빌드 실행
- 웹 검색
- 데이터베이스 조회
- Git과 배포 도구
도구는 많다고 좋은 것이 아니다. 필요한 기능만 제공하고 읽기, 쓰기, 삭제, 외부 발송의 권한을 분리한다.
4. 중간 산출물: 바로 최종 결과로 가지 않기
긴 작업은 중간 결과를 파일로 남긴다.
요구사항 정리 → 조사 노트 → 목차 → 초안 → 검토표 → 최종본
중간 산출물이 있으면 방향을 일찍 확인하고, 실패한 단계만 다시 실행하고, 다른 에이전트나 사람이 이어받을 수 있다.
5. 검증: 무엇을 통과해야 하는가
- 단위 테스트와 통합 테스트
- 빌드와 타입 검사
- 링크 검사
- 사실 확인 체크리스트
- 형식과 정책 검사
- 배포 뒤 실제 동작 확인
가능하면 “AI가 보기에 괜찮다”보다 코드, 스키마, 테스트, 외부 상태처럼 독립적으로 확인 가능한 신호를 사용한다.
6. 권한과 승인: 어디서 사람이 책임지는가
AI가 제안하는 것과 실제로 실행하는 것을 분리한다.
초안 작성 자동 가능
내부 테스트 자동 가능
고객에게 발송 사람 승인 후 실행
프로덕션 배포 정책에 따라 승인
데이터 삭제 대상과 복구 가능성 확인 후 승인
승인 게이트에서는 실제 실행을 멈추고, 행동과 영향 범위를 보여 준 뒤 명시적인 승인을 받아야 한다.
7. 기록과 개선: 다음 실행을 어떻게 더 좋게 할까
- 어떤 입력과 버전으로 실행했는가
- 어떤 도구를 호출했는가
- 어디서 실패했는가
- 사람이 무엇을 수정했는가
- 비용과 시간이 얼마나 들었는가
- 다음번에 바꿀 규칙은 무엇인가
실패를 모델 탓으로만 끝내지 않고, 빠진 문서·도구·테스트·경계가 무엇이었는지 찾아 하네스에 반영한다.
산출물 계약이란 무엇인가
에이전트에게 “조사하고 글을 써”라고 하면 조사 결과가 대화 속에만 남거나 다음 단계가 어떤 내용을 믿어야 할지 모를 수 있다.
산출물 계약은 어떤 단계가 무엇을 어디에 저장하고, 다음 단계가 그것을 어떻게 읽는지 정한 약속이다.
| 단계 | 입력 | 출력 | 완료 조건 |
|---|---|---|---|
| 조사 | 주제, 공식 출처 | artifacts/research.md |
주장마다 출처 기록 |
| 작성 | 조사 노트, 문체 가이드 | artifacts/draft.md |
목차와 예제 포함 |
| 검토 | 초안, 평가 기준 | artifacts/review.md |
결함과 수정 제안 분리 |
| 최종화 | 초안, 검토표 | artifacts/final.md |
필수 기준 모두 통과 |
파일 이름 자체보다 중요한 것은 다음 단계가 추측하지 않고 이어받을 수 있다는 점이다.
Codex 프로젝트의 작은 하네스 예시
Codex에서 반복적인 콘텐츠 작업을 운영한다고 가정해 보자.
project/
├── AGENTS.md
├── .agents/
│ └── skills/
│ └── blog-writing-orchestrator/
│ └── SKILL.md
├── .codex/
│ └── agents/
│ └── technical-reviewer.toml
└── artifacts/
├── README.md
├── research.md
├── draft.md
├── review.md
├── final.md
└── improvement-log.md
처음 보면 파일이 많아 보이지만 역할은 단순하다.
AGENTS.md: 프로젝트에서 지켜야 할 안내판.agents/skills/.../SKILL.md: 반복 작업의 매뉴얼.codex/agents/*.toml: 별도 책임이 필요한 팀원 역할 카드artifacts/: 조사, 초안, 검토, 최종본, 개선 기록 보관함
간단한 작업이라면 이 구조를 전부 만들 필요가 없다. 반복 횟수, 실패 비용, 여러 사람의 인수인계 필요성이 커질 때 하나씩 추가한다.
Agent, Skill, Orchestrator를 쉽게 구분하기
Agent: 일을 맡은 팀원
예: 기술 사실만 검토하는 리뷰어. 책임과 입력·출력, 하지 말아야 할 일을 좁게 정한다.
Skill: 팀원이 따르는 작업 매뉴얼
예: “공식 출처 확인 → 주장 목록 작성 → 코드 검증 → 결함 표 작성”이라는 반복 절차.
Orchestrator: 순서와 전달을 관리하는 팀장
예: 조사 결과가 저장되면 작성 단계로 넘기고, 검토에서 실패하면 초안 단계로 돌려보내며, 배포 전 사람 승인을 요청한다.
모든 일을 여러 Agent로 나눌 필요는 없다. 한 에이전트가 순서대로 처리해도 문맥과 책임이 명확하면 그것이 더 단순하고 저렴하다.
하네스 설계 Phase 0부터 7까지
Phase 0. 현재 상황 확인
사용자의 목표, 경험 수준, 기존 프로젝트 구조와 도구를 확인한다.
Phase 1. 사람이 하는 절차 분석
AI 이야기를 잠시 빼고 사람이 이 일을 어떻게 하는지 적는다. 반복 단계, 필요한 자료, 위험 지점, 판단이 필요한 곳을 찾는다.
Phase 2. 최종 산출물 정의
마지막에 무엇을 열어 보거나 제출하면 성공인지 정하고 산출물 계약을 만든다.
Phase 3. 실행 패턴 선택
순차 실행, 병렬 조사, 작성-검토, 감독형 중 실제 업무에 맞는 흐름을 고른다.
Phase 4. Agent 역할 결정
책임과 문맥이 정말 분리될 때만 별도 역할로 나눈다. 에이전트 수가 많을수록 좋은 것은 아니다.
Phase 5. Skill 작성
각 작업의 트리거, 절차, 출력 형식, 품질 기준, 실패 대응을 반복 가능한 매뉴얼로 만든다.
Phase 6. Orchestrator 연결
단계 순서, 파일 전달, 재시도, 중단, 사람 승인, 부분 재실행 규칙을 연결한다.
Phase 7. 테스트와 개선
정상 사례, 애매한 사례, 실패하기 쉬운 사례로 시험하고 실제 실패를 개선 기록에 남긴다.
좋은 하네스는 자유와 제약을 다르게 배치한다
모든 행동을 세세하게 고정하면 모델의 판단 능력을 활용하지 못한다. 반대로 모든 것을 자유롭게 두면 일관성과 안전성이 떨어진다.
넓은 자유가 가능한 곳
- 제목 아이디어 발산
- 코드 구현 방법 선택
- 조사 검색어 선택
강한 제약이 필요한 곳
- 개인정보 취급
- 데이터 스키마
- 아키텍처 의존 방향
- 배포와 삭제 권한
- 법적 필수 문구
경계와 합격 기준은 엄격하게, 그 안의 구현 방식은 자율적으로 두는 방식이 실용적이다.
검증을 작성자와 분리하기
결과를 만든 모델이 스스로 “완벽하다”고 평가하면 놓친 오류를 그대로 통과시킬 수 있다.
작성자: 초안을 만든다.
평가자: 초안을 만든 과정은 보지 않고 결과와 기준만 확인한다.
검증 도구: 빌드, 테스트, 링크 검사로 객관적인 신호를 낸다.
사람: 중요한 판단과 외부 실행을 승인한다.
평가자도 모델이므로 항상 맞지는 않는다. 통과·실패 예시와 체크리스트를 제공하고, 가능한 항목은 자동 테스트에 묶는다.
재실행 가능성을 설계하기
좋은 하네스는 처음부터 끝까지 다시 돌리는 것만 지원하지 않는다.
초기 실행 자료가 없으므로 조사부터 시작
부분 재실행 검토만 실패했으므로 작성 단계부터 재개
새 실행 이전 산출물을 보관하고 새 실행 ID로 시작
각 산출물에 생성 시점, 입력 버전, 상태를 기록하면 오래된 자료를 실수로 재사용하는 일을 줄일 수 있다.
관찰 가능성: 무슨 일이 있었는지 볼 수 있어야 한다
운영 중에는 최종 답변만 저장해서 부족하다.
- 단계별 소요 시간
- 모델과 프롬프트 버전
- 도구 호출과 결과 상태
- 입력·출력 토큰과 비용
- 재시도 횟수
- 승인 대기 시간
- 실패 유형
- 사람이 수정한 부분
다만 로그에 API 키, 개인정보, 원문 기밀 자료를 그대로 남기지 않도록 마스킹과 보존 기간을 정한다.
자주 하는 실패
긴 프롬프트를 하네스라고 부른다
도구, 상태, 검증, 권한, 기록이 없다면 정교한 프롬프트일 수는 있어도 완전한 실행 하네스는 아니다.
처음부터 멀티 에이전트를 만든다
책임과 문맥 경계가 없는데 역할만 여러 개로 나누면 비용과 전달 오류가 늘어난다. 먼저 단일 흐름으로 시작한다.
문서만 쓰고 강제하지 않는다
중요한 규칙은 테스트, 스키마, 린터, 권한 정책처럼 기계적으로 확인해야 한다.
중간 결과를 대화에만 남긴다
세션이 길어지거나 중단되면 사라진다. 다음 단계가 읽을 수 있는 산출물로 외부화한다.
승인이라고 써 놓고 멈추지 않는다
“사람 검토 필요”라는 라벨만 붙인 채 발송이나 배포까지 실행하면 승인 게이트가 아니다.
하네스를 계속 두껍게만 만든다
모델과 도구가 좋아져 더는 필요 없는 규칙도 생긴다. 각 구성 요소가 실제 실패를 막는지 정기적으로 확인하고 불필요한 부분은 제거한다.
작은 하네스부터 시작하는 방법
블로그 글 작성 업무라면 첫 버전은 이 정도면 충분하다.
1. 목표: 초보자용 기술 글 1편
2. 입력: 주제, 독자, 공식 출처
3. 중간 결과: 목차 → 초안
4. 검증: 사실 체크 + Jekyll 빌드
5. 승인: 게시 전 사용자 확인
6. 기록: 수정 요청을 improvement-log에 저장
실제로 반복하면서 “링크 누락이 자주 난다”는 실패를 발견하면 링크 검사를 추가한다. “문체가 매번 달라진다”면 좋은 글 예시와 문체 규칙을 추가한다. 실제 실패가 하네스의 다음 요구사항이 된다.
실습: 블로그 글 한 편의 작업 환경 만들기
먼저 사람이 할 일을 순서대로 적는다. 주제를 정하고, 근거를 찾고, 초안을 쓰고, 사실과 링크를 검토한 뒤 게시한다. 이 순서에서 매번 빠지는 항목을 찾는다.
예를 들어 게시한 글에서 깨진 링크가 자주 발견된다면 최종 검토에 링크 확인을 넣고, 실패하면 게시 단계로 넘어가지 않게 한다. 이것은 모델의 문장 능력을 바꾸는 것과 다른 종류의 개선이다.
입력: 주제, 독자 수준, 참고 자료
조사 결과: 주장과 출처 목록
초안: 제목, 설명, 예제, 예상 결과
검토: 사실 오류, 링크 오류, 빠진 전제
완료: 검토 통과 + 게시 권한 확인
처음부터 역할을 많이 만들지 않기
처음에는 한 에이전트가 이 순서를 따라도 된다. 조사와 검토의 문맥이 너무 커지거나 독립적인 책임 분리가 필요할 때만 역할을 나눈다.
대신 중간 결과는 남긴다. “조사를 잘했다”는 대화 한 줄보다, 어떤 주장에 어떤 출처가 있는지 적힌 파일이 다음 작업에서 더 유용하다.
실패 후 무엇을 고칠까
기술 설명이 틀렸다면 근거 확인 규칙을, 파일을 찾지 못했다면 자료 위치 안내를, 테스트를 생략했다면 완료 기준을 고친다. 모든 실패를 프롬프트 문장 하나로 해결하려 하지 말고 어느 실행 조건이 부족했는지 찾는다.
체크리스트
- 최종 산출물과 완료 기준이 명확한가?
- AI가 먼저 읽어야 할 자료 경로가 있는가?
- 도구의 책임과 권한이 필요한 만큼만 열려 있는가?
- 중간 결과가 대화 밖에 저장되는가?
- 작성과 평가가 적절히 분리됐는가?
- 외부 행동 전에 실제로 멈추는 승인 게이트가 있는가?
- 실패한 단계부터 재실행할 수 있는가?
- 실행 기록으로 원인을 추적할 수 있는가?
- 실제 실패를 규칙·도구·테스트 개선으로 되돌리는가?
- 필요 없는 구성 요소를 제거할 기준도 있는가?
정리
하네스 엔지니어링의 핵심은 AI에게 더 긴 지시를 주는 것이 아니다. 목표, 컨텍스트, 도구, 산출물, 검증, 권한, 기록을 실행 환경에 넣어 모델이 안정적으로 일하도록 만드는 것이다.
하지만 구조가 그럴듯하다고 좋은 하네스인 것은 아니다. 다음 편에서는 동일한 테스트 사례로 프롬프트와 에이전트를 측정하고, 변경이 실제 개선인지 판단하는 평가 방법을 다룬다.