AI 에이전트는 왜 "한 번 잘 됐다"고 믿으면 안 되는가

5가지 관점에서 Skill과 Hook으로 적용하는 Provider-Free 하네스

---

요약

AI 에이전트를 운영할 때 가장 위험한 착각은 "한 번 잘 됐으니 이제 된다"는 믿음이다. 에이전트는 같은 입력에도 다른 경로를 택하고, 도구를 호출하며, 중간 상태를 만들고, 때로는 사람의 승인을 기다린다. 그래서 에이전트 품질은 모델 성능만으로 결정되지 않는다. 무엇을 할 줄 아는지(Skill), 언제 개입할지(Hook), 어떻게 기록하고 판정할지(Harness) 가 함께 있어야 한다.

하네스는 테스트 스크립트 하나가 아니다. 에이전트를 반복 실행하고, 과정을 기록하고, 성공을 판정하고, 비용을 제한하고, 사람의 개입을 상태로 다루는 운영 구조다. 이 구조를 만들려면 최소한 다섯 가지 요소가 필요하다.

이 다섯 가지는 단순한 체크리스트가 아니다. 각각이 에이전트 시스템에서 기존 소프트웨어 테스트와 달라지는 지점을 대표한다.

비결정성은 "한 번 잘 됐다"를 믿을 수 없게 만드는 출발점이다. 전통적인 함수는 같은 입력이면 같은 출력이 나오는 것을 기대한다. 하지만 에이전트는 같은 요청에서도 다른 검색어를 만들고, 다른 도구를 고르고, 다른 순서로 추론할 수 있다. 따라서 하네스는 단일 실행 결과가 아니라 반복 실행의 분포를 봐야 한다. 핵심은 성공 여부가 아니라 성공률, 흔들림, 재현 조건이다.

궤적은 에이전트가 무엇을 했는지의 과정 기록이다. 최종 답이 맞더라도 중간에 위험한 파일 명령을 시도했거나, 불필요한 외부 호출을 반복했거나, 근거 없는 정보를 가져왔을 수 있다. 에이전트 품질은 "답"만으로 판단할 수 없고, 어떤 도구를 어떤 인자로 호출했고, 어떤 판단으로 다음 단계로 넘어갔는지를 함께 봐야 한다. 궤적은 디버깅 자료이면서 동시에 감사 자료다.

오라클은 성공과 실패를 판정하는 장치다. 에이전트는 출력이 자연어인 경우가 많기 때문에 단순한 expected == actual 비교가 잘 먹히지 않는다. "좋은 요약", "충분한 근거", "정책에 맞는 조치" 같은 기준은 규칙, LLM judge, 인간 평가를 섞어야 판정할 수 있다. 오라클이 약하면 시스템이 틀렸는데도 성공으로 기록되는 false pass가 생긴다. 그래서 하네스는 에이전트뿐 아니라 판정 기준 자체의 신뢰성도 관리해야 한다.

비용은 에이전트 하네스가 테스트 자동화와 달라지는 현실적인 제약이다. 모델 호출, 검색, 브라우저 조작, 외부 API 호출은 모두 비용과 지연 시간을 만든다. 게다가 비결정성을 측정하려면 같은 시나리오를 여러 번 돌려야 하므로 비용은 곱셈으로 늘어난다. 따라서 하네스는 품질만 보는 장치가 아니라 실행 예산, 반복 횟수, 조기 중단 조건, 비용 대비 가치를 관리하는 장치여야 한다.

HITL은 Human-in-the-Loop, 즉 사람의 개입을 뜻한다. 중요한 점은 사람의 개입이 예외나 실패가 아니라는 것이다. 고위험 행동에서는 사람이 승인해야 하고, 그 승인은 "대화 중에 허락받았다"가 아니라 구조화된 상태로 남아야 한다. 무엇을 승인하는지, 위험이 무엇인지, 어떤 근거가 있는지, 승인 후 어디서 재개할지가 명확해야 한다. 하네스는 사람의 판단을 중단, 승인, 거절, 수정, 재개라는 상태 전이로 다룬다.

