Jev 판단층: 설계, 명령, 적용, 실습

Jev는 TypeSafe System One의 판단 모델입니다. 글을 쓰지 않고, 주어진 상태(state)와 질문(questions)에 대해 Choice(여러 선택지의 확률), Noul(예/아니오 확률), Score(척도 값) 세 형태의 판단만 돌려줍니다. 가격은 입력 100만 tokens당 $0.042입니다.

이 페이지는 그 판단층의 구조, 로컬 명령 세 개(retrieve, classify, project), 볼트 명령에 실제로 반영한 것, 그리고 누구나 따라 해 볼 수 있는 실습 키트를 정리합니다. 실행 코드 저장소는 비공개이고, 여기서는 명령의 입출력 규약과 설계를 설명합니다.

1. Architecture아키텍처: 명령 뒤의 판단층

1.1 네 층의 분업

Jev에게 묻는 것은 코드로 결정론적으로 계산할 수 없고, 답이 문장이 아니라 선택이며, 한 질문에 한 판단으로 끝나는 것뿐입니다. 되돌릴 수 없는 행동은 사람이 하고, 보내면 안 되는 자료는 코드의 경로와 패턴 규칙이 막습니다. Jev에게 "이것이 비밀인가"를 묻지 않습니다.

1.2 PROPOSE 원칙

• 볼트에는 한 글자도 쓰지 않습니다. 분류값 기입, 파일 이동, 검색 결과 채택은 사람과 기존 명령의 일입니다.
• 확신도(confidence)로 자동 승인하지 않습니다. 87개 분류에서 confidence 0.7 이상 구간이 r3에서 16/33만 맞았습니다.
• 실패하면 열어 둡니다(fail-open). 키가 없거나 Jev가 오류를 내면 제안 없이 원래 절차가 그대로 진행됩니다. 검색은 이때도 로컬 후보 목록을 돌려줍니다.
• 결정은 Jev의 응답 문구가 아니라 코드가 확률값으로 내립니다. 두 순서의 1위가 다르거나, 1위와 2위가 같거나, 1위가 "보류"나 "해당 없음"이면 보류입니다.

1.3 판단이 흐르는 길

/query에 한국어 질문이 들어오면 판단은 다섯 단계를 거칩니다. 점선 안이 판단층입니다.

/connect와 /query의 답변 저장 단계에서는 저장 전 초안을 classify에 넘겨 분류 후보 세 개를 옆에 보여 줍니다. 최종 분류값은 사람이 고릅니다.

같은 거버넌스를 2026-09-24에 만든 shadow 모듈 네 개도 씁니다: /connect 경로 제안, 요청 난이도 티어 제안, 문서와 주장의 관계 판정, 해시 기반 변경 감지 게이트입니다.

1.4 영수증

호출 하나가 영수증 한 행입니다. 각 행에는 다음이 남습니다.

• 요청: 실제로 보낸 요청 본문 전체(state와 questions)
• 모델과 상태: 요청 모델과 응답 모델, HTTP 상태, 시도 기록과 재시도 수
• 비용과 시간: 입력과 출력 tokens, 지연 시간, 보내기 전 추정 tokens
• 판단: 응답 확률 분포와 그 순서에서 코드가 내린 결정
• 해시 네 개: payload_sha256, state_sha256, options_revision(선택지 이름 목록), candidate_set_revision(선택지 이름, 설명, 제시 순서)

payload_sha256는 키를 정렬해 계산하므로 정순과 역순에서 같은 값이 나옵니다. 제시 순서의 차이는 candidate_set_revision이 담습니다. 이 값이 바뀌면 그 후보 집합에서 고른 이전 컷은 무효입니다.

판단 영수증 뷰어는 이 기록을 한 항목씩 펼칩니다. 두 순서의 확률 막대와 컷 위치, 제안과 보류를 만든 규칙, 보낸 필드별 글자 수와 한도, 브라우저 안에서 다시 계산한 해시 일치 여부, 호출 기록을 보여 주고, 사람 검토(수락, 수정, 보류 유지)를 JSON으로 내보냅니다. 연 파일은 브라우저 밖으로 나가지 않습니다.

