하네스 엔지니어링 입문 가이드 — AI 에이전트 시대에 사람이 하는 일

AI와 함께 일한다는 건, 함께 요리하는 것과 비슷합니다

여러분 팀에 요리를 엄청나게 잘하는 새 팀원이 들어왔다고 생각해 보세요. 어떤 요리든 만들 수 있고, 속도도 빠릅니다. 문제는 이 팀원이 여러분의 주방에서 일해본 적이 없다는 것뿐입니다.

이 팀원에게 "오늘 저녁 알아서 해줘"라고 하면 어떻게 될까요? 냉장고에 있는 재료를 쓰는 대신 새 재료를 사오고, 집에 없는 도구를 찾고, 가족 중 누가 알레르기가 있는지도 모릅니다. 접시 위치도 몰라서 주방을 어지럽히죠. 요리 실력은 훌륭한데, 결과물은 기대와 다릅니다.

2026년, AI를 실무에 쓰는 상황이 딱 이렇습니다. AI는 코드를 짜고, 글을 쓰고, 데이터를 분석할 줄 압니다. 그런데 "알아서 해줘"라고 하면 우리 상황을 모른 채 자기 방식대로 일해 버립니다.

그래서 나온 게 하네스 엔지니어링(Harness Engineering)입니다. 쉽게 말해, 이 새 팀원이 우리 주방에서 제대로 일할 수 있도록 레시피, 재료 목록, 조리 순서, 맛 검수 기준을 미리 갖춰두는 겁니다.

어떻게 여기까지 왔나 — 용어가 빠르게 바뀐 이유

하네스 엔지니어링이라는 말이 갑자기 튀어나온 게 아닙니다. AI와 사람이 함께 일하는 방식이 점점 발전하면서, 단계마다 새 이름이 붙었을 뿐입니다. 요리 팀원 비유로 이 흐름을 따라가 보겠습니다.

2024년: "이건 어떻게 만들어?" — 프롬프트 엔지니어링 시대

ChatGPT가 일상에 자리 잡은 시기입니다. 사람들은 AI에게 질문하는 법을 배웠습니다. "파스타 레시피 알려줘"라고 물으면 AI가 답을 주는 식이었죠. 이때 사람이 하는 일은 질문을 잘 던지는 것이었습니다. 이걸 프롬프트 엔지니어링(Prompt Engineering)이라고 불렀습니다.

요리로 치면, 레시피 책에서 원하는 페이지를 정확히 찾는 기술입니다. AI는 책이고, 사람은 독자였습니다.

2025년 초: "이거 대신 만들어줘" — 바이브코딩 시대

OpenAI 공동 창립자 안드레이 카파시(Andrej Karpathy)가 바이브코딩(Vibe Coding)이라는 말을 만들었습니다. "분위기(Vibe)에 맡긴다"는 뜻인데, 채팅창에 "쇼핑몰 만들어줘"라고 치면 AI가 코드를 통째로 만들어주는 방식입니다. 코딩을 전혀 몰라도 앱을 만들 수 있다는 가능성이 열렸습니다.

요리로 치면, "오늘 저녁 파스타 만들어줘"라고 말하면 AI가 처음부터 끝까지 다 만들어주는 겁니다. 사람은 맛만 보면 됐습니다.

그런데 문제가 생겼습니다. AI가 만든 파스타 맛은 괜찮은데, 냉장고에 있는 재료를 안 쓰고 새 재료를 사왔습니다. 조리대도 어질러 놓았고요. 가족은 매운 걸 못 먹는데 고추를 넣었습니다. 한 번 만들어주는 건 괜찮은데, 매일 같이 일하기엔 문제가 많았습니다.

2025년 말: "우리 주방 상황을 좀 알려줘야겠다" — 컨텍스트 엔지니어링 시대

사람들이 깨달은 겁니다. AI에게 결과만 요청하면 안 되고, 우리 쪽 사정을 충분히 알려줘야 한다는 걸요. "냉장고에 이런 재료가 있고, 가족은 매운 거 못 먹고, 30분 안에 만들어야 해"라고 상황을 설명해주니까 결과가 훨씬 나아졌습니다.

