AI 튜토리얼

JevHarness로 빠르고 작업별 특화된 의사결정 파이프라인 구축

JevHarness가 작업 관찰 결과를 구조화된 저지연 의사결정으로 변환하는 방법을 알아보세요. 이 튜토리얼에서는 아키텍처, Claude Code 및 Codex 설치, 보관된 Pokémon 예제, 작업별 하네스 생성, 평가 기반 개선, 런타임 요구 사항, 자격 증명, 트레이스, 검증된 하네스를 고정하는 기법을 다룹니다.

2026년 9월 22일약 19분 소요

JevHarness의 기능

JevHarness는 작성 LLM이 Jev를 위한 작업별 의사 결정 하니스를 만들 수 있도록 지원합니다. 이 하니스는 허용된 관찰 정보를 유용한 특징으로 변환하고, 구조화된 Jev 질문과 기준을 구성하며, 답변을 법적으로 허용되는 작업으로 결합합니다.

핵심 개념은 비용이 많이 드는 전략 개발과 반복적인 실행을 분리하는 것입니다.

개발 중에는 깊이 추론합니다. 전략을 고정합니다. Jev가 빠르고 유연하게 판단하도록 합니다.

개발 중에는 LLM이 하니스 코드, 질문, 그래프, 상태, 기준 및 메모리를 수정할 수 있습니다. 하니스를 선택하고 고정한 후에는 런타임 의사 결정이 해당 고정 로직과 Jev 호출을 사용합니다. 작성 LLM은 모든 작업을 다시 추론할 필요가 없습니다.

따라서 JevHarness는 코드가 신뢰할 수 있는 사실을 계산할 수 있지만 일부 결정은 상황에 따라 달라지거나 모호한 작업에 적합합니다. 예를 들어 코드는 법적으로 허용되는 작업을 판단하고 수치 특징을 계산할 수 있으며, Jev는 사용 가능한 작업 중 작업별 기준을 가장 잘 충족하는 작업을 판단할 수 있습니다.

아키텍처와 책임 경계

JevHarness는 신뢰할 수 있는 작업 어댑터와 의사 결정 하니스를 분리합니다. 이 경계는 하니스가 자체 보상을 변경하거나 숨겨진 작업 상태에 접근하지 못하도록 합니다.

작업 어댑터: 관찰 정보, 법적으로 허용되는 작업, 부작용 및 점수 계산을 담당합니다.
하니스: 특징 구성, Jev 판단 및 의사 결정 로직을 담당합니다.
환경: 작업을 실행하고 신뢰할 수 있는 결과 또는 보상을 반환합니다.
작성 LLM: 개발 및 선택적 성찰 과정에서 하니스를 생성하거나 수정합니다.

검증된 PipelineSpec은 PipelineRuntime을 통해 실행됩니다. 파이프라인을 선택하면 해당 사양, 런타임, 평가기 및 선언된 작업 리소스와 함께 고정할 수 있습니다.

주요 기능

구조화된 Jev 판단

Jev는 choice, score 및 noul 답변 유형을 지원합니다. 하나의 요청에 이름이 지정된 여러 질문을 포함할 수 있으며, 서로 독립적인 그래프 노드는 동시에 실행될 수 있습니다.

명시적인 전략 표현

전략은 코드, 계산된 특징, 상태, 지침, 기준, 메모리 및 제어 흐름에 보존됩니다. 따라서 의사 결정 과정이 작성 대화 안에 남지 않고 검사하고 재사용할 수 있는 형태로 유지됩니다.

완전한 실행 추적

성찰 과정에는 관찰 정보, 결정, 노드 입력 및 출력, Jev 질문과 답변, 메모리 및 실패를 포함한 선택된 에피소드의 전체 기록을 전달할 수 있습니다. 손실 없는 중복 제거로 반복을 줄입니다. 성찰 입력이 구성된 바이트 제한을 초과하면 자동으로 잘리지 않고 보관된 후 거부됩니다.

선택적 보상 기반 개선

선택적 GEPA 통합은 인스턴스 프런티어에서 부모를 선택하고, 동일한 학습 배치에서 각 부모와 제안의 성능을 비교하며, 승인된 제안을 Eval에서 평가합니다. 거부된 제안을 포함해 실제 계보를 기록합니다.

검사 가능한 고정 아티팩트

고정하면 선택한 하니스와 선언된 종속성이 보존됩니다. Jev 노드를 포함하는 고정 하니스는 런타임에도 Jev가 필요합니다. 또한 호스팅 모델 별칭이 향후 제공업체 동작의 불변을 보장하지는 않으므로, 저장된 응답과 새 호출은 재현성 측면에서 서로 다른 수준을 제공합니다.

사전 요구 사항

실행하려는 항목에 맞는 요구 사항을 선택하세요.