1.5 shadow 로그와 human_final

명령을 한 번 실행하면 로그에 한 줄이 쌓입니다.

{"schema": "jev-cmds-shadow/1",
 "cmd": "retrieve",
 "run_id": "…", "ts": "…",
 "dry_run": false,
 "writes_vault": false,
 "input": {…}, "result": {…},
 "calls": [영수증 행, …],
 "human_final": null,
 "human_note": null,
 "human_reviewed_at": null}

• writes_vault는 항상 false입니다.
• human_final은 사람이 실제로 고른 값을 적는 칸입니다. 처음에는 비어 있고, 채워지는 순간 그 줄이 사람 골드가 됩니다. 앞으로의 정확도는 이 칸으로 잽니다.
• 로그와 월별 예산 상태 파일은 볼트와 검색 색인 밖에만 둡니다. 로그 위치가 볼트나 색인 컬렉션 안이면 명령이 거부합니다. 로그가 색인 안에 있으면 다음 검색이 Jev의 과거 답을 근거처럼 다시 끌어오기 때문입니다.

1.6 거버넌스

1.7 설계에서 얻은 교훈

• 개인정보 필터는 표본을 뽑기 전과 보내기 직전, 두 번 겁니다. 제목과 설명만 보는 필터로는 부족합니다. 설명이 없는 노트는 본문 머리가 요약으로 나가기 때문입니다. 그래서 본문 앞 1,500자까지 보고, 조립이 끝난 payload 전체에 다시 겁니다. 생성 모델로 질문을 만드는 호출도 같은 필터를 거칩니다.
• 정규식 규칙은 과잉 차단과 누락이 모두 있습니다. 평범한 동사 속 두 음절이 가족 호칭 키워드와 겹쳐 질문 하나가 빠졌고, 거버넌스를 설명하느라 "비밀번호"를 언급한 노트도 막혔습니다. 저는 보수적인 쪽을 택했습니다.
• dry-run 추정은 실측보다 1.7~2.7배 컸습니다(2026-09-26 통합 스모크 14회). 예산 판단에는 안전한 쪽이라 그대로 둡니다.

2. CLICLI 명령 3개: retrieve, classify, project

세 명령은 노트를 읽기만 하고, 제안 JSON과 shadow 로그 한 줄만 남깁니다. 키는 환경 변수로만 받고 로그에 남기지 않습니다.

export TYPESAFE_API_KEY="YOUR_KEY"
python3 -m jev_cmds retrieve \
  --query "배운 걸 점점 긴 간격을 두고 다시 떠올리는 공부법을 정리한 노트가 어디 있지?" --json
python3 -m jev_cmds classify --file "<노트.md>" --top 3
python3 -m jev_cmds project  --file "<노트.md>"

명령 형태입니다. 실행 코드 저장소는 비공개입니다.

2026-09-26 13:07~13:12 KST 통합 스모크에서 세 명령을 실제로 14회 호출했습니다. 입력 47,658 tokens, $0.0020, 전부 HTTP 200, 요청과 응답 모델 일치, 재시도 0, 호출당 지연 228~339ms였고, 그동안 볼트에서 바뀐 파일은 0건이었습니다. 단위 테스트는 가짜 전송층과 가짜 검색 색인으로 90개를 돌리며, 뷰어의 판정 코드도 node에서 함께 검사합니다.

2.1 공통 옵션과 종료 코드

2.2 retrieve: 검색 후보 재선택과 유지 집합

음절 구문 BM25. qmd의 전문 검색 색인은 한글을 음절마다 띄어 저장합니다. "기록"으로 찾으면 0건, "기 록"으로 찾으면 2,726건입니다(2026-09-26 07:30 재확인). 그래서 한국어 단어를 인접 음절 구문으로 바꿔 보냅니다. 색인을 고치지 않는 우회입니다. r2 최종 표본에서 후보에 표적이 든 비율이 46/55에서 50/55로, 목록 1위 적중이 21/55에서 30/55로 올랐습니다.

측정 결과. 한국어 질문, 기존 노트 하나를 정답으로 둔 재현입니다.

• 끝단 정확도의 분해. 끝단 정확도는 후보 재현율 × Jev 조건부 선택으로 정확히 나뉩니다. r3는 45/49 × 44/45 = 44/49입니다. 네 표본 모두 조건부 선택이 90% 이상이라, 남은 손실은 대부분 후보를 만드는 층에 있습니다.
• 유지 집합(절단 0.3, r3 등록 전 고정): 표적 44/45 97.8% [88.4, 99.6]를 후보 평균 17.55개 중 2.39개 안에 남겼습니다(86.4% 축소). 같은 표본에서 절단 0.5는 39/45, 크기를 맞춘 검색 상위 3개는 25/45였습니다. 떨어진 1건은 Noul이 정확히 0.30이었습니다.
• 두 순서 합의 규칙(r3): 49개 중 46개에 답했고 그중 43개가 맞았습니다(93.5%). 순서를 뒤집어 답이 바뀐 것은 3/49입니다.
• 호출과 비용: C1(정순) + C1R(역순) + C2(유지 집합) = 3회. r3 실측 입력은 호출당 C1 1,716 tokens, C2 2,108 tokens로, 질문 하나에 약 5,540 tokens, 약 $0.00023입니다.

2.3 classify: CMDS 87 서브카테고리 top-3 제안

• 보내는 것. 제목, 설명, 태그, 본문 머리(가림 처리 뒤)와 87개 분류 이름 + 각 정의 + "보류", 그리고 "형식이 분명하면 주제보다 형식 분류를 먼저 고려하라"는 지시 한 문장입니다. 경로, type, 기존 분류값은 보내지 않습니다.
• 정의 파일. 등록한 정의 버전을 보내고, 불러올 때마다 해시로 무결성을 확인합니다. 87개 중 73개는 각 카테고리 노트의 설명이고, 14개는 제가 아직 최종 확인하지 않은 초안입니다. 제안이 초안 정의 클래스면 draft_definition: true를 붙입니다.
• 측정 결과. 이름만 준 조건은 r2 최종 24/120 20.0% [13.8, 28.0], 이름 + 정의 + 형식 우선 지시는 91/120 75.8% [67.5, 82.6]였습니다. 같은 요청을 한 번도 쓰지 않은 폴더 세 곳에 보낸 r3는 28/65 43.1% [31.8, 55.2]였습니다. top-3 적중은 r2 112/120, r3 42/65입니다. 주제와 도구 분류는 두 라운드 모두 40% 안팎(r2 7/18, r3 28/65)이었고, 생성형 AI 분류는 r2 0/3, r3 0/8이었습니다.
• 규칙표를 기본값으로 두지 않은 이유. Jev를 부르지 않는 frontmatter type → 분류 규칙표는 r2에서 101/120으로 모든 Jev 조건 이상이었지만, 새 폴더에서는 적용된 27건 중 1건만 맞혔습니다. 규칙 우선 조합은 r3 20/65로 Jev 단독 28/65보다 낮았습니다.
• 결정. 정순 top-3를 항상 제안으로 보여 주고 역순으로 한 번 더 묻습니다. 두 순서 1위가 다르거나 동률이거나 "보류"가 1위면 decision: 보류입니다. r3에서 이 규칙은 65건 중 10건을 보류로 돌렸고, 답한 55건 중 27건이 맞았습니다(규칙 없이 64건 중 28건). 자동 오답이 8건 줄고 사람 대기가 9건 늘어나는 교환입니다.
• 비용. 2회 호출, r3 실측 호출당 5,761 tokens로 약 11,500 tokens, 약 $0.00048입니다.

2.4 project: 활성 프로젝트 라우팅

