Notice

[팁]주옥같은 안드로이드 팁

Recent Posts

Recent Comments

Link

« 2026/10 »
일	월	화	수	목	금	토
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Tags more

Archives

Today

Total

관리 메뉴

오늘도 공부

하네스 설계 입문 본문

카테고리 없음

하네스 설계 입문

행복한 수지아빠 2026. 9. 25. 13:25

기초 지식 정리에서 실무로의 스텝업

HARNESS ENGINEERING · SEMINAR

1페이지 — 하네스 설계 입문

하네스 설계 입문
~ 기초 지식 정리에서 실무로의 스텝업 ~

제1부

하네스 엔지니어링의 계보

5개 학파와 정의의 차이
이후의 수렴과 표준화
그리고 실증

4페이지 — 하네스 엔지니어링이란?

OVERVIEW

에이전트가 같은 실패를 반복하지 않도록 모델 바깥쪽의 ‘환경’을 설계하는 것

AGENT = MODEL + HARNESS

지시 파일, 도구, 검증, 가드레일, 루프 등
모델 이외의 모든 것이 하네스입니다.

흐름은 다음과 같습니다.

Prompt Engineering (2022~)
→ Context Engineering (2024~)
→ Harness Engineering (2026~)

2026년 2월 5일
Mitchell Hashimoto가 명명.

“실패했다면, 같은 일이 두 번 다시 일어나지 않도록 환경을 고친다.”

2026년 2월 11일
OpenAI가 실제 사례 공개.

3명이 작업
100만 줄 규모
코드의 95%를 AI가 생성

그 후 여러 기업과 전문가가 하네스라는 개념을 사용하기 시작했지만, 당시에는 사람마다 정의가 조금씩 달랐습니다. ハーネス設計入門_20260924

5페이지 — 하네스 엔지니어링의 5개 학파

같은 ‘하네스’라는 말을 쓰더라도, 어떤 구현을 본보기로 삼았느냐에 따라 의미의 범위가 다릅니다.

1. Chase 학파

광의·분류론

대표:

Harrison Chase
LangChain

핵심 주장:

모델 이외의 모든 것이 하네스

2. Hashimoto 학파

운영 철학

대표:

Mitchell Hashimoto

핵심 주장:

실패했다면 환경을 다시 설계하라

3. Fowler 학파

제어 이론

대표:

Birgitta Böckeler
Thoughtworks

핵심 주장:

컨텍스트 설계의 특수한 형태로 정의

4. Chawla 학파

동심원 모델

대표:

Avi Chawla

핵심 주장:

LLM의 OS 계층. 3중 중첩 구조

5. Codex 학파

스케일 중심

대표:

Ryan Lopopolo
OpenAI Codex

핵심 주장:

규모가 커질수록 무너지는 문제에 대한 해답 ハーネス設計入門_20260924

6페이지 — 서로 대립했던 구조

핵심 쟁점은 하네스와 컨텍스트 중 어느 것이 더 바깥 개념인가였습니다.

Chase / Chawla

하네스 ⊃ 컨텍스트

하네스

컨텍스트
- 프롬프트

즉, 전체 프레임워크 설계 관점입니다.

Fowler

컨텍스트 ⊃ 하네스

컨텍스트 설계

하네스
- guides
- sensors

즉, feedforward / feedback 제어이론 관점입니다.

2026년 상반기에는 이 차이가 논쟁의 중심이었지만, 이후 용어는 점차 하나로 수렴합니다. ハーネス設計入門_20260924

7페이지 — 이후: 용어의 수렴과 표준화

2026년 3~7월

3월 10일
LangChain 「The Anatomy of an Agent Harness」에서 하네스의 구성 요소를 정리.

4월 19일
Addy Osmani:

“하네스들은 서로 다른 모델보다 오히려 서로 더 닮아가고 있다.”

Build 2026

Agent Harness 안정 버전
Pydantic v2.0이 하네스 중심으로 재설계

2026년
Linux Foundation이 Agentic AI Foundation 설립.

대상:

MCP
AGENTS.md
Goose

