Jev로 강의 추천 기능 만들기: 세 문장 직접 실행한 결과

"예약 신청을 받는 작은 웹서비스를 만들어보고 싶어요." 이 문장을 Jev Playground에 넣었더니 build_service가 돌아왔습니다. 입력을 비누 광고 이미지로 바꾸자 creative_assets, "AI를 배우고 싶어요"라고만 쓰자 unsure를 골랐습니다. 같은 질문과 네 선택지를 유지한 채 문장만 바꿔 실제로 세 번 실행한 결과입니다. 이 값을 강의 카드나 추가 질문 화면에 연결하는 작은 추천 기능을 만들어봅시다.

TypeSafe는 2026년 9월 15일 Jev를 공개했습니다. 아래 실습은 2026년 10월 5일 공식 Playground에서 jev-latest를 선택해 진행했으며, 응답 JSON에는 실제 모델이 jev-1.13.0으로 표시됐습니다. 사용할 수 있는 계정과 기존 크레딧으로 세 번 호출했습니다. 후반부의 코딩 에이전트 지시와 서버 코드는 이 응답을 제품에 연결하는 다음 실습입니다.

Jev가 하는 일을 추천 화면 하나로 이해하기

방문자가 "예약을 받는 작은 서비스를 만들고 싶고, 코딩은 해본 적 없어요"라고 입력했다고 합시다. 이 문장 전체를 버튼 이름이나 데이터베이스 검색 조건으로 쓰기는 어렵습니다. 제품에는 build_service, creative_assets, research, unsure처럼 미리 정한 분류가 필요합니다. Jev에 문장과 선택지 설명을 주고, 돌아온 선택에 맞춰 화면을 바꾸는 것이 이 글의 연습입니다.

Jev의 입력은 state와 questions로 나뉩니다. state에는 판단할 문장이나 데이터를 넣고, questions에는 무엇을 고를지 정의합니다. 결과는 애플리케이션이 읽을 수 있는 구조화된 값입니다. 이 예제에서 Jev는 강의 분류를 고르고, 코딩 에이전트는 선택한 강의의 카드를 보여주는 화면을 만듭니다. 강의 소개 문구는 미리 작성해 두므로, 방문자가 입력할 때마다 새로 생성하지 않아도 됩니다.

첫 실습에서는 Choice 하나만 사용합니다. 질문을 늘리기 전에 선택지가 실제 상품 구성과 맞는지 보는 편이 이해하기 쉽습니다. 나중에 경험 수준을 별도 질문으로 추가하면 "서비스를 만들고 싶은 초보자"와 "기존 서비스를 고치려는 경험자"를 다른 과정으로 연결할 수 있습니다. 결과물 종류와 경험 수준을 하나의 문장으로 섞어 물을 필요는 없습니다.

먼저 추천할 강의와 선택지를 정하기

아래는 이 글을 위한 가상의 강의 목록입니다. 실제 DAYABLE 수강 일정이나 판매 상품과는 다릅니다. 연습용 서비스는 네 종류의 입력을 받아 세 강의 중 하나를 추천하거나 추가 질문을 보여줍니다. 카드에 넣을 강의 이름과 소개를 먼저 정해 두면 각 분류 값이 화면에서 무엇을 바꾸는지 바로 확인할 수 있습니다.

선택지 이름만 짧게 적고 뜻을 모델이 알아서 추측하게 두지 마세요. 예를 들어 marketing이라는 값에는 광고 이미지 제작, 시장 조사, 홈페이지 개발이 모두 들어갈 수 있습니다. 결과물을 기준으로 설명하면 "홍보가 필요해요"처럼 넓은 문장은 추가 질문으로 보내고, "향수 사진을 인스타 광고로 바꾸고 싶어요"처럼 구체적인 문장은 이미지 과정으로 연결할 수 있습니다.

Playground에 같은 질문을 넣고 세 문장 실행하기

공식 Quick start의 Playground 링크에서 로그인합니다. Google 로그인과 이메일 코드 로그인 중 이용 가능한 경로를 쓰면 됩니다. 이번에는 이메일 코드 로그인으로 들어갔습니다. 화면의 State에는 판단할 입력을, Questions에는 질문 정의를 넣습니다. 아래 예시에서는 State를 JSON으로 표시하고 request라는 항목에 방문자의 문장을 담았습니다.

{
  "request": "예약 신청을 받는 작은 웹서비스를 만들어보고 싶어요. 코딩 경험은 없고, 주말 하루를 투자할 수 있습니다."
}

Questions에 아래 JSON을 넣습니다. goal은 응답에서 찾을 질문 이름이고, criteria 안의 네 이름이 화면 연결에 쓸 값입니다. jev-latest를 선택한 뒤 Run request를 누르면 오른쪽 Response에 결과가 나옵니다. Overview에서는 선택과 분포를 보고, JSON에서는 실제 모델 이름·응답·토큰 사용량을 읽을 수 있습니다. 이 화면에서 복사한 결과를 아래에 실었습니다.