• 선택지는 호출할 때 읽습니다. 허용 목록의 프로젝트 중 폴더가 실제로 있는 것만 선택지가 되고, 각 README 설명(200자 이내, 가림 처리, 개인정보 규칙 통과)이 판단 기준이 됩니다. README가 없거나 설명이 규칙에 걸리면 이름만 보내고 readme: false와 사유를 표시합니다. 민감 범주의 프로젝트 12개는 제외 목록에 있어 선택지도 되지 않고, 그 폴더의 노트도 보내지 않습니다.
• 측정 결과(r2 최종, 뚜렷이 다른 프로젝트 6개, n = 80): 이름만 69/80 86.3% [77.0, 92.2], 이름 + README 설명 78/80 97.5% [91.3, 99.3]. 호출당 입력이 1,239에서 1,573 tokens로 334 늘었습니다. 순서에 따라 답이 바뀐 것은 1/80입니다.
• 측정 범위. 허용 목록 12개 중 측정한 것은 6개입니다. 비슷한 프로젝트끼리의 혼동, 어느 프로젝트에도 속하지 않는 노트의 보류, README 설명 길이 차이의 영향은 재지 않았습니다.
• 비용. 2회 호출, 약 3,150 tokens, 약 $0.00013입니다.

2.5 출력 필드(--json)

2.6 영수증 예시(합성 데이터)

아래는 retrieve 한 번의 shadow 로그 한 줄을 줄인 것입니다. 질문, 노트 제목, 설명, 확률, tokens, 지연은 모두 설명을 위해 지어낸 값이고, 요청 본문과 해시는 실제 명령과 같은 코드로 만들었습니다.

{
 "schema": "jev-cmds-shadow/1",
 "cmd": "retrieve",
 "run_id": "sample-retrieve-1",
 "dry_run": false,
 "writes_vault": false,
 "input": {"query": "배운 걸 점점 긴 간격을 두고 다시 떠올리는 공부법을 정리한 노트가 어디 있지?",
           "collections": ["wiki"], "k": 10, "keep_cut": 0.3, "reverse": true},
 "result": {
  "choice": {"top_label": "간격 반복 (Spaced Repetition)", "decision": "제안",
             "rule": "both orders agree on a non-abstain argmax (no tie)"},
  "keep": [{"title": "간격 반복 (Spaced Repetition)", "p": 0.88},
           {"title": "인출 연습 (Retrieval Practice)", "p": 0.41}],
  "keep_rule": "keep iff noul > 0.3 (strict; equal = not kept)",
  "pool": {"n_candidates": 8,
           "fts_query": "\"배 운\" OR \"점 점\" OR \"간 격\" OR \"두 고\" OR \"다 시\" OR \"떠 올 리\" OR \"공 부 법\" OR \"정 리 한\" OR \"노 트\" OR \"어 디\" OR \"있 지\""},
  "model": "jev-1.13.0", "input_tokens": 1258, "latency_ms": 1551
 },
 "calls": [
  {"cond": "C1", "order": "normal", "model_requested": "jev-1.13.0", "model_actual": "jev-1.13.0", "http": 200,
   "input_tokens": 342, "latency_ms": 512, "retries": 0,
   "payload_sha256": "ed7e3c30236c7629fadc0d1bf476aafdf1771ae79baf34f92cacdbc0f2512110",
   "candidate_set_revision": "ba29e052325fb1cc3aaa0de10db982bfe34beb01aac1971f4167a21af406ad9c",
   "response": {"probabilities (상위 3)": {"간격 반복 (Spaced Repetition)": 0.78, "분산 학습": 0.09, "인출 연습 (Retrieval Practice)": 0.06}},
   "decision": "간격 반복 (Spaced Repetition)"},
  {"cond": "C1R", "order": "reversed", "model_requested": "jev-1.13.0", "model_actual": "jev-1.13.0", "http": 200,
   "input_tokens": 342, "latency_ms": 498, "retries": 0,
   "payload_sha256": "ed7e3c30236c7629fadc0d1bf476aafdf1771ae79baf34f92cacdbc0f2512110",
   "candidate_set_revision": "afb08e84ef647db52d2d4c630d30724a4d1a599fe855edbf50e05e69c9fd1acf",
   "response": {"probabilities (상위 3)": {"간격 반복 (Spaced Repetition)": 0.71, "분산 학습": 0.12, "인출 연습 (Retrieval Practice)": 0.09}},
   "decision": "간격 반복 (Spaced Repetition)"},
  {"cond": "C2", "order": "normal", "model_requested": "jev-1.13.0", "model_actual": "jev-1.13.0", "http": 200,
   "input_tokens": 574, "latency_ms": 541, "retries": 0,
   "payload_sha256": "739e237edd80b8760cc32d442ad090e1f3b8aa275fb1ea7897135494af20018b",
   "noul_cut": 0.3,
   "response": {"nouls (상위 3)": {"간격 반복 (Spaced Repetition)": 0.88, "인출 연습 (Retrieval Practice)": 0.41, "분산 학습": 0.27}},
   "decision": "noul_set"}
 ],
 "human_final": null, "human_note": null, "human_reviewed_at": null
}

