Jev를 코딩 에이전트에 연결해 구조화된 판단을 맡긴다

Claude Code, Codex, Cursor 같은 코딩 에이전트에서 Jev를 쓰려면 TypeSafe의 에이전트 스킬을 설치한 뒤, Jev를 호출하는 코드를 작성하도록 에이전트에 요청하면 된다. 에이전트의 기본 모델은 그대로 유지되며, Jev는 에이전트가 만드는 앱 안에서 사용된다.

Jev는 TypeSafe의 의사결정 모델이다. 텍스트와 몇 가지 유형이 지정된 질문을 보내면 예·아니요 확률, 직접 정한 목록에서 고른 항목, 설명한 척도상의 위치를 각각 확률과 함께 반환한다. 텍스트를 생성하지는 않는다. 처음 접한다면 Jev 심층 소개부터 읽어볼 수 있다.

에이전트별로 TypeSafe 스킬을 추가하는 방법은 다음과 같다.

그런 다음 에이전트에 문서를 마크다운으로 제공하고, 계획을 세우는 프롬프트부터 요청한다. 에이전트가 작성한 내용은 아래 체크리스트에 따라 검토한다.

Jev가 코딩 에이전트의 모델을 대체할 수 있나?

아니다. model: "jev-latest" 같은 설정으로 Claude Code나 Cursor를 Jev 기반 에이전트로 바꾸는 기능은 없다.

코딩 에이전트에는 텍스트를 쓰고 도구를 호출하며 파일을 편집하는 모델이 필요하지만, Jev는 그런 작업을 하지 않는다. TypeSafe는 코딩 에이전트와 Jev 사용법에서 LLM 기반 에이전트는 그대로 두고, 제품에서 빠르고 구조화된 판단이 필요한 부분을 Jev로 호출하는 코드를 작성하도록 에이전트에 요청하라고 안내한다.

코딩 에이전트가 Jev를 잘못 사용하는 이유

코딩 에이전트는 LLM API를 호출하는 코드 사례를 오랫동안 학습했기 때문에, 그때의 습관을 Jev에도 적용한다.

첫 번째 문제는 호출마다 질문을 하나씩 보내는 것이다. LLM을 쓸 때는 질문을 하고 답을 읽은 뒤 다음 질문을 정하는 방식이 흔하다. Jev는 같은 상태를 대상으로 모든 질문을 병렬로 처리하므로, 서로 독립적인 질문을 한 요청에 모아 보내고 필요한 답을 코드에서 선택해야 한다. TypeSafe는 이를 추측적 팬아웃(speculative fan-out)이라고 부른다.

에이전트는 요청 필드를 지어내기도 한다. Jev 요청의 최상위 필드는 model, state, questions 세 가지다. LLM을 다루던 습관으로 작성한 코드에는 messages, temperature, max_tokens 같은 필드가 더해지곤 한다. TypeSafe의 에이전트 스킬 페이지는 요청과 응답 필드를 임의로 추가하는 일을 알려진 문제로 설명한다. 보통 오래된 스킬 사본을 사용했을 때 생긴다.

요약, 답변, 추출값처럼 Jev에 무언가를 작성해 달라고 하는 문제도 있다. Jev는 제공된 선택지 중 하나를 고를 뿐이다. 텍스트에서 값을 추출하려면 코드가 정규식 같은 방법으로 후보를 찾고 Jev가 그중 하나를 선택하게 해야 한다.

질문에 수학이나 날짜 계산을 넣는 경우도 있다. “청구서가 30일 넘게 연체됐나?”는 판단처럼 보이지만 실제로는 산술 계산이다. TypeSafe의 jaggedness 페이지에 따르면 Jev는 수를 안정적으로 세지 못하고 날짜를 텍스트로 읽으므로, 이런 작업은 코드가 맡아야 한다. 이 습관에 관해서는 LLM에게 계산을 맡기지 말아야 하는 이유에서도 다룬다.

TypeSafe는 에이전트가 질문을 잘 작성하지 못하는 경우도 있다고 설명한다. 질문은 에이전트와 함께 수정할 필요가 있다.

