하네스 엔지니어링이 뭔가요

바이브 코딩은 왜 어려운가

모델은 점점 좋아지는데, 왜 AI 코딩 결과물은 여전히 들쭉날쭉할까?

나도 한동안은 더 좋은 툴을 찾아다니면 해결될 문제라고 생각했다.

Cursor도 써보고, Claude Code도 써보고, Codex도 오래 붙잡아 봤다. 하지만 시간이 지나고 보니 문제는 툴 하나하나의 성능보다, 그 툴을 어떤 환경에서 어떻게 일하게 만들고 있었는가에 더 가까웠다.

그리고 바이브 코딩 너머 개발자 생존법을 읽고 돌아보니, 내가 해온 바이브 코딩은 실패할 수밖에 없는 방식이었다는 생각이 들었다.

제대로 시작해보는 바이브 코딩

이제는 AI를 쓰느냐 마느냐보다 AI를 어떻게 쓰느냐가 더 중요해진 시대다.

문제는 이 업계가 너무 빠르게 바뀐다는 점이다. 
몇 주 사이에도 툴과 모델의 평가가 뒤집히고, 새 기능이 쏟아진다.

그래도 한 가지는 크게 달라지지 않는다. 
좋은 결과는 결국, 더 좋은 모델 하나만으로 나오지 않는다. 
그 모델이 어떤 환경에서 일하는지에 따라 결과물의 품질은 생각보다 크게 달라진다.

그래서 이제는 프롬프트만이 아니라, 에이전트가 일하는 환경 전체를 함께 봐야 한다.

하네스 엔지니어링?

얼마 전까지만 해도 프롬프트보다 컨텍스트라고 하며 컨텍스트 엔지니어링이 한창 유행했었다.

프롬프트 엔지니어링이 에이전트에게 무엇을 지시할까에 가까웠다면, 컨텍스트 엔지니어링은 에이전트에게 무엇을 보여줄까에 가깝다. 에이전트는 사용자가 전달한 컨텍스트를 바탕으로 프롬프트를 이해하고, 그 방향에 맞춰 작업한다.

최근에는 프롬프트나 컨텍스트를 넘어, 에이전트가 일하는 작업 환경 전체를 설계하는 관점을 하네스 엔지니어링이라고 설명하는 경우가 늘고 있다. 프롬프트와 컨텍스트를 포함해 에이전트에게 어떤 도구, 제약, 검증, 피드백 루프를 쥐어줄까를 함께 설계하는 개념이다.

내가 이해한 방식으로 단순화하면, 하네스 엔지니어링은 프롬프트와 컨텍스트를 포함해 에이전트의 작업 환경 전체를 다루는 관점에 가깝다.

하네스 엔지니어링은 왜 중요한가?

모델은 계속 좋아지고 있다. 내 경험만 해도 GPT-5 시절의 Codex와 2026년 3월 28일 기준 GPT-5.4는 실제 사용감에서 체감 차이가 꽤 크다.

하지만 똑똑해진 모델도 여전히 실수한다. 이런 실무적 실패는 대부분 환경 문제에서 발생한다.

권한이 과하면 사용자가 의도하지 않은 작업으로 치명적인 결과를 초래할 수 있고, 부족하면 작업 중간마다 사람의 손길이 필요해 생산성이 떨어질 수 있다.

또한 검증 루프가 없다면 모델의 환각은 곧 코드가 된다. 여기에 저장소 규칙과 승인 흐름까지 없다면, 에이전트는 코드 구조뿐 아니라 작업 이력까지 쉽게 어지럽힐 수 있다.

결국 실무에서의 경쟁력은 최고의 모델을 쓰느냐보다, 에이전트가 일할 환경을 얼마나 탄탄하게 설계했느냐에 더 크게 좌우된다.

하네스 엔지니어링이 중요하고 이를 배워야 할 이유는 인간 엔지니어의 역할이 코드를 직접 작성하는 일보다, AI가 안정적으로 성과를 내는 환경을 설계하는 일로 이동하고 있기 때문이라고 생각한다.

그래서 하네스 엔지니어링은 무엇을 설계해야 하는가?

하나의 규칙이 분명한 소프트웨어 팀을 만든다고 생각하면 이해하기 쉽다. 그 팀의 구성원들이 지켜야 할 규칙, 사용해야 할 도구, 일하는 과정을 포함해 개발 과정의 평가와 운영까지 함께 설계하는 셈이다.

하나의 운영 가능한 시스템을 구성해야 한다. 이 글에서는 어떤 부분을 설계해야 하는지 간단한 목록으로만 소개한다.

1. 도구 접근

에이전트가 뭘 할 수 있나? 더 똑똑한 모델보다 적절한 도구를 가진 모델이 문제 해결에 더 유용할 수 있다.

• 파일 읽기/쓰기
• 터미널 실행
• 테스트 실행
• 린터/포매터 실행
• 문서 검색
• 이슈/PR 읽기
• 배포 권한 유무

최근의 코딩 에이전트 도구들은 멀티 에이전트와 스킬 기반 작업을 지원한다. 이런 기능을 활용하면 상황에 맞는 도구를 연결하고, 에이전트마다 권한 범위도 다르게 설계할 수 있다.

2. 제약 조건

에이전트가 뭘 하면 안 되나?

• 특정 디렉터리만 수정 가능
• 민감 파일 접근 금지(.env나 keyfile)
• 스키마/아키텍처 규칙 강제
• 허용된 명령만 실행
• 사람 승인 후에만 머지/배포 가능

OpenAI의 하네스 엔지니어링 글에서도 긴 AGENTS.md 하나에 모든 내용을 몰아넣기보다, 짧은 AGENTS.md를 목차처럼 두고 별도 문서 체계를 함께 운영하는 방식이 더 잘 작동했다는 사례를 소개한다.

장문의 AGENTS.md와 관련한 내용은 해당 논문이나 OpenAI의 Best Practices 글을 추가로 읽어보길 권한다.

이런 제약 조건은 AGENTS.md 같은 마크다운 문서로만 제어하기보다, 실제 개발 도구나 스크립트로 함께 제한하는 편이 더 효과적이다.

3. 피드백 루프

에이전트가 결과를 어떻게 교정할 수 있는가?

• 테스트 실패
• 타입 체크 실패
• 린트 실패
• 벤치마크 점수
• 리뷰 코멘트
• 로그와 추적 기록

"이게 아니야, 다시 해줘" 같은 감각적인 재시도 프롬프트보다 테스트 실패나 타입 오류처럼 기계적으로 검증 가능한 피드백을 주는 편이 훨씬 낫다.

테스트, 타입 체크, 린트, 벤치마크는 자신이 쓰는 언어의 도구를 미리 세팅해 두고, 에이전트가 사용할 수 있게 환경을 구성해 둘 수 있다.

또한 Git과 GitHub를 활용하면, 메인 브랜치에 바로 반영하기보다 PR 검토를 거쳐 머지하는 흐름을 만들 수 있다. 이 검토 과정 역시 전용 에이전트에게 맡기도록 설계할 수 있다.

로그와 추적 기록도 관련 환경을 잘 갖춰두면, 에이전트가 오류 원인을 더 쉽게 추적하도록 도울 수 있다.

4. 상태와 기억

에이전트는 이전 작업을 얼마나 기억할 수 있는가?

• 작업 로그
• 설계 의사결정 기록
• 저장소 규칙
• 이전 실패 사례
• 할 일 목록과 체크리스트

OpenAI의 하네스 엔지니어링 글에 따르면, 이런 저장소 지식을 docs 폴더에 정리해 하나의 기록 시스템으로 만들고 에이전트에게 제공하는 방식이 강조된다.

한 작업이 끝날 때마다 관련 문서를 남겨두면, 다음 작업에서도 그 맥락을 이어받을 수 있다. 이는 일관성을 높이고 같은 실수를 반복하지 않게 만드는 데 도움이 된다.

5. 평가와 운영

현재 하네스가 잘 작동하고 있는가?

• 성공률
• 재시도율
• 인간 개입 빈도
• 평균 수정 횟수
• 테스트 통과율
• 회귀 발생률
• 작업 소요 시간

좋은 하네스는 감으로 판단하기 어렵다.

겉으로 보기엔 에이전트가 잘 일하는 것 같아도, 실제로는 재시도가 늘고 사람 검토 시간이 더 길어졌을 수도 있다.

그래서 결국 운영 지표가 필요하다.

성공률, 재시도율, 인간 개입 빈도 같은 숫자를 봐야 지금의 환경이 정말 생산성을 높이는지 판단할 수 있다.

결국 하네스 엔지니어링도 말장난이 아닌가?

프롬프트, 컨텍스트 엔지니어링처럼 하네스도 결국 한때의 유행이 아닐까 생각할 수도 있다.

하지만 내가 이해한 방식으로 보면, 하네스 엔지니어링은 프롬프트와 컨텍스트를 포함해 에이전트의 작업 환경 전체를 다루는 관점에 가깝다.

앞으로는 하네스 엔지니어링이라는 표현 대신 더 나은 말이 등장할 수도 있다. 그래도 에이전트가 더 잘 일하도록 환경을 설계한다는 문제 자체는 쉽게 사라지지 않을 것이다.

하네스 엔지니어링도 갑자기 나타난 것이 아니라, 이전 개념들을 더 발전시키는 과정에서 나온 표현이기 때문이다.

"더 편하고 좋은 방식이 금방 나오지 않을까?"하며 덮어두기엔, 당신 스스로에게 AI 기술 부채가 쌓이고 있다.

그래서 뭘 공부해볼까?

AI 에이전트를 같은 팀의 신입 팀원이라고 생각해보자. 그리고 그 팀원과 함께 사이드 프로젝트를 진행한다고 가정해보자.

우리는 일정한 품질로 개발을 진행하기 위해 규칙을 정해야 한다.

• 테스트 자동화
  • unit/integration/e2e test 과정
  • 또한 테스트 실패를 팀원(에이전트)들이 이해하기 쉬운 형태로 돌려주는 법
• 정적 검증
  • lint, formatter, type checker
  • schema validation
• Repository 구조화
  • 문서화 규칙
  • 작업 규칙 명시
  • 각종 컨벤션을 팀원(에이전트)이 읽기 쉽게 만드는 법
• 도구 권한 설계
  • 각자의 역할에 맞게 특정 도구를 허용하거나 금지할지 설계
  • sandbox와 approval flow 설정
• 평가 체계
  • 하나의 개발 과정(브랜치)에 대해 결과를 어떻게 측정할지
  • 또한 그 결과가 좋은지 나쁜지를 어떤 기준으로 판단할지
  • 회귀를 어떻게 탐지할 것인지
• 관찰 가능성
  • 로그, 실행 이력, 실패 원인 추적 방법

마무리: 팀장이 되어보자

나도 아직 5년 차 개발자로서 부족한 게 많다.

우리는 AI 에이전트라는 신입 팀원을 받았다. 시키는 일을 잘하지만, 많이 덜렁대고 사고도 많이 치는...팀원이다.

이 신입이 사고를 치지 않도록 세심하게 챙겨주고, 좋은 환경을 만들어주는 팀장이 되어보자.

이미 이런 식으로 에이전트의 작업 환경을 설계하고 운영하는 개발자라면, 사실상 작은 개발 조직의 팀장과 비슷한 역할을 하고 있는 셈이다.