{
  "goal": {
    "type": "choice",
    "instructions": "가장 먼저 만들고 싶은 결과물은 무엇인가?",
    "criteria": {
      "build_service": "작동하는 웹사이트, 예약, 신청, 판매 또는 내부 앱",
      "creative_assets": "제품 사진, 상세 이미지, 광고 소재 또는 영상",
      "research": "시장 자료, 문헌 또는 인터뷰를 조사하고 정리한 자료",
      "unsure": "제공한 정보만으로 위 목표를 구분하기 어려움"
    }
  }
}

다음 두 번에는 Questions를 그대로 두고 State의 request 문장만 바꿨습니다. 한 번은 "직접 만든 수제 비누 사진으로 인스타그램 광고 이미지를 만들고 싶어요.", 다음에는 "AI를 배우고 싶어요."를 입력했습니다. 아래 표는 세 호출의 원본 응답에서 읽은 값입니다. 처음 두 입력은 구체적인 결과물이 있고, 세 번째 입력에는 무엇을 만들고 싶은지가 드러나지 않습니다.

여기서 unsure는 우리가 만든 선택지 이름입니다. Jev가 정해진 상품 중 하나를 억지로 고르는 대신, 이 분류를 반환할 수 있도록 질문에 넣었습니다. 서비스 코드에서는 build_service와 creative_assets에 각각 준비한 카드를 연결하고, unsure에는 "먼저 만들고 싶은 것은 무엇인가요?"라는 질문과 세 버튼을 보여줄 수 있습니다. 버튼을 누른 다음에는 방문자가 직접 고른 값을 사용합니다.

{
  "type": "choice",
  "choice": "unsure",
  "confidence": 0.96,
  "probabilities": {
    "research": 0.02,
    "build_service": 0.01,
    "unsure": 0.97,
    "creative_assets": 0
  },
  "stats": {}
}

직접 따라 해볼 때는 같은 입력부터 실행해 비교한 다음, 한 문장만 바꿔보세요. 예를 들어 "AI를 배우고 싶어요" 뒤에 "내 상품 사진을 광고 이미지로 바꾸려고 해요"를 붙이면 목적이 구체적이 됩니다. 이 추가 문장은 아직 실행하지 않은 후속 연습입니다. 바뀐 입력과 실제 나온 값을 함께 저장해 두면 어떤 표현에서 화면을 더 물어봐야 하는지 알 수 있습니다.

코딩 에이전트에 공식 스킬 연결하기

이제 Claude Code나 다른 코딩 에이전트가 추천 화면을 만들도록 할 수 있습니다. TypeSafe는 자신의 API를 쓰는 에이전트용 공식 스킬을 제공합니다. 처음 보는 라이브러리의 함수나 응답 형식을 에이전트가 기억만으로 작성하지 않도록, 현재 API 문서를 읽는 방법을 함께 전달하는 용도입니다.

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

위 명령은 공식 Quick start의 범용 설치 방식입니다. 실행 중 사용할 에이전트를 선택하며, 기본 설치 범위는 현재 프로젝트입니다. Claude Code에서는 공식 안내의 marketplace·plugin 설치 방식도 사용할 수 있습니다. 한 가지 방식으로 설치한 뒤 프로젝트에서 스킬을 읽을 수 있는지 확인하고 다음 지시를 전달합니다.

TypeSafe 공식 스킬을 읽고 강의 추천 페이지를 만들어줘.

입력: 방문자가 원하는 결과물을 자유롭게 쓰는 문장.
분류: build_service / creative_assets / research / unsure.
선택지의 의미는 내가 제공한 표를 그대로 사용해.

첫 단계에서는 API 없이 mock 응답으로 화면을 완성해줘.
입력창, 추천 카드, 선택 이유를 설명하는 고정 안내문, 다시 고르기 버튼이 필요해.
그다음 서버에서 Jev를 호출하는 함수를 붙여줘.
브라우저 코드에 API 키를 넣지 말고 서버 환경변수로 읽어.
unsure일 때는 결과물 3개를 직접 고르는 화면을 보여줘.
응답 대기, API 실패, 빈 입력 상태도 실제로 눌러볼 수 있게 만들어줘.

mock 응답으로 화면을 만들 때는 네 분류 값을 하나씩 선택해 카드와 추가 질문 화면을 살펴보세요. 응답을 기다리는 동안 버튼을 다시 눌러도 되는지, 입력을 지웠을 때 안내가 보이는지도 함께 조정합니다. mock 값에는 개발용 데이터라는 표시를 붙여 실제 API 결과와 구분합니다. 화면이 준비되면 호출 함수를 Jev로 바꾸고, 카드 구성과 분류 값은 그대로 사용합니다.