Claude Code에 TypeSafe 스킬 설치하기

Claude Code에서는 플러그인으로 스킬을 설치한다. 터미널에서 다음 명령을 실행한다.

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

첫 번째 명령은 TypeSafe의 GitHub 저장소를 플러그인 마켓플레이스로 등록하고, 두 번째 명령은 그곳에서 typesafe 플러그인을 설치한다. 플러그인은 사용자 계정에 설치되므로 모든 프로젝트에서 사용할 수 있다. 팀 저장소에 설치 정보를 기록하려면 설치 명령에 --scope project를 추가한다.

Claude Code는 작업이 관련 있어 보일 때 스킬을 불러온다. 직접 불러오려면 /typesafe:typesafe-ai를 실행하거나 프롬프트에 “use the TypeSafe skill”이라고 쓴다.

나중에 스킬을 업데이트하려면 다음 명령을 실행한다.

claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai

새 버전을 불러오려면 Claude Code를 다시 시작하거나 /reload-plugins를 실행한다. /plugin의 Marketplaces 메뉴에서 자동 업데이트를 켤 수도 있다.

Codex, Cursor 및 기타 에이전트에 설치하기

나머지 에이전트에는 Vercel Labs의 skills CLI를 사용한다.

npx skills add typesafe-ai/skills --skill typesafe-ai

이 명령은 저장소를 복제한 뒤 설치할 에이전트를 선택하도록 한다. -a로 에이전트를 지정하면 선택 화면을 건너뛸 수 있고, -y를 추가하면 확인 단계도 생략한다.

npx skills add typesafe-ai/skills --skill typesafe-ai -a codex -a cursor -y

기본 설정에서는 현재 프로젝트에 설치한다. 2026년 9월 기준으로 프로젝트에 설치하면 다음 항목이 생긴다.

• 스킬은 .agents/skills/typesafe-ai/에 저장되며 Codex와 Cursor가 이 경로를 읽는다.
• Claude Code도 선택했다면 .claude/skills/typesafe-ai에 심볼릭 링크가 생긴다.
• 스킬의 출처를 기록하는 skills-lock.json 파일이 프로젝트 루트에 생성된다.

이 파일들을 커밋하면 저장소를 복제한 팀원도 스킬을 사용할 수 있다.

사용자 계정에 설치하려면 -g를 추가한다. 스킬 사본은 ~/.agents/skills/typesafe-ai/에 저장되며 Codex와 Cursor가 모든 프로젝트에서 읽는다. Claude Code용으로는 ~/.claude/skills/에 심볼릭 링크가 생긴다.

에이전트마다 설치 방법은 하나만 사용한다. Claude Code 플러그인을 설치했다면 선택 화면에서 Claude Code도 고르지 않는다. 같은 스킬 사본이 두 개 생길 수 있다.

Codex에서는 프롬프트에 $typesafe-ai를 넣어 스킬을 지정할 수 있다. Codex 가이드에서 스킬을 더 설명한다. Cursor에서는 Agent 채팅에서 /를 입력한 뒤 typesafe-ai를 선택한다. fx도 .agents/skills/를 확인하므로 프로젝트에 설치하면 함께 사용할 수 있다.

OpenCode도 프로젝트와 홈 폴더의 .agents/skills/를 읽으므로 같은 설치 방법을 쓸 수 있다. OpenCode에만 설치하려면 에이전트 이름인 opencode를 지정한다.

npx skills add typesafe-ai/skills --skill typesafe-ai -a opencode -y

OpenCode는 설치된 스킬 목록을 모델에 보여주며, 작업과 관련 있을 때 모델이 skill 도구로 스킬을 불러온다. 확실히 사용하게 하려면 프롬프트에 “use the TypeSafe skill”이라고 쓴다.

업데이트하려면 npx skills update를 실행한다.

CLI는 스킬이 에이전트의 권한으로 실행된다고 알린다. TypeSafe 스킬은 스크립트가 없는 짧은 마크다운 파일 하나로 구성되어 있어, 설치 전에 읽는 데 몇 분이면 된다.

