같은 AI 모델을 써도 누구는 잘 만들고 누구는 헛고생합니다. 그 차이를 만드는 것이 하네스(Harness)입니다. 1인 개발자가 7-에이전트 하네스를 지난 3주간 돌리며 실험해본 구성·시행착오·실측 효과를 공유합니다.
1. 하네스가 뭔지
AI 모델(GPT, Claude, Gemini…)은 점점 똑똑해지고 있습니다. 그런데 똑같은 모델을 쓰고도 어떤 사람은 잘 만들고, 어떤 사람은 헛고생만 합니다. 그 차이를 만드는 것이 하네스(harness)입니다.
하네스는 원래 "말을 잡아두는 굴레"라는 뜻입니다. AI 맥락에선 모델이 일하는 환경 전체를 가리킵니다 — 어떤 역할을 갖고, 무슨 도구를 쓰고, 어떤 절차로 검증받고, 어떤 가드 안에서 움직이 는지. 사람으로 치면 "직무 정의서 + 업무 프로세스 + 결재 라인 + 회사 규정"을 통째로 묶은 것에 가깝습니다.
업계가 정착시킨 공식이 하나 있습니다.
Agent = Model + Harness모델은 핵심이지만 일부일 뿐, 그 주변을 둘러싼 하네스가 전체 결과를 결정한다는 뜻입니다.
2. 왜 요즘 다들 하네스를 중요하게 다루나
지난 1~2년 사이 AI 활용 담론은 빠르게 이동했습니다.
"어떤 프롬프트가 좋은가" (2023)
↓
"어떤 에이전트가 좋은가" (2024~25)
↓
"어떤 하네스가 좋은가" (2025~26)이는 제 개인 관찰이 아니라 업계 흐름입니다. 굵직한 신호 몇 개만 살펴봅니다.
Anthropic은 자사 엔지니어링 블로그에 "Effective harnesses for long-running agents"를 올리며 harness 개념을 정착시켰고, 같은 글과 공식 문서에서 Claude Agent SDK를 "general-purpose agent harness"로 명명합니다. Agent = Model + Harness 표현 자체는 업계 합의로 자리잡은 표현입니다.
Andrej Karpathy는 2025년 말 트윗으로 "11월엔 수동 코딩이 80%였는데 12월엔 에이전트 도움이 80%로 뒤집혔습니다. 20년 만의 가장 큰 변화"라고 말했습니다. 그가 강조한 한 줄은 "context engineering matters more than prompts"입니다. 2026년 3월엔
autoresearch라는 미니 레포로 "스크립트 편집 → 시간 박스 실험 → 측정 → 유지/폐기" 반복 루프를 공개했습니다.Martin Fowler 사이트엔 Birgitta Böckeler가 쓴 "Harness Engineering for Coding Agent Users"가 정식 아티클로 올라왔습니다. 그가 제시한 "Guides(사전 가이드) + Sensors(사후 감지)"가 코딩 에이전트 가드 설계의 표준 어휘로 자리잡고 있습니다.
MongoDB는 아예 "The Agent Harness: Why the LLM Is the Smallest Part of Your Agent System"이라는 제목의 글을 냈습니다. "모델은 가장 작은 부분이다"라는 도발적인 명제입니다.
Hamel Husain(전 GitHub·Airbnb ML 엔지니어)은 Lenny's Newsletter 인터뷰에서 "AI evals are the hottest new skill for product builders"로 소개되며 매주 강의를 엽니다. 그의 핵심 메시지는 모델을 평가하기 전에 실제 트레이스를 사람이 직접 보고 실수 패턴을 분류하라는 것이고, 그것이 모든 환경 설계의 출발점이라는 것입니다.
모두가 같은 결론을 가리킵니다 — 모델을 갈아끼우는 것보다, 그 주변 환경(하네스)을 다듬는 쪽이 ROI가 훨씬 높습니다. 그래서 "harness engineering"이 하나의 직무로 떠오르고 있습니다. GitHub에는 이미 awesome-harness-engineering이라는 큐레이션 레포가 만들어져 있습니다.
3. 제가 구성한 하네스 — 4가지 부품
운영 중인 두 프로덕트를 한 모노레포로 합치면서 보안·UI·번역까지 동시에 손보는 작업에 하네스를 깔았습니다. 지난 몇 주간 100여 차례의 작업 라운드를 굴려본 구성을 정리합니다.
⓪ 어떤 위에 짰나 — 베이스 스택
완전히 처음부터 짠 것은 아닙니다. 이미 잘 만들어진 오픈소스 위에 제 도메인을 얹는 형태입니다.
Ouroboros(
ouroboros-ai, uv tool install) — 에이전트 워크플로우 엔진입니다. interview → seed → evolve → run → evaluate → qa → unstuck 7-phase 구조와 자동 반복 루프(ralph 모드)를 제공합니다. 제 7 에이전트는 이 7 phase에 1:1로 매핑됩니다.Anthropic Claude Code — 메인 인터페이스입니다. 모델 호출, 도구 실행, sub-agents, Agent Teams(라운드별 멀티 에이전트 통신)까지 한 CLI 안에서 처리합니다.
Serena MCP(oraios/serena) — LSP 기반 코드 인덱서입니다. 에이전트가 "계획서만 읽고 끝내는" 실수를 막기 위해, 실제 코드를 심볼 단위로 조회하게 만드는 핵심 도구입니다.
gstack — 보강 워크플로우 모음(
/design-review,/qa-only,/health,/cso,/investigate,/ship등)입니다. 라운드 단위 verifier·reviewer를 보강해줍니다.OpenAI Codex CLI — reviewer 에이전트의 2차 의견을 담당합니다. 같은 코드를 다른 회사 모델에 한 번 더 보여줌으로써 사각지대를 줄입니다.
그 위에 제 도메인 정의가 얹힙니다.
.claude/agents/*.md # 7명 에이전트 정의
.claude/skills/rona-*/ # 8개 도메인 스킬
.mcp.json # project-scope MCP 서버 (Ouroboros, Serena)
AGENTS.md # 코드 가드레일 (import alias, Drizzle batch 등)
_workspace/{date-slug}/ # 라운드별 산출물 + 증거 파일이제 4가지 부품이 각각 어떤 도구·파일로 구현됐는지를 살펴봅니다.
① 7명, 회사 조직처럼 분업
그림: 하네스 안의 7 에이전트. 4·5·6은 자동 반복 루프, 7번은 새 규칙을 만들어 다음 라운드의 시작점(1번)으로 되먹입니다.
구조는 회사와 같습니다. 기획자 → 명세 작성자 → 설계자 → 개발자 → 검증자 → 리뷰어. 마지막 한 명은 조금 특이합니다 — "이번에도 같은 실수가 났네"를 잡아내서 환경을 손보는 환경 정비공입니다. 환경 정비공이 만든 새 규칙은 다시 처음 단계로 피드백되어, 다음 라운드부터는 같은 실수가 안 나오게 됩니다(위 그림의 곡선 화살표).
역할 하는 일 Ouroboros phase
─────────────────────────────────────────────────────────────
1. 기획자 뭘 왜 만들지 정리 interview
2. 명세 작성자 스펙 문서 작성 seed
3. 설계자 큰 일을 작은 라운드로 쪼개기 evolve
4. 개발자 코드 변경 + 브랜치 머지 run
5. 검증자 빌드/테스트/타입체크 실행 evaluate
6. 리뷰어 보안·로직·코드 품질 점검 qa
7. 환경 정비공 재발 방지용 도구/규칙 손보기 unstuck각 에이전트는 .claude/agents/<역할>.md 파일 하나로 정의됩니다. 시스템 프롬프트 + 허용 도구 + 호출 규칙 + 산출물 형식. Anthropic이 정리한 sub-agents 권장 패턴 — "한 명의 만능 에이전트보다, 자기 컨텍스트 창과 도구를 가진 전문 에이전트들이 더 안정적이다" — 와 같은 원리입니다.
② 사람이 안 끼는 자동 반복 루프
분업만 한다고 1인 운영이 되는 것은 아닙니다. 매번 제가 누구에게 일을 넘기는지 라우팅하면 결국 제가 다시 병목이 됩니다.
그래서 4번(개발자) → 5번(검증자) → 6번(리뷰어) 세 명이 한 묶음으로 자동 반복되게 묶었습니다. 구현은 Ouroboros의 ralph 모드 + Claude Code의 Agent Teams 조합입니다. 라운드를 시작하면 그 라운드 전용 임시 팀이 만들어지고, 개발자가 코드를 쓰면 검증자가 돌려보고, 깨지면 다시 개발자에게 돌아갑니다. 리뷰어가 "APPROVE"를 찍을 때까지 제가 끼어들지 않아도 됩니다. 그 사이 저는 다음 라운드를 시작하거나, 그냥 쉽니다.
발상은 Karpathy의 autoresearch와 동일합니다 — "한 번 편집하고, 시간을 정해 돌려보고, 결과를 측정하고, 유지하거나 버린다. 밤새도록 반복한다."
③ AI 거짓말을 막는 외부 검증 게이트
AI는 종종 "다 했습니다"라고 자 신 있게 보고하면서 실제로는 하지 않습니다. 자동 루프가 빠르게 돌수록 이런 거짓 완료가 무더기로 누적됩니다.
그래서 모든 라운드가 끝날 때 _workspace/{date-slug}/05_round_evidence.json을 무조건 남기게 했습니다. JSON 스키마는 다음과 같습니다.
{
"round_id": "round-email-pii-mask",
"branch": "feat/email-pii-mask",
"head_sha": "7cc235d1...",
"planned_files": [...],
"actual_files": [...],
"commands": {
"typecheck": { "status": "PASS", "output_lines": 0 },
"lint": { "status": "PASS", ... },
"test": { "status": "PASS", ... },
"build": { "status": "PASS", ... }
},
"diff_stats": { "files": 12, "insertions": 348, "deletions": 41 },
"reviewer_decision": "APPROVE",
"evidence_hash": "<SHA-256 of 12 fields>"
}그리고 별도의 검증 스크립트 _workspace/validate_round_evidence.sh가 이 파일을 점검합니다. 점검 항목은 ① JSON Schema(Draft-07) 형식, ② reviewer_decision 열거값, ③ APPROVE 시 typecheck·test가 PASS인지, ④ evidence_hash가 12개 필드 정규화 SHA-256과 일치하는지입니다. 리뷰어가 "APPROVE"를 찍어도 이 스크립트가 exit 0을 내지 않으면 머지가 거부됩니다. AI가 자기 자신을 인증하는 길을 외부에서 막은 것입니다.
이는 Plan-Execute-Verify에서 "Verify" 단계의 핵심 원리이기도 합니다 — 검증은 에이전트 안이 아니라 에이전트 밖에서 일어나야 합니다.
④ 재발 방지 가드 — 하네스의 자가 진화
위 셋을 다 깔고도 한 번 크게 데인 적이 있습니다. 4페이지짜리 UI 작업 계획을 자동 리뷰에 돌렸더니 "통과"가 나왔는데, 코드를 열어보니 큰 문제 8개가 발견됐습니다 — 이미 삭제된 화면 요소를 참조하고 있고, 결제 시스템에 보안 구멍이 있고, 라우팅이 틀어져 있는 식이었습니다.
원인은 의외로 단순했습니다. 계획 문서를 리뷰한 AI가 실제 코드를 보지 않고, 계획서 자체만 읽은 것이었습니다. 계획서에 "X가 있다"고 적혀있으니 리뷰어는 "그래, X가 있구나" 하고 통과시켰던 것입니다. 정작 코드엔 X가 없는데도 말이죠.
이때 7번 환경 정비공(harness-evolver 에이전트)이 등판합니다. 새 규칙을 CLAUDE.md·AGENTS.md·각 에이전트 정의 파일에 박아 넣었습니다 — 모든 계획·리뷰는 Serena MCP를 통해 실제 코드를 심볼 단위로 조회한 결과로만 판단해야 합니다. 계획서 자가 평가 금지. 이후 같은 실수는 0건입니다.
Hamel Husain이 강조하는 error analysis 루프 — "실수 트레이스를 보고 패턴을 분류하고 환경을 바꾼다" — 의 1인 운영 버전입니다. 하네스는 정적인 설정이 아니라, 시간이 갈수록 단단해지는 살아있는 환경입니다.
한눈에 보는 전체 스택
레이어 구성 요소 쓴 도구
────────────────────────────────────────────────────────────────────────
워크플로우 엔진 7-phase + ralph 자동 반복 Ouroboros
메인 CLI / 모델 에이전트 호출·통신·도구 Anthropic Claude Code
에이전트 정의 7명 분업 .claude/agents/*.md
도메인 스킬 라운드 진행 규칙 .claude/skills/rona-*/
코드 인덱서 심볼 기반 fact-check Serena MCP
2차 코드 리뷰 사각지대 줄이기 OpenAI Codex CLI
보강 워크플로우 UI·QA·보안·배포 gstack (/design-review 등)
증거 파일 라운드별 강제 산출물 05_round_evidence.json
검증 스크립트 JSON Schema 자동 점검 validate_round_evidence.sh
멀티 에이전트 통신 라운드별 team Claude Code Agent Teams
가드레일 import·DB·PII·LLM trust 등 AGENTS.md + CLAUDE.md4. 이렇게 하니까 어떤 효과가 났나
주관적 인상이 아니라 라운드 단위 evidence 파일(§3③)과 마스터 체크리스트에 기록으로 남아있는 실측 결과만 정리합니다.
지표 결과
──────────────────────────────────────────────────────────
누적 작업 라운드 지난 약 3주간 100여 차례
보안 우선순위 이슈 9건 전부 해결
· 인증 헤더 신뢰 경로 16개 정비
· OAuth state TTL, open redirect 차단
· 결제 토큰 암호화 5개 콜사이트 적용
· 결제 webhook idempotency 가드
· prod DB 가드 / migrate 스크립트 봉인
UI 패리티 검증 36개 주요 화면 시각·기능 회귀 스냅샷
자동화 (Playwright) + 84개 컴포넌트
스토리북 + 70개 갭 회귀 테스트
한·영 번역 키 동기화 완전 일치 (1727 키 = 1727 키)
ko/en 카운트 단일 게이트로 영구화
새 규칙 적용 후 동일 실수 0건
재발
리뷰어 점수 중반 외부 평가 6.3점 →
후반 자가 재평가 8점 이상
(외부 재측정은 미실시)숫자만 보기엔 추상적이라 한 가지 사례만 풀어보겠습니다. 위 보안 9건 중 가장 컸던 것은 "인증 헤더 신뢰 경로"였습니다. 사용자 신원을 헤더로 받아 그대로 신뢰하는 코드가 16개 라우트에 흩어져 있었는데, 1라운드에 1~2개씩 픽업해서 모두 세션 기반 검증으로 갈아끼웠습니다. 사람이 코드 리뷰만으로 잡아내기 어려운 분량을, 리뷰어 에이전트가 보안 가드 체크리스트를 매 라운드 자동으로 돌리니까 누락 없이 클리어됐습니다.
그리고 결과 자체보다 구조 자체의 누적 효과가 큽니다. 사고가 나면 사람이 수습하는 게 아니라 환경(규칙·도구·가드)을 고칩니다. 시간이 갈수록 같은 실수가 다시 나올 확률이 줄어듭니다 — 하네스의 가장 큰 매력은 "한 번 박힌 규칙이 다음 라운드부터 영구히 작동한다"는 점입니다. 위에서 인용한 "모델보다 하네스가 ROI가 높다"의 실제 작동 방식이기도 합니다.
마지막으로 한 가지 안전장치를 더 말씀드리고 싶습니다. 하네스를 만들다 보면 1인 운영자는 자주 함정에 빠집니다 — 본질 작업(물건 만들기)보다 메타 작업(계획·리뷰·하네스 손보기)이 많아지는 것입니다. 그래서 룰을 하나 더 넣었습니다 — Tripwire: "2번 연속으로 메타 작업이 본 작업보다 많은 라운드가 나오면 즉시 멈춘다." AI 활용의 목적은 시스템 정비가 아니라 물건을 만드는 것이라는 것을 잊지 않으려는 가드입니다.
참고 자료
Anthropic — Effective harnesses for long-running agents
Anthropic — Create custom subagents (Claude Code Docs)
Andrej Karpathy — autoresearch (minimal agent loop, 2026-03)
Martin Fowler — Harness engineering for coding agent users
MongoDB — The Agent Harness: Why the LLM Is the Smallest Part of Your Agent System
Hamel Husain — LLM Evals FAQ · Why AI evals are the hottest new skill
Parallel.ai — What is an agent harness?
Curated list — awesome-harness-engineering
Ouroboros — Q00/ouroboros · PyPI: ouroboros-ai
Serena MCP — oraios/serena (LSP indexer for code agents)