보관된 웹사이트: Node.js와 최신 브라우저가 필요합니다. 모델 자격 증명, 게임 엔진 또는 Python 샌드박스는 필요하지 않습니다.
Python 프로젝트: Python 3.11 이상이 필요합니다.
기능성 Python 노드: 지원되는 macOS 네이티브 샌드박스가 필요합니다. 격리를 사용할 수 없으면 실행이 안전하게 실패합니다.
버전 2 표현식 및 Jev 흐름: 기능성 Python 워커를 실행하지 않습니다.
실시간 Jev 호출: 지원되는 제공업체 계정과 해당 API 키가 필요합니다.
선택적 작성 및 성찰: 로컬 Claude CLI, OpenAI, Azure 또는 Anthropic 엔드포인트를 사용하는 구성된 Proposer가 필요합니다.

Claude Code에 스킬 설치

가장 빠른 Claude Code 설정 방법은 저장소를 플러그인 마켓플레이스로 추가하고, 플러그인을 설치한 다음 플러그인을 다시 불러오는 것입니다.

/plugin marketplace add https://github.com/TianyuCodings/JevHarness.git
/plugin install jev-harness@jevharness
/reload-plugins

플러그인을 설치하면 스킬과 참조 자료가 다운로드되지만 Python 종속성을 설치하거나 모델 자격 증명을 구성하지는 않습니다. 저장소가 비공개인 경우 GitHub 인증이 이미 작동해야 하며 계정에 읽기 권한이 있어야 합니다.

Codex에 스킬 설치

내장된 skill-installer를 제공하는 Codex 호스트에서 저장소로부터 직접 설치를 요청합니다.

$skill-installer Install the jev-harness skill from https://github.com/TianyuCodings/JevHarness/tree/main/skills/jev-harness

다음 턴부터 스킬을 사용하세요. Codex가 즉시 스킬을 검색하지 못하면 세션을 다시 시작하세요.

수동 설치

Claude Code, Codex 또는 둘 모두에 스킬을 수동으로 설치할 수 있습니다. /path/to/your-project를 기존 프로젝트 디렉터리로 바꾸세요.

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
python3 scripts/install-skill.py --target both --scope project --project /path/to/your-project

이 명령은 Codex용 프로젝트 수준 설치 경로인 .agents/skills/jev-harness/와 Claude Code용 .claude/skills/jev-harness/를 생성합니다. 한 가지만 설치하려면 --target codex 또는 --target claude를 사용하세요.

모든 프로젝트에서 사용할 수 있는 사용자 수준 설치를 수행하려면 다음을 실행하세요.

python3 scripts/install-skill.py --target both --scope user

개인 설치 위치는 ~/.agents/skills/jev-harness/ 및 ~/.claude/skills/jev-harness/입니다. 설치 프로그램은 기존에 다른 설치가 있으면 덮어쓰지 않습니다. 스킬이 검색되지 않으면 에이전트 세션을 다시 시작하세요.

보관된 Pokémon 예제 살펴보기

포함된 Pokémon 예제는 보관된 실행 기록, 선택된 하네스, 탐색 가능한 진화 트리, 전체 의사 결정 기록, 거부된 제안, Jev의 답변과 동기화된 리플레이 하이라이트를 제공합니다. 이 보관 기록을 탐색하는 동안 모델 요청이 발생하지 않으며 게임도 시작되지 않습니다.

저장소를 복제합니다.
웹사이트를 빌드합니다.
로컬 미리보기 서버를 시작합니다.
최신 브라우저에서 사이트를 엽니다.

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
node website/build.mjs
node website/preview.mjs --port 8768

localhost:8768을 엽니다. 배틀 애니메이션은 공식 Pokémon Showdown 렌더러에서 에셋을 다운로드합니다. 보관된 배틀 로그는 브라우저에 남아 있으며 리플레이 서버로 업로드되지 않습니다.

보고된 Pokémon 결과에서 5회의 성찰 라운드 후 Eval 승률이 25퍼센트, 즉 12게임 중 3게임에서 75퍼센트, 즉 12게임 중 9게임으로 향상되었습니다. 검색에서는 3라운드 후보를 최상의 하네스로 유지했습니다. 이는 선택 Eval 세트에서 측정한 결과이며, 보지 못한 게임에서의 성능을 독립적으로 추정한 값으로 간주해서는 안 됩니다.

기본 의사 결정 이해하기

하네스는 state, 이름이 지정된 questions, 답변 type, 그리고 가능한 행동을 평가하는 데 사용되는 instructions와 criteria를 포함한 작업별 Jev 요청을 작성합니다.

기록된 Pokémon 예제에서 하네스는 Slowbro가 Gastrodon과의 대미지 경쟁에서 패배할 가능성이 높다고 계산합니다. 세 가지 기술과 Scizor로 교체하는 선택지를 포함해 네 가지 합법적인 선택지를 제시합니다. 행동 질문은 choice 유형을 사용하며 Jev가 나열된 행동 ID 중 정확히 하나를 반환하도록 요구합니다.