프롬프트를 붙여넣는 방법

가능하다. 에이전트 스킬 페이지의 ‘에이전트에 복사’ 프롬프트는 에이전트가 직접 스킬을 설치하도록 요청한다.

Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.

TypeSafe 콘솔 홈에도 에이전트 설정용 프롬프트가 있다. GitHub 저장소의 skills/typesafe-ai 폴더를 에이전트의 스킬 디렉터리에 직접 복사할 수도 있다.

TypeSafe SKILL.md의 내용

스킬은 짧은 파일 하나로 되어 있다. Jev를 이해하는 방법을 에이전트에 알려주고 세부 사항은 최신 문서에서 확인하게 한다. GitHub에서 파일을 읽을 수 있다.

파일은 공식 문서를 기준으로 삼으라고 안내한다. 에이전트는 llms.txt 색인부터 확인하고, 페이지를 마크다운으로 가져오며, 통합 코드를 작성하기 전에 현재 API 또는 SDK 페이지를 읽어야 한다. 작업과 문서 페이지를 연결하는 표도 제공한다. 문서에 접속할 수 없다면 그 사실을 밝히고 세부 사항을 지어내지 말고 설치된 SDK의 타입을 사용하라고 안내한다.

Jev를 어디에 적용할지는 앱이 무엇을 표시하거나 다음 단계로 넘겨야 하는지부터 살펴본 뒤, 필요한 판단을 거꾸로 찾는다. 이미 정해진 규칙, 계산, 정확한 조회, 실행은 코드가 담당한다. 스킬은 요청 분류와 인수 채우기, 생성 대신 값 선택, 주장 확인, 사람에게 넘기기 등 시작점으로 삼을 패턴을 소개한다.

질문 작성 부분에서는 어떤 기본 유형을 쓸지, 상태의 일부를 가리키는 ticket.messages[0].text 같은 백틱 경로, 질문 하나에 좁은 판단 하나만 담는 방식, 어떤 선택지도 맞지 않을 때의 선택지를 설명한다.

마지막 부분은 질문 조합을 다룬다. 같은 상태를 대상으로 하는 독립된 질문은 함께 보내고, 앞선 답에 따라 다음에 가져오거나 물어볼 내용이 달라질 때만 두 번째 요청을 한다. 신뢰도는 확률이 얼마나 분산됐는지를 나타내며, 안전하게 행동해도 되는지를 뜻하지 않는다. Noul 값이 0.5에 가까우면 ‘중간’이 아니라 ‘판단할 수 없음’이다. 실제 사례로 시험하고 API 키는 서버에 보관해야 한다.

스킬에는 정확한 요청 스키마, SDK 메서드 이름, 모델 ID가 들어 있지 않다. 에이전트가 문서에서 이를 확인해야 하므로, 다음 단계가 중요하다.

에이전트에 TypeSafe 문서 제공하기

문서는 Mintlify에서 제공되며 모든 페이지를 마크다운으로도 볼 수 있다. URL 끝에 .md를 붙이면 된다.

curl -sL https://docs.typesafe.ai/confidence.md

모든 페이지의 색인은 https://docs.typesafe.ai/llms.txt에 있다. 사이트 전체를 한 파일로 모은 llms-full.txt도 있지만 용량이 약 900KB로 프롬프트에 넣기에는 너무 크므로, 에이전트에는 색인을 알려주는 편이 낫다.

에이전트가 MCP를 지원한다면 문서 사이트를 원격 MCP 서버로 연결할 수도 있다. 2026년 9월 확인 기준으로 서버 주소는 https://docs.typesafe.ai/mcp다. 검색 도구와 문서 페이지를 나열하고 읽는 읽기 전용 도구를 제공하므로, 에이전트가 사이트를 긁어오지 않고도 문서를 찾을 수 있다.

Claude Code에서는 다음을 실행한다.

claude mcp add --transport http typesafe-docs https://docs.typesafe.ai/mcp

Codex에서는 다음을 실행한다.

