정책 정보가 오래되었습니다: 사실(Fact) 드리프트를 포착하는 Sanity AI 에이전트 구축기

이는 Sanity Challenge, Path Two: Vibe-Code Something Strange에 제출하는 글입니다.

제가 구축한 것 (What I Built)

Fact Ledger: Sanity Content Lake를 기반으로 구축된 AI 지원 사실 드리프트 탐지 및 복구 엔진입니다.

이것이 해결하는 문제는 한 장면으로 설명합니다:

SaaS 회사에서 근무하는 제품 관리자가 환불 기간을 30일에서 60일로 연장하기로 결정했습니다. 그녀는 CMS를 열고 '환불 정책(Refund Policy)' 페이지를 찾아 업데이트한 후, 발행 버튼을 누릅니다. 끝입니다. 그녀는 슬랙 메시지를 보냅니다: _

하드코딩된 일반 텍스트가 남아있는 모든 페이지(시스템 이전의 것이거나 누군가가 몰랐기 때문일 수 있음)에 대해, 결정론적 스캐너가 모든 웹훅 이벤트에서 실행되어 오래된 사본을 찾아 구조화된 finding 문서를 생성합니다. AI 에이전트가 이를 수정하기 위한 정확한 Sanity 패치 뮤테이션(mutation) 초안을 작성합니다. 사람이 이전/이후 차이점(diffs)을 검토하고 버튼을 클릭하면 됩니다. 모든 것이 단일 트랜잭션으로 원자적으로 업데이트됩니다. 감사 장부(audit ledger)가 전체 과정을 기록합니다.

핵심 원칙을 단계별 네 단어로 요약하자면: 규칙이 플래그를 지정하고. AI가 초안을 작성하며. 사람이 승인하고. Sanity가 기억하게 합니다.

Fact Edit → Webhook → 결정론적 스캐너 → Finding Graph
         → AI 뮤테이션 합성 → 초안 릴리스 → 사람의 승인 → 제로 드리프트

5가지 스캐너 규칙 (AI 미사용)

디자인이 흥미로운 부분이 바로 여기입니다. 이 스캐너는 순수 결정론적 TypeScript이며, 모델 호출이나 임베딩(embeddings), 퍼지 매칭 라이브러리를 사용하지 않습니다. 밀리초 단위로 실행되며 정확한 블록 키와 문자 오프셋을 가진 발견 사항을 생성합니다.

워크플로우

Sanity에 발견된 결과가 있으면, AI 복구 에이전트가 작동합니다. 이 에이전트는 페이지의 Portable Text를 가져와 스캐너가 식별한 정확한 블록과 문자 범위를 찾고, 오래된 텍스트를 잘라내어 유효한 Sanity 패치 뮤테이션(patch mutation)을 생성합니다. 이는 수동으로 작업할 때 작성하는 방식과 같지만, 대시보드를 새로고침하는 시간 동안 20페이지 분량을 처리해줍니다.

이 모든 것은 remediation 문서에 기록됩니다. 이 문서는 fixes 배열을 가진 구조화된 릴리스이며, 각 항목은 beforeText, afterText, 원본 패치 JSON, 그리고 편집자가 토글할 수 있는 approved 불리언 값을 가집니다.

Sanity Studio에는 remediation 타입에 커스텀 "수정 적용 및 게시(Apply Fixes & Publish)" 문서 액션이 있습니다. 편집자는 변경 사항(diffs)을 검토합니다. 개별 수정사항을 승인하거나 거부할 수 있습니다. 만족하면, 한 번의 클릭으로 client.transaction()이 실행되어 다음 작업을 원자적으로 수행합니다:

• 영향받는 모든 페이지에 패치 적용
• 연결된 모든 발견 사항(finding) 상태를 fixed로 변경
• 복구 문서 자체 게시
• 감사 장부(audit ledger)에 불변의 changeEvent 기록

