01. LLM Agent Harness Engineering

Harness 란

LLM 호출은 상태 없는 함수다. 입력 → 텍스트 한 번 이 전부다. 이를 스스로 일하는 에이전트로 만드는 것은 모델을 감싸는 소프트웨어 레이어이며, 이를 harness 라 한다.

harness = 모델이 아직 스스로 못 하는 것을 코드로 메우는 scaffolding. 모델이 좋아질수록 얇아진다.
harness engineering = harness 를 설계·구현·튜닝하는 행위. 문서 한 장 작성이 아니라 아래 루프와 그 주변 인프라 전체를 다룬다.

Agent Loop

표준 실행 패턴은 ReAct loop 다. Thought → Action → Observation 사이클을 종료 조건까지 반복한다.

loop:
  prompt = system + history + tools
  out    = LLM(prompt)
  if out has tool_call:
      result = execute(tool_call)   # Action
      history += result             # Observation
      continue
  else:
      return out                    # 종료

루프 자체는 20줄 남짓이다. harness engineering 의 무게는 루프가 아니라 그 주변 인프라에 있다.

context 관리 = prompt 에 무엇을 넣고 뺄지 (토큰은 유한하다)
도구 설계 + 권한/샌드박스 = 무엇을 쥐여주고 어디까지 믿을지
폭주 방지 = step 한도, 동일 실패 반복 감지
compaction = context 가 차면 옛 기록 요약 또는 내용 대신 경로로 치환
상태 영속화 = 새 세션에서 작업 이어받기 (파일·git)

두 가지 작업 층위

harness engineering 은 깊이가 다른 두 층위로 나뉜다. 문서(CLAUDE.md) 작성은 그중 코드 없는 층위의 한 가지일 뿐, harness engineering 전체가 아니다.

설정 층위 (코드 없음) = 기존 harness 의 동작을 설정으로 조율한다. CLAUDE.md, 서브에이전트 호출, /clear, 슬래시 명령
구현 층위 (코드) = harness 자체를 코드로 만든다. 루프·tool·compaction·권한을 직접 작성
CLAUDE.md 작성은 설정 층위의 한 도구다 (system prompt 주입). harness 본체(Claude Code 등)는 구현 층위의 코드다.

Claude Code = Harness 구현체

사용 중인 Claude Code 자체가 harness engineering 의 산출물이다. 한 세션에서 관측되는 동작이 곧 harness 다.

루프 = 답변 → 도구 호출 → 결과 → 재판단
tool dispatch = Read / Bash / WebSearch 등을 harness 가 정의·실행
guardrail = plan mode 의 쓰기 금지 강제 (권한 게이트)
multi-agent = Explore / Plan 서브에이전트가 분리 실행되고 결과만 반환 (메인 context 보호)
system prompt 주입 = CLAUDE.md 가 매 턴 prompt 에 포함
context 관리 = 길어진 대화를 자동 압축

적용 지점

이미 쓰는 harness 를 의도적으로 조율하는 것이 곧 설정 층위의 harness engineering 이다.

CLAUDE.md 에 컨벤션·워크플로우 작성 = system prompt 주입
주제 전환 시 /clear = context 리셋
Explore / Plan 서브에이전트 = multi-agent + 메인 context 보호
plan mode 읽기 전용 = permission / guardrail
외부 CLAUDE.md 를 자기 맥락에 맞게 적응·통합 = 행동 정책 재사용

CLAUDE.md vs SKILL.md

둘 다 harness 레버지만 푸는 문제가 다르다. 핵심 트레이드오프 = 무엇을 항상 들고 갈지 vs 필요할 때 꺼낼지.

CLAUDE.md = 항상 context 상주. 레포 전반 ambient 규칙. 무조건 트리거. 매 턴 토큰 비용 발생.
SKILL.md = progressive disclosure. 설명만 상주하고 본문은 매칭 시 로드. 특정 작업 한정. 명시 호출 또는 매칭 시 트리거. 호출 전 비용 거의 0. 스크립트·리소스 번들 및 플러그인 배포 가능.
SKILL.md 의 progressive disclosure 는 필요할 때까지 context 에 안 올린다는 점에서 compaction 과 같은 사상이다. 상시 적용할 행동은 CLAUDE.md, 가끔 쓰는 무거운 절차는 Skill 로 분리한다.

주의점

stale assumption = harness 는 모델이 못 하는 것에 대한 가정의 집합이다. 모델이 좋아지면 가정이 낡는다. 모델이 스스로 하는 일을 계속 대신하면 오히려 성능을 깎는다.
context bloat = 도구 결과를 raw 로 쌓으면 window 를 빠르게 소진한다. reversible compaction(경로화)을 기본값으로 한다.
무한 루프 / 툴 남용 = step 한도·budget·동일 실패 감지가 없으면 폭주한다.
보안 = 도구는 임의 코드 실행 표면이다. 권한 게이트·샌드박스 없이 셸·파일·네트워크 도구를 노출하지 않는다.
재시작 복원력 = fresh context 에서 상태를 복원하지 못하면 long-running 이 성립하지 않는다. 상태를 외부(파일·git)에 남긴다.

meatsby.github.io

Explorer