codex mcp add typesafe-docs --url https://docs.typesafe.ai/mcp

Cursor에서는 프로젝트의 .cursor/mcp.json에 다음 내용을 추가한다.

{
 "mcpServers": {
 "typesafe-docs": {
 "url": "https://docs.typesafe.ai/mcp"
 }
 }
}

OpenCode에서는 프로젝트의 opencode.json에 원격 서버로 다음 내용을 추가한다.

{
 "mcp": {
 "typesafe-docs": {
 "type": "remote",
 "url": "https://docs.typesafe.ai/mcp"
 }
 }
}

SDK를 설치한 뒤에는 node_modules/@typesafe-ai/sdk의 타입 정의가 해당 버전에서 사용할 수 있는 옵션과 필드 이름의 최종 기준이다.

에이전트에 처음 요청할 내용

코드 작성보다 계획부터 요청한다. TypeSafe가 제안하는 브레인스토밍 프롬프트는 다음과 같으며, 기존 프로젝트를 살펴볼 때 사용할 수 있다.

Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.

취약한 코드는 계속 깨지는 정규식이나 LLM에 JSON을 요청하는 프롬프트 등을 말한다. 에이전트가 제안한 목록을 검토한 뒤에야 코드 변경을 맡긴다.

새 프로젝트라면 빠른 시작 문서에 다음 프롬프트가 있다.

Let's build a simple CLI that uses the TypeSafe API to evaluate a set of supplied documents on multiple dimensions. Use the TypeSafe skill to understand how to use the TypeSafe API and how to structure the system. Ask me questions about what kinds of documents I want to evaluate and on what dimensions.

마지막 문장은 에이전트가 평가할 문서와 기준을 추측하지 않고 사용자에게 묻게 한다.

콘솔에서 API 키를 발급받았다면, 에이전트 스킬 페이지는 TYPESAFE_API_KEY로 키를 내보내고 변경안을 제안하기 전에 비용이 적은 테스트 요청을 실행하도록 권한다. Jev 이용 권한과 API 키를 받는 방법도 참고할 수 있다. 2026년 9월 말 기준으로 TypeSafe는 수요 때문에 신규 가입을 중단했으므로, 이 단계에는 기존 계정이 필요하다.

에이전트가 작성한 Jev 코드 검토하기

TypeSafe는 질문과 임계값을 한 파일에 모으라고 권한다. 사람이 검토해야 하는 내용이기 때문이다. 다음은 지원 티켓을 다루는 예시로, src/jev/questions.ts에 저장한다. SDK 호출을 검토하려면 Node.js에서 Jev 사용하기를 참고할 수 있다.

import { choice, noul, score } from '@typesafe-ai/sdk'

export const TICKET_QUESTIONS = {
 category: choice('What kind of request is `ticket.message`?', {
 billing: 'Charges, invoices, refunds, subscriptions',
 bug_report: 'Something is broken or shows an error',
 feature_request: 'Asks for something the product does not do yet',
 other: 'None of the above',
 }),
 refund_requested: noul('Does `ticket.message` ask for money back?'),
 bug_severity: score('If `ticket.message` reports a bug, how severe is it?', [
 'Cosmetic; no impact on functionality',
 'Broken or degraded feature, but a workaround exists',
 'Blocking issue; no workaround exists',
 ]),
}

export const THRESHOLDS = {
 minCategoryConfidence: 0.6,
 refundYes: 0.7,
 urgentBugScore: 1.5,
}

이 질문을 사용하는 코드는 모든 질문을 한 번에 보낸다.

import { TypeSafeClient } from '@typesafe-ai/sdk'
import { THRESHOLDS, TICKET_QUESTIONS } from './questions.js'

const client = new TypeSafeClient()

export async function triage(message: string) {
 const { answers } = await client.systemOne({
 state: { ticket: { message } },
 questions: TICKET_QUESTIONS,
 })

 if (answers.category.confidence < THRESHOLDS.minCategoryConfidence) return 'human'
 if (answers.category.choice === 'billing') {
 return answers.refund_requested.noul > THRESHOLDS.refundYes ? 'refunds' : 'billing'
 }
 if (answers.category.choice === 'bug_report') {
 return answers.bug_severity.score > THRESHOLDS.urgentBugScore ? 'on_call' : 'bug_backlog'
 }
 return 'support'
}