읽는 법:

• 정순과 역순 모두 같은 노트가 1위라 제안입니다. 정순과 역순의 payload_sha256가 같고 candidate_set_revision만 다른 것은 1.4에서 설명한 대로 제시 순서만 바뀌었기 때문입니다.
• 유지 집합에는 0.3을 넘은 두 개가 남았습니다. 0.27인 "분산 학습"은 빠졌습니다.
• human_final은 비어 있습니다. 사람이 뷰어에서 수락하거나 고치면 그 값이 골드가 됩니다.

전체 샘플은 뷰어에서 "샘플 영수증 열기"를 누르면 바로 열리고, 원본은 /viewer/sample-receipt.json입니다. 세 건이 들어 있습니다.

1. 두 순서가 합의한 제안. 위 예시입니다.
2. 순서 불일치 보류. 노트 제목 짓기 질문: 정순 1위는 "노트 이름 짓기 규칙" 0.47, 역순 1위는 "제목은 주장으로 짓는다" 0.52로 갈려 보류됩니다. 유지 집합은 두 노트를 남겨, 보류여도 읽을 목록은 좁혀 줍니다.
3. 전송 전 차단. 실습 키트 S4의 회의 정리 질문: 회의 관련 후보 두 개는 후보를 만드는 단계에서 이미 빠지고, 질문 자체가 "대화와 회의 파생" 규칙에 걸려 첫 호출부터 보내지 않습니다. 결정은 보류, 사유는 전송 전 차단입니다.

3. Service서비스 적용: 2026-09-26에 바뀐 것

세 라운드 결과를 같은 날 볼트 명령에 옮겼습니다. 바뀐 곳은 모두 shadow 단계라 제안만 보이고, 키가 없거나 Jev가 실패하면 원래 절차로 돌아갑니다.

같은 변경을 세 실행 환경(Claude Code, Codex 단일 에이전트, Codex 멀티 에이전트)의 명령 파일에 함께 넣었습니다. 멀티 에이전트 환경에서는 작업자가 Jev 제안을 돌려주기만 하고, 사용자에게 보이고 결정하는 일은 조정자가 합니다.

3.1 /query

• 한국어 키워드 검색 규칙. 한국어 질문을 키워드 검색에 넣을 때는 조사와 어미를 뺀 내용어만 넣고, 질문 문장은 의미 검색과 가상 답변 검색에 둡니다. 질문 문장을 키워드 검색에 그대로 넣으면 음절 저장 방식 때문에 거의 맞지 않습니다.
• Jev 재선택 단계. 한국어 자연어 질문이고 검색 후보가 3개 이상일 때만 retrieve를 부릅니다. 질문에 건강, 가족, 제3자 이름, 회의 내용이 있으면 부르지 않습니다. 컬렉션은 측정한 3개만 씁니다.
• 읽는 순서. 답변을 쓰는 단계는 Jev가 고른 노트와 유지 집합을 먼저 읽되, 원래 검색 결과를 버리지 않습니다.
• 답변 저장 단계. 답을 볼트에 남길 때는 저장 전 초안에 classify --title을 불러 분류 후보 세 개를 옆에 보여 줍니다.

3.2 /connect

