"하네스 엔지니어링 기초 (1/4) — AI 에이전트에서 모델보다 하네스가 중요한 이유"

-

좋은 모델을 붙였는데도 결과가 들쭉날쭉하다면, 문제는 모델보다 그 모델이 읽는 지시문, 호출하는 도구, 실패를 잡는 검증 루프에 있을 가능성이 높다. 이 글은 그 작업 환경 전체를 묶어 하네스라고 부르는 이유를 설명한다.

핵심 요약

  • 이제 많은 팀의 차이는 "어떤 모델을 샀는가"보다 모델이 어떤 환경에서 일하는가에서 벌어진다.
  • 하네스는 프롬프트 한 줄이 아니라 지시 파일, 컨텍스트 조립, 도구 표면, 권한, 검증, 기록, 인계 구조까지 포함하는 작업 환경이다.
  • 우리 리서치 기준으로 좋은 에이전트는 대체로 모델이 똑똑해서가 아니라, 실수하기 어렵고 실패를 빨리 드러내는 구조를 갖고 있었다.
  • 그래서 하네스 엔지니어링은 프롬프트 엔지니어링의 하위 주제가 아니라, 에이전트 품질을 좌우하는 상위 설계 문제에 가깝다.

1. 왜 지금 "모델보다 하네스" 이야기가 나오는가

초기에는 모델 성능 차이가 워낙 컸기 때문에 "최신 모델로 갈아타면 해결된다"는 기대가 어느 정도 통했다. 하지만 에이전트 사용이 본격화되면서 다른 현상이 더 눈에 띄기 시작했다. 같은 계열 모델을 써도 어떤 팀은 안정적으로 결과를 뽑고, 어떤 팀은 비슷한 작업에서 계속 흔들린다.

이 차이는 대체로 모델 내부가 아니라 바깥에서 생긴다.

  • 모델에게 무엇을 먼저 읽히는지
  • 도구를 어떤 이름과 설명으로 노출하는지
  • 실패했을 때 테스트와 리뷰가 어디서 잡아주는지
  • 긴 작업을 다음 세션으로 어떻게 넘기는지

즉, 모델이 일하는 작업대 자체가 성능의 일부가 됐다.

2. 하네스는 정확히 무엇인가

하네스라는 말은 원래 배선과 부품을 묶고 연결하는 구조에서 왔다. 자동차의 wiring harness가 엔진, 센서, 전원을 연결하듯이, AI 하네스도 모델과 실제 작업 세계를 연결한다.

소프트웨어 관점에서 풀면 더 직관적이다. 원시 모델은 강한 추론 엔진일 수는 있어도, 그 자체로는 "어디를 읽고, 무엇을 실행하고, 언제 멈추고, 어떤 기준으로 성공을 판정할지"를 안정적으로 보장하지 못한다. 하네스는 그 빈칸을 메운다.

이 블로그에서는 하네스를 다음처럼 본다.

하네스 = 모델을 제외한 나머지 작업 환경 전체

여기에는 최소한 아래 요소가 들어간다.

  • 목표와 금지사항을 알려 주는 지시 구조
  • 필요한 문서만 보여 주는 컨텍스트 설계
  • 파일 읽기, 검색, 실행 같은 도구 표면
  • 승인, 차단, 샌드박스 같은 권한 경계
  • 테스트, 리뷰, 재시도 같은 검증 루프
  • handoff 문서, 메모리, 로그 같은 상태 보존 장치

3. 프롬프트 엔지니어링과 무엇이 다른가

프롬프트 엔지니어링이 모델 입력 문장을 더 잘 만드는 일이라면, 하네스 엔지니어링은 모델이 반복해서 일하는 전체 런타임을 설계하는 일이다.

둘의 차이는 범위에서 드러난다.

질문 프롬프트 엔지니어링 하네스 엔지니어링
무엇을 다루나 한 번의 입력과 출력 여러 턴에 걸친 작업 흐름
주된 관심사 표현, 역할, 형식 문맥, 도구, 권한, 검증, 기록
실패 원인 지시가 모호함 시스템 구조가 불안정함
개선 방식 문장 수정 작업 환경과 피드백 루프 수정

그래서 에이전트 작업에서는 "프롬프트를 더 잘 쓰자"보다 "에이전트가 틀렸을 때 어디서 잡히는가"가 더 중요한 경우가 많다.

4. 우리 리서치가 공통으로 본 세 가지 차이

sources/260518_하네스엔지니어링_15장_블로그활용노트.md와 시리즈 설계 문서를 기준으로 정리하면, 좋은 하네스는 대체로 아래 세 축에서 차이를 만들었다.

4.1 지시보다 구조가 먼저다