이걸 컨텍스트 엔지니어링(Context Engineering)이라고 불렀습니다. AI에게 주는 정보의 양과 질을 설계하는 기술이죠.

2026년: "매일 함께 요리하려면 식당 운영 체계가 필요하다" — 하네스 엔지니어링 시대

상황을 잘 알려주면 한 번의 결과는 좋아집니다. 그런데 매일, 반복적으로, 안정적으로 AI와 함께 일하려면 매번 처음부터 설명하는 것만으로는 부족합니다.

이 시기에 Anthropic의 Claude Code 같은 AI 에이전트 도구가 실무에서 본격적으로 쓰이기 시작했습니다. Claude Code는 프로젝트 전체를 읽고, 코드를 짜고, 테스트를 돌리고, 에러를 고치는 것까지 스스로 수행합니다. 그런데 이 강력한 도구를 제대로 쓰려면, 프로젝트에 규칙과 구조가 잘 잡혀 있어야 한다는 게 분명해졌습니다.

요리로 치면 이런 깨달음입니다.

“

"매일 다른 메뉴를 만들어야 하는데, 매번 레시피를 읊어줄 수는 없잖아. 그러면 식당을 운영하듯이 체계를 갖추자. 냉장고 재료를 파악하는 담당, 홀 예약을 관리하는 담당, 조리 순서를 짜는 담당, 완성된 요리의 맛을 검수하는 담당을 정하면, 매일 수십 가지 요리를 안정적으로 낼 수 있지 않을까?"

이게 하네스 엔지니어링입니다. 혼자 요리하던 주방에서, 역할이 나뉜 식당 시스템으로 바뀌는 겁니다. 2026년 초 OpenAI가 이 개념을 공식 블로그에서 정리하면서 이름이 붙었고, Martin Fowler(소프트웨어 엔지니어링의 거장)가 관련 글을 쓰면서 업계 전체로 퍼졌습니다.

용어가 4번이나 바뀌었지만, 방향은 하나입니다. "AI에게 한 번 시키기"에서 "AI와 매일 함께 일하는 팀 만들기"로, 점점 더 넓은 범위를 설계하게 된 것이죠. 새 용어가 나올 때마다 처음부터 다시 배워야 하는 게 아니라, 이전 단계 위에 한 겹이 더 쌓인 거라고 보면 됩니다.

이 용어는 어디서 나왔고, 왜 갑자기 퍼졌나

하네스 엔지니어링은 학교나 연구소에서 천천히 만들어진 개념이 아닙니다. 현장에서 AI 에이전트를 쓰다 보니 자연스럽게 생긴 겁니다.

"AI가 대신 짜준다는데, 왜 결과가 들쭉날쭉하지?"

2025년 말~2026년 초, Claude Code 같은 AI 에이전트를 실무에 도입한 팀들이 공통으로 겪은 문제가 있었습니다.

• AI가 코드를 잘 짜긴 하는데, 팀의 코딩 규칙을 무시합니다
• 기존 프로젝트와 안 맞는 방식으로 파일을 만듭니다
• 한 번은 괜찮은데, 매일 돌리면 결과가 들쭉날쭉합니다
• 에러가 나면 결국 사람이 직접 고쳐야 합니다

식당으로 치면, 실력 좋은 셰프를 데려왔는데 우리 식당의 메뉴, 식자재 기준, 조리 동선, 접시 규격을 모르니까 매번 다른 결과가 나오는 상황입니다.

이 문제를 해결한 팀들의 공통점이 있었습니다. AI 모델을 더 좋은 걸로 바꾼 게 아니라, AI가 일하는 환경을 체계적으로 갖춘 겁니다.

Claude Code에서의 하네스 — 실제로 어떻게 생겼나

이 블로그를 예로 들겠습니다. 저는 Claude Code로 이 블로그를 만들고 운영하고 있습니다. 처음에는 "이거 만들어줘"라고 말하면 됐는데, 프로젝트가 커지면서 AI의 결과물이 일관되지 않는 문제가 생겼습니다. 그래서 이런 구조를 만들었습니다.

