하네스 워크북 교재 0/11

Harness Engineering · 실습 워크북

LLM은 두뇌,
하네스는 몸.

LLM은 두뇌, 하네스는 몸. 파이썬으로 에이전트를 처음부터 만들어 보는 11개의 랩. 각 랩은 개념 → 따라 해보기 예제 → 확인 퀴즈 → 브라우저에서 코드 채우기 → 자동 채점 순서로 진행됩니다. 휴대폰에서도 됩니다.

시작하기 추천 교재 전체 코드

진행 상황은 이 기기 브라우저에 저장됩니다.

Part I · 몸의 기본

  1. 01 대화는 그냥 JSON 배열이다 LLM API는 상태가 없다. 매 요청에 대화 전체를 배열로 보낸다. 20분
  2. 02 도구 = JSON 스키마 + 함수 디스패치 도구 = 모델에게 보여줄 JSON 스키마 + 하네스가 실행할 함수. 25분
  3. 03 에이전트 루프 stop_reason 이 tool_use 인 동안 [호출 → 실행 → 결과 덧붙이기]를 반복한다. 25분

Part II · 오래 달리기

  1. 04 컨텍스트는 예산, 캐싱은 순서 큰 도구 결과는 들어오는 순간 잘라야 한다. 30분
  2. 05 서브에이전트 = 컨텍스트 포크 서브에이전트 = 새 배열로 같은 루프를 한 번 더 돌리는 것. 20분
  3. 06 돌고 있는 루프 조종하기 실행 중 리마인더는 다음 tool_result 메시지 끝에 <system-reminder> 로 붙인다. 25분

Part III · 믿을 수 있는 몸

  1. 07 반사신경과 가드레일 프롬프트의 '조심해'는 부탁, 하네스 코드는 규칙. 25분
  2. 08 배열 디버깅 에이전트 문제의 원인은 거의 항상 '실제로 보낸 배열' 안에 있다. 20분

Part IV · 데이터 입히기

  1. 09 RAG는 원래 하네스 패턴이었다 RAG도 '배열에 무엇을 넣을지' 고르는 하네스 코드다. 35분
  2. 10 온톨로지: 에이전트에게 도메인 지도 입히기 온톨로지 = 개념 · 관계 · 속성 · 해석 규칙을 명시한 도메인 지도. 40분

마무리

  1. 11 캡스톤: 미니 하네스 지금까지의 패치를 하나의 몸으로 조립한다. 30분

큰 그림

            ┌──────────────────────── 하네스 (몸) ────────────────────────┐
 사용자 ──▶ │  배열 = [system(+온톨로지), user, assistant, tool_result…]     │
            │     │                                       ▲               │
            │     ▼  요청(배열 전체 + 도구 스키마)          │ 결과 덧붙이기  │
            │  ┌────────┐   tool_use    ┌──────────────────┴────────────┐  │
            │  │  두뇌  │ ────────────▶ │ 가드레일 → 도구 실행 → 자르기     │  │
            │  │ (LLM)  │ ◀──────────── │ (파일·셸·검색·온톨로지·서브에이전트)│  │
            │  └────────┘  end_turn     └───────────────────────────────┘  │
            │        리마인더/todo 는 다음 user 메시지 끝에 주입               │
            └─────────────────────────────────────────────────────────────┘

RAG와 온톨로지는 어디에 끼나?

둘 다 결국 "배열에 무엇을, 언제, 어디에 넣을지" 의 문제입니다.

방식배열의 어디에강점실패 지점
온톨로지 전체 주입시스템 프롬프트 (고정 prefix → 캐시됨)누락 없음, 고치기·디버깅 쉬움커지면 컨텍스트를 잡아먹음
온톨로지 조회 도구필요할 때 tool_result 로컨텍스트 절약모델이 조회를 안 하거나 잘못된 용어로 조회
RAG 사전 주입사용자 메시지 앞모델이 검색을 몰라도 됨top-k 가 연결 고리를 놓침
RAG 검색 도구tool_result 로여러 번 다시 검색 가능검색어 선택을 모델에 의존
그래프 탐색도구 결과로 경로를multi-hop 관계에 강함운영 비용, 쿼리가 틀리면 확신 있게 틀림

Lab 9·10은 같은 질문 "대금지급 전에 검수가 끝나야 하나요?" 으로 이 차이를 직접 확인합니다. RAG top-3 은 대금지급·검수 문서는 찾지만 둘을 잇는 삼자대사·입고 문서를 놓치고, 온톨로지는 대금지급 -requires→ 3-Way Match -compares→ 입고 -requires→ 검수 경로를 그대로 보여 줍니다.

공부하는 법

  1. 개념을 읽습니다. 랩마다 "무엇이 깨지나 → 패치 → 비용" 세 단락입니다.
  2. 따라 해보기 예제를 봅니다. 비유와 함께 짧은 코드와 실제 출력이 있고, ▶ 실행·✎ 고쳐 보기로 직접 바꿔 볼 수 있습니다. 💡 표시가 바꿔 볼 거리입니다.
  3. 확인 퀴즈로 핵심을 점검합니다.
  4. 실습 편집기에서 TODO 를 채웁니다. TODO 찾기 버튼이 다음 빈칸으로 데려갑니다.
  5. ▶ 채점을 누르면 브라우저 안의 파이썬(Pyodide)이 테스트를 돌립니다. 처음 한 번은 10MB 정도를 내려받습니다.
  6. 막히면 정답 보기로 비교하세요. 작성한 코드는 자동 저장됩니다.
  7. PC에서는 zip을 받아 python run_tests.py 로 같은 테스트를 돌리고, ANTHROPIC_API_KEY 를 넣으면 진짜 Claude와 대화합니다.

출처

개념과 흐름: Harness Engineering 101 © Isuru Wijesiri (본문 CC BY-NC-ND 4.0, 코드 MIT). 이 워크북은 원문을 옮기지 않고 한국어로 새로 쓴 학습 자료입니다.
온톨로지 확장 순서: 장한별, 「그래서 Agent에 데이터를 어떻게 입히나요?」

GitHub에서 코드 보기