이 글은 2026년 4월 기준으로 작성되었습니다. AI 코딩 도구와 하네스 엔지니어링은 빠르게 변화하는 분야이므로, 참조된 도구 버전과 수치는 해당 시점 기준입니다. |
2026년 AI 코딩의 가장 뜨거운 키워드는 단연 '하네스 엔지니어링(Harness Engineering)'이다. 유튜브를 열면 하네스 극찬 영상이 쏟아지고, 커뮤니티에는 "하네스 없이 바이브 코딩은 무의미하다"는 글이 넘친다. 그런데 정작 Claude Code의 스킬(Skills) 2.0이 뭔지도 모르는 상태에서 갑자기 하네스라니 — 이 녀석은 대체 뭘 하는 녀석일까?
이 글은 하네스 엔지니어링의 본질을 이해하고, 한 경험 많은 개발자의 "나는 하네스를 도입하지 않기로 했다"는 선언을 겸허하게 받아들이며, 나 자신이 개발 중인 '글쓰기 하네스'를 중간점검하는 기록이다. Claude Code로 바이브 코딩을 하고 있거나, AI 에이전트의 품질 관리 방법을 고민하는 개발자라면 이 여정이 참고가 될 것이다.
Claude Code에서 스킬이란 단순한 프롬프트 템플릿이 아니다. 스스로 테스트하고 수정하며 발전하는 작업 시스템이다 (출처: 비바코딩 — Claude Skill 2.0 출시). 슬래시 커맨드(/commit, /review-pr 등)로 호출하면 해당 스킬이 자체 컨텍스트 윈도우에서 실행된다.
하나의 스킬 폴더는 3가지 핵심 요소로 구성된다:
요소 | 역할 | 비유 |
|---|---|---|
SKILL.md | AI에게 전달하는 업무 매뉴얼. 이름, 단계별 프로세스, 예시 출력, 규칙과 제한 조건을 정의 | 신입 직원에게 주는 SOP 문서 |
참조 자료 | 템플릿, 데이터, 예시 결과물 등 스킬이 참고할 파일들 | SOP와 함께 주는 샘플 포트폴리오 |
스크립트 | 데이터 처리 및 자동화 코드 (Python, Node.js 등) | 직원이 쓰는 업무 도구 |
2026년 초 Skills 2.0에서 중요한 변화가 일어났다. 슬래시 커맨드와 스킬이 완전히 통합되어, 슬래시 커맨드 = 스킬 + user-invocable: true로 멘탈 모델이 단일화되었다. 그리고 단순히 구조가 바뀐 것이 아니라, 스킬이 자기 발전하는 시스템으로 진화했다.
Skill 2.0은 단순 명세서를 넘어 자기 발전하는 시스템으로 진화했다. 핵심은 세 가지다:
업그레이드 | 한줄 설명 | 비유 |
|---|---|---|
1. Evals (자동 테스트) | 샘플 입력 → 결과 생성 → 원하는 출력과 비교. 오류 지점을 자동 식별한다. | 프로그램 출시 전 QA 테스트 |
2. Auto Refinement (자동 개선) | Evals 결과를 기반으로 SKILL.md를 자동 수정. 사람이 수동으로 고칠 필요 없이 스킬이 스스로 발전한다. | 시험 결과를 보고 스스로 공부법을 바꾸는 학생 |
3. Composability (스킬 연결) | 여러 스킬을 파이프라인으로 연결. 주제 조사 → 콘텐츠 작성 → 서식 정리를 하나의 흐름으로. | 공장의 컨베이어 벨트 |
특히 주목할 것은 Evals + Auto Refinement의 조합이다. 이 루프는 'Generator-Evaluator 아키텍처'의 원형이다. GAN(즉, 생성과 판별을 분리한 AI 학습 구조)에서 영감을 받아, 생성과 평가를 분리함으로써 "자기 평가의 맹점(self-evaluation blindness)"을 해결한다.
그리고 Evals에는 또 하나의 숨은 역할이 있다. 스킬이 반복적으로 낮은 점수를 받으면?
그 스킬을 '은퇴'시키고 더이상 필요없는 스킬을 정리하는 것이다. 아직은 홍수처럼 더 생겨날 테지만, 개인적으로 Skill 2.0의 핵심 기능 중 가장 높이 평가하는 부분은 Eval의 평가 작동이 은퇴 시점까지 감지하고, 처음부터 없앨 준비도 하라는 설계 철학이라고 해석한다.
벤치마킹: 같은 입력을 여러 번 실행하여 출력 결과의 일관성을 확인하는 기능도 있다. 결과 편차가 크면 SKILL.md의 지침이 모호하다는 신호다. 이것 또한 "프로그램 출시 전 테스트"와 같은 개념이다. |
하네스 엔지니어링을 이해하려면, IT 세계가 왜 이렇게 동물을 사랑하는지부터 보면 쉽다.
동물원 → 목장 → 마구: IT의 동물 비유 3부작 분산 시스템을 관리하는 ZooKeeper는 동물원 관리자였다. "분산 시스템은 동물원이다"라는 솔직한 고백이었다. → 자세한 이야기는 클러스터는 목장이다 — ZooKeeper, Rancher, 그리고 AI 마구(Harness) 참조 |
하네스 엔지니어링은 이 스킬 시스템을 더 큰 그림으로 확장한 것이다. 동물원 관리자(ZooKeeper)가 우리를 만들고, 목장 주인(Rancher)이 목초지를 조성하듯, 하네스 엔지니어는 AI가 올바른 방향으로 달릴 수 있는 환경과 방향을 설계한다.
OpenAI의 정의를 빌리면, 하네스 엔지니어링은 다음 세 가지를 설계하는 분야다:
구성요소 | 설명 | 비유 |
|---|---|---|
Context Engineering | AI가 필요한 정보에 접근하도록 보장 | 직원에게 업무 매뉴얼을 주는 것 |
Architectural Constraints | 제안이 아닌 기계적 강제 | 공장의 안전 가드레일 |
Entropy Management (즉, 시간이 지나면서 누적되는 코드의 혼란과 불일치를 주기적으로 정리하는 것) | 주기적 정리와 검증 | 주기적인 코드 리뷰 |
쉽게 말하면, "모델은 CPU고 하네스는 OS다." 아무리 CPU가 강력해도 OS가 나쁘면 성능이 저하된다. 마구(馬具)의 비유로 돌아오면 — AI는 강력한 말이고, 엔지니어의 역할은 코드를 직접 짜는 것이 아니라, 말이 올바른 방향으로 힘을 쓸 수 있도록 마구를 설계하는 것이다.
스킬과 하네스는 경쟁 관계가 아니다. 웹 개발에 익숙한 개발자라면 이 비유가 와닿을 것이다:
웹 개발 비유 | AI 코딩 대응 | 역할 |
|---|---|---|
라이브러리 (lodash, axios) | 스킬 (개별 SKILL.md) | 특정 작업을 수행하는 독립 단위. 필요할 때 꺼내 쓴다. |
툴킷 (Material UI, Bootstrap) | 스킬 집합 (일관된 스킬 묶음) | 같은 철학으로 설계된 유용한 스킬의 일관성 집합체. |
프레임워크 (Next.js, Spring) | 하네스 (harness/ 전체 구조) | agents/, engine/, knowledge/ 등의 규칙과 제약으로 구조화된 레이어. 마치 웹 프레임워크처럼 "이 안에서 이 규칙대로 작동하라"고 환경 자체를 제공한다. |
핵심 차이: 웹 프레임워크는 코드가 실행되지만, 하네스는 LLM이 관여한다는 점이 다르다. 그러나 본질은 같다 — 프레임워크 없이 웹을 바닐라 JavaScript로 개발하는 것과, 하네스 없이 CLAUDE.md 하나로 AI를 운용하는 것은 비슷한 차이다. 둘 다 작동은 하지만, 규모가 커질수록 구조화된 프레임워크의 가치가 드러난다. |
CLAUDE.md는 하네스와 유사한 역할을 하지만, 하네스는 여기서 한 단계 더 나아간다. harness/knowledge/(도메인 지식), harness/agents/(에이전트 행동 정의), harness/engine/(워크플로우 규칙) 같은 구조화된 레이어로 분리하여, 웹 프레임워크의 MVC 패턴처럼 관심사를 분리한다.
하네스 엔지니어링의 효과를 보여주는 수치들은 확실히 인상적이다:
LangChain: 모델은 동일하게 두고 하네스만 변경했더니 벤치마크가 52.8% → 66.5%로 상승, Top 30에서 Top 5로 진입했다 (출처: Anthropic Engineering Blog)
OpenAI: 5개월간 100만 줄 이상의 앱을 인간 코드 0줄로 구축, "인간 팀 대비 약 1/10 시간" (출처: OpenAI - Harness Engineering)
Anthropic의 Feature List 패턴: 200개 이상의 피처를 JSON으로 정의하고, AI가 모두 통과할 때까지 반복 실행
이런 수치만 보면 하네스를 도입하지 않을 이유가 없어 보인다.
반대편의 데이터도 간과할 수 없다:
토큰 낭비 문제 ETH Zurich 연구에 따르면, AI가 생성한 CLAUDE.md 파일은 "성능을 저하시키면서 토큰을 20% 이상 더 소비"했다. 에이전트가 컨텍스트 파일 지시를 처리하는 데 14~22%의 추론 토큰을 추가로 사용했지만, 해결률은 개선되지 않았다 (출처: HumanLayer Blog). |
과도한 제약의 역효과
Vercel v0 팀은 사용 가능한 도구의 80%를 제거했더니 측정 가능한 수준으로 더 나은 결과를 얻었다. "더 많은 도구는 더 많은 혼란, 더 많은 잘못된 도구 선택, 더 많은 실패한 작업"을 의미했다 (출처: HumanLayer - Skill Issue).
AI 코드 품질 통계
2025 Qodo 보고서에 따르면, AI 코딩 도구를 하루 여러 번 사용하는 개발자 중 51%가 더 많은 코드 품질 문제를, 53%가 더 많은 보안 취약점을 보고했다. CodeRabbit 분석에서는 AI 생성 코드가 인간 코드 대비 1.7배 더 많은 이슈를 생성했다 (출처: Qodo Report, CodeRabbit Report).
Martin Fowler의 사이트에서 Birgitta Boeckeler(Thoughtworks)는 OpenAI의 하네스 접근법에서 "기능과 동작의 검증이 부재"함을 지적했다 (출처: Martin Fowler - Harness Engineering).
하네스 엔지니어링의 '과도한 구조화' 문제를 이해하려면 팔란티어(Palantir)의 온톨로지(Ontology)를 살펴볼 필요가 있다.
팔란티어의 온톨로지는 실세계 대응물(물리적 자산, 고객 주문, 금융 거래)과 연결되는 운영 레이어다. AI 에이전트가 운영 변경을 제안하면 Git의 브랜칭처럼 존재하고, 인간이 승인하면 머지된다. 이론적으로 완벽해 보이는 이 구조에 대해 HN(Hacker News) 커뮤니티에서는 날카로운 비판이 쏟아졌다 (출처: HN Discussion):
"이건 그냥 뷰, 물리화된 뷰, UDF, 저장 프로시저를 팬시한 기업 용어로 포장한 것"
"OWL(Web Ontology Language)은 전이적 속성, 합집합, 카디널리티를 검증 가능한 결정 가능성 보장으로 지원하지만 Palantir 모델은 이를 결여"
"고객을 Palantir 생태계에 종속시키고 유연성을 희생"
핵심: 과도한 구조화는 에이전트의 자율성을 제한하고, 구현 복잡성이 'last-mile implementation'에서 반복적으로 실패로 이어진다. 하네스 엔지니어링도 같은 위험을 안고 있다. |
고승원 님은 페이스북에 "나는 바이브코딩에서 하네스 엔지니어링을 쓰지 않기로 했다"는 글을 올렸다 (출처: 고승원 님 페이스북).
"하네스 엔지니어링은 분명 좋다. 다만 나와 안 맞을 뿐이다." |
이 한 문장에 핵심이 담겨 있다. 하네스가 나쁘다는 것이 아니라, 자신의 맥락에서 최적이 아니라는 판단이다.
고승원 님은 하네스를 '가두리 양식장'에 비유했다. AI를 촘촘한 테스트 그물 안에 가두고, "이 그물을 벗어나지 말고 통과할 때까지 무한 반복하라"고 명령하는 방식이라는 것이다.
이 비유가 날카로운 이유가 있다. 앞서 살펴본 데이터가 이를 뒷받침한다:
ETH Zurich의 "토큰은 더 쓰면서 해결률은 개선 안 됨" 발견
Vercel의 "도구 80%를 제거했더니 오히려 더 잘 됨" 사례
Martin Fowler 사이트의 "기능 검증 부재" 지적
품질의 역설: 테스트를 통과하는 것과 우아한 설계를 만드는 것은 같지 않다. 하네스가 '오답을 줄이는 소거법'에는 탁월하지만, '가두리 밖의 더 넓은 바다'에 있는 창의적 해결책을 AI에게 허용하지 않을 수 있다.
고승원 님이 제안하는 대안은 '6개 문서(md) 기반 워크플로우'다:
순서 | 문서 | 역할 |
|---|---|---|
1 | brd.md (비즈니스 요구사항) | 무엇을 만들 것인가 |
2 | cps.md (맥락·문제·솔루션) | 왜 만드는가 |
3 | design.md (설계) | 어떻게 구현할 것인가 |
4 | plan.md (구현 계획) | 언제 무엇을 할 것인가 |
5 | todo.md (작업 목록) | 지금 무엇을 하고 있는가 |
6 | test.md (테스트 시나리오) | 검증은 어떻게 할 것인가 |
이 문서들을 CLAUDE.md가 앵커로 묶어주면, AI는 "가두리에 갇히지 않고도 프로젝트 핵심 설계 원칙과 자신의 위치를 명확히 이해"한다.
흥미롭게도 이 접근법은 GitHub와 Thoughtworks Technology Radar에 등재된 'Spec-Driven Development'와 정확히 겹친다 (출처: GitHub Blog, Thoughtworks Radar). 26년 현장 경험에서 우러난 판단이 업계의 최신 방법론과 동기화된 셈이다.
"하네스를 도입하지 않겠다"는 결정은 아무나 내릴 수 없다. 이 판단이 설득력을 가지는 이유는:
충분한 실험: 본인이 직접 하네스 엔지니어링을 "다양한 실험을 진행"했다고 밝혔다
비교 대상의 존재: 26년간 축적한 문서 기반 워크플로우라는 검증된 대안이 있다
양날의 칼 인식: "하네스는 분명 좋다"고 인정한 후에 "나와 안 맞다"고 판단했다
하네스를 써보지 않고 부정하는 것과, 써본 후에 자신의 맥락에서 최적이 아니라고 판단하는 것은 전혀 다른 무게를 가진다.
나는 현재 개인 테크니컬 라이팅용 하네스를 개발 중이다. 코딩이 아닌 '글쓰기'에 하네스를 적용하고 있다. 구조는 다음과 같다:
harness/ ├── knowledge/ ← 글쓰기 기법, 독자 분석, 출처 품질 기준 ├── agents/ ← 리서처, 작성자, 평가자 에이전트 └── engine/ ← 워크플로우, RPG 레벨 시스템, 로그 관리 |
이 하네스는 6가지 콘텐츠 유형(Memorizer, Confluence, 위키, 로컬 문서 등)에 대해 idle → researching → writing → evaluating → publishing → recording 상태 흐름을 따른다. 5축 평가(외부 자료 품질, 비개발자 접근성, 독자 명확성, 구조 완결성, 사실 정확성)로 품질을 관리하고, 70점 이상이어야 발행된다.
4일간 18편의 글을 작성했고, 평균 84.7점, A등급 비율 61%를 기록했다. 겉으로 보면 잘 돌아가고 있다.
고승원 님의 비평을 거울삼아 자문해본다.
Q1. 나의 하네스도 '소거법'에 갇혀 있는가?
솔직히 말하면, 일부분 그렇다. 5축 평가에서 70점 이상을 맞추기 위해 글이 '평가 기준에 맞추는 방향'으로 수렴할 위험이 있다. 참신한 구조의 글, 실험적인 문체의 글이 평가 체계에 맞지 않아 걸러질 수 있다.
Q2. 토큰 낭비가 발생하고 있는가?
발생한다. 매 글마다 harness/knowledge/ 파일 3개, agents/ 파일 3개, engine/ 워크플로우 파일을 로드한다. ETH Zurich가 지적한 "컨텍스트 파일 처리에 추론 토큰 14~22% 추가 소비" 문제가 나에게도 해당된다.
Q3. 그럼에도 하네스가 주는 가치가 있는가?
있다. 그것도 명확하게. 글쓰기에서 하네스의 가치는 코딩과 다르다:
일관된 품질 유지: 5축 평가 없이는 "이번에는 출처를 덜 찾아도 괜찮겠지"라는 게으름이 끼어든다
성장 추적: RPG 레벨 시스템이 없었다면 18편을 연속으로 쓸 동기가 부족했을 것이다
워크플로우 표준화: 매번 "웹 조사부터 할까, 바로 쓸까" 고민하지 않아도 된다
중간점검 결과 — 4가지 개선 과제 |
1. 평가 축의 유연화
현재 5축은 모든 글에 동일하게 적용된다. 글의 유형(기술 튜토리얼 vs 에세이 vs 분석 보고서)에 따라 가중치를 달리 해야 한다. 가두리의 그물 간격을 글마다 조절하는 것이다.
2. 컨텍스트 로딩 최적화
매번 전체 knowledge/ 파일을 로드하는 대신, 글의 유형에 따라 필요한 파일만 선별 로드하는 '선택적 컨텍스트' 메커니즘이 필요하다.
3. 창의적 탈출구
평가 루프에 "이 글은 실험적이므로 특정 축 평가를 면제한다"는 옵션을 만들어야 한다. 가두리 밖으로 나갈 수 있는 문을 열어두는 것이다.
4. 6개 문서 워크플로우와의 접목
고승원 님의 brd→cps→design→plan→todo→test 흐름은 코딩뿐 아니라 글쓰기에도 적용 가능하다. 현재 나의 하네스에는 'CPS(왜 이 글을 쓰는가)'에 해당하는 단계가 약하다.
패러다임의 진화를 정리하면 이렇다:
시기 | 접근법 | 인간의 역할 |
|---|---|---|
2024 | 바이브 코딩 | "이거 만들어줘" → 수락 |
2025 | 스펙 기반 개발 | 구조화된 명세 작성 → 검토 |
2026 | 하네스 엔지니어링 | 환경 설계 → 제약과 피드백 루프 |
하네스 엔지니어링은 분명 강력하다. LangChain의 벤치마크 점프, OpenAI의 100만 줄 앱, Anthropic의 Feature List 패턴 — 이런 성과를 무시할 수 없다.
그러나 동시에 "가두리 양식장"이라는 비유도 유효하다. ETH Zurich의 토큰 낭비 연구, Vercel의 도구 감축 실험, Martin Fowler 사이트의 검증 부재 지적 — 이런 경고도 무시할 수 없다.
대기업은 늘 안정성과 효율을 추구한다. 그러나 아이러니하게도 그들이 갈망하는 것은 스타트업의 속도다. 빠르게 실행하고, 실패를 감수하며, 시장에 먼저 닿는 힘. 그래서 그들은 '하네스'를 찾는다. 조직을 묶어주는 장치이되, 동시에 속도를 방해하지 않는 유연한 구조를.
반대로 스타트업은 자유로움 속에서 시작하지만, 성장의 순간에 부딪힌다. 규칙이 없던 조직은 점점 혼란을 겪고, 결국 질서를 갈망하게 된다. 이때 등장하는 것이 또 다른 형태의 하네스다. 통제와 기준을 부여해 일관된 결과를 만들어내는 장치.
흥미로운 점은, 이 두 흐름이 결국 같은 지점을 향한다는 것이다. 빠르되 무너지지 않기 위해, 자유롭되 흩어지지 않기 위해 — 각자의 방식으로 하네스를 만든다.
하지만 언제나 예외는 존재한다. 어떤 크리에이터는 시스템 없이도 높은 품질을 만들어낸다. 오롯이 개인의 감각과 숙련된 스킬로 결과를 끌어올린다. 그들에게 하네스는 필수가 아니라 선택이다. |
결국 중요한 것은 정답이 아니다. 상황에 맞는 선택이다. 조직의 크기, 단계, 목표에 따라 하네스는 달라져야 한다. 과도하면 속도를 잃고, 부족하면 방향을 잃는다. 하네스는 도구일 뿐이다. 그것을 어떻게, 언제, 얼마나 사용하는지가 결국 결과를 결정한다.
나 자신의 글쓰기 하네스를 4일간 운영하면서 느낀 것도 같은 맥락이다: 하네스는 만능 해결사가 아니다. '나에게 맞느냐'가 핵심이다.
코딩에서: 반복적 테스트 검증이 중요한 프로덕션 코드 → 하네스가 강력한 선택
코딩에서: 설계 철학과 문서 중심 협업이 핵심 → 6개 문서 워크플로우가 더 맞을 수 있음
글쓰기에서: 일관된 품질과 성장 추적이 필요 → 하네스의 평가 루프가 유용
글쓰기에서: 실험적이고 자유로운 글쓰기 → 하네스가 오히려 족쇄
고승원 님의 말을 빌려 결론을 맺는다:
"바이브코딩의 핵심은 AI를 얼마나 통제하느냐가 아니라, 인간의 통찰력이 담긴 설계를 AI와 얼마나 밀도 있게 공유하느냐에 달려 있다." |
그래서 묻는다 — 당신에게 하네스는 가두리인가, 항해의 장비인가?
이 질문에 대한 답은 당신만이 알고 있다.
클러스터는 목장이다 — ZooKeeper, Rancher, 그리고 AI 마구(Harness) — IT 세계의 동물 비유로 하네스 엔지니어링을 이해하는 선행 글
HumanLayer - Skill Issue: Harness Engineering for Coding Agents
고승원 님 페이스북 — "나는 바이브코딩에서 하네스 엔지니어링을 쓰지 않기로 했다"