결국 5개 학파에서 사용하던 용어는 약 5개월 만에 상당 부분 하나로 수렴했습니다.

Agent Plugins 1.0 — 2026년 8월 6일

Skills와 MCP 서버를 하나의 폴더 포맷으로 구성합니다.

plugin.json
skills/
mcp.json

참여:

Vercel
Amazon
Cursor
GitHub
Microsoft
OpenAI
Google

구현:

ChatGPT
Codex
Cursor
GitHub Copilot
Kiro
VS Code

한 번 만들면 여러 클라이언트에서 사용할 수 있는 방향으로 발전했습니다.

다만 완전한 호환성은 아닙니다.

Claude Code는 독자 형식을 유지
Skills 또는 MCP 중 하나만 지원하는 클라이언트도 존재
hooks / commands / rules는 표준화 대상이 아니어서 클라이언트마다 다름

즉,

용어는 수렴했고 포맷 표준화도 시작됐지만, 완전한 호환성은 아직 아니다. ハーネス設計入門_20260924

8페이지 — 하네스만 바꿔도 결과가 달라진다

모델을 변경하지 않고 하네스만 변경했는데 성능과 품질이 달라진 사례입니다.

벤치마크 순위

30위 → Top 5

모델은 그대로 두고 하네스만 변경했더니 Terminal Bench 2.0 순위가 상승.

— LangChain

설정에 따른 점수 차이

±5점 이상

하네스 설정만으로 점수가 이 정도 움직였습니다.

— Anthropic 2026 Agentic Coding Trends Report

품질 저하 원인 조사

3건 중 3건

Claude Code 품질 저하의 원인이 모두 하네스 측 변경이었던 사례.

— 2026년 4월 ハーネス設計入門_20260924

제2부

하네스 설계 실전

목표:

AI 에이전트가 스스로 실패를 발견하고, 스스로 수정하여 작업을 끝까지 완주하게 만드는 방법

10페이지 — 제2부의 흐름

1. 하네스를 만든다

에이전트에게

“어떻게 달려야 하는가”

를 알려주는 계층.

구성:

AGENTS.md
Skills
Sub-agent

2. 가드레일을 설치한다

일탈을 기계적으로 찾아내는 계층

lint
type check
test

이들을 하나의 check 명령어로 묶습니다.

3. 루프를 닫는다

에이전트에게

검증기
목표

를 주고 스스로 수정하면서 끝까지 진행하게 합니다. ハーネス設計入門_20260924

11페이지 — 전제: 생성형 AI는 확률로 움직인다

같은 지시를 내려도 매번 같은 결과가 나오지는 않습니다.

예를 들어:

“테스트를 ___”

다음 토큰의 확률이:

작성한다: 54%
실행한다: 28%
건너뛴다: 11%
기타: 7%

일 수 있습니다.

따라서 확률이 낮은 ‘나쁜 선택’도 0%는 아닙니다.

수천 개의 토큰이 생성되면 작은 확률 차이가 누적됩니다.

같은 지시에서도:

정상 코드 A
정상 코드 B
위험한 일탈

중 하나로 갈 수 있습니다.

기존 프로그램

같은 입력 → 같은 출력

결정적(deterministic)

생성형 AI

같은 입력 → 확률분포에서 샘플링

확률적(probabilistic)

따라서:

지시에만 의존하지 말고 환경과 검증 시스템으로 받아내야 한다. ハーネス設計入門_20260924

12페이지 — Harness와 Guardrails의 차이

HARNESS

하네스 = 말의 마구

달리기 전에

“어떻게 달렸으면 하는가”

를 알려주는 사전 설계 계층

예:

Custom Instructions / AGENTS.md
Skills
Sub-agent

GUARDRAILS

가드레일 = 울타리

달린 뒤

“길에서 벗어나지 않았는가”

를 기계적으로 검사하는 사후 검증 계층

예:

lint
format
type check
build
unit / integration / E2E test
Hooks

핵심:

하네스는 확률적이고, 가드레일은 기계적이다.

