[하네스 공부 1탄] 하네스가 뭔데? 빵 심부름으로 이해하기

안녕하세요 . 얼레벌래입니다 ~^^ 

네이버로쓰다 velog도 해봣다 역시 전 관심이 필요해서 velog는 좀 부실한것 같고 .. 네이버는 관심은 적절한데 

사진올리기가 힘들어서 자꾸 힘들면뭐다..? 손이안간다....ㅠㅠ 그래서 새로운 둥지를 틀어봤습니다 

심심하던 찰나에 이런 글을 발견했고 저는 '소장'님의 말씀대로 하네스를 공부했을뿐, 절때 딴짓한게 아닙니다? 

https://walkinglabs.github.io/learn-harness-engineering/ko/

Learn Harness Engineering에 오신 것을 환영합니다 | Learn Harness Engineering

 

그렇담 내용 시작합니다 ..~  귀찮음 관계로 ai딸깍 md 문서로 대체합니다^^- 나중에 이걸 자동화해서 글쓰도록도 해볼 예정 인데 

말투는 차차... 다듬는걸로 하겠슴다 

[하네스 공부 1탄] 하네스가 뭔데? 빵 심부름으로 이해하기

출처: Learn Harness Engineering - 강의 02. 하네스란 실제로 무엇인가 강의 읽다가 헷갈린 부분을 질문하면서 정리한 내용

 

0. 처음 내가 생각한 하네스

처음엔 하네스를 이렇게 생각했다.

디자인 에이전트 → 백엔드 에이전트 → QA 에이전트 → 배포 에이전트
        (이걸 다 묶어서 범용적으로 사이클 돌려주는 것)

근데 강의를 읽을수록 이게 아니었다. 강의가 말하는 하네스는 훨씬 아래층 이야기였다.

---

1. 공식부터

모델 + 하네스 = 에이전트
에이전트 여러 개 + 연결 규칙 = 오케스트레이션

용어 한 줄 정의 예시

모델	뇌. 듣고 → 생각하고 → 다음 행동을 말함	Claude Opus, Sonnet, GPT
하네스	모델 빼고 전부	Claude Code 루프, CLAUDE.md, 셸, Docker, 테스트
에이전트	모델 + 하네스가 합쳐져서 실제로 일하는 녀석	"FVSS 코드 고치는 그 녀석"
오케스트레이션	에이전트 여러 개를 엮고 일을 넘기는 구조	내가 처음 생각했던 그림

내가 처음 생각한 건 오케스트레이션이었고, 하네스는 그 밑바닥이었다.

---

2. 빵 심부름 비유

"빵 사와!" 시키는 상황으로 전부 매칭해보면:

빵 심부름 AI 세계 개발 업무 예시

심부름 시키는 엄마	사용자	나
"빵 사와!"	작업 지시	"로그인 API 만들어줘"
심부름 가는 애 (전체)	에이전트	Claude Code
└ 그 애의 뇌	모델	Claude Opus
└ 차비, 지도, 메모, 영수증	하네스	셸, CLAUDE.md, Docker, 테스트
빵집 + 빵 파는 직원	작업 대상 / 외부 시스템	코드베이스, DB, 외부 API
빵	결과물	완성된 API 코드, PR

ps. 여기서 뇌는 opus5.5 , 아르곤 등 모델명이라 하대요,, 이것저것 예시를 들어봣는데 뇌가 제일 잘맞는 느낌이라카,대요..?

헷갈렸던 포인트: 모델은 빵 파는 직원이 아니다

처음엔 모델을 "빵 만들어 파는 쪽"으로 착각했다. 아니다. 모델은 심부름 가는 애의 머릿속(뇌) 이다. 바깥에 따로 있는 존재가 아님.

입력: "빵 사와"
모델 생각: "식빵이겠지? 가까운 빵집은 OO니까 버스 타야겠다"
출력: "버스 타고 OO빵집 가기"

