본 글은 Sanity Challenge, Path One: 실시간 콘텐츠를 조회하는 에이전트를 배포하기에 제출하는 내용입니다.

제가 만든 것

나이지리아에서는 JAMB의 UTME에서 좋은 점수를 받고 입학 허가를 받아도 클리어런스(clearance) 단계에서 거절되는 경우가 있습니다. 클리어런스는 대학이 지원자의 O'level 성적을 해당 학과 규칙과 대조하여 확인하는 과정입니다. 실수들은 작고 구체적인 것들입니다:

해당 학과가 한 번의 응시만 허용하는데, 두 번째 응시에서 얻은 물리학(Physics) 학점.
UNILAG 컴퓨터 과학 전공에 필요한 추가 수학(Further Maths) 학점이 없음.
법학(Law) 과정 지원 시 UTME 과목 중 하나로 계산된 수학 성적.

단 하나의 잘못된 과목 때문에 1년 전체를 날릴 수 있습니다.

Clearance Desk는 지원자(그리고 그들을 돕는 부모님과 선생님들)를 위한 에이전트입니다. 이 에이전트는 지원자가 입학하기 전에 UNILAG, UI, OAU, UNN, LASU의 공개된 2026/2027년 요건에 맞춰 UTME 과목, UTME 점수, O'level 응시 기록을 확인해 줍니다.

각 학과별로 지원자가 **적격(Eligible)**한지, **위험군(At risk)**인지, 또는 **부적격(Not eligible)**한지를 알려주고, 모든 출처를 연결하여 일반적인 영어로 그 이유를 설명합니다.
이후 Knowledge Base에 다음 조치 사항을 문의할 수 있습니다: 마감일, 심사 기간, 대기 중인 성적 등. 답변은 오직 JAMB와 대학 공지에서만 나옵니다.

핵심 설계 원칙은 다음과 같습니다: 모델이 찾고 설명하며, 결정론적 코드(deterministic code)가 판단합니다. Claude는 결정을 내리지 않습니다. 대신 Sanity Context를 통해 올바른 규칙을 찾아내고, 작은 TypeScript 평가기가 이를 검사한 후, Knowledge Base를 사용하여 Claude가 결과를 설명해 줍니다.

데모

실시간: https://clearancedesk.vercel.app. 로그인 없이 사용 가능하며 휴대폰에서도 작동합니다. 상단에 있는 세 가지 샘플 지원자 중 하나를 탭해 보세요:

산티(Sanity) 컨텍스트의 각 단계가 실시간으로 표시되는 것을 볼 수 있습니다.
판결은 코드가 결정하는 즉시, 보통 10~15초 이내에 나타납니다.
그 후 설명이 도착합니다.
마지막으로, 결과 아래에서 제안된 질문 중 하나를 시도해 보세요.

2분 분량의 내레이션 비디오에서는:

Chioma (UTME 301)가 UNILAG 의학 계열을 확인했으나 자격 미달(Not eligible) 판정을 받습니다. 이는 UNILAG가 한 번만 응시를 허용하며, 그녀의 물리 학점은 두 번째 응시에서 나온 것이기 때문입니다.
동일한 결과로 UNN 간호학과(두 번 응시 가능)에서는 자격 있음(Eligible) 판정을 받습니다.
"내가 자격을 갖춘 과정 보기(Show courses I qualify for)" 기능이 10개 과정을 한 번에 확인합니다.
그녀는 Knowledge Base에 업로드 마감일을 문의했고, 이 기한이 연장된 것으로 밝혀집니다.
Knowledge Base가 어떻게 구축되었는지와 추적 경로를 살펴봅니다.
평가(eval).

코드

GitHub logo big14way / clearancedesk

Clearance Desk

나이지리아 대학 입학 시험(UTME) 과목, UTME 점수 및 O'level 성적이 특정 대학의 특정 과정에 대한 공지된 요건을 충족하는지 여부를 지원자에게 알려주는 AI 에이전트입니다. 이는 지원하기 전에 확인하여, 합격했다가 나중에 클리어런스(clearance) 단계에서 거절되는 일을 방지합니다.

DEV × Sanity Challenge의 Path One: "실제 콘텐츠를 쿼리하는 에이전트 배포(Ship an Agent That Queries Real Content)"을 위해 구축되었습니다.

라이브: https://clearancedesk.vercel.app (로그인 불필요). About 페이지에서 아키텍처와 실시간 데이터 커버리지를 확인할 수 있습니다.

Architecture: one agent, two Sanity Context endpoints, one deterministic evaluator

핵심 원칙: 모델이 찾고 설명하고, 결정론적 코드(deterministic code)가 판단합니다.

🚧 작업 진행 중입니다. 계획은 BUILD_SPEC.md에서, 빌드 일지(build journal)는 BUILD_LOG.md에서 확인하세요.

레이아웃 (Layout)

경로 (Path)	내용 (What)
`studio/`	Sanity Studio + 스키마 (출처, 과목, 기관, 프로그램, 요건)
...