이 구조를 갖추고 나니, AI에게 "하네스 엔지니어링에 대한 블로그 글을 써달라"고 하면 매번 비슷한 수준의 결과가 나옵니다. 리서치, 초안, SEO 메타데이터, 퀴즈까지 정해진 순서대로 진행됩니다.

용어가 공식화된 계기

2026년 초, OpenAI가 자사 블로그에서 이 작업 방식을 하네스 엔지니어링(Harness Engineering)이라고 이름 붙이면서 용어가 퍼졌습니다. 같은 시기에 Martin Fowler가 관련 글을 냈고, Anthropic도 2026년 보고서에서 "엔지니어의 95%가 매주 AI 도구를 사용한다"는 수치를 공개하면서 업계 전체로 확산됐습니다.

핵심 메시지는 하나였습니다.

“

"진짜 어려운 건 AI 모델이 아니라 모델이 일하는 환경이다. 좋은 셰프를 뽑는 것보다, 그 셰프가 매일 안정적으로 요리를 낼 수 있는 식당 운영 체계를 만드는 게 더 중요하다."

하네스 엔지니어링이란 구체적으로 뭔가

용어의 뜻

하네스(Harness)는 원래 말에 씌우는 마구를 뜻하는 영어 단어입니다. 동사로는 "강력한 것을 길들여서 쓸모 있게 활용한다"는 뜻이고요. OpenAI는 이렇게 정리했습니다.

“

"하네스는 AI 에이전트를 감싸는 환경, 규칙, 확인·수정 체계 전부를 말한다. 에이전트가 안정적으로 일할 수 있게 만드는 틀이다."

쉽게 풀면, 실력 좋은 셰프가 우리 식당에서 매일 안정적으로 요리를 낼 수 있게 만드는 운영 체계 전체입니다.

하네스의 4가지 구성 — 식당 역할로 이해하기

핵심은 이겁니다. 하네스는 AI 에이전트 자체(셰프)가 아닙니다. 셰프를 둘러싼 식당 운영 체계 전체입니다. 좋은 AI 모델을 고르는 건 실력 좋은 셰프를 뽑는 것이고, 하네스 엔지니어링은 그 셰프가 매일 좋은 요리를 낼 수 있는 팀과 시스템을 만드는 겁니다.

하네스 엔지니어링의 5가지 핵심 원칙

Martin Fowler와 OpenAI의 문서를 종합하면, 하네스 엔지니어링은 5가지 원칙으로 구성됩니다.

1. 범위를 정해주기 — "이 재료만 쓰고, 여기서만 요리해"

AI에게 "알아서 해줘"라고 하면 범위를 넘어서는 일을 합니다. 파일을 지우거나, 엉뚱한 라이브러리를 깔거나, 의도하지 않은 방향으로 코드를 바꿀 수 있습니다.

새 팀원에게 "냉장고 안에 있는 재료만 써. 새 재료 사지 마. 오븐은 쓰지 말고 가스레인지만 사용해"라고 범위를 정해주는 것과 같습니다. 이게 없으면 매번 예상 밖의 결과가 나옵니다.

실무 예시: CLAUDE.md 같은 프로젝트 지침 파일에 "TypeScript만 사용, 새 파일 만들기 전에 기존 파일부터 확인, 이 태그 목록에서만 선택"이라고 적어둡니다.

2. 우리 쪽 사정 알려주기 — "레시피랑 우리 가족 취향은 이래"

AI는 능력은 있지만, 여러분의 프로젝트에 대해서는 아무것도 모릅니다. 코딩 규칙, 폴더 구조, 이름 짓는 방식 같은 걸 알려줘야 합니다.

"우리 집은 매운 거 안 먹어. 아이가 있어서 재료를 잘게 썰어야 해. 그릇은 이 찬장에 있어." 이런 정보를 미리 알려주면 팀원이 처음부터 가족 입맛에 맞는 요리를 만들 수 있습니다.

실무 예시: 프로젝트에 README.md, 아키텍처 문서, API 명세를 작성해두면 AI가 이걸 참고해서 일관된 코드를 만듭니다.

3. 자동으로 맛보기 — "간 봐보자, 맛이 맞나?"

AI가 코드를 짰다고 끝이 아닙니다. 그 코드가 제대로 도는지 확인해야 합니다. 사람이 일일이 보면 느리니까, 자동으로 돌아가는 검증 시스템을 만드는 거죠.