그리고 이 다섯 요소를 실제 운영에 어떻게 옮길 것인가가 중요하다. 결론부터 말하면, 반복되는 업무 지식은 Skill로 만들고, 반드시 지켜야 하는 실행 정책은 Hook으로 만든다. Skill은 에이전트에게 "이 업무를 어떻게 해야 하는지" 알려준다. Hook은 런타임에게 "이 시점에는 반드시 이것을 확인하라"고 강제한다.

예전에는 hook이 특정 도구, 특히 Claude Code 쪽의 편의 기능처럼 보였다. 그래서 provider-free 구성을 지향하는 입장에서는 hook에 너무 의존하는 것이 꺼려질 수 있었다. 그런데 Codex 계열에서도 hook과 유사한 실행 개입점이 등장하고, 여러 런타임이 lifecycle hook, middleware, guardrail, approval, tracing을 공통 기능으로 다루기 시작하면서 그림이 바뀌었다. 이제 hook은 특정 provider의 특수 기능이라기보다 에이전트 런타임의 표준 인터페이스에 가까워지고 있다.

---

Skill과 Hook은 무엇을 나누는가

Skill과 Hook은 둘 다 에이전트를 통제하기 위한 장치지만, 담당하는 층위가 다르다.

Skill은 업무 지식의 단위다. 어떤 목표를 달성해야 하는지, 입력은 무엇인지, 어떤 절차를 따를지, 어떤 산출물을 내야 하는지, 무엇을 실패로 볼지를 문서화한다. 예를 들어 research-brief Skill은 자료를 어떻게 찾고, 출처를 어떻게 붙이고, 어떤 형식으로 브리프를 낼지 알려준다. kb-rewrite Skill은 노트를 고칠 때 frontmatter와 wikilink를 보존해야 한다고 알려준다.

하지만 Skill은 기본적으로 에이전트가 읽는 지침이다. 좋은 Skill은 모델의 행동을 안정시키지만, 그 자체로 파일 삭제를 막거나, 비용 초과를 중단하거나, 승인 패킷을 생성하지는 않는다. 즉 Skill은 해야 할 일을 구조화하지만, 실행 시점의 강제력은 약하다.

Hook은 런타임 개입 지점이다. 에이전트가 도구를 호출하기 전, 파일을 쓰기 전, 응답을 내보내기 전, 비용이 갱신될 때, 실행이 끝날 때 끼어들어 검사한다. Hook은 allow, block, rewrite, require_approval 같은 결정을 내릴 수 있다. 예를 들어 pre_tool_use hook은 rm -rf를 승인 대기로 돌릴 수 있고, pre_response hook은 출처 없는 응답을 재작성으로 돌릴 수 있다.

그래서 둘의 관계는 이렇게 볼 수 있다.

하네스는 이 둘을 묶는다. Skill만 있으면 좋은 매뉴얼은 있지만 검문소가 없다. Hook만 있으면 검문소는 있지만 어떤 업무를 잘해야 하는지 모른다. 운영 가능한 에이전트 시스템에는 둘 다 필요하다.

---

Memory만으로는 왜 부족한가

에이전트 시스템을 오래 쓰다 보면 가장 먼저 떠오르는 해법은 memory다. 반복되는 맥락, 사용자 선호, 프로젝트 규칙, 과거 결정, 실패 이력을 memory에 남겨두면 에이전트가 더 일관되게 행동할 것처럼 보인다.

위험한 명령은 실행하지 마.
출처 없는 주장은 쓰지 마.
비용을 너무 많이 쓰지 마.
파일을 수정하기 전에 원문 링크를 보존해.
고위험 작업은 사람에게 확인해.

이런 규칙을 memory에 넣어두는 것은 필요하다. 하지만 충분하지는 않다. memory는 모델이 참고할 수 있는 과거 맥락이지, 런타임에서 행동을 강제하는 장치가 아니다. 모델이 해당 memory를 검색하지 못하거나, 잘못 해석하거나, 긴 작업 중 더 강한 현재 맥락에 밀리면 정책은 흔들릴 수 있다.

Skill은 memory보다 한 단계 더 명시적이다. 업무별 절차, 입력, 출력, 금지사항, 평가 기준을 독립 파일로 분리할 수 있기 때문이다. 그러나 Skill 역시 기본적으로 읽히는 문서다. Skill은 에이전트가 따라야 할 절차를 제공하지만, 도구 호출을 실제로 막거나, 비용 초과를 중단하거나, 승인 패킷을 생성하는 실행 권한을 갖지는 않는다.

이 지점에서 Hook이 필요해진다.

따라서 실무 패턴은 이렇게 잡는 것이 좋다.

Memory  = 누적 맥락과 과거 이력
Skill   = 업무별 작전 교범
Hook    = 런타임 검문소
Harness = 실행·검증·감사 체계

---

Provider-Free 하네스의 최소 구조

Provider-free 하네스는 특정 모델이나 앱을 피하자는 뜻이 아니다. 좋은 기능은 쓰되, 바뀌어도 되는 provider adapter와 바뀌면 안 되는 운영 지식을 분리하자는 뜻이다.

agent-harness/
  memory/
    project_context.md
    decisions.jsonl
    failure_patterns.md
  skills/
    research-brief/SKILL.md
    kb-rewrite/SKILL.md
    customer-risk-review/SKILL.md
  hooks/
    pre_tool_use.yaml
    post_tool_use.yaml
    pre_response.yaml
    on_cost_update.yaml
    on_run_end.yaml
  evaluators/
    citation_check.yaml
    policy_rubric.yaml
    trajectory_check.yaml
  fixtures/
    research_cases.yaml
    kb_rewrite_cases.yaml
  runs/
    2026-05-11T090000Z/
      trace.jsonl
      result.md
      eval.json
  provider-adapters/
    claude-code/
    codex/
    langgraph/
    temporal/

여기서 유지해야 할 계약은 세 가지다.

도구별 문법은 다를 수 있다. Claude Code hook, Codex hook, LangGraph middleware, Temporal activity wrapper는 구현 모양이 다르다. 하지만 pre_tool_use, post_tool_use, pre_response, on_cost_update, on_run_end 같은 이벤트 계약을 먼저 세우면 provider를 바꿔도 운영 원칙은 유지된다.

---

1. 비결정성: Skill fixture와 반복 실행으로 다룬다

문제

에이전트는 같은 입력에도 다른 경로를 택할 수 있다. 전통 소프트웨어처럼 "입력 A → 출력 B" 한 번만 보면 안 된다. 데모 한 번의 성공은 증거가 아니라 샘플 하나일 뿐이다.

Skill로 할 일

Skill에는 업무 절차와 성공 기준을 명시한다. 예를 들어 리서치 브리프 Skill이라면 다음처럼 쓴다.

# research-brief

## Purpose
사용자의 질문을 근거 기반 리서치 브리프로 정리한다.

## Procedure
1. 질문을 하위 쟁점으로 분해한다.
2. 각 쟁점마다 1차 출처를 우선 수집한다.
3. 주장마다 출처를 연결한다.
4. 근거가 약한 주장은 별도 표시한다.
5. 최종 브리프에는 결론, 근거, 한계, 다음 질문을 포함한다.

## Success Criteria
- 최소 5개 이상의 출처를 사용한다.
- 핵심 주장에는 출처를 붙인다.
- 한계와 불확실성을 분리해 쓴다.

그리고 Skill별 fixture를 둔다.

skill_id: research-brief
cases:
  - id: case_001
    input:
      research_question: "Agent runtime에서 checkpoint가 필요한 이유"
      scope: "최근 5년 연구와 공식 문서"
    expected:
      min_sources: 5
      required_sections:
        - conclusion
        - evidence
        - limitations
    repeat: 10

Skill만으로 부족한 점

Skill은 "이렇게 하라"고 알려줄 수 있지만, 같은 fixture를 몇 번 반복할지, 실행 조건을 고정할지, 실패율을 계산할지는 직접 수행하지 않는다. 모델은 자신이 10회 중 6회만 안정적으로 성공한다는 사실을 스스로 알기 어렵다.

Hook으로 보완할 일

반복 실행과 환경 고정은 harness hook에서 처리한다.

id: run_fixture_repetitions
event: before_suite
applies_to:
  - research-brief
controls:
  repeat: 10
  freeze:
    - model_version
    - skill_version
    - fixture_version
    - tool_versions
metrics:
  - success_rate
  - pass_at_k
  - flaky_rate

이렇게 하면 질문이 바뀐다. "한 번 됐는가?"가 아니라 "고정된 조건에서 몇 번 중 몇 번 됐는가?" 를 보게 된다.

---

2. 궤적: Hook event를 trace로 남긴다

문제

에이전트는 결과만 맞아도 과정이 틀릴 수 있다. 최종 답은 좋아 보이지만 중간에 잘못된 도구를 호출했거나, 불필요하게 비용을 썼거나, 민감한 정보를 외부로 보냈을 수도 있다. 그래서 에이전트 품질은 답변뿐 아니라 궤적(Trajectory)으로 평가해야 한다.

Skill로 할 일

Skill에는 기대되는 실행 흐름을 적는다.

# kb-rewrite

## Expected Trajectory
1. 원문 frontmatter를 읽는다.
2. 기존 wikilink 목록을 추출한다.
3. 핵심 주장과 근거를 분리한다.
4. 재작성 초안을 만든다.
5. frontmatter와 wikilink 보존 여부를 확인한다.
6. 변경 요약을 남긴다.

Skill만으로 부족한 점

Skill은 기대 경로를 설명할 수 있지만, 실제로 그 경로를 따랐는지는 실행 후 기록이 있어야 알 수 있다. memory에 "로그를 남겨야 한다"는 과거 규칙이 있어도, 어떤 이벤트를 어떤 형식으로 남길지 런타임에서 강제되지 않으면 감사 가능한 기록이 되기 어렵다.

Hook으로 보완할 일

모든 중요한 런타임 이벤트를 trace로 남긴다.

id: trace_agent_trajectory
event:
  - skill_loaded
  - pre_tool_use
  - post_tool_use
  - pre_file_write
  - pre_response
  - on_run_end
write_to: runs/{run_id}/trace.jsonl
include:
  - timestamp
  - run_id
  - skill_id
  - tool_name
  - arguments_hash
  - decision
  - cost
  - status

예상 trace는 이렇게 생겼다.

{"event":"skill_loaded","skill_id":"kb-rewrite","skill_version":"2026-05-11"}
{"event":"pre_tool_use","tool":"read_file","decision":"allow"}
{"event":"pre_file_write","check":"preserve_wikilinks","decision":"rewrite"}
{"event":"pre_response","check":"rewrite_summary_exists","decision":"allow"}
{"event":"on_run_end","status":"passed","total_cost":0.42}

이제 "답이 맞았나?"뿐 아니라 "어떤 경로로 맞았나?" 를 볼 수 있다.

---

3. 오라클: 평가 기준을 Skill 밖으로 분리한다

문제

에이전트가 잘했는지 판정하는 기준을 오라클(Oracle)이라고 부른다. 문제는 오라클 자체가 흔들릴 수 있다는 점이다. "좋은 글", "충분한 근거", "안전한 답변" 같은 기준은 사람마다 다르게 해석된다.

Skill로 할 일

Skill에는 성공 기준과 실패 조건을 적는다.

## Success Criteria
- 모든 핵심 주장에는 출처가 있다.
- 최신성이 중요한 주장에는 날짜가 있다.
- 내부 정책과 충돌하는 권고를 하지 않는다.

## Failure Conditions
- 출처 없는 단정문
- 원문에 없는 사실 추가
- 정책상 금지된 조치 권고

Skill만으로 부족한 점

Skill에 기준이 있어도, 그 기준을 실행마다 일관되게 적용하는 것은 별도 문제다. 모델에게 "출처 없는 주장을 쓰지 마"라고 해도, 모델은 자신이 방금 쓴 문장이 근거 없는 주장인지 놓칠 수 있다. LLM-as-Judge를 쓰더라도 편향과 불일치가 생긴다.

Hook으로 보완할 일

평가 기준을 evaluator로 분리하고, pre_response 또는 on_run_end hook에서 실행한다.

id: citation_and_policy_oracle
event: pre_response
applies_to:
  - research-brief
  - policy-analysis
evaluators:
  - citation_check
  - source_freshness_check
  - policy_conflict_check
decision:
  on_pass: allow
  on_minor_fail: rewrite
  on_major_fail: require_human_review
  max_rewrite_attempts: 2

Evaluator 자체도 독립 파일로 둔다.

id: citation_check
type: hybrid
rules:
  - "Every non-trivial factual claim must include a source."
  - "Sources must be listed in sources.json."
llm_judge:
  rubric:
    - claim_support
    - source_relevance
    - uncertainty_labeling
human_review:
  required_when:
    - llm_judge_score_below: 0.75
    - policy_sensitive: true

이렇게 하면 "잘했다"라는 감각이 아니라 기계적으로 실행 가능한 판정 기준이 생긴다. 모델을 바꿔도 오라클 계약은 유지된다.

---

4. 비용: Hook으로 예산을 강제한다

문제

에이전트 테스트와 운영은 비용이 쉽게 폭발한다. 한 시나리오를 여러 번 반복해야 하고, 한 번의 실행 안에서도 여러 번의 모델 호출과 도구 호출이 일어난다.

시나리오 수 × 반복 횟수 × 단계 수 × (LLM 토큰 + 도구 호출 비용) = 총 비용

Skill로 할 일

Skill에는 업무 가치에 맞는 기본 예산과 종료 조건을 적는다.

## Budget
- default_run_budget_usd: 5.00
- max_model_calls: 25
- max_tool_calls: 40
- stop_when_confidence_is_low: true

## Cost Policy
- 핵심 출처를 찾지 못한 채 검색을 5회 이상 반복하지 않는다.
- 같은 검색 질의를 반복하지 않는다.
- 예산의 80%를 넘으면 남은 계획을 요약한다.

Skill만으로 부족한 점

모델에게 "비용을 아껴"라고 말해도, 실제 누적 비용을 정확히 세고 차단하는 것은 런타임의 일이다. 긴 작업에서는 모델이 현재까지 몇 번 호출됐는지, 얼마를 썼는지, 남은 예산이 얼마인지 안정적으로 관리하기 어렵다.

Hook으로 보완할 일

비용은 hook이 강제해야 한다.

id: enforce_skill_budget
event:
  - pre_model_call
  - pre_tool_use
  - on_cost_update
applies_to:
  - research-brief
limits:
  max_run_cost_usd: 5.00
  max_model_calls: 25
  max_tool_calls: 40
thresholds:
  warn_at: 0.8
  block_at: 1.0
decision:
  on_warn: summarize_remaining_plan
  on_block: stop_and_report
  on_override_request: require_approval

이 hook은 memory보다 강하다. 모델이 과거 비용 정책을 검색하지 못해도 런타임이 막는다. 또한 Skill별로 예산을 다르게 줄 수 있다. 단순 문서 정리는 낮은 예산, 고가치 조사나 감사 작업은 높은 예산을 줄 수 있다.

---

5. HITL: 사람의 개입을 Hook decision으로 만든다

문제

사람이 끼어드는 것은 자동화 실패가 아니다. 고위험 작업에서는 오히려 잘 설계된 런타임의 일부다. 문제는 memory에 "위험하면 사람에게 물어봐"라는 과거 규칙을 남겨두는 것만으로는 충분하지 않다는 것이다. 언제 멈출지, 무엇을 보여줄지, 승인 후 어디서 재개할지가 구조화되어야 한다.

Skill로 할 일

Skill에는 인간 승인이 필요한 조건을 적는다.

## Human Review Required When
- 외부 고객에게 메시지를 보낸다.
- 파일을 삭제하거나 대량 변경한다.
- 권한, 결제, 계약, 법률, 인사 관련 조치를 제안한다.
- 정책 그래프와 현재 요청이 충돌한다.

Skill만으로 부족한 점

Skill은 승인 조건을 설명할 수 있지만, 실제 도구 호출 직전에 멈추고 승인 패킷을 만들고, 승인 후 checkpoint에서 재개하는 일은 런타임이 해야 한다. 모델이 "승인받겠습니다"라고 말하는 것과, 실제 실행이 멈춰서 승인 상태로 들어가는 것은 다르다.

Hook으로 보완할 일

고위험 도구 호출 앞에 approval hook을 둔다.