데이터 (Data) (Phase 2)

34개의 2026/2027 학기 입학 요건을 5개 대학에 걸쳐…

View on GitHub

이 리포지토리는 다음을 포함합니다:

Studio 스키마
출처 추적 데이터 파이프라인
49개의 단위 테스트가 있는 평가기(evaluator)
에이전트 및 Next.js 앱
평가(eval)
모든 잘못된 경로의 정직한 빌드 로그

Sanity를 사용한 방법

1. 구조화된 콘텐츠로서의 입학 규칙

요건은 산문이 아니라 프로그램이 확인할 수 있는 데이터셋인 Sanity에 존재합니다. 여기에는 source, subject, institution, programme, requirement라는 다섯 가지 문서 유형이 있습니다. requirement는 한 학기의 하나의 프로그램에 대한 규칙을 담고 있습니다:

필드	텍스트가 아닌 데이터인 이유
`utmeCompulsory`, `utmeChoices` (`{pick: 1, from: [subject refs]}`)

Endpoint	출처 (Source)	에이전트가 사용하는 도구 (Tools the agent uses)
`clearance-rules`	dataset `cynv9mfk.production`, GROQ 필터를 사용하여 5가지 유형으로 제한됨	`rules_groq_query`, `rules_schema_explorer`
`clearance-policy`	지식 기반 (Knowledge Base)	`policy_knowledge_base_read`, `policy_knowledge_base_search`

Sanity의 자체 패턴을 따라, 두 엔드포인트 모두의 initial_context는 HTTP를 통해 가져와 시스템 프롬프트에 포함됩니다. 에이전트는 도구 호출을 사용하지 않고도 스키마와 KB 개요를 알고 시작합니다.

각 엔드포인트에는 지침 (Instructions) 또한 있습니다. rules 엔드포인트의 지침은 다음과 같습니다:

_id로 과목을 일치시키고, 이름으로는 절대 하지 않기
선택 그룹(choice groups)을

경로(route)는 루프가 실행되는 동안 스트리밍합니다. Sanity Context 단계가 완료될 때마다, 그리고 설명이 작성되기 직전에 **evaluate_eligibility가 반환하는 즉시 판정(verdict)**을 보여줍니다. 휴대폰으로 볼 경우, 규칙 질의와 확인 사항들이 도착하고 결정된 판정이 전체 시간의 절반 정도에 걸쳐 나타납니다.

일부 보장은 프롬프트뿐만 아니라 코드에서도 강제됩니다:

KB 경로가 해당 실행에서 실제로 읽히지 않았다면 정책 메모(policy note)는 표시되지 않습니다.
확인 모드(check mode)는 다른 과정을 평가할 수 없습니다.
모델이 절대 완료되지 않더라도 정확한 판정은 얻을 수 있습니다.

모든 답변에는 추적 기록(trace)이 포함됩니다:

The trace: GROQ via clearance-rules, deterministic checks, KB entries via clearance-policy

4. 지식 기반(Knowledge Base)

규칙은 무엇을 해야 하는지 말하고, 지식 기반은 왜 중요한지 그리고 무엇을 해야 하는지를 알려줍니다: 커트라인 점수, Post-UTME 심사, 결과 대기 기간, 업로드 마감일, 응시 규칙. 저는 26개의 공식 자료(JAMB 및 5개 대학의 공지 및 요구 사항 PDF 포함)와 6개의 블로그를 통해 이를 구축했습니다. 이 블로그들은 의도적으로 배치되어 Context가 공식 출처와 의견이 다른 부분을 부각할 수 있도록 합니다.

Context는 **7가지 충돌(conflicts)**을 발견했습니다. 저는 6개를 해결하고 1개는 허위 충돌로 무시했습니다. 각 해결책은 영구적인 지침이 되었습니다. 예를 들어:

LASU의 195점: 한 블로그에서는 이를 '커트라인 점수(cut-off mark)'라고 불렀지만, LASU 자체 공지에는 '최소 195점'이라고 명시되어 있습니다. 공식적인 문구를 따르는 것이 좋습니다.
UNILAG 응시: UNILAG은 오직 한 번의 시험(at one sitting only)으로 다섯 개의 O'level 학점을 요구합니다. 이것이 데모에서 '자격 미달(Not eligible)'로 표시된 규칙입니다.
UNILAG의 O'level 업로드 마감일: 연장 공지(2026년 8월 24일 월요일)가 원래 날짜보다 앞섭니다.
OAU 영어: OAU 페이지에는 '영어 언어에서 O-Level 합격(a pass at O-Level … in English Language)'이라고 되어 있습니다. 만약 OAU가 학점 합격(credit pass)을 의미한다면, 단순 합격으로는 지원자가 거절될 수 있으므로 저는 더 엄격한 해석인 '만점 학점(full credit)'을 유지했습니다.
UNILAG의 최저 성적 커트라인: 입학 요건으로 주장된 기상학이 아니라 교육 경제학(Education Economics) (49.65점)입니다.