부분적인 상태 변화는 없습니다. "21페이지 중 17개 페이지만 수정하고 탭이 닫혔다"와 같은 일이 발생하지 않습니다. 21개 페이지 모두가 동일한 트랜잭션 내에서 업데이트되거나, 아니면 아무것도 업데이트되지 않습니다. 대시보드의 Drift Score는 다시 0으로 떨어지고 그 상태를 유지합니다. 다음 사실(fact)이 변경될 때까지 말이죠.

🌟 주요 기능 (App SDK 경험)

https://fact-ledger.onrender.com/dashboard에 있는 Next.js 대시보드는 Content Lake 위에 올라간 실시간 상호작용 레이어입니다. 단순히 읽기 전용 프런트엔드가 아니라, 완전한 App SDK 제어 센터입니다.

1. 조항 영향 트리(The Clause Impact Tree)
정책이 변경되면 공무원들은 단지 깨진 페이지 목록을 보는 것이 아닙니다. 그들은 **연쇄적 변화 그래프(cascading change graph)**를 봅니다. 조항 영향 트리는 단 하나의 정식 사실(canonical fact)이 전체 기업 문서 그래프에 어떻게 파급되는지를 시각화하며, 웹훅이 발생하는 즉시 노드가 빨간색으로 변하는 것을 보여줍니다.

2. 실시간 제어 센터 및 차트 (The Live Control Center & Charts)
대시보드의 모든 숫자와 그래프는 실시간 GROQ 쿼리에서 가져옵니다.

• KPI 행 (The KPI Row): 현재 드리프트 점수(Drift Score), 총 사실 수, 스캔된 페이지 수 및 전반적인 상태를 추적합니다.
• 해결도 건강 차트 (Resolution Health Chart): 릴리스별로 발견된 미해결 사항과 수정된 사항을 비교하는 분석표입니다.
• 히트맵 (The Heatmap): Fact × Page 드리프트 이상 징후를 시각화한 CSS 그리드입니다. 드리프트는 빨간색, 정상은 초록색으로 표시됩니다.
• 상호작용 트리아지 (Interactive Triage): 편집자는 대시보드 테이블에서 발견된 사항을 승인하거나 기각할 수 있습니다. API 라우트가 Sanity의 해당 발견 문서(finding document)를 즉시 수정하고, 페이지를 새로고침하지 않고도 테이블이 실시간으로 재쿼리됩니다.

3. 직원 의견 포털 (The Employee Voice Portal)
정책 혼란은 아래로만 흐르지 않습니다. 직원과 고객이 가장 먼저 오래된 정책을 발견합니다. 직원 의견(Employee Voice) 포털은 이러한 신호를 위한 공간을 제공합니다.

• 직원은 정책 관련 불만이나 질문을 제출할 수 있습니다.
• 이러한 제출물들은 Sanity에 complaint 또는 policyQuestion 문서로 직접 저장됩니다.
• 담당자들은 Sanity Studio에서 열린 발견 사항 바로 옆에 모든 제출물을 볼 수 있습니다. 직원이

라이브 대시보드 (Live Dashboard): https://fact-ledger.onrender.com/dashboard
Sanity Studio: https://pritam.sanity.studio/

60초 만에 완성되는 전체 루프(The Full Loop)

사실 정보가 변경될 때 시스템이 실제로 어떻게 작동하는지 보여드립니다:

1. 트리거 (The Trigger)
Sanity Studio에서 편집자가 취소 정책 (Cancellation Policy)의 사실 값(fact value)을 60에서 30으로 변경합니다.

2. 감지 (The Detection)
The 웹훅(webhook)이 작동합니다. 스캐너가 모든 페이지에 걸쳐 R1부터 R5까지 실행됩니다. 대시보드의 드리프트 점수(Drift Score)가 급증하고 KPI가 빨간색으로 깜빡입니다.

3. 수정 초안 (The Remediation Draft)

5. 해결 (The Resolution)
client.transaction()이 커밋됩니다. 모든 페이지가 원자적으로 패치되고, 발견된 오류는 '수정됨(fixed)'으로 바뀌며, 드리프트 점수(Drift Score)는 0으로 돌아갑니다.

코드