• 새 스텁을 만들 때만, 저장 전 초안에 classify를 불러 top-3를 보여 줍니다. 기존 노트를 갱신하는 경우와 전용 스킬로 넘기는 유형은 건너뜁니다.
• top-3의 앞자리에 관심사, 주제, 변수, 용어 밖의 분류가 오면 볼트 구조 라우팅 대상이라는 신호로만 읽습니다.
• 규칙 우선 기본값은 두지 않았습니다. type 규칙표가 새 폴더에서 적용된 27건 중 1건만 맞혔기 때문입니다.
• 실행 보고에 제안과 사람 선택의 일치, 불일치, 보류 수를 한 줄로 남깁니다.

3.3 지렛대는 카테고리 정의였다

87분류 재현을 20.0%에서 75.8%로 올린 것은 모델 설정이 아니라 선택지 설명이었습니다(r2 최종, n = 120). 이득은 대부분 설명이 비어 있던 클래스에서 났습니다.

이름만 주면 지식관리를 다룬 뉴스레터 원고가 "지식관리" 주제 분류로 끌려가지만, "주제가 무엇이든 발행 형식의 원고면 여기"라고 적어 주면 형식 분류로 돌아옵니다.

그래서 볼트의 카테고리 노트 중 설명(description)이 비어 있던 14개를 채웠고, 이제 87개 모두 설명이 있습니다. 802와 104에는 "주제가 아니라 형식으로 분류한다"는 문장을 넣었습니다. 14개 문구는 제가 최종 확인하기 전인 초안입니다.

3.4 사람에게 남긴 것

하지 않는 것: 분류값 자동 기입, 이동, 삭제, 발행, 확신도로 자동 승인, Jev 결과로 출처 제외.

3.5 만들지 않은 것

• 메인 볼트 대 위키 볼트 라우팅. r1 두 표본 80.0%(32/40), 75.0%(30/40)에서 r2 최종 51/80 63.8% [52.8, 73.4]로 내려갔고, 오류는 두 방향으로 같은 크기(11건, 11건, 보류 7건)였습니다. 순서에 따라 답이 갈린 7건을 첫 사람 골드 대기열로 둡니다.
• type 규칙표 캐스케이드. 2.3의 이유입니다.
• 모든 자동 적용.

시스템 파일(CLAUDE.md 등)은 바꾸지 않았습니다. Jev 단계는 두 명령 안의 선택 단계라서, 사람 골드가 쌓인 뒤 다시 판단합니다.

4. Practice실습 키트: 입력 3종 + 검색 3종

2026-09-24 AI & Beyond 발표의 후속 자료로 만든 요청 파일 6개입니다. 노트를 어디에 넣을지(입력 라우팅)와 검색 후보 중 무엇을 고르고 남길지(검색)를 Jev에 직접 묻습니다. 모든 문장, 노트 제목, 프로젝트 이름은 이 키트를 위해 새로 쓴 가상 데이터라 실제 노트 원문이나 사람 이름이 없습니다.

시나리오별 설명, 웹 Playground와 curl로 해 보는 법, 내 노트로 바꿔 쓸 때의 주의는 실습 페이지에 있습니다. 공개 전에 요청 파일 6개를 실행해 보지는 않았으므로 응답값은 직접 확인해 주세요.

5. Limits주장하지 않는 것

• 사람 판단 대비 정확도. 모든 수치는 볼트에 이미 있던 분류와 위치의 재현이고, 불일치 일부는 볼트 쪽이 틀렸을 수 있습니다.
• 검토 시간 절감, 일반적인 추천 품질 향상. 재지 않았습니다.
• 개인 볼트 검색 성능. r3 검색 표적은 모두 위키 페이지였습니다.
• "찾는 노트가 없다"를 알려 준다는 것. 표적 부재 때 "해당 없음" 1위는 r2 0/5, r3 0/4였습니다.
• 실제 사용자 질문에서의 성능. 질문은 다른 생성 모델이 노트 설명을 보고 만든 것입니다.
• 결정성. 한 모델 버전, 하루, 조건마다 한 번 실행이었습니다.
• 0.3 절단이 다른 과제에도 맞는다는 것. 컷은 과제마다 따로 고릅니다.
• 87분류 자동 확정. 새 폴더에서 43.1%(28/65)였습니다.

측정 방법과 결과 전체는 실측 결과와 원본 학습 페이지에 있습니다.