긴 설명서를 한 번에 밀어 넣는다고 더 똑똑해지지 않는다. 오히려 AGENTS.md, CLAUDE.md, 스킬 문서, handoff 파일처럼 역할별로 나뉜 구조가 있을 때 모델이 필요한 규칙을 더 안정적으로 따른다.

4.2 도구 개수보다 도구 표면이 중요하다

도구를 많이 붙이는 것보다, 모델이 "언제 어떤 도구를 써야 하는지" 판단하기 쉬운 이름·설명·입력 형식을 갖추는 편이 훨씬 중요하다. 도구 표면이 나쁘면 모델은 강력한 기능을 갖고도 반복해서 잘못 호출한다.

4.3 메모리보다 검증과 인계가 먼저다

장시간 작업에서 모두가 메모리를 강조하지만, 실제 운영에서는 그 전에 progress file, handoff 문서, 테스트, 로그 같은 구조가 먼저 필요하다. 기억을 오래 남기는 것보다, 다음 세션이 다시 들어와도 상황을 재구성할 수 있게 만드는 편이 더 안정적이다.

5. 우리 저장소 관점에서 보면 하네스는 이미 익숙한 구조다

하네스가 거창한 새 개념처럼 보일 수 있지만, 실제로는 이미 많은 팀이 다른 이름으로 하고 있는 일이다. 이 저장소 기준으로도 바로 대응되는 층이 있다.

하네스 층 우리 저장소 예시 하는 일
지시 구조 AGENTS.md, CLAUDE.md 역할, 제약, 출력 규칙 고정
컨텍스트 지도 tasks/plan.md, docs/memory-map.md 지금 읽어야 할 문서 범위 축소
인계 구조 tasks/handoffs/, tasks/sessions/ 긴 작업을 다음 세션으로 넘김
검증 장치 quality gate, 검토 절차 오류를 초기에 드러냄
권한 경계 publish 금지 규칙, config 보호 하면 안 되는 일을 구조적으로 차단

즉, 하네스는 미래 개념이 아니라 이미 운영 중인 규칙들을 하나의 설계 언어로 묶어 부르는 이름에 가깝다.

6. 모델이 좋아도 결과가 흔들리는 이유

좋은 모델만으로는 아래 문제를 자동으로 해결하지 못한다.

문맥 과적재

모든 문서를 한 세션에 다 넣으면 중요한 규칙이 오히려 묻힌다.

도구 오용

이름이 모호한 도구, 과하게 넓은 권한, 장황한 결과 출력은 모델 판단을 흐린다.

검증 부재

틀린 결과를 바로 잡아줄 테스트나 리뷰가 없으면, 에이전트는 같은 실수를 반복한다.

세션 단절

긴 작업에서 progress와 handoff가 없으면, 다음 세션은 매번 같은 맥락을 다시 추론해야 한다.

이 네 가지는 모두 모델 교체보다 하네스 개선으로 더 직접적으로 줄일 수 있는 문제다.

7. 실무자는 어디부터 설계해야 하나

하네스 엔지니어링을 너무 크게 잡으면 추상론으로 끝난다. 입문 단계에서는 아래 순서가 현실적이다.

  1. 모델이 반드시 지켜야 할 규칙을 짧은 지시 파일로 분리한다.
  2. 자주 읽는 문서와 한 번만 읽을 문서를 나눠 컨텍스트를 줄인다.
  3. 도구 이름·설명·입력 형식을 정리해 오용을 줄인다.
  4. 테스트, 리뷰, 체크리스트 중 최소 한 가지 검증 루프를 둔다.
  5. 긴 작업은 메모리보다 handoff 문서부터 남긴다.

이 순서는 화려하지 않지만, 실제 품질 차이를 만드는 쪽에 가깝다.

8. 이 시리즈에서 이어서 다룰 것

이번 A1은 하네스의 정의와 문제 설정이다. 다음 글부터는 더 구체적인 층으로 내려간다.

  • A2: AI 에이전트의 실제 작동 원리와 에이전트 루프
  • A3: 프롬프트보다 중요한 지시 구조와 컨텍스트 설계
  • A4: MCP와 도구 엔지니어링, 그리고 도구 표면 설계

즉, "하네스가 중요하다"는 선언에서 끝내지 않고, 어떤 층을 어떻게 설계해야 하는지로 바로 이어갈 예정이다.

참고 자료

  • docs/blog_series_하네스엔지니어링_총괄_design.md
  • sources/260518_하네스엔지니어링_15장_블로그활용노트.md
  • Martin Fowler, Harness engineering for coding agent users
  • WikiDocs, 하네스 엔지니어링 백과사전 1장 활용 메모

이 글은 하네스 엔지니어링 기초 시리즈의 1/4 편입니다. 다음 편: AI 에이전트는 실제로 어떻게 작동하는가 — 컨텍스트, 도구 호출, 에이전트 루프.

시리즈 전체 안내: 하네스 엔지니어링 시리즈 안내

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »