https://www.youtube.com/watch?v=DrekqeDlO1w
해당 영상을 보고 공부한 내용을 간략하게 요약해 두려고 한다.
하네스 엔지니어링이란?
에이전트가 실수를 할 때마다, 그 실수가 다시는 반복되지 않도록 환경 자체를 설계하는 것
- 고삐, 인장 같이 말을 다루는 도구를 뜻하는 Harness에서 유래됐다.
프롬프트를 더 잘 쓰는 것이 아니라, 에이전트가 일하는 구조를 바꾸는 것이다.
AI 엔지니어링은 어떻게 진화했나
하네스가 왜 주목받게 됐는지 이해하려면 흐름을 먼저 보는 게 좋다.
프롬프트 엔지니어링 — AI한테 말을 잘 거는 기술. "이렇게 설명하면 더 잘 이해하더라"는 수준이었다.
컨텍스트 엔지니어링 — 단순히 질문을 잘 하는 걸 넘어, 프로젝트 상황과 배경을 AI에게 체계적으로 전달하는 방식으로 발전했다.
MCP + 스킬 — AI에게 도구를 연결하고, 사용할 수 있는 범위를 정해주기 시작했다. 그런데 스킬이 많아지자 AI가 오히려 헷갈려하는 문제가 생겼다.
하네스 엔지니어링 — 도구나 지시를 넘어, 에이전트가 일하는 환경 자체를 설계하는 단계다. 현재 가장 앞단의 흐름이다.
기존 방식의 두 가지 한계
하네스가 필요해진 데는 구체적인 이유가 있다.
1. 컨텍스트 부패
작업이 길어질수록 AI의 컨텍스트 창이 꽉 차면서 앞에서 했던 지시를 잊어버린다. 아무리 처음에 잘 설명해줘도, 대화가 길어지면 리셋된다.
해결책 — CLAUDE.md (Agents.md)
새 세션이 시작될 때마다 에이전트가 가장 먼저 읽는 파일이다. 1000줄짜리 설명서가 아니라, 60줄 이하의 핵심 지도 같은 것이다. 처음부터 완벽할 필요 없고, 실패할 때마다 한 줄씩 추가하면 된다.
2. 구조적 제약의 부재
"이건 절대 하면 안 돼"라는 규칙을 말로만 전달하면 언제든 어겨질 수 있다. 앞서 DB 테이블 삭제 사례처럼. 정보의 문제가 아니라 구조의 문제다.
해결책 — 훅(Hooks)
코드를 저장하기 직전에 자동으로 검사를 실행한다. 문제가 있으면 저장 자체가 안 되고, 에이전트가 스스로 수정하게 된다. 사람이 개입할 필요가 없다. "잘 짜줘"라고 부탁하는 게 아니라, 못 짜면 저장이 안 되는 구조를 만드는 것이다.
하네스의 3가지 핵심 요소
1. 컨텍스트 파일 (CLAUDE.md / Agents.md)
AI가 작업 시작 전 가장 먼저 읽는 파일이다. 규칙, 금지 사항, 프로젝트 맥락을 담는다. 핵심은 간결함이다. 항상 적용되는 내용만 넣고, 세부 사항은 별도 파일로 분리한다. 실패할 때마다 한 줄씩 추가하면서 점진적으로 발전시키는 방식이 효과적이다.
2. 자동 강제 시스템
말로 하는 규칙이 아니라, 위반하면 자동으로 막히는 구조다.
- 린터 — 코드 맞춤법 검사기처럼, 규칙을 어기면 자동으로 에러를 낸다.
- 프리커밋 훅 — 저장 전 자동 검사. 에러가 있으면 에이전트가 스스로 수정하고 다시 시도한다.
이 자동 교정 루프 덕분에 사람이 일일이 검토하지 않아도 된다.
3. 가비지 컬렉션
AI는 기존 코드를 보고 패턴을 따라간다. 나쁜 코드가 쌓이면 나쁜 패턴이 계속 복제된다. 그래서 주기적으로 청소하는 에이전트가 필요하다.
- 문서가 실제 코드와 달라진 건 없는지
- 규칙을 위반한 코드가 새로 생겼는지
- 사용하지 않는 코드가 쌓였는지
특정 스크립트나 파일이라기 보다는 "주기적으로 AI 한테 청소 작업을 시키는 루틴"에 가깝다.
예시는 다음과 같다.
문서 동기화
/docs 폴더의 API 문서랑 실제 코드를 비교해서 달라진 부분을 찾아줘. 문서가 오래된 거면 코드 기준으로 업데이트해줘.
죽은 코드 정리
우리 코드베이스에서 어디서도 import되거나 호출되지 않는 함수, 클래스, 변수를 찾아서 목록으로 보여줘. 삭제해도 안전한 것들은 바로 지워줘.
하네스 핵심 철학
에이전트가 규칙을 어겼을 때 프롬프트를 고치는 게 아니라, 그 실패가 구조적으로 반복 불가능하도록 환경을 수정한다.
https://openai.com/ko-KR/index/harness-engineering/
하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기
작성자: Ryan Lopopolo, 기술 스태프 멤버
openai.com
OpenAI가 공개한 하네스 블로그에서도 동일한 철학을 확인할 수 있다.
그들은 5개월 동안 크게 네 가지 규칙을 정해두고 바이브 코딩을 하는 실험을 진행하였다.
- Agents.md — AI 업무 지침서. 해도 되는 것과 절대 안 되는 것을 명시
- CI 게이트 — 저장할 때마다 자동 테스트 실행
- 도구 경계 — AI가 접근할 수 있는 범위와 권한을 사전에 설정
- 피드백 루프 — AI가 코딩 → 리뷰 → 규칙 보강 → 반복