기계적인 판단이 강해질수록 에이전트에게 더 많은 권한을 맡길 수 있습니다. ハーネス設計入門_20260924

13페이지 — Harness 상세

하네스는 달리기 전에 전달하는 사전 설계 계층입니다.

역할

프로젝트의:

전제
규약
절차
금지사항

을 에이전트가 참조할 수 있는 형태로 명문화합니다.

성격

사람이 판단하는 주관적 계층입니다.

많이 적을수록 강하게 작용하지만 너무 많이 적으면 컨텍스트를 소비합니다.

따라서:

무엇을 적을 것인가를 선택하는 것 자체가 설계다.

또한 자연어로 표현하는 ‘의도’이기 때문에 100% 보장되지는 않습니다.

그래서 기계적으로 판정하는 가드레일과 함께 사용해야 합니다. ハーネス設計入門_20260924

14페이지 — Guardrails 상세

가드레일은:

길에서 벗어나지 않았는지 검사하는 계층

입니다.

사용:

lint
type check
build
test

이들은 Yes / No를 기계적으로 판정합니다.

누가 실행해도 같은 결과가 나오는 객관적인 계층입니다.

따라서:

판정이 기계적일수록 에이전트가 스스로 실패를 발견하고 스스로 수정하기 쉬워진다.

확률적으로 움직이는 모델을 결정적인 검증 시스템으로 지탱하는 구조입니다. ハーネス設計入門_20260924

15페이지 — Feedback Loop

1. 구현한다

에이전트가 작업 진행

↓

2. 검증한다

에이전트가 직접

check

를 실행하고 결과를 읽음

↓

3. 스스로 수정한다

오류 출력을 보고:

수정
재실행

↓

다시 반복

사람이 준비하는 것은 두 가지입니다.

검증기 = 문

check

라는 하나의 명령

목표

check가 모두 통과한다

AGENTS.md에는:

실행 명령
공통 조건

등을 기록합니다.

작업별 조건까지 테스트로 만들어 check 안에 넣으면:

check가 모두 통과했다 = 작업 완료

라고 판정할 수 있습니다.

즉,

검증기와 목표를 제공하면 에이전트 스스로 피드백 루프를 닫을 수 있다. ハーネス設計入門_20260924

16페이지 — 하네스의 도구 상자

1. Rules

적용: 항상

대표적으로:

AGENTS.md

주요 도구들이 읽는 사실상의 공통 포맷.

매 세션 컨텍스트에 들어가며 얕고 넓게 작동합니다.

적합:

규약
명령어
금지사항

2. Skills

적용: 필요할 때

특정 작업용 절차서.

필요할 때만 읽기 때문에 상시 컨텍스트를 소비하지 않습니다.

목적:

정형 작업의 재현성

3. Sub-agent

적용: 역할 단위

특정 전문 프롬프트를 가진 에이전트.

예:

조사
구현
리뷰

목적:

병렬화 + 컨텍스트 분리

권장 순서

첫 단계는 AGENTS.md다.

기본 토대를 먼저 만들고 Skills와 Sub-agent를 그 위에 추가합니다. ハーネス設計入門_20260924

17페이지 — AGENTS.md에 무엇을 써야 하는가

AGENTS.md는 매번 컨텍스트에 들어가기 때문에

한 줄마다 ‘임대료’를 낸다

고 생각해야 합니다.

◎ 써야 할 것

프로젝트 개요

한 문단 정도.

무엇을 위한 프로젝트인지 알려주면 판단 기준이 맞춰집니다.

명령어

build
test
lint

에이전트가 스스로 검증할 수 있게 합니다.

프로젝트 고유 규약

예:

네이밍
디렉터리
에러 처리 방식

하지 말아야 할 것

예:

수정하면 안 되는 파일
변경 금지 API

✕ 쓰지 말아야 할 것

일반 지식 / 프로그래밍 언어 기본 규칙

모델이 이미 알고 있습니다.

코드를 보면 알 수 있는 내용

코드와 문서를 이중 관리하게 됩니다.

긴 설계 문서 전체

Skills 또는 링크로 분리합니다.