{
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "Choose the single action most likely to win the whole battle, not only this turn.",
      "criteria": {
        "switch:2": "switch to Scizor; switching concedes one free attack",
        "move:2": "Psychic; roughly 3 hits to knock out the target",
        "move:3": "Ice Beam; roughly 4 hits to knock out the target",
        "move:4": "Slack Off; predicted incoming damage exceeds current HP"
      }
    }
  }
}

Jev는 행동 선택 확률 0.72로 switch:2를 선택하고, 하네스는 해당 선택을 수락합니다. 이 값은 나열된 행동을 서로 비교한 결과이며, 플레이어가 배틀에서 승리할 확률이 72퍼센트라는 예측이 아닙니다.

기록된 요청, 답변, 소요 시간 및 출처 정보 전체는 Pokémon 12번째 턴 JSON 기록에서 확인할 수 있습니다.

나만의 하네스 만들기

모든 Jev 지침과 기준을 직접 작성할 필요는 없습니다. 설치된 스킬을 호출하고 작업을 설명한 다음, 코딩 에이전트가 필요한 계약 세부 정보를 수집하도록 하세요.

Claude Code 플러그인 호출

/jev-harness:jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

독립 실행형 Claude Code 호출

/jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

Codex 호출

$jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

스킬은 즉시 파이프라인을 생성하기보다 먼저 작업을 명확히 해야 합니다. 다음 정보를 수집할 것으로 예상하세요.

허용되는 작업 관찰 정보와 숨겨진 상태의 경계.
합법적인 행동과 행동 검증 방식.
대표 예제와 사용 가능한 데이터.
성공 기준, 보상 또는 평가 절차.
런타임 및 격리 요구 사항.
자격 증명과 제공업체 사용 가능 여부.
실험 예산과 최적화 리소스.

계약이 명확해지면 에이전트가 하네스를 구축하고 검증할 수 있습니다. 신뢰할 수 있는 피드백이 있고 최적화를 요청하면, 선택된 결과를 고정하기 전에 궤적과 보상을 사용해 성찰을 수행할 수 있습니다.

Jev 자격 증명 구성

JevHarness는 문서화된 두 가지 Jev 전송 구성을 지원합니다.

Vercel AI Gateway: JevClient(transport="vercel")을 생성하고 AI_GATEWAY_API_KEY를 설정합니다.
TypeSafe 직접 연결: JevClient(transport="typesafe")를 생성하고 TYPESAFE_API_KEY를 설정합니다.

제공업체 어댑터를 사용하더라도 모든 모델이나 엔드포인트를 계정에서 사용할 수 있다고 보장되지는 않습니다. 자격 증명은 환경 변수나 무시되도록 설정한 로컬 .env 파일에 저장하세요. 자격 증명을 작업 관찰 정보, 트레이스 또는 고정된 아티팩트에 절대 넣지 마세요.

하네스 평가 및 개선

성찰은 선택 사항입니다. 신뢰할 수 있는 보상 또는 평가 방법이 있을 때만 사용하세요. 실용적인 워크플로는 다음과 같습니다.

작업 범위를 정의합니다. 숨은 상태, 점수 산정, 합법적 행동 검증, 부작용은 신뢰할 수 있는 어댑터에서 관리합니다.
기준 하니스를 만듭니다. 코드에서 신뢰할 수 있는 특징을 계산하고, 맥락에 민감한 판단은 Jev에 맡깁니다.
파이프라인을 검증합니다. PipelineSpec과 런타임이 작업 계약을 충족하는지 확인합니다.
완전한 트레이스를 수집합니다. 관찰값, 노드 입력과 출력, 질문, 답변, 메모리, 실패, 보상을 보존합니다.
수정을 제안합니다. 작성 LLM이 증거를 검토하고 코드, 프롬프트, 그래프 구조 또는 메모리를 수정하도록 합니다.
공정하게 비교합니다. 동일한 학습 배치에서 상위 항목과 제안 항목을 비교합니다.
채택된 제안을 평가합니다. 전체 Eval 평가를 실행하고, 거부된 제안을 포함해 실제 후보 계보를 보존합니다.
선택한 하니스를 동결합니다. 선정된 사양을 해당 런타임, 평가기, 선언된 작업 리소스에 연결합니다.

학습 증거와 Eval 선택 결과를 명확히 분리합니다. 후보를 선택하는 데 Eval을 사용했다면, 이를 편향되지 않은 미관측 작업 성능 추정치가 아니라 선택 성능으로 보고합니다.

지연 시간과 동시성