임계값은 직접 분류한 티켓으로 조정할 예시 값이다. 이 구조를 기준으로 다음 항목을 확인한다.

• 질문과 임계값은 한 파일에 둔다. 경로 처리 코드 곳곳에 흩어 놓지 않는다.
• 상태마다 한 번 호출한다. 같은 티켓에 관한 독립 질문은 하나의 systemOne() 호출에 담는다. 하나의 상태에 대해 질문을 반복 호출하는 것은 LLM의 습관이다. 티켓을 반복 처리하는 것은 괜찮다.
• 필요한 곳에서는 신뢰도를 기준으로 처리한다. 되돌리기 어려운 작업은 신뢰도를 확인하고 사람에게 넘길 수 있어야 한다. 가장 적합한 선택지만 필요하다면 choice만으로 충분하다. Jev 신뢰도 점수와 임계값도 참고할 수 있다.
• 질문에 산술이나 날짜 계산을 넣지 않는다. 합계, 개수, 날짜 비교는 코드에서 처리한다.
• 모든 Choice에 빠져나갈 선택지를 둔다. Jev가 틀린 답을 억지로 고르지 않도록 other나 값이 없을 수 있을 때의 “not stated”를 포함한다.
• 질문의 의미를 문장에 온전히 담는다. 질문 ID는 모델에 전달되지 않으므로 지시문에 의미를 적어야 한다.
• 실제 필드만 사용한다. 원시 요청에는 model, state, questions만 두고, 직접 작성한 타입 대신 SDK 타입을 사용한다.
• 키는 서버에 둔다. JavaScript SDK는 dangerouslyAllowBrowser를 설정하지 않으면 브라우저에서 실행되지 않는다. 이 옵션은 위험 신호로 취급한다.
• 모델 버전을 기록한다. 모든 응답에는 jev-1.13.0 같은 버전이 붙은 모델 정보가 포함된다. 이를 기록하고 임계값을 조정한 뒤에는 버전을 고정한다.

AGENTS.md에 넣을 내용

에이전트는 관련 있다고 판단할 때 스킬을 불러온다. AGENTS.md에 몇 줄을 추가하면 Jev를 다루는 모든 작업에서 규칙을 확인하게 할 수 있다. 다음 내용을 붙여넣을 수 있다.

## Jev (TypeSafe)

- Jev is a decision model, not an LLM. It returns typed answers (noul, choice, score) with probabilities and never generates text.
- Use the TypeSafe skill. Read the docs as Markdown: start at https://docs.typesafe.ai/llms.txt and add `.md` to any page URL.
- Use the official SDK. A raw request has only `model`, `state` and `questions`. Don't add other fields.
- Keep every question and threshold in `src/jev/questions.ts`.
- Send all independent questions about the same state in one call. Only make a second call when the first answer decides what to fetch or ask next.
- Write the full question in `instructions`. Question IDs are not sent to the model.
- Add an `other` or "not stated" option to every Choice that might not fit every input.
- Do math, counting, and date comparisons in code, never in a question.
- Gate irreversible actions on confidence and fall back to a person.
- Keep `TYPESAFE_API_KEY` on the server. Never set `dangerouslyAllowBrowser`.
- Log the `model` field from every response.

파일 경로는 프로젝트에 맞게 바꾼다. Codex, Cursor, OpenCode는 AGENTS.md를 직접 읽는다. 프로젝트에 CLAUDE.md가 없으면 Claude Code도 이 파일을 읽는다. CLAUDE.md가 있다면 그 파일에 @AGENTS.md를 적어 불러와야 한다.

스킬과 문서, 규칙을 준비한 뒤에는 프로젝트에서 취약한 파싱 코드 한 부분을 골라 브레인스토밍 프롬프트를 에이전트에 입력하면 된다.