Harness Engineering — Claude Code 자동화 아키텍처
정의: Harness Engineering은 Claude Code의 에이전틱 루프 상의 여러 지점에 지침(Hooks, Skills, MCP)을 삽입하여, 반복적인 작업을 자동화하고 개발 효율을 극대화하는 소프트웨어 엔지니어링 방법론입니다.
핵심 개념
하네스 문제와 새로운 해법들 (valid_as_of 2026-05-20)
Hashline (Oh-My-OpenAgent): LINE#ID 콘텐츠 해시로 모든 편집 전에 내용을 검증. “모델이 수정하려는 라인에 대한 안정적이고 검증 가능한 식별자를 주지 않는 것”이 대부분 에이전트 실패의 원인이라는 진단에서 출발. Grok Code Fast 1 성공률 6.7% → 68.3% 향상. (출처: oh-my-openagent-github-readme)
Skill-Embedded MCPs (Oh-My-OpenAgent): MCP 서버가 컨텍스트 예산을 갉아먹는 문제를 해결. 스킬이 자기 MCP를 데리고 다니다가 태스크 완료 시 자동 종료 → 컨텍스트 창 깨끗하게 유지.
2026-05-13 한강 AI-native 러닝 이벤트에서 Jeffrey Kim은 핸드폰만으로 에이전트를 돌려 1시간 내 프로젝트 2개를 완성하며 이렇게 말했다:
“중요한 것은 코드를 직접 얼마나 많이 치느냐가 아니라, 에이전트가 멈추지 않고 목적지까지 가게 만드는 하네스를 얼마나 잘 만드느냐인 것 같습니다.” (출처: Jeffrey-Kim-한강-AI-native-런-LinkedIn)
Harness Engineering의 본질을 가장 간결하게 정의한 문장 중 하나. vibe-coding의 모바일 확장과 함께, 하네스 설계 역량이 개발자 생산성의 핵심 변수임을 실증한 사례.
Hermes Agent 사례는 Harness Engineering의 목적을 “사용자가 반복 프롬프트 병목이 되지 않도록 루프 밖으로 나가는 것”으로 설명한다. 크론, 스킬, 메모리, 브라우저, LLM Wiki 같은 지점은 단순 기능 목록이 아니라 에이전틱 루프에 자동화·학습 장치를 삽입하는 하네스 포인트다. (출처: yt-WXka6bp1aYw-헤르메스-에이전트-20분-총정리)
같은 관점에서 z2zlife 영상은 명령 → 결과 피드백 → 메모리/스킬 저장 → 크론 자동화로 이어지는 개인 AI 생태계를 강조한다. 이는 Harness Engineering을 “개별 도구 최적화”가 아니라 사람이 반복 입력 병목에서 빠지고 시스템이 조건 기반으로 실행되도록 만드는 운영 설계로 해석하게 해준다. (출처: yt-GsMB3SHHlzI-Hermes-Agent-완벽-구축-가이드)
메이커 에반의 Claude Code 도구 큐레이션은 하네스를 “속도 향상 장치”보다 “루프 제어 장치”로 보는 실전 사례다. obra-superpowers는 계획·테스트·리뷰를 강제하고, gstack은 office-hours와 browse로 아이디어 검증·브라우저 QA를 보강하며, openai-codex의 codex:review는 마지막 다른 모델 검증 게이트로 쓰인다. (출처: yt-BZPaZzjLIOY-Claude-Code-핵심도구6개)
Garry-Tan(YC CEO)은 이를 “Thin-Harness-Fat-Skills” 원칙으로 요약한다: 하네스(CLAUDE.md + settings)는 얇게, 재사용 가능한 스킬은 두껍게 쌓아야 한다. 에이전트 생산성 차이는 모델이 아니라 스킬 설계에서 결정된다. (출처: Claude-Code-6개-추천-스킬-LinkedIn)
에이전틱 루프 (Agentic Loop)
Loop engineering은 이 루프를 사람이 매번 프롬프트로 밀어 넣는 방식이 아니라, 태스크 발견 → 분배 → 실행 → 검증 → 다음 결정이 자동 순환하도록 설계하는 관점이다. RLM/Claude Code dynamic workflow 사례처럼 subagent 결과를 장문 context 덤프가 아니라 검증 가능한 결과 변수처럼 다루면, 토큰 비용·goal drift·agentic laziness를 줄이는 하네스 설계로 이어진다. (출처: linkedin-jeongmin-lee-loop-engineering-rlm-2026-06-09)
Claude Code는 무한 피드백 루프에서 작동합니다:
사용자 요청
↓
Claude 생각 + 계획
↓ (Hook: PreToolUse)
도구 실행 (Read, Write, Bash, ...)
↓ (Hook: PostToolUse)
결과 검증 + 로깅
↓
다음 단계 결정
↓ (Hook: Stop)
세션 종료
Harness Engineering은 각 지점에 자동화 규칙을 삽입합니다.
4단계 하네스 구축
Phase 1: 지침 (CLAUDE.md)
무엇: 인간이 읽을 수 있는 규칙 문서
예:
# CLAUDE.md
## 로깅 규칙
모든 wiki/ 수정 전 **log.md 먼저** append.
→ wiki 편집 → (setup 미완료 시만) PROGRESS.md 체크리스트 업데이트효과: Claude가 매번 수동으로 실행 (규칙을 읽고 따름)
제한: 반복되는 실수 시 다음 단계로 진행
Phase 2: Skill (재사용 절차)
무엇: CLAUDE.md의 절차를 .claude/skills/로 분리
예:
.claude/skills/log-wiki-update/SKILL.md
├─ 목적: 작업 완료 후 로깅 자동화
├─ 7단계 절차 (프로젝트 식별 → log.md 작성 → 체크박스 동기화 → ...)
├─ 체크리스트 (단계별 검증 항목)
└─ 사용 예시 (Phase 9 Dashboard.md 흐름)
호출:
/log-wiki-update
# Claude가 Skill을 로드하고 절차 실행효과:
- 절차가 명시적 문서화됨
- 사용될 때만 로드 → 컨텍스트 효율
- Claude가 여전히 수동으로 호출 (사용자가 지시)
Phase 3: Hook (자동 기동)
무엇: Claude가 특정 이벤트 발생 시 자동으로 Skill 실행
설정 (settings.json):
{
"hooks": {
"PostToolUse": {
"condition": "작업 유형이 edit/write 포함",
"action": "log-wiki-update 스킬 자동 실행"
},
"Stop": {
"condition": "프로젝트 파일 변경 있을 때",
"action": "project-sync 스킬 자동 실행"
}
}
}5가지 Hook 이벤트:
| 이벤트 | 시점 | 용도 |
|---|---|---|
| PreToolUse | 도구 실행 전 | 위험 작업 차단 (exit 2) |
| PostToolUse | 도구 실행 후 | ⭐ 자동 검증·로깅 (가장 많이 사용) |
| Notification | 알림 이벤트 | 외부 시스템 연동 |
| Stop | 세션 종료 | 정리·요약 작업 |
| PreCompact | 컨텍스트 압축 전 | 중요 정보 보존 |
Exit Code:
0: ✅ 성공, 계속1: ⚠️ 에러, 피드백2: 🛑 즉시 차단, 인간 확인 필요
효과: 사용자가 완전히 손 떼도 Claude가 자동으로 로깅·검증 수행
Phase 4: Orchestration (대규모 자동화)
무엇: Subagents, MCP, Agent Teams로 복잡한 워크플로우 자동화
예:
- Subagent: 대규모 탐색 → 요약만 반환 (컨텍스트 절약)
- MCP: 외부 API 연동 (GitHub, Slack, DB)
- Agent Teams: 병렬 독립 세션 (대규모 배치 작업)
실제 적용: Phase 9 로깅 자동화
현재 (Phase 1-2)
사용자: "Dashboard.md 만들었어"
↓
Claude:
1. wiki/log.md 엔트리 작성
2. Phase 9 Next Actions 체크박스 업데이트
3. progress_percent 수정
4. wiki/index.md 반영
(매번 수동 실행)
목표 (Phase 3)
Claude가 views/dashboard.md 파일 저장
↓ (PostToolUse Hook 자동 발동)
log-wiki-update Skill 자동 실행:
- log.md 엔트리 ✅
- 체크박스 ✅
- progress_percent ✅
- index.md ✅
(모두 자동)
CLAUDE.md 작성 기준
길이 제한
목표: 200줄 이하
이유 (ETH Zurich 연구):
- 인간 작성 지침 ~4% → 성능 개선 ✅
- LLM 생성 지침 (>4%) → 성능 악화 + 비용 20% 증가 ❌
내용 분류
| 항목 | 위치 | 비고 |
|---|---|---|
| 지침 (Directive) | CLAUDE.md | ”로깅 규칙”, “경로 규칙” 등 |
| 절차 (Procedure) | .claude/skills/SKILL.md | 단계별 방법론 |
| 자동화 (Automation) | settings.json Hooks | 이벤트 기반 자동화 |
| 상세 구현 | 별도 문서 | 참고 문서, 예시 모음 |
성숙도 평가
| Phase | 구성 | 효과 | 대상 |
|---|---|---|---|
| 1 | CLAUDE.md + 지침 | 규칙 명확화 | 초급 (1-2개월) |
| 2 | + Skills | 절차 재사용 | 중급 (2-6개월) |
| 3 | + Hooks | 자동화 50-100% | 고급 (6개월+) |
| 4 | + Subagent/MCP | 복잡 워크플로우 | 마스터 |
배운 점
1. 규칙 → 절차 → 자동화 순서
- 먼저 무엇을 할지 명확히 (규칙)
- 다음 어떻게할지 구체화 (절차)
- 마지막 자동화 (Hook)
2. 반복 실패 = 다음 단계 신호
- 같은 실수 2번 → Phase 2 (Skill 작성)
- 매번 수동 실행 → Phase 3 (Hook 설정)
4. “알고 있다 ≠ 실행한다” — 구체성의 원칙
CLAUDE.md 지침(Phase 1)을 작성할 때 추상적 원칙 대신 구체적 실행 규칙을 써야 한다. 이는 OpenClaw의 절대 규칙 설계(agent-error-learning-loop)와 동일한 원칙이다.
| 유형 | 예시 | 결과 |
|---|---|---|
| ❌ 추상 원칙 | ”불필요한 반복을 피하라” | AI가 해석 → 실패 가능 |
| ✅ 구체 규칙 | ”최초 1회만. 메모리에서 확인” | 해석 없이 실행 |
CLAUDE.md 지침이 추상적이면 → AI가 “알고 있지만 실행 못하는” 상황이 발생한다. 지침의 구체성이 하네스 품질의 핵심이다.
3. 컨텍스트는 유한함
- CLAUDE.md 200줄 이하 유지
- 긴 절차는 Skills로 분리
- LLM 생성 규칙은 금지
🔨 행동 체크리스트
신규 프로젝트 하네스 구축 시
- CLAUDE.md 작성: 200줄 이하로 지침·컨벤션 정의
- 반복 실수 모니터링: 동일 실수 2번 감지 → Skill 작성 검토
- 수동 반복 작업 식별: 매번 수동으로 실행하는 작업 → Hook 설정 후보 리스트업
- PostToolUse Hook 설정: 파일 편집 후 자동 검증·로깅 규칙 정의
- Stop Hook 설정: 세션 종료 시 정리 및 요약 작업 자동화
- PreToolUse 차단 규칙 정의: 위험 작업(git reset, 삭제 등) 차단 조건 명시
정기 하네스 점검 (주간·월간)
- CLAUDE.md 지침 최신성 확인: 지난달 지침이 여전히 유효한가?
- 수동 반복 작업 재평가: 새로운 Hook 후보가 있는가?
- Skill 중복·비효율 검토: 중복 사용되는 Skill을 통합할 수 있는가?
- 컨텍스트 버짓 점검: 하네스 구성 파일(CLAUDE.md + Skills)의 총 크기가 적절한가?
💡 교육자·PM 활용: 새로운 팀원 온보딩 시 이 체크리스트를 통해 “이 프로젝트의 하네스는 어느 단계인가?”를 파악하고, 다음 성숙도 단계로의 전환을 계획하세요.
실증 사례: OpenClaw 에이전트 (뽀짝이)
지피터스 AI스터디 운영 에이전트 뽀짝이(bbojjak-openclaw-agentic-architecture-lesson01)는 CLAUDE.md 하네스 원리를 일반 에이전트 프레임워크로 구현한 실사례다.
| 하네스 레이어 | Claude Code 구현 | OpenClaw 구현 |
|---|---|---|
| 역할 지침 (Phase 1) | CLAUDE.md | SOUL.md + AGENTS.md |
| 기억 관리 (Phase 2) | memory/ Skill | MEMORY.md + memory/ 폴더 |
| 자동 루틴 (Phase 3) | Stop Hook + CronCreate | HEARTBEAT.md + 크론잡 |
| 도구 연동 (Phase 4) | MCP 서버 | TOOLS.md + SDK 스크립트 |
핵심 교훈: “같은 LLM이어도 워크스페이스 파일(하네스)이 달라지면 완전히 다른 에이전트가 된다.” — 하네스 = 에이전트의 정체성 레이어.
시스템 프롬프트 자동 로딩: 터미널 Claude Code는 CLAUDE.md 1개만 자동 로드하지만, OpenClaw는 6개 파일(SOUL/AGENTS/TOOLS/USER/IDENTITY/HEARTBEAT)을 매 대화마다 자동 주입한다. 이것이 “규칙을 절대 안 까먹는” 이유이며, Phase 1 하네스(CLAUDE.md) 운영의 한계와 런타임 레이어의 필요성을 실증한다. (출처: bbojjak-openclaw-runtime-architecture-lesson07)
자세한 구조는 agent-workspace-structure, agent-runtime-architecture 참조.
”Hook이 안 되면 지침으로” — 토큰 최적화 실전 사례
RTK(Rust Token Killer) 사례: Claude Code에서는 PreToolUse hook으로 CLI 출력을 자동 압축하지만, OpenClaw에서는 exec가 hook 경로를 거치지 않아 자동 치환이 안 된다. 해결책: AGENTS.md에 “rtk 접두어 붙이기” 지침 한 줄 추가 → 동일 효과. (출처: bbojjak-openclaw-token-optimization-lesson16)
이것이 2중 방어선의 실전 변형: 시스템(hook) 구축이 환경 제약으로 불가할 때, 지침(AGENTS.md)이 대안으로 동일한 결과를 낸다. → agent-token-optimization 참조.
참고 개념
- compound-engineering — 슈퍼파워스 사이클 끝에 끼우는 “실수 누적 학습” 단계. ZeroCho 실전 시연
- agent-skill-design — OpenClaw 스킬 = Claude Code Skills(Phase 2) 동일 원리. SKILL.md + scripts/ + references/ 구조. 에이전트가 description 매칭으로 자동 선택
- agent-error-learning-loop — AGENTS.md 절대 규칙 탄생 루프; CLAUDE.md 지침 작성 원칙과 동일 (“알고있다≠실행한다”, 구체성 원칙, 2중 방어선)
- agent-workspace-structure — 에이전트 워크스페이스 파일 구조 (하네스 실증)
- heartbeat-mechanism — 능동적 에이전트를 위한 크론잡 패턴
- agent-token-optimization — hook 불가 시 지침 대안; 토큰 소비처 분석; RTK
- claude-code-harness-guide — 공식 가이드
- phase9-pkm-improvement — 실제 적용 사례
AI 네이티브 조직의 하네스 3조건 (지피터스 실전)
(출처: yt-gpters-openclaw-ai-native-company-2026)
- 토큰 무제한 지원 — 시도할 수 없으면 성장도 없다. 인건비 대비 월 $200 플랜은 미미한 투자.
- SSOT (리니어 집중) — “AI한테 맥락을 줘야 더 잘 도와주겠구나”를 팀원 스스로 깨달아야 SSOT가 자발적으로 작동한다. 지시가 아닌 내적 동기.
- 스킬 생태계 — 개발자가 스킬 배포 인프라 구축 → 누구나 스킬 만들어 공유 → 팀 전체가 함께 AI 네이티브 조직으로 성장.
이 3조건은 harness-engineering의 4단계(CLAUDE.md→Skills→Hooks→Teams)를 조직 차원으로 확장한 것이다.
외부 가이드 사례: Karpathy-Inspired CLAUDE.md
andrej-karpathy-skills-github-repo는 하네스의 “지침 레이어(Phase 1)“를 오픈소스 템플릿으로 배포한 사례다. 핵심은 4원칙(Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution)이며, 본 문서의 원칙과 직접 대응된다.
- 지침을 추상 슬로건이 아니라 실행 가능한 규칙으로 명시
- 과설계 방지와 변경 범위 통제(요청과 무관한 수정 금지)
- 검증 가능한 성공 기준 기반 루프 실행
즉, 하네스 엔지니어링은 특정 도구 한정 기법이 아니라, “에이전트 행동 품질을 규칙으로 설계”하는 범용 패턴임을 보여준다.