보관된 Pokémon Eval 실행에서 선택된 하니스는 전체 결정을 완료하는 데 중앙값 568밀리초가 걸렸습니다. 개별 Jev 요청의 중앙값 소요 시간은 269밀리초였습니다. 초기 하니스의 전체 결정 시간 중앙값은 678밀리초였습니다.

초기 하니스 전체 결정: 중앙값 678ms, P95 1,495ms, 결정 238회.
선택된 하니스 전체 결정: 중앙값 568ms, P95 657ms, 결정 113회.
선택된 하니스의 개별 Jev 요청: 중앙값 269ms, P95 348ms, 요청 226회.

전체 결정 시간에는 특징 계산, 병렬 Jev 호출, 최종 행동 선택이 포함됩니다. 개별 요청 시간에는 클라이언트 및 네트워크 오버헤드가 포함됩니다. 병렬 호출의 실행 시간은 서로 겹치므로 합산해서는 안 됩니다. 전투 시뮬레이션과 작성 또는 성찰 시간은 이러한 결정 측정값에 포함되지 않습니다.

이 보관된 관찰에서는 로컬 응답 캐시 적중을 제외했지만, 런타임의 모든 결정을 LLM이 수행하는 경우와의 통제된 벤치마크는 아니었습니다.

고급 팁

판단을 요청하기 전에 사실을 계산합니다

합법적 행동, 수치 추정치, 임계값, 파생 상태와 같은 사실에는 결정론적 코드나 표현식을 사용합니다. 남은 모호한 선택을 위해 Jev에 집중된 상태와 명시적인 기준을 제공합니다.

행동 기준을 구체적으로 만듭니다

각 사용 가능한 행동을 작업과 관련된 증거로 설명합니다. Pokémon 하니스에서는 남은 체력, 피해 추정치, 속도, 기절에 필요한 턴 수, 교체 시 무료 공격을 허용하는 비용 등이 기준에 포함됩니다.

독립성이 실제로 존재하는 곳에서 병렬 노드를 사용합니다

독립적인 그래프 노드는 동시에 실행할 수 있으며, 여러 질문이 하나의 요청을 공유할 수 있습니다. 작업에 필요하지 않은 종속성을 도입하지 않으면서 이를 활용하도록 그래프를 구성합니다.

확률을 올바르게 해석합니다

선택 확률은 요청에 제공된 선택지의 순위를 나타냅니다. 평가기가 별도로 그 의미를 확립하지 않았다면 이를 전체 작업 성공의 보정된 확률로 재해석하지 마세요.

실패를 완전하게 보존합니다

실패는 잘못된 가정, 누락된 관찰값, 취약한 기준을 드러낼 수 있습니다. 성찰이 전체 증거를 받을 수 있도록 성공적인 결정과 함께 트레이스에 보존합니다.

자동 잘림을 피합니다

현실적인 성찰 바이트 제한을 설정합니다. JevHarness는 성찰 입력이 너무 크면 잘라내는 대신 보관하고 거부합니다. 이는 증거의 무결성을 보호하지만 실험 규모를 적절히 계획해야 함을 의미합니다.

동결된 로직과 동결되지 않은 제공자 동작을 구분합니다

하니스를 동결하면 선택한 파이프라인과 선언된 리소스는 고정되지만, 호스팅 모델 별칭은 시간이 지나면서 변경될 수 있습니다. 정확한 과거 검사가 중요하다면 기록된 응답을 보존하고, 새로 제공자에 호출하는 경우는 다른 재현성 조건으로 취급합니다.

저장소 지도를 활용합니다

auto_jev/에는 사양 검증, 병렬 런타임, Jev 전송, 성찰, GEPA, 저장소, 동결 기능이 들어 있습니다.
examples/pokemon/에는 신뢰할 수 있는 전투 어댑터, 시드가 적용된 로컬 엔진 브리지, 하니스, 프레젠테이션 코드가 들어 있습니다.
examples/pokemon/sample/에는 선택된 하니스와 선별된 웹사이트 아카이브가 들어 있습니다.
docs/에는 작업 작성 자료, 기록된 Jev 호출, 동영상, 스크린샷이 들어 있습니다.
skills/jev-harness/에는 작업별 하니스를 작성하는 코딩 에이전트용 지침이 들어 있습니다.
website/에는 읽기 전용 데모와 배포 어댑터가 들어 있습니다.

결론

JevHarness는 LLM이 개발한 전략을 명시적이고 검토 가능한 런타임 로직으로 바꿉니다. 먼저 엄격한 작업 범위를 정의하고, 스킬을 통해 파이프라인을 구축하고 검증하며, 성찰 기반 개선을 원한다면 완전한 트레이스와 신뢰할 수 있는 보상을 사용합니다. 후보가 선택되면 이를 동결하여 각 행동마다 작성 LLM을 호출하지 않고도 코드와 집중된 Jev 판단을 사용해 일상적인 결정을 수행할 수 있습니다.