API 호출은 서버의 작은 함수로 분리하기

공식 JavaScript SDK의 패키지 이름은 @typesafe-ai/sdk입니다. SDK는 Node.js 20 이상을 요구하며 TYPESAFE_API_KEY 환경변수를 읽습니다. 아래는 DAYABLE의 연습용 기준으로 작성한 코드입니다. 서버에서 사용하도록 만든 예시이며 브라우저에 그대로 붙여 넣는 코드가 아닙니다. 실제 API를 호출하면 계정의 사용량에 반영될 수 있습니다.

npm install @typesafe-ai/sdk

import { TypeSafeClient, choice } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();

export async function recommendGoal(message) {
  const input = message.trim();
  if (!input) throw new Error("원하는 결과물을 입력해 주세요.");
  const result = await client.systemOne({
    state: { request: input },
    questions: {
      goal: choice("가장 먼저 만들고 싶은 결과물은 무엇인가?", {
        build_service: "작동하는 웹사이트, 예약, 신청, 판매 또는 내부 앱",
        creative_assets: "제품 사진, 상세 이미지, 광고 소재 또는 영상",
        research: "시장 자료, 문헌 또는 인터뷰를 조사하고 정리한 자료",
        unsure: "제공한 정보만으로 위 목표를 구분하기 어려움",
      }),
    },
  });
  return result.answers.goal;
}

응답의 choice로 보여줄 카드를 정하고, probabilities와 confidence는 분류를 살펴볼 때 사용합니다. 실제 세 번째 호출은 unsure의 probability가 0.97, confidence가 0.96이었습니다. "AI를 배우고 싶다"만으로는 결과물을 고를 수 없다는 선택에 분포가 모인 것입니다. confidence가 높다고 꼭 특정 강의를 추천해야 하는 것은 아닙니다. 이 예제에서는 choice가 unsure이면 원하는 결과물을 고르는 화면을 띄웁니다.

목표가 두 개 들어 있는 문장도 넣어보기

실제 방문자는 "사이트도 만들고 광고도 하고 싶어요"처럼 여러 목표를 한 번에 적을 수 있습니다. 아래 입력을 예제 파일로 모아두고 질문 설명을 바꿀 때마다 다시 실행해보세요. 각 문장에서 어떤 카드를 보여주고 싶은지 먼저 적으면, 분류 설명을 바꿀지 추가 질문을 만들지 결정하기 쉽습니다.

예상과 다른 카드가 나오면 state에 목표를 판단할 정보가 있는지, 두 선택지의 설명이 겹치는지 살펴봅니다. "시장 조사도 하고 사이트도 만들고 싶어요"처럼 두 목표가 함께 있다면, 화면에 "먼저 완성하고 싶은 것은 무엇인가요?"라는 질문을 추가할 수 있습니다. 질문 설명을 바꾼 이유와 예제 파일을 함께 남겨두면 다음 수정에서도 같은 기준으로 비교할 수 있습니다.

자유 입력을 제품 동작으로 연결할 자리에 쓰기

방문자가 이미 "서비스 만들기" 버튼을 눌렀다면 그 값을 그대로 사용하면 됩니다. 목록에서 선택한 값을 다시 AI에게 판단시킬 이유는 적습니다. Jev를 붙여볼 지점은 자유로운 표현을 읽어 정해진 제품 동작으로 연결해야 하는 곳입니다. 가격이나 남은 좌석처럼 데이터베이스에 확정된 값은 원본 데이터에서 읽습니다. 이 경계를 정하면 모델 호출도 필요한 자리에만 남습니다.

이번 실행에서 응답의 evaluation_time_ms는 약 51.22, 61.76, 133.88ms였습니다. 이는 원본 JSON에 들어 있는 평가 시간이며, 로그인·네트워크·화면 표시를 합친 전체 대기 시간과는 다릅니다. 입력당 한 번씩 실행한 세 결과로 속도나 추천 정확도를 일반화할 수는 없습니다. 요금도 별도로 측정하지 않았습니다. 자체 서버에서 SDK를 연결할 때는 그 환경의 전체 응답 시간과 계정 사용량을 따로 살펴보세요.

추천 화면에 다음 질문 추가하기

이번에 직접 실행해 얻은 것은 세 입력의 분류 결과와 원본 JSON입니다. 서버 코드와 화면 제작 지시는 이 값을 자신의 서비스에 연결하는 다음 단계입니다. 연결한 뒤에는 "수강 경험" 질문을 추가해보세요. 같은 서비스를 만들고 싶어도 처음 배우는 사람에게는 시작 과정을, 경험자에게는 기존 프로젝트를 확장하는 과정을 보여주도록 카드 연결을 나눌 수 있습니다.