요리가 완성되면 맛을 보는 것과 같습니다. 다만 매번 사람이 직접 맛보는 대신, "소금 농도가 이 범위 안에 있는지 자동으로 체크하는 장치"를 달아 두는 겁니다.

실무 예시: 테스트 자동 실행, 린터(코드 스타일 검사), 타입 체크, 빌드 테스트를 CI 파이프라인에 설정합니다.

4. 알아서 고치게 하기 — "짜면 물 넣고, 싱거우면 소금 넣어"

검증에서 문제가 발견되면, AI가 스스로 고칠 수 있게 흐름을 만들어 둡니다. 사람이 매번 끼어들면 속도가 떨어지니까요.

"너무 짜? 그럼 물 좀 넣어. 너무 싱거워? 소금 추가해." 이런 조정 규칙을 미리 정해두면, 팀원이 매번 물어보지 않고 스스로 맛을 조절합니다.

실무 예시: 테스트가 실패하면 AI에게 에러 메시지와 함께 수정 요청을 자동으로 넘기는 흐름을 설정합니다.

5. 마지막은 사람이 보기 — "마지막 접시는 내가 확인할게"

자동화가 아무리 잘 되어도, 중요한 결정은 사람이 합니다. 배포 전 코드 리뷰, 보안 관련 변경, 아키텍처 결정 같은 건 사람의 승인을 거칩니다.

팀원이 아무리 잘 만들어도, 손님상에 올라가기 전에 헤드 셰프가 마지막으로 접시를 확인하는 겁니다.

실무 예시: PR(Pull Request) 리뷰를 사람이 승인해야 합쳐지도록 설정합니다. AI가 아무리 좋은 코드를 짜도, "이거 내보내도 되나?"는 사람이 판단합니다.

왜 지금 하네스 엔지니어링이 중요한가

바이브코딩만으로는 매일 함께 일할 수 없습니다

바이브코딩은 시제품을 빠르게 만드는 데 좋습니다. 하지만 매일 반복적으로 함께 일하는 환경에서는 벽에 부딪힙니다. AI가 만든 코드가 기존 프로젝트와 안 맞거나, 보안 구멍이 있거나, 팀 규칙을 무시할 수 있으니까요.

식당에 비유하면, 실력 좋은 셰프를 데려와서 "아무거나 만들어봐"라고 한 겁니다. 한 번은 괜찮지만, 식자재 기준도 없고, 메뉴판도 없고, 검수 과정도 없으면 매일 일관된 요리를 낼 수가 없습니다. Claude Code가 강력한 이유는 AI 모델이 좋아서이기도 하지만, CLAUDE.md, 에이전트, 스킬 같은 하네스 구조를 체계적으로 지원하기 때문입니다.

업계 전체가 같은 방향으로 움직이고 있습니다

Gartner는 2026년 말까지 기업 애플리케이션의 40%가 AI 에이전트를 포함할 것으로 전망했습니다(2025년 5% 미만에서 급증). 이제 문제는 "AI를 쓸 것인가"가 아닙니다. "AI 팀원들이 잘 일하도록 어떻게 식당을 운영할 것인가"입니다.

실무에서 하네스 엔지니어링은 어떤 모습인가

구체적인 예시로, 이 블로그(준이아빠블로그) 프로젝트의 하네스 구조를 보여드리겠습니다.

CLAUDE.md가 메뉴 기획서 역할입니다. "이 식당은 한식 기반이야(Next.js), 메뉴판에 없는 건 안 돼(정해진 태그 목록만 사용), 맞춤법은 반드시 지켜"라는 규칙이 적혀 있습니다. .claude/agents/에는 각 AI 에이전트의 담당 업무가 정의되어 있고요. 콘텐츠를 만드는 셰프, SEO를 점검하는 검수 담당, 코드를 리뷰하는 품질관리 담당이 각자 맡은 범위 안에서 일합니다.

