OpenAI가 100만 줄짜리 소프트웨어를 만들었는데, 사람이 직접 쓴 코드는 0줄이에요. 비결? 에이전트한테 코드를 맡기되, 에이전트가 일하는 환경 자체를 설계한 거예요.
이게 뭔데?
Harness는 원래 말(馬)을 제어하는 장비를 뜻해요. 고삐, 안장, 재갈 — 강력하지만 제멋대로인 동물을 원하는 방향으로 이끄는 도구 세트죠. AI 코딩 에이전트에게도 정확히 같은 게 필요해요.
Harness Engineering은 AI 에이전트가 일하는 환경·제약·피드백 루프를 설계하는 새로운 엔지니어링 분야예요. 프롬프트 엔지니어링이 "뭘 시킬지"에 집중한다면, 하네스 엔지니어링은 "어떤 환경에서 일하게 할지"에 집중해요.
Philipp Schmid(전 Hugging Face)는 이걸 컴퓨터에 비유했어요 — 모델이 CPU, 컨텍스트 윈도우가 RAM이라면, 하네스는 운영체제(OS)예요. 컨텍스트를 관리하고, 부팅 시퀀스(프롬프트, 훅)를 처리하고, 표준 드라이버(도구 핸들링)를 제공하는 거죠.
왜 지금 화제냐고요? OpenAI Codex 팀이 5개월간 100만 줄 이상의 코드를 에이전트로만 작성했는데, 엔지니어 3명이 하루 평균 3.5개의 PR을 머지했어요. 사람이 한 일은 코드 작성이 아니라 하네스 설계였어요. LangChain도 모델은 그대로 두고 하네스만 바꿔서 벤치마크 순위를 Top 30에서 Top 5로 뛰어올렸고요.
핵심 구분
프롬프트 엔지니어링 = 단일 상호작용에서 효과적인 지시를 만드는 것
컨텍스트 엔지니어링 = 모델이 보는 정보를 최적화하는 것
하네스 엔지니어링 = 에이전트 시스템 전체(환경, 제약, 피드백, 라이프사이클)를 설계하는 것
하네스의 구성 요소 — Commands, Skills, Hooks
@_petercha의 바이브 코딩 용어 정리 시리즈가 이 구성 요소를 아주 잘 정리했어요. Claude Code를 기준으로 하네스를 구성하는 핵심 도구 3가지를 볼게요.
뭐가 달라지는 건데?
하네스 없이 에이전트를 쓰면 어떻게 되는지 다들 경험해봤을 거예요. 잘못된 방향으로 폭주하거나, 같은 실수를 반복하거나, 컨텍스트가 길어지면 초반 지시를 까먹어요. 모델이 아무리 좋아져도, 하네스 없으면 소용없어요.
| 하네스 없이 에이전트 사용 | 하네스 적용 | |
|---|---|---|
| 방향성 | 프롬프트에 의존, 자주 이탈 | 제약과 피드백으로 자동 교정 |
| 품질 일관성 | 매번 결과가 다름 | 아키텍처 규칙 + 린터로 강제 |
| 장시간 작업 | 50단계 넘으면 드리프트 | 컨텍스트 압축, 서브에이전트로 분산 |
| 팀 협업 | 개인마다 제각각 | 공유 하네스로 팀 전체 일관성 |
| 확장성 | 사람 개입 계속 필요 | 자율 운영 → 사람은 리뷰만 |
NxCode의 정리에 따르면, 하네스 엔지니어링의 3가지 핵심 축은 이거예요.
- 컨텍스트 엔지니어링
에이전트가 올바른 정보를 올바른 시점에 보게 하는 것. AGENTS.md를 백과사전이 아니라 "목차"로 쓰고, 상세 문서는 구조화된 docs/에 분산해요. - 아키텍처 제약
"좋은 코드 써"가 아니라, 좋은 코드의 구조를 기계적으로 강제하는 것. 의존성 방향, 네이밍 규칙, 파일 크기 제한을 린터와 CI로 검증해요. - 엔트로피 관리
AI가 생성한 코드는 시간이 지나면 드리프트해요. 주기적으로 문서 정합성, 패턴 위반, 불필요한 코드를 스캔하는 "청소 에이전트"를 돌려요.
실전 하네스 프레임워크 3종 비교
이론은 충분하고, 지금 당장 쓸 수 있는 오픈소스 하네스 프레임워크를 비교해볼게요.
| 프레임워크 | 핵심 철학 | GitHub Stars | 지원 에이전트 |
|---|---|---|---|
| Superpowers | TDD 기반 자율 개발 워크플로우 | 76.5K | Claude Code, Codex, Cursor, OpenCode |
| Oh-my-claudecode | Teams-first 멀티에이전트 오케스트레이션 | 9.2K | Claude Code (+ Codex, OpenCode 변형) |
| Ouroboros | 소크라테스식 질문으로 의도 추출, 진동 방지 | 1.1K | Claude Code |
Superpowers는 Jesse Vincent가 만든 에이전틱 스킬 프레임워크예요. 가장 멋진 점은 TDD(Test-Driven Development)를 강제한다는 거예요 — 에이전트가 코드를 쓰기 전에 반드시 테스트를 먼저 쓰고, 빨간불 → 초록불 → 리팩토링 사이클을 따라요. 설치하면 에이전트가 자동으로 브레인스토밍 → 설계 → 계획 → 서브에이전트 실행 → 코드 리뷰 → 브랜치 마무리까지 전체 워크플로우를 수행해요.
Oh-my-claudecode는 한국 개발자 허예찬이 만든 프레임워크로, 21개의 전문 에이전트(코드 리뷰어, 디버거, 아키텍트 등)가 팀처럼 협업하는 구조예요. Claude Code용 oh-my-claudecode, Codex용 oh-my-codex, OpenCode용 oh-my-openagent로 패밀리를 이루고 있어요.
Ouroboros는 Q00이 만든 프레임워크로, "프롬프트를 그만 쓰고, 스펙을 작성하라(Stop prompting. Start specifying.)"는 철학을 따라요. 소크라테스식 질문으로 사용자의 진짜 의도를 끌어내고, 모호성(Ambiguity Score)과 에이전트 진동(Oscillation) 상태를 수치로 추적해서 에이전트가 헤매지 않게 해줘요.
핵심만 정리: 시작하는 법
- CLAUDE.md(또는 AGENTS.md)부터 정리하기
프로젝트의 아키텍처, 코딩 규칙, 디렉토리 구조를 100줄 이내로 정리하세요. 백과사전이 아니라 목차로요. - Hooks로 결정론적 규칙 설정하기
.claude/settings.json에 PostToolUse 훅으로 린트 자동 실행, Stop 훅으로 작업 완료 알림을 걸어보세요. - 하네스 프레임워크 하나 설치해보기
Claude Code 사용자라면/plugin install superpowers한 줄이면 됩니다. TDD 워크플로우가 자동으로 적용돼요. - 점진적으로 제약 추가하기
처음부터 완벽한 하네스를 만들려 하지 마세요. 기본 린팅에서 시작해서, 패턴이 보이면 아키텍처 제약을 추가하고, 필요하면 서브에이전트를 도입하세요.
주의: 과도한 설계의 함정
Philschmid의 핵심 조언 — "삭제할 수 있게 만들어라(Build to Delete)." 모델은 빠르게 발전하기 때문에, 2024년에 복잡한 파이프라인이 필요했던 기능이 2026년에는 단일 프롬프트로 해결돼요. 제어 흐름을 과도하게 설계하면 다음 모델 업데이트에 시스템이 무너져요.
