하네스 엔지니어링의 기초

하네스 엔지니어링은 에이전트에게 "무엇을 하라"고 말하는 기술보다, 에이전트가 무엇을 볼 수 있고, 어떤 기준으로 판단하며, 어디서 멈추고, 어떻게 검증받는지를 설계하는 기술에 가깝습니다.

작업이 길어질수록 병목은 이동한다

왜 프롬프트만으로는 부족한가

짧은 작업에서는 프롬프트 품질이 체감 성능을 좌우할 수 있습니다. 하지만 작업 시간이 길어지고, 리포지터리가 커지고, 변경 범위가 넓어질수록 병목은 다른 곳에서 생깁니다.

• 필요한 맥락이 리포 안에 없어서 에이전트가 추론할 재료가 부족함
• 완료 기준이 모호해서 스스로 "끝났다"고 착각함
• 검증 루프가 약해서 겉보기로만 동작하는 결과를 만들기 쉬움
• 오래된 문서와 규칙이 뒤섞여서 stale context가 누적됨
• 사람의 승인 지점이 정의되지 않아 위험한 변경과 안전한 변경을 구분하지 못함

즉, 문제는 모델이 멍청해서가 아니라 모델이 일하는 작업장 자체가 정리되어 있지 않아서 생기는 경우가 많습니다.

무엇이 바뀌었기에 하네스가 전면으로 올라왔는가

하네스는 무엇을 포함하는가

하네스는 보통 아래를 함께 다룹니다.

프롬프트 엔지니어링, 컨텍스트 엔지니어링과의 관계

컨텍스트 엔지니어링은 하네스의 일부입니다. 하지만 하네스는 거기서 멈추지 않고 역할 분리, 평가 루프, 승인 흐름, 운영 규율까지 포함합니다.

왜 지금 더 중요해졌는가

최근 코딩 에이전트는 더 긴 작업을 수행하고, 브라우저와 쉘, 로그, 배포 시스템까지 다룰 수 있게 되었습니다. 그 결과 "한 번 잘 답하게 만드는 것"보다 "몇 시간 동안 방향을 잃지 않게 만드는 것"이 더 중요한 문제가 됐습니다.

OpenAI는 2026년 2월 11일 글에서 agent-readable repo, 짧은 AGENTS.md, 구조화된 docs/, 브라우저와 관측성 접근, 그리고 문서 가드닝을 강조했습니다. Anthropic은 2026년 3월 24일 글에서 긴 작업에서 planner와 evaluator가 언제 유의미한지, 그리고 모델이 좋아질수록 하네스도 단순화될 수 있지만 사라지지는 않는다고 설명했습니다.

핵심은 같습니다.

2026년 기준 주요 자료들이 던진 문제

하네스 엔지니어링의 산출물

좋은 하네스는 추상적인 철학으로 끝나지 않습니다. 리포지터리 안에 다음과 같은 형태로 남습니다.

• 짧고 최신 상태인 AGENTS.md 또는 동등한 진입 문서
• 아키텍처와 도메인 규칙을 설명하는 버전 관리 문서
• 실행 계획, 릴리즈 규칙, 테스트 루틴, QA 체크리스트
• 역할별 슬래시 커맨드, 스킬, 에이전트 정의 파일
• 누가 언제 승인해야 하는지 드러나는 워크플로우
• 무엇이 stale인지 찾고 정리하는 운영 루프

하네스가 없는 팀의 증상

안티패턴

• 거대한 규칙 파일 하나에 모든 것을 넣기
• "잘 알아서 해"에 가까운 암묵지 의존
• 문서와 워크플로우를 분리해서 따로 관리하기
• 평가 기준 없이 결과만 많이 생성하도록 유도하기
• 팀 특화 규칙 없이 외부 템플릿을 그대로 복붙하기

기억할 문장

하네스 엔지니어링은 모델을 보완하는 비법이 아니라, 모델이 실패하기 쉬운 지점을 시스템으로 감싸는 설계입니다.