사실 이 글 자체가 하네스 엔지니어링의 산물입니다. 사람(저)이 "이런 주제로 글을 써달라"고 주문하면, 콘텐츠 담당 AI가 write-insight라는 표준 레시피에 따라 리서치하고, 정해진 포맷으로 초안을 쓰고, SEO 메타데이터를 채웁니다. 사람은 완성된 글을 보고 다듬습니다. 요리는 AI 팀이 하고, 메뉴 기획과 마지막 검수는 사람이 합니다.

왜 사람들이 이 변화에 적응하기 어려운가

AI 분야가 "따라가기 어렵다"고 느끼는 건 당연합니다.

도구가 너무 빠르게 쏟아집니다

2026년 기준으로 AI 코딩 도구만 해도 Cursor, Replit, Claude Code, GitHub Copilot, Windsurf, v0.dev, Lovable, Bolt 등 수십 개입니다. 마치 매달 새로운 조리 기구가 나오는 것처럼, 각각의 특징을 파악하는 것만으로도 벅찹니다.

그런데 하네스 엔지니어링의 관점에서 보면, 도구(조리 기구)는 바뀌어도 원칙(좋은 주방 운영법)은 같습니다. 어떤 도구를 쓰든 "범위 정하기 → 사정 알려주기 → 자동 검증 → 알아서 수정 → 사람이 확인"의 흐름은 동일합니다. 개별 도구 사용법을 외우는 것보다 이 원칙을 이해하는 게 더 오래가는 지식입니다.

"나는 개발자가 아닌데"라는 마음의 벽

하네스 엔지니어링은 코드를 직접 짜는 게 아닙니다. 함께 일하는 환경과 규칙을 설계하는 겁니다. 이 블로그를 Claude Code로 운영하면서 제가 하는 일의 대부분은 문서 작성, 구조 설계, 결과 확인입니다. 코딩이 아닙니다.

주방장이 직접 모든 요리를 하지 않아도 됩니다. 좋은 주방장은 팀원들이 최고의 요리를 만들 수 있는 환경을 만드는 사람이니까요. 기획자, 마케터, PM 누구나 이 역할을 할 수 있습니다.

지금 시작할 수 있는 첫걸음

하네스 엔지니어링을 당장 시작하고 싶다면, 거창한 것부터 할 필요 없습니다. 주방 정리부터 하면 됩니다.

1. 프로젝트에 README.md를 쓰세요. "이 프로젝트는 뭐고, 어떤 규칙을 따르고, 어떤 구조로 되어 있다"를 정리하는 것만으로도 AI 에이전트의 결과물 품질이 달라집니다. 주방에 재료 위치를 라벨로 붙여두는 것과 같습니다.

2. 규칙을 문서로 남기세요. "파일 이름은 이렇게, 변수 이름은 이렇게, 에러는 이렇게 처리한다"를 적어두면 AI가 일관된 코드를 만듭니다. 레시피북을 만드는 거죠.

3. 자동 검증을 하나만 달아보세요. 린터(코드 스타일 검사)나 타입 체크 같은 자동 검증 도구를 하나만 켜도 AI의 실수를 자동으로 잡아줍니다. 맛 검수 기준을 하나 정하는 겁니다.

이 세 가지만 해도, 이미 하네스 엔지니어링을 하고 있는 겁니다.

---

3줄 요약:

• 하네스 엔지니어링은 AI 에이전트가 안정적으로 작동하도록 '환경, 규칙, 확인·수정 체계'를 설계하는 것입니다. 함께 요리하는 팀원이 우리 주방에서 잘 일할 수 있도록 주방을 세팅하는 것과 같습니다.
• 프롬프트 → 바이브코딩 → 컨텍스트 → 하네스로 이어지는 흐름은 "AI에게 한 번 시키기"에서 "AI와 매일 함께 일하는 시스템 만들기"로 발전한 것입니다.
• 코딩 능력보다 "AI가 일하는 환경을 설계하는 능력"이 중요해지고 있으며, 개발자가 아니어도 시작할 수 있습니다.

---

Sources:

• Harness engineering: leveraging Codex in an agent-first world — OpenAI
• Harness engineering for coding agent users — Martin Fowler
• 2026 Agentic Coding Trends Report — Anthropic
• Harness engineering: Structured workflows for AI-assisted development — Red Hat Developer
• The importance of Agent Harness in 2026 — Philipp Schmid