아키텍처

Optra Prism은 세 개의 쌓인 측정 계층과 하나의 병렬 인텔리전스 파이프라인입니다. 계층은 데이터 흐름에 따라 아래에서 위로 번호가 매겨지고(신호는 Layer 0에서 Layer 1을 거쳐 Layer 2로 올라갑니다), 각 계층은 정확히 한 종류만 담습니다.

flowchart LR
    L0["Layer 0 — 텔레메트리<br/>Claude Code의 OpenTelemetry"] --> L1["Layer 1 — 사실<br/>목표 달성 · 재작업 · 토큰 · 프롬프트 등급"]
    L1 --> L2["Layer 2 — 점수<br/>프롬프트 점수(APG) · 완료율"]
    L1 -.-> PIQ["프롬프트 루브릭 에이전트<br/>불리언 7개 × 의도 8개"]
    PIQ -.-> L1

    style L0 fill:#22c55e,stroke:#16a34a,color:#fff
    style L1 fill:#f59e0b,stroke:#d97706,color:#fff
    style L2 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style PIQ fill:#a855f7,stroke:#9333ea,color:#fff

Layer 0 — 텔레메트리

모든 수치의 출발점입니다. Claude Code가 OpenTelemetry로 비용, 토큰, 이벤트, 링크, 라벨을 내보냅니다. git 웹훅도, 저장소 스캐너도, CI 연동도 쓰지 않습니다.

기능을 온전히 쓰려면 환경 변수 세 개를 켜야 합니다.

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_LOG_USER_PROMPTS=1
OTEL_LOG_TOOL_DETAILS=1

OTEL_LOG_USER_PROMPTS가 없으면 프롬프트 루브릭과 goal_complete, rework 채점기가 모두 제한된 상태로 돌아갑니다. 채점에 쓸 프롬프트 본문이 없기 때문입니다. 토큰·턴·활성 시간처럼 숫자만 세는 값은 영향을 받지 않지만, 해당 서브세션은 틀린 점수를 매기는 대신 “미채점”으로 남습니다. OTEL_LOG_TOOL_DETAILS가 없으면 파일 경로를 뽑아내지 못합니다. 다만 서브세션 경계는 시각과 주제 전환, /clear 이벤트로 계속 판단합니다.

/prism:setup을 실행하면 이 값들이 알아서 설정됩니다.

Layer 1 — 사실

엔진은 서브세션마다 결과를 판단할 근거가 되는 값 네 가지를 뽑아냅니다.

goal_complete — 참/거짓. 서브세션에서 내건 목표에 도달했는가? 세션 텔레메트리를 근거로 LLM이 판정합니다.
rework — 참/거짓. 그 목표를 나중에 다시 해야 했는가? git이 아니라 이후 세션의 텔레메트리, 즉 교정 턴과 후속 작업을 보고 판단합니다.
token_sum — 모델별 내역이 붙은 정수. OTel의 tokens.input, tokens.output, tokens.cache_read, tokens.cache_write를 씁니다.
prompt_grade — A+부터 F까지의 문자 등급. 프롬프트 루브릭(항목 7개 × 의도 8종)의 결과를 모아 냅니다. 아래 프롬프트 루브릭 에이전트를 참고하세요.

서브세션은 실질 기준을 넘고, goal_complete가 참이며, rework가 아닐 때 완료로 봅니다. 이 값이 Layer 2의 보조 지표인 완료율로 이어집니다.

Layer 2 — 점수

개발자가 보는 숫자들입니다. Layer 1의 값에서 계산만으로 나오며, 이 단계에는 LLM 판정이 들어가지 않습니다.

점수	계산식	범위
프롬프트 점수(대표)	프롬프트별 `prompt_grade`의 평균	0–100 + 문자 등급
완료율(보조)	`완료한 서브세션 ÷ 채점된 서브세션`	0–100%