id: require_approval_for_high_risk_actions
event: pre_tool_use
when:
  risk_level:
    - high
  tool_name:
    - send_external_email
    - update_customer_plan
    - delete_file
    - change_access_level
decision: require_approval
approval_packet:
  action: "{tool_name}"
  arguments: "{arguments}"
  risk: "{risk_level}"
  reason: "{risk_reason}"
  evidence:
    - current_plan.md
    - relevant_policy.md
  options:
    - approve
    - reject
    - edit_and_resume
resume:
  checkpoint: "{checkpoint_id}"
  expires_at: "{approval_expiry}"

이렇게 하면 HITL은 "사람에게 물어봄"이 아니라 interrupt → review → approve/reject/edit → resume이라는 명시적 상태 전이가 된다. 승인 기록은 trace와 audit log에 남는다.

---

다섯 관점을 Skill-Hook으로 매핑하면

정리하면 다음과 같다.

핵심은 간단하다. Skill은 의도를 구조화하고, Hook은 그 의도가 실행 시점에 지켜지게 만든다. 둘 중 하나만으로는 부족하다.

---

Hook이 표준이 된다는 것의 의미

Hook이 여러 에이전트 도구에 들어오기 시작했다는 것은 중요한 신호다. 에이전트 개발의 중심이 memory/skill 중심의 맥락 관리에서 런타임 제어로 이동하고 있다는 뜻이기 때문이다.

Memory와 Skill은 모델에게 "이런 맥락과 절차를 참고해"라고 말한다. Hook은 런타임에게 "이 시점에는 반드시 이것을 확인해"라고 말한다.

Claude Code에만 hook이 있을 때는 이것이 provider-specific 기능처럼 보였다. 하지만 Codex와 다른 런타임에서도 hook, middleware, guardrail, lifecycle event가 공통 패턴으로 자리 잡고 있다면 이야기가 달라진다. Hook은 특정 도구에 갇힌 기능이 아니라, 에이전트 시스템을 운영 가능한 구조로 바꾸는 표준적인 제어면이 된다.

Provider-free 전략은 hook을 피하는 것이 아니라, hook을 추상화하는 쪽이 맞다. 같은 정책을 Claude Code hook, Codex hook, LangGraph middleware, Temporal activity wrapper, 자체 runner adapter로 옮길 수 있게 만드는 것이다.

---

최소 실행 가능한 Skill-Hook 하네스

처음부터 거대한 시스템을 만들 필요는 없다. 다음 정도면 시작할 수 있다.

1. 자주 반복하는 업무 하나를 Skill로 만든다.
2. 그 Skill의 대표 fixture 10~20개를 만든다.
3. 반드시 막아야 하는 위험 행동 3개를 pre_tool_use hook으로 만든다.
4. 반드시 지켜야 하는 품질 기준 3개를 pre_response evaluator로 만든다.
5. 비용 상한과 max retry를 hook으로 둔다.
6. 모든 hook decision을 trace.jsonl에 남긴다.
7. 같은 fixture를 5~10회 반복 실행한다.
8. success rate, cost, hook block, approval count를 본다.
9. 실패가 반복되는 부분을 Skill 또는 Hook으로 승격한다.

여기서 중요한 문장은 이것이다. 반복되는 맥락은 Memory로, 반복되는 업무 절차는 Skill로, 반복되는 런타임 사고는 Hook으로 승격한다. 이것이 하네스가 성장하는 방식이다.

---

정리

에이전트 하네스는 "테스트를 많이 돌리자"는 말이 아니다. Provider가 바뀌어도 유지되는 운영 골격을 만드는 일이다.

다섯 가지 관점은 하네스가 무엇을 봐야 하는지 알려주고, Skill-Hook 구조는 그것을 어떻게 실행할지 알려준다.

따라서 provider-free 하네스의 핵심은 특정 모델을 피하는 데 있지 않다. 모델과 도구는 바뀔 수 있다. 하지만 업무 Skill, 위험 정책, 평가 기준, 승인 기록, 실행 trace는 조직의 자산으로 남아야 한다. Skill은 업무 지식의 이식 단위로, Hook은 런타임 정책의 이식 단위로, Harness는 그 둘을 검증하고 기록하는 운영 단위로 설계한다.