근데 뇌는 혼자서 손발이 없다.

• 뇌가 "버스 타자" 생각만 함 → 실제로 버스 타는 건 하네스 (교통카드, 다리)
• 뇌가 "dotnet test 돌려보자" 글만 씀 → 실제로 실행하는 건 하네스 (셸)
• 뇌는 어제 일을 기억 못 함 → 기억시켜주는 건 하네스 (PROGRESS.md)

그래서 뇌(모델)는 갈아끼울 수 있다. Opus든 Sonnet이든 GPT든.

---

3. 하네스 = md 파일 아님

강의 첫 문단부터 박혀 있음:

대부분의 사람들이 하네스라고 할 때 "프롬프트 파일"을 의미합니다. 그것은 하네스가 아닙니다.

CLAUDE.md는 하네스의 1/5 일 뿐이다.

구성요소 빵 심부름 실체 md인가?

① 지시	"OO빵집 식빵 2개, 품절이면 바게트" 메모	CLAUDE.md, AGENTS.md	✅ 문서
② 도구	차비, 교통카드, 휴대폰	셸 권한, MCP, 스크립트	❌ 실제 기능
③ 환경	버스 노선도, 빵집 위치	Docker, 버전 고정 파일	❌ 실제 인프라
④ 상태	"1번 빵집 품절, 2번 가는 중" 기록	PROGRESS.md, git 커밋	반쯤 문서
⑤ 피드백	영수증 확인, 사진 보내서 "이거 맞아?"	테스트, 린트, 빌드	❌ 돌아가는 코드

md는 "이렇게 해"라고 말해주는 것이고, 나머지는 실제로 할 수 있게 / 틀리면 걸리게 만드는 것.

백엔드 개발자 감각으로 말하면: 하네스 = 신입 한 명을 위한 온보딩 문서 + 개발환경 + CI 세팅 전부. 신입이 첫날부터 혼자 빌드하고 테스트 돌리고 PR 올릴 수 있게 해놓은 "상태 자체".

---

4. 제일 가성비 좋은 건 ⑤ 피드백

강의 결론: 검증 명령어부터 맞춰라.

CLAUDE.md에 "이거 돌려서 통과하면 성공"이라고 적어두기만 해도 효과가 크다. 에이전트가 스스로 맞았는지 확인할 수 있게 되니까.

강의 예시(가상 수치):

단계 추가한 것 성공률

1	아무것도 없음 (README만)	20%
2	AGENTS.md (지시)	60%
3	검증 명령어 (피드백)	80%
4	진행 파일 (상태)	80~100%

모델은 한 번도 안 바꿨다. 주방 정리만 했다.

그리고 하나 더: 에이전트는 자기 작업을 자신만만하게 칭찬하는 경향이 있다. → "일하는 애"와 "확인하는 애"를 분리하라. (이게 사실 내가 처음 생각한 QA 에이전트 분리의 가장 작은 형태였음)

---

5. 내 프로젝트에 적용하면 (예시)

# FVSS
- .NET 8, ClickHouse, PostgreSQL, Docker Compose

## 실행
- docker compose up -d

## 검증 (작업 끝나면 반드시 실행)
- dotnet build && dotnet test

## 절대 규칙
- ClickHouse 스키마 변경은 migrations/ 폴더로만

(버전, 경로는 예시)

---

6. 한 줄 요약

똑똑한 애(모델)한테 돈이랑 지도랑 메모랑 확인방법(하네스)을 쥐여주면, 빵 잘 사오는 심부름꾼(에이전트)이 된다.

머리가 좋아도 차비 없고 메모 없으면 엉뚱한 빵 사오거나 길 잃는다. 그게 "하네스 없는 에이전트"다.

---

다음 편 예고

• 2탄: 하네스 5요소 하나씩 직접 세팅해보기? / 오케스트레이션은 하네스 위에 어떻게 올라가나?