대표 수치는 프롬프트 점수입니다. 프롬프트 등급의 평균이며, 대시보드 맨 위에 문자 등급과 함께 나옵니다. 완료율은 채점된 서브세션 중 완료한 비율로, 결과 쪽을 보는 보조 지표입니다. 개인 화면과 팀 화면 모두 같은 방식으로 계산하되, 팀 점수는 팀 전체를 한꺼번에 집계한 값이지 개인 점수를 평균한 값이 아닙니다. 개발자 화면에는 보조 지표 세 가지, 곧 속도(CSPW)·역량(역량 지수)·토큰 사용량(완료당 토큰)과 역량 티어(초보 → 최상위)가 함께 놓입니다. 각각의 설명은 프롬프트 점수, 숫자들이 어떻게 맞물리는지는 스코어링 모델을 참고하세요.

프롬프트 루브릭 에이전트 — 인텔리전스 파이프라인

루브릭 에이전트는 계층 위에 얹히는 것이 아니라 계층과 나란히 돌아갑니다. 프롬프트 원문을 읽어 프롬프트별 문자 등급을 매기고, 그것이 prompt_grade가 됩니다.

언어 판별과 의도 분류 — 프롬프트마다 여덟 가지 의도(질문, 원인 조사, 리뷰, 계획·설계, 소규모 수정, 버그 수정, 기능 개발, 리팩터링) 중 하나로 분류하고 확신 정도를 함께 남깁니다.
루브릭 채점 — 프롬프트를 일곱 개 항목으로 판정합니다. goal_explicit, scope_bounded, references_concrete, context_sufficient, verification_requested(가중치 2배), root_cause_oriented, plan_first입니다. 어떤 항목을 적용할지는 의도에 따라 달라집니다.
문자 등급 — 적용된 항목 중 통과한 것을 0–100 점수로 합산하고, v3 루브릭 구간(A+ 90 이상, 기준선 B 50, 12 미만은 F)에 따라 문자 등급을 정합니다.
집계 — 프롬프트별 등급을 모아 서브세션의 prompt_grade로 만듭니다.

루브릭 에이전트가 내놓은 결과는 처음부터 끝까지 되짚어 볼 수 있습니다. 항목별 통과 여부와 의도 분류가 모두 기록으로 남아, 그 프롬프트가 왜 그 점수를 받았는지 사람이 확인할 수 있습니다.

전체 흐름

sequenceDiagram
    participant Dev as 사용자
    participant Plugin as Prism 플러그인
    participant Ingest as Ingest 서비스
    participant Worker as Prism worker
    participant API as Prism API
    participant Dash as 대시보드

    Dev->>Plugin: 프롬프트 작성
    Plugin->>Ingest: 텔레메트리와 프롬프트 전송
    Ingest->>Worker: 이벤트 전달
    Worker->>Worker: 저장 → 서브세션 경계 정리 → 사실 추출·루브릭 채점 → 추세 집계
    Dev->>Dash: 대시보드 열기
    Dash->>API: 채점된 제품 데이터 조회
    Dash-->>Dev: 프롬프트 점수 + 문자 등급 + 보조 지표 3종

대시보드에 나오는 값은 모두 S3 Parquet과 Postgres에서 다시 계산해 낼 수 있습니다. 메모리에만 있다가 사라지는 점수는 없습니다.

인증

모든 통신에 Prism API 키를 씁니다. 키는 Prism이 알아서 발급해 보관하며, 대시보드 헤더의 Connect 패널이 그 키가 담긴 셋업 명령을 그대로 보여 줍니다. 새 키는 prism_* 형식이며 예전 gck_* 키도 그대로 받습니다.

플러그인은 Ingest로 보내는 모든 요청에 키를 실어 보냅니다
Ingest는 키를 확인하고 데이터를 해당 조직에 연결합니다
대시보드 로그인은 Supabase(이메일·비밀번호 또는 OAuth)를 씁니다

키는 ~/.prism/config.json에 저장되며, 파일 권한을 좁게 잡아 둡니다.

플러그인 키

플러그인 키는 본인 컴퓨터의 ~/.prism/config.json에 있습니다. Claude Code 요청이 legacy Optra gateway를 거칠 때 인증하며, /prism:setup으로 넣는 키가 이것입니다.