하네스 엔지니어링이 무엇이고, 어떻게 사용하는가

하네스 엔지니어링에 대해 찾아보게 된 이유

왜 이제야 하네스 엔지니어링에 대해 찾아보게 되었느냐가 더 정확하다.
요즘 AI에 관련된 영상들이 나의 유튜브 알고리즘의 비중을 많이 차지하고 있다. 그래서 '하네스 엔지니어링'이라는 것을 알게 되었는데, 사실 하네스 엔지니어링이 이슈가 된 지는 꽤 오래됐다. 하지만 이 주제로 너무 많은 영상들이 올라오는 것을 보게 되어서 사실 조금 외면하고 있었다. 빠른 AI 업데이트, 다양한 사람들의 프롬프트 전략 등 유튜브나 SNS에서 AI 관련 내용이 너무 많아져서 피로해진 것도 영향이 있다.
하네스 엔지니어링에 대한 내용도 많이 보이길래 언젠가는 제대로 찾아봐야겠다고 생각하고 있던 차에, 왜 이슈가 된 건지, 내가 써볼 만한 것인지 정리해 보기 위해 유튜브 영상들을 보며 알아보게 되었다.

하네스 엔지니어링이란?

먼저 하네스 엔지니어링이 등장하기 전, 어떤 엔지니어링이 있었는지부터 알아보면 이해하기 쉽다.
처음은 '프롬프트 엔지니어링'이다. 프롬프트 엔지니어링을 잘하기 위해서는 AI에게 최대한 잘 설명하기 위한 "말을 잘하는 기술"이 필요했다.
다음은 '컨텍스트 엔지니어링'이다. 자세히 설명하는 것에서 일의 히스토리까지 AI가 알게 하는 것이다.
그 다음이 '하네스 엔지니어링'이다. 자세히 설명하고 히스토리까지 알게 하더라도, 너무 많은 텍스트를 제공하다 보면 AI도 자세히 읽어보지 않고 실수를 하게 된다. 많은 텍스트 안에서 무엇이 중요한지, 어떤 순서로 판단해야 하는지, 어떤 내용을 신뢰해야 하는지가 명확히 분리되어 있지 않기 때문이다. 이런 실수를 하지 않도록 바운더리를 만들어주는 것이 하네스 엔지니어링이다. AI가 실수를 하더라도 스스로 실수를 발견하고 피드백을 거쳐 수정하는 것이다.
즉, 컨텍스트 엔지니어링은 규칙을 텍스트로 제공하고 AI가 이해하길 기대하는 방식이기 때문에, 텍스트가 많아질수록 중요한 규칙이 묻히거나 일부만 반영될 수 있다. 하네스 엔지니어링은 중요한 규칙을 테스트, 구조화된 피드백처럼 시스템적으로 '벗어날 수 없는 경계'로 만든다. 그래서 AI가 텍스트를 모두 반영하지 못해도, 바운더리 밖의 잘못된 행동을 감지하고 수정할 수 있도록 제어할 수 있다.

그럼 하네스 엔지니어링은 어떻게 이슈가 되었을까?
Open AI에서 하네스 엔지니어링 사용에 대한 문서(https://openai.com/ko-KR/index/harness-engineering/)가 공개되었다. 이 문서는 5개월 동안 개발자가 코드를 전혀 작성하지 않고 서비스를 출시하는 실험에 대한 내용이다.
바이브 코딩으로 인해 결국 AI가 코드를 구현하며 개발 속도가 빨라지긴 했지만, 결국 테스트는 개발자가 직접 해야 한다. 빠른 구현으로 인해 오히려 개발자의 개입이 생산성을 떨어뜨리게 된 것이다.
AI가 최대한 스스로 만들 수 있도록 시스템은 만드는 것이 하네스 엔지니어링의 시작이다.

Open AI 팀의 하네스 엔지니어링 전략은 다음과 같다.

로그 시스템을 통한 AI의 가시성 확보
컨텍스트 목차화를 통해 AI가 스스로 원하는 컨텍스트를 찾아가도록 만들기
AI가 정해진 룰을 벗어날 때 에러를 걸어줄 수 있는 훅 세팅

이미 사용 중인 하네스와 커스텀 하네스

우리가 사용하는 Claude Code나 Codex 같은 AI 도구들은 이미 '하네스' 그 자체이다. 유출된 Claude Code의 내부에서 "메인 브랜치에 force push 하지 말라", "새 커밋을 생성해라"와 같은 규칙들이 시스템 차원에서 설정되어 있는 것이다.
하네스 엔지니어링이 이미 탑재되었다고 해도, 서비스를 만들기 위해서는 아키텍트, 코드 리뷰, 테스트와 같이 더 탄탄한 시스템이 필요하다. oh-my-claudecode 와 같이 이미 잘 만들어진 오픈소스 하네스가 존재하기도 하지만, 결국 각각 프로젝트만의 규칙(API 규칙, 확정된 DB 스키마, 사용하지 않을 라이브러리 등)은 직접 채워야 한다. 이미 내장된 하네스나 오픈소스 하네스 모두 '커스텀 하네스'를 추가하는 작업이 필요하다.

하네스 프레임워크 예시

https://www.youtube.com/watch?v=AQOvNx87Urs

다음은 위 유튜브 영상에서 소개해준 '하네스 프레임워크' 전략으로, 전체적인 흐름을 이해하는데 도움이 되었다.

CLAUDE.md 는 AI가 코딩할 때 제일 먼저 읽는 파일이다. AI가 절대 어기면 안 되는 핵심 규칙들을 명시한다.

docs/는 프로젝트의 모든 컨텍스트가 들어가는 디렉터리이다.

execute.py는 하네스 실행 스크립트이다. docs/ 안의 문서를 기반으로 AI가 구현 단계를 여러 Phase로 쪼개고, 헤드리스 모드(claude -p)를 활용해 각 Phase를 실행하고 상태를 JSON 형태로 관리한다.

hooks/는 AI가 실수하기 전에 자동으로 차단하는 파일들이 있는 디렉터리이다.

이 프레임워크의 실행 흐름은

docs/ 문서를 전부 읽고,
구체화할 것이 있으면 개발자(사용자)와 논의한다.
구현 계획을 Phase로 쪼개고,
phases/에 Phase 파일을 생성한다.
execute.py를 실행한다.

개발자는 docs/채우고, /harness를 입력하는 것으로 사용할 수 있다.

정리하며

하네스 엔지니어링에 대해 찾아보며, 내가 사용했던 클로드 코드가 왜 내 명령을 제대로 수행하지 않았는지 알게 되었다. AGENTS.md, SKILL.md에 내가 원하는 내용을 추가하는 것에만 신경을 썼는데, 그 이후에도 클로드 코드가 내가 원하는 대로 작업해준다는 느낌을 받지 못했다. 내용을 더 추가했던 행동이 오히려 클로드가 임의로 판단을 하게 만들었던 것이다.

하네스 엔지니어링 시스템을 완전히 도입하여 사용하기까진 어렵다는 느낌이 들지만, 다음 사항들은 수행해 보려고 한다.

Claude.md 파일에 클로드가 하지 않아야 하는 것을 강조하기
AGENTS.md 내용을 목차화하고, 구체적인 내용은 docs/로 분리하기

새롭게 이슈되는 모든 AI를 다 활용해 보진 못하겠지만, 내가 하던 프로젝트에 필요한 부분만 조금씩 도입하는 것만으로도 AI 활용 능력을 올리는 방법이라고 생각한다.

boolean isGrowing = true;