기계적으로 검증할 수 없는 정신론

예:

“코드를 깔끔하게 작성한다.”

대신 기계적으로 판정할 수 있는 형태로 바꿔야 합니다.

기준

처음에는 최소한으로 작성합니다.

모든 줄이 실제 실패나 프로젝트 규칙과 연결되어 있어야 한다.

그리고 일탈이 발생하면 한 줄씩 추가합니다. ハーネス設計入門_20260924

18페이지 — Skills

필요한 경우에만 읽는 절차서

모든 것을 Rules에 넣으면 컨텍스트가 넘칩니다.

반복되는 정형 작업은 Skill로 분리합니다.

예:

# 엔드포인트 추가

## 사용할 때
REST API에 새로운 라우트를 추가할 때

## 절차
1. routes/ 에 route 정의
2. handlers/ 에 로직 구현
3. schemas/ 에 validation 정의
4. __tests__/ 에 테스트 추가
5. docs/api.md 업데이트

## 모범 예제
routes/health.ts 참고

판단 기준

매번 필요하다
→ Rule

특정 작업에서만 필요하다
→ Skill

헷갈리면:

Skill 쪽으로 빼라.

/create-skill을 사용해 대화식으로 생성할 수도 있습니다. ハーネス設計入門_20260924

19페이지 — Sub-agent를 호출하는 두 가지 방식

A. 필요할 때 즉석 생성

부모 에이전트가 필요해진 순간 자식 에이전트를 생성합니다.

일회성 위임에 적합합니다.

예:

대규모 조사
여러 항목 비교
컨텍스트를 많이 사용하는 탐색
결과 요약만 받고 싶은 경우

예:

“세 라이브러리를 각각 별도의 Sub-agent에게 병렬 조사시키고 핵심만 보고해.”

B. 미리 정의해두고 호출

역할, 관점, 출력 형태를 파일에 정의해 놓고 이름으로 호출합니다.

반복해서 사용할 작업에 적합합니다.

예:

리뷰
보안 감사
테스트

리뷰 에이전트:

“변경 사항을 규약·보안·테스트 커버리지의 세 관점으로 검토해.”

병렬 실행

비동기로 실행하면 대기 시간은 줄지만 동시에 실행하는 만큼 단위시간당 토큰 사용량은 늘어납니다.

핵심은:

컨텍스트 분리

자식 에이전트에도 자체 하네스가 적용됩니다. ハーネス設計入門_20260924

20페이지 — Guardrails의 계층

오른쪽으로 갈수록 판정이 강해집니다.

Formatter

표현 통일

예:

Prettier
gofmt

Linter

작성 규칙 검사

예:

ESLint
Clippy

Type Check

정합성 검증

예:

tsc
mypy

Build

프로그램이 실제 결과물로 성립하는지 확인

Test

의도한 동작을 보장

이 다섯 가지를 하나의 명령으로 묶습니다.

check

사람도 AI도 같은 문을 통과합니다.

완료 조건:

check가 모두 통과함

원칙:

가드레일이 강할수록 에이전트가 자신의 실패를 스스로 발견할 수 있고, 그만큼 맡길 수 있는 범위가 넓어진다. ハーネス設計入門_20260924

21페이지 — 가드레일을 실행하는 3개의 레일

가드레일은 판정 도구이고, 레일은 이 검사를 자동 실행하는 위치와 시점입니다.

1. 에이전트 Hooks

위치:

클라이언트 내부

시점:

파일 편집
명령 실행

예:

afterFileEdit → lint
beforeShellExecution → rm 차단

장점:

가장 빠르게 검사

단점:

클라이언트 설정으로 비활성화 가능

2. Git Hooks

시점:

commit
push

도구:

Husky
lefthook

예:

pre-commit
pre-push

여기서 check 실행.

다만:

--no-verify

로 우회 가능합니다.

3. CI

시점:

PR 생성
PR 업데이트

동일한 check를 CI에서 실행하고, branch protection으로 실패하면 merge할 수 없도록 합니다.

가장 강력합니다.

핵심

가까움 · 빠름 · 약함
        ↓
멀리 있음 · 느림 · 강함

안쪽에서 빠르게 발견하고, 바깥쪽에서 확실하게 막는다. ハーネス設計入門_20260924

22페이지 — 가드레일은 2종류다

1. 결과물에 대한 가드레일

이미 작성한 것을 사후 검증합니다.

lint
type check
build
test

질문:

“올바르게 만들었는가?”

실패 결과는 피드백 루프의 입력이 됩니다.

2. 행동에 대한 가드레일

위험한 행동을 실행 전에 차단합니다.

Hooks
허용 목록

예:

beforeShellExecution에서:

rm
외부 전송

등을 차단합니다.

질문:

“실행해도 되는가?”

일어난 뒤에는 되돌릴 수 없는 사고에 사용합니다.

공통 원칙:

사람의 주의력에 의존하지 않고 기계적으로 막는다. ハーネス設計入門_20260924

23페이지 — 하네스 설계의 3계층

문서에서는 이를 말 / 울타리 / 경계에 비유합니다.

1. 말의 마구 — 방향

달리기 전에 어떻게 움직여야 하는지 알려줍니다.

AGENTS.md
Skills

2. 울타리 — 판정

길에서 벗어났는지 기계적으로 판단.

lint
type
test
Hooks

에이전트가 결과를 읽고 수정합니다.

3. 경계 — 가동 범위

아예 접근 가능한 영역 자체를 결정합니다.

격리
차단
최소 권한

도달할 수 없게 해야 하는 자산

Production
DB
Secrets
개인정보

핵심:

가드레일은 길의 끝에서 일탈을 탐지한다.
경계는 되돌릴 수 없는 장소로 가는 길 자체를 처음부터 만들지 않는다. ハーネス設計入門_20260924

24페이지 — 3계층의 역할

하네스

방향을 제시

가드레일

길을 벗어났는지 판정

인프라 경계

갈 수 있는 범위 자체를 제한

경계가 묻는 질문:

접근할 수 있는가?

특성:

구조적이며 사전적이다.
판단하는 것이 아니라 접근 자체를 불가능하게 만든다.

수단:

Container
Sandbox
네트워크 차단
최소 권한

강도의 단계:

지시한다
확률적
↓
가드레일로 막는다
기계적
↓
경계로 불가능하게 만든다
구조적

핵심:

되돌릴 수 있는 일탈은 가드레일로 잡아 루프로 돌려보내고, 되돌릴 수 없는 일탈은 경계에서 시도 자체를 없앤다. ハーネス設計入門_20260924

25페이지 — 하네스와 보안

자율성을 높일수록 에이전트 자체가 공격의 진입점이 될 수 있습니다.

1. 간접 Prompt Injection

외부 콘텐츠에 숨어 있는 지시에 모델이 따르는 문제

2. 기밀·개인정보 유출

인증 정보와 고객 데이터를 에이전트가 읽을 수 없게 해야 합니다.

3. 파괴적 작업

예:

rm
force push

실행할 수 없도록 해야 합니다.

4. Supply Chain

AI가 제안한 dependency package는 사람이 확인해야 합니다.

가장 위험한 조합

기밀 데이터 접근
×
의심스러운 콘텐츠 읽기
×
외부 데이터 전송

이 3개를 동시에 허용하지 말아야 합니다.

이를 Lethal Trifecta라고 합니다.

방어:

행동 가드레일
×
Sandbox 격리
×
신뢰 경계

검토된 Skill과 Plugin만 허용합니다. ハーネス設計入門_20260924

26페이지 — 자율 실행 시간 자체가 목표는 아니다

목표는:

짧게, 적게, 싸게 끝내는 것

입니다.

Uber의 비용 방정식:

사용자 수
×
사용자당 세션 수
×
세션당 턴 수
×
턴당 요청 수
×
요청당 토큰 수
×
토큰당 가격

하네스가 줄일 수 있는 것은 중간 항목입니다.

Turn

계획을 빠르게 만들어 불필요한 턴과 오류 감소

