바이브코딩과 하네스 엔지니어링
AI 코딩 에이전트가 사람 대신 계획을 세우고 코드를 짜고 테스트까지 돌리는 시대가 되면서, 개발자의 역할도 조금씩 바뀌고 있습니다. 처음엔 “느낌 가는 대로” AI에게 코딩을 맡기는 바이브 코딩(Vibe Coding)이 유행했지만, 프로젝트가 커질수록 이 방식만으로는 한계가 드러났습니다. 그 한계를 넘어서기 위해 최근 주목받는 개념이 바로 하네스 엔지니어링(Harness Engineering)입니다.
이 글에서는 하네스 엔지니어링이 무엇인지, 왜 바이브 코딩의 대안으로 떠올랐는지, 그리고 클로드 코드(Claude Code)와 구글 안티그래비티(Antigravity)에서 실제로 어떻게 적용하는지 정리해 보겠습니다.
1. 하네스 엔지니어링(Harness Engineering)이란?
“하네스(Harness)”라는 단어는 원래 자동차의 와이어링 하네스(Wiring Harness)나 말에 채우는 마구(馬具)를 가리키는 말입니다. 아무리 강력한 엔진이나 힘센 말이 있어도, 그 힘을 원하는 방향으로 전달해줄 배선이나 고삐가 없으면 무용지물이라는 뜻이죠.
그림 1. 하네스 엔지니어링 개념도 (자체 제작)
AI 코딩 에이전트도 마찬가지입니다. 모델이 아무리 똑똑해도 “어떻게 일해야 하는지”를 알려주는 체계가 없으면 매번 다른 품질의 결과물을 내놓습니다. 한 블로그는 이 관계를 승마에 빗대어, 모델이 아무리 강력해도 고삐와 안장 같은 하네스가 없으면 원하는 방향으로 나아갈 수 없다고 설명합니다. 즉 하네스 엔지니어링이란 AI 에이전트에게 주어야 할 신호를 코드와 설정 파일로 체계화해서, 에이전트의 행동을 지속적이고 일관되게 통제하는 방법론을 말합니다.
앤트로픽 역시 비슷한 관점에서 이 개념을 설명하는데, 에이전트 하네스를 모델이 실제로 에이전트처럼 동작할 수 있도록 입력을 처리하고 도구 호출을 조율하며 결과를 반환하는 시스템으로 정의합니다. 결국 좋은 프롬프트 한 줄로 끝나는 게 아니라, AI가 어떤 정보와 도구를 바탕으로 어떤 절차 속에서 작업할지를 사람이 함께 설계해야 한다는 뜻입니다.
소프트웨어 설계 분야의 유명 저자 마틴 파울러(Martin Fowler) 역시 이 주제를 다뤘는데, 그의 글에서는 하네스를 구성하는 피드백 루프를 가이드(guide)와 센서(sensor)로 나누어 설명하고, Stripe의 실제 도입 사례를 함께 소개한 것으로 알려져 있습니다.
하네스 엔지니어링의 4가지 핵심 구성요소
| 구성요소 | 역할 | 예시 |
|---|---|---|
| 지시문서 (Instruction Docs) | 에이전트가 지켜야 할 규칙과 맥락 전달 | CLAUDE.md, AGENTS.md |
| 아키텍처 제약 (Architecture Constraints) | 실수할 여지를 구조적으로 줄이는 설계 | 폴더 구조, 코드 컨벤션, 타입 시스템 |
| 피드백 루프 (Feedback Loop) | 결과를 검증하고 다시 알려주는 장치 | 자동 테스트, 린트, 리뷰 프로세스 |
| 지식 저장소 & 가비지 컬렉션 | 맥락을 기록하고 불필요한 정보를 정리 | progress.md, 세션 로그 관리 |
2. 바이브 코딩의 한계점을 극복하기 위해 하네스 엔지니어링이 필요한 이유
바이브 코딩이라는 말은 OpenAI 공동 창립자인 안드레이 카파시(Andrej Karpathy)가 처음 만든 표현으로, 사람이 세세한 코드를 신경 쓰지 않고 “느낌”과 자연어 지시만으로 AI에게 개발을 맡기는 방식을 뜻합니다. 짧은 프로토타입이나 개인 프로젝트에는 매우 효율적이지만, 프로젝트 규모가 커지고 협업 인원이 늘어나면 다음과 같은 한계가 나타납니다.
• 일관성 부족: 세션마다 컨텍스트가 초기화되기 때문에, 어제 알려준 규칙을 오늘은 기억하지 못합니다.
• 반복되는 실수: 같은 실수를 지적해도 다음 작업에서 다시 반복되는 경우가 많습니다.
• 품질 편차: 프롬프트를 어떻게 쓰느냐에 따라 결과물의 품질이 크게 요동칩니다.
• 검증 부재: 사람이 매번 결과물을 처음부터 끝까지 확인해야 하므로, 자동화의 이점이 줄어듭니다.
한 IT 인사이트 글에서는 이런 흐름을 요리에 비유해 설명합니다. AI에게 질문을 잘 던지는 프롬프트 엔지니어링에서 시작해, 이제는 AI와 매일 함께 일하는 시스템을 만드는 하네스 엔지니어링으로 발전했다는 것입니다. 즉 프롬프트 한 줄에 의존하기보다, AI가 실수했을 때 그 실수가 반복되지 않도록 환경·구조·도구 자체를 설계하는 쪽으로 무게 중심이 옮겨가고 있는 셈입니다.
실제 사례로 자주 언급되는 것이 결제 서비스 기업 Stripe입니다. 한 블로그 글에 따르면 Stripe 개발자가 슬랙에 원하는 기능을 요청하면, 하네스가 갖춰진 AI 에이전트가 코드를 작성하고 테스트를 통과시킨 뒤 코드 리뷰 요청까지 스스로 올려 매주 1,000건 이상을 처리한다고 합니다. 이는 잘 설계된 하네스가 있을 때, “느낌”에 의존하던 바이브 코딩이 얼마나 안정적인 워크플로로 바뀔 수 있는지를 잘 보여주는 사례입니다.
그림 2. 바이브 코딩 vs 하네스 엔지니어링 워크플로우 비교 (자체 제작)
바이브 코딩 vs 하네스 엔지니어링 비교
| 구분 | 바이브 코딩 (Vibe Coding) | 하네스 엔지니어링 (Harness Engineering) |
|---|---|---|
| 접근 방식 | 자연어 지시와 감(感)에 의존 | 규칙·도구·검증 체계를 사전에 설계 |
| 일관성 | 세션마다 결과가 달라짐 | 문서·훅으로 지속적인 행동 통제 |
| 적합한 규모 | 프로토타입, 소규모 개인 프로젝트 | 실무 프로젝트, 팀 단위 협업 |
| 실수 처리 | 매번 사람이 직접 확인·수정 | 피드백 루프로 자동 검증 및 재발 방지 |
| 대표 도구 | 단일 프롬프트, 채팅 인터페이스 | CLAUDE.md / AGENTS.md, Hooks, Subagents |
물론 하네스를 지나치게 촘촘하게 만들면 오히려 AI의 유연한 문제 해결 능력, 즉 '바이브'가 막혀 속도가 느려질 수 있다는 지적도 있습니다. 그래서 하네스 엔지니어링은 바이브 코딩을 완전히 대체한다기보다, 바이브 코딩의 자유로움과 하네스의 안정성 사이에서 균형을 잡는 작업에 가깝습니다.
3. 클로드 코드와 안티그래비티에서 하네스 엔지니어링을 적용하는 방법
이론은 이쯤 하고, 실제로 많이 쓰이는 두 도구인 클로드 코드(Claude Code)와 구글 안티그래비티(Antigravity)에서 하네스를 어떻게 구성할 수 있는지 살펴보겠습니다.
앤트로픽 공식 블로그에서는 클로드 코드를 조종하는 여러 장치를 소개하는데, 그중 서브에이전트에 대해 .claude/agents/ 폴더에 저장되는 마크다운 파일로, 특정 하위 작업을 위한 독립된 어시스턴트를 정의한다고 설명합니다. 이 파일은 YAML 프런트매터로 이름과 설명, 사용할 모델과 도구 권한을 지정하고, 본문이 해당 서브에이전트의 시스템 프롬프트 역할을 합니다.
1) 클로드 코드(Claude Code)에서 하네스 구성하기
| 구성요소 | 위치 | 역할 |
|---|---|---|
| CLAUDE.md | 프로젝트 루트 | 세션 시작 시 자동으로 읽는 규칙·코딩 스타일 문서 |
| Skills | .claude/skills/ | 반복 작업을 절차화한 재사용 가능한 스킬 |
| Subagents | .claude/agents/ | 특정 역할(백엔드, 리뷰어 등)을 맡는 독립 컨텍스트 에이전트 |
| Hooks | .claude/hooks/, settings.json | 특정 이벤트(수정 후 테스트 실행 등) 발생 시 자동 실행되는 스크립트 |
| MCP Servers | 프로젝트/전역 설정 | 외부 도구·데이터와 연결하는 표준 인터페이스 |
실제 적용 팁을 정리한 한 가이드에서는 실행 절차를 다음과 같이 소개합니다.
• 프로젝트 루트에 CLAUDE.md를 만들어 프로젝트 맥락과 규칙을 적어둔다.
• 반복되는 작업 절차는 Skill로 분리해 컨텍스트를 절약한다.
• “수정 후 반드시 테스트 실행”처럼 놓치면 안 되는 규칙은 Hook으로 강제한다.
• 백엔드, 리뷰 등 역할이 뚜렷한 작업은 Subagent로 분리해 메인 컨텍스트를 깨끗하게 유지한다.
한 실전 후기 글에서는 과거 세션 로그를 서브에이전트에게 분석시켜 자주 반복되는 실수와 마찰 지점을 찾고, 그 결과를 바탕으로 새로운 Hook과 CLAUDE.md 규칙을 만들었다는 경험을 공유하기도 했습니다. 이는 하네스를 한 번에 완성하는 것이 아니라, 실제 작업 로그를 근거로 계속 다듬어가는 과정임을 보여줍니다.
또한 권한 모드도 하네스의 일부입니다. 한 가이드는 파일 편집은 자동으로 승인하되 bash 명령은 실행 전 확인하는 모드가 안전성과 생산성의 균형이 가장 좋다고 추천합니다.
2) 안티그래비티(Antigravity)에서 하네스 구성하기
구글 딥마인드가 2025년 11월 18일 공개한 에이전트 중심 개발 플랫폼인 안티그래비티는 VS Code 기반이면서도, 단순 코드 제안을 넘어 AI가 직접 계획을 세우고 코드를 작성한 뒤 브라우저로 검증까지 수행합니다.
그림 3. 클로드 코드 vs 안티그래비티 하네스 구성 비교 (자체 제작)
| 구성요소 | 클로드 코드 | 안티그래비티 |
|---|---|---|
| 지시문서 | CLAUDE.md | AGENTS.md |
| 실행 환경 | 터미널(CLI) 중심 | GUI 기반 에디터(VS Code 계열) |
| 재사용 절차 | Skills | Skills / Workflows |
| 검증 방식 | Hooks + 테스트 자동 실행 | 브라우저 자체 검증 포함 |
| 진입 장벽 | 명령어 학습 필요 | GUI로 입문자 친화적 |
안티그래비티는 2026년 3월 6일 출시된 버전부터 AGENTS.md를 지원하기 시작하면서, 클로드 코드에 견줄 만한 프로젝트 제어 기능을 갖추게 되었다고 알려져 있습니다. 즉 클로드 코드의 CLAUDE.md처럼, 안티그래비티에서는 AGENTS.md 하나로 프로젝트 규칙과 폴더 구조, 사용 프레임워크 같은 맥락을 에이전트에게 지속적으로 전달할 수 있습니다.
입문자 입장에서는 터미널 창을 직접 열고 명령어를 입력해야 하는 클로드 코드보다, GUI가 있는 안티그래비티가 진입 장벽이 낮다는 점이 자주 언급됩니다. 그래서 실무에서는 두 도구를 상황에 따라 병행하는 경우도 많습니다 — 예를 들어 기획 초기 탐색이나 GUI 확인이 필요한 작업은 안티그래비티로, 반복적인 자동화나 세밀한 권한 제어가 필요한 작업은 클로드 코드로 나누는 식입니다.
공통 적용 원칙
• 작게 시작하기: 처음에는 지시문서(CLAUDE.md/AGENTS.md) 하나만으로 시작하고, 작업이 커지면 규칙을 계층으로 나눕니다.
• 롤백 지점 마련하기: 작업을 맡기기 전 “이 작업이 실패하면 어디로 되돌아갈 것인가”를 먼저 정해두면(예: 잦은 커밋), 하네스의 절반은 완성된다는 조언도 있습니다.
• 과적합 주의: 규칙을 지나치게 세밀하게 만들면 에이전트의 유연한 문제 해결력이 오히려 저하될 수 있습니다.
• 로그 기반 개선: 세션 로그나 실패 사례를 근거로 하네스를 지속적으로 업데이트합니다.
마치며
회사에서 AX와 바이브 코딩을 모든 직원에게 적극 지원하고 이를 위해 개발 가이드를 작성하면서 알게된 것이 AGENTS.md 파일이고 이게 하네스 엔지니어링의 일부라는 것을 알게 된 것은 얼마 되지 않았습니다.
시작은 단순했으나 “AI와 매일 안정적으로 함께 일하는 시스템을 만드는 기술”이라 정리할 수 있는 하네스 엔지니어링을 프로젝트 개발부터 배포까지 전반에 반영되도록 학습하고 테스트하고 적용해 보려 합니다.
AI 모델이라는 강력한 엔진에, 방향을 잡아줄 배선과 고삐를 얼마나 잘 설계해주느냐가 실제 결과물의 품질을 좌우하기 때문입니다.
참고 출처 (Reference)
1. 함께해요 바이브 코딩 - 11장. 하네스 엔지니어링 (wikidocs) https://wikidocs.net/338973
2. 하네스 엔지니어링이란? — 뜻부터 실전 예시까지 완벽 정리 (gpters.org) https://www.gpters.org/nocode/post/what-harness-engineering-complete-gP3o5gHfMud3Ms9
3. 하네스 엔지니어링 완벽 정리 (gpters.org) https://www.gpters.org/nocode/post/harness-engineering-complete-summary-3knw3BTfdPoX5K0
4. '하네스(Harness) 엔지니어링'이란? (셀렉트스타 블로그) https://selectstar.ai/blog/insight/about-harness-engineering/
5. 초보자도 쉽게 따라하는 하네스 엔지니어링 (gpters.org) https://www.gpters.org/dev/post/harness-engineering-easy-follow-25VIHLOgYq6YGzt
6. 피그마 '하네스 엔지니어링'이 대체 뭐길래? (Figmapedia) https://figmapedia.com/entry/332fdea8-0034-8027-8118-dcdcae821819
7. 0. 들어가며 - 하네스 엔지니어링 입문 (wikidocs) https://wikidocs.net/340857
8. 하네스 엔지니어링 입문 가이드 (digitalmarketer.co.kr) https://www.digitalmarketer.co.kr/insights/harness-engineering-beginner-guide
9. Google Antigravity 사용법: 설치부터 Skills까지 완전 정복 https://magister1318.blog/2026/03/09/google-antigravity-사용법-설치부터-skills까지-완전-정복/
10. 클로드 코드 입문자를 위한 안티그래비티 활용법 (juct.com) https://www.juct.com/entry/클로드-코드-입문자를-위한-안티그래비티-활용법
11. ClaudeCode Harness Engineering -1편 (velog) https://velog.io/@kyeongjun1007/ClaudeCode-Harness-Engineering-1편
12. Steering Claude Code: skills, hooks, rules, subagents (Claude 공식 블로그) https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
13. Claude Code 하네스 엔지니어링 가이드 (Soobin gitbook) https://judy-valentine.gitbook.io/judy/technical-notes/claude-code/claude-code-2
14. 제7장. Claude에서 하네스 구축하기 - 하네스 엔지니어링 백과사전 (wikidocs) https://wikidocs.net/346799
15. Claude Code Hooks, Skills and Subagents: a Practical Setup (Bartek Paczesny)
https://dev.paczesny.pl/blog/en/how-to-setup-claude-code-hooks-skills