Request

사내 정보를 근거로 제공하여 쓸데없는 탐색 감소

Token

항상 상주하는 컨텍스트 감소

예:

MCP를 CLI화
캐싱

Uber의 2026년 2월 → 8월 결과

사용자:

7배

요청:

9.4배

그런데도 총비용은 거의 그대로.

추가로:

1,000 요청당 비용: -34%
세션당 비용: -52%

가장 효과적이었던 방법:

Sub-agent를 저렴한 모델로 변경

결론:

오래 자율적으로 실행됐다는 사실 자체는 성과가 아니다. ハーネス設計入門_20260924

27페이지 — 하네스는 숨겨진 기술 부채다

잘 만든 하네스에도 수명이 있습니다.

Han Lee, 2026:

“좋은 팀일수록 많은 하네스를 만든다. 그리고 그중 많은 것은 다음 세대 모델에서는 필요 없어질 것이다.”

현재 모델의 약점을 보완하기 위해 만들어 놓은:

우회책

예:

“생략하지 말고 전부 출력해”
“전부 읽은 다음 수정해”

과도한 설계

세밀하게 나눈 절차
독자적인 retry 처리

이런 것은 모델이 좋아지면 사라질 수 있습니다.

반면 남는 것은:

핵심

test / check
권한과 경계
프로젝트 고유 규칙

즉:

모델 발전
↓
임시 우회책 → 사라짐
과도한 절차 → 사라짐
검증·보안·고유 규칙 → 남음

따라서:

한 시점의 하네스 구조에 집착하지 말고, 가볍게 유지하며 정기적으로 정리해야 한다. ハーネス設計入門_20260924

28페이지 — 하네스 엔지니어링 구현 순서

1. 먼저 경계를 만든다

안전한 작업 환경 준비.

Sandbox
Cloud Agent

그리고:

Production 인증 정보는 주지 않는다.

2. AGENTS.md 작성

최소한으로 시작합니다.

모든 줄은 실제:

실패
프로젝트 규칙

과 연결되어야 합니다.

초안은 AI에게 작성시킨 뒤 사람이 삭제하면서 다듬습니다.

3. 가드레일을 만들고 1개의 명령으로 묶는다

lint
type
test
↓
check

사람과 AI 모두 같은 검증을 통과합니다.

4. 루프를 닫는다

에이전트에게:

검증기
목표

를 줍니다.

목표:

check가 모두 통과

5. 반복 작업이 생기면 도구를 추가한다

반복되는 절차:

→ Skills

반복되는 관점:

→ Sub-agent

6. 운영하면서 성장시키고 정기적으로 정리한다

일탈이 생기면:

Rule 한 줄 추가

몇 달에 한 번 정도는:

전체를 지웠다가 정말 필요한 것만 다시 넣어보는 정리

도 권장합니다.

Git으로 관리하면 안전하게 시도할 수 있습니다.

핵심 순서

경계를 먼저 만든다.
Rules보다 먼저 도구를 늘리지 않는다. ハーネス設計入門_20260924

29페이지 — 결론: 하네스 엔지니어링 4원칙

1. 돌아올 수 없는 곳으로 가는 길을 만들지 않는다

다음에는 애초에 접근할 수 없어야 합니다.

Production
Secrets
개인정보
되돌릴 수 없는 작업

사용:

격리 환경
통신 차단
최소 권한

경계를 먼저 만든다.

2. 진행 방향은 하네스로 알려준다

명문화:

규칙
명령어
금지사항

일탈이 생길 때마다 한 줄씩 추가합니다.

작성보다 운영이 중요하다.

3. 일탈은 가드레일로 탐지한다

lint
type
test
Hooks

이를 하나의:

check

로 묶습니다.

사람도 AI도 같은 문을 통과합니다.

판정은 기계적으로 합니다.

4. 루프를 닫아 자율 실행시킨다

에이전트에게:

검증기
목표

를 제공하면,

에이전트가:

구현
검증
오류 확인
수정
재검증

을 반복하여 스스로 작업을 완료합니다.