개발 에이전트 관측성 + Judge LLM 적용 설계

전체 구조와 검증 대상

왼쪽 두 칸(수집·저장)은 도구가 이미 해결한 문제입니다. 리스크는 판정과 산출에 몰려 있고, 그 검증은 LangSmith를 켜지 않고도 할 수 있습니다.

Hermes는 전용 수집 경로가 없어 이 도식에서 제외했습니다(2장). 개인정보 게이트는 업로드를 켤 때만 적용되며, 위 검증 레인은 로컬이라 해당되지 않습니다(4장).

에이전트 작업이 실패하면 눈에 보이는 것은 마지막 신호(테스트 FAIL, 사용자의 "그거 아니야")뿐입니다. 그런데 실제 손실은 그보다 훨씬 앞, 탐색 공간을 근거 없이 좁힌 순간에 발생합니다. 그 지점 이후의 Read·Grep·Edit는 전부 낭비입니다.

Step 1  사용자 프롬프트: "iPad에서 영상 디코드 안 됨 원인 분석"
Step 2  Read player.ts                                  → 정상
Step 3  "codec 문제로 보인다" 라고 확정                  → ★ First Bad Turn
Step 4  codec 관련 코드만 Grep                          → 탐색 편향
Step 5  codec config Edit                               → 검증 전 수정
Step 6  Test FAIL                                       → 여기서야 실패가 보인다

Step 3에서 readyState·media.error·실제 codec metadata·네트워크 상태를 아무것도 확인하지 않았습니다. 판정 대상은 Step 6이 아니라 Step 3입니다.

판정: 조건부 적합. 수집 계층에서 편의성은 최선이지만 유일한 경로가 아닙니다 — Claude Code는 네이티브 OTel로 span도 내보냅니다(2026-09-08 공식 문서 확인). 판정 계층에서는 보조 도구입니다.

2-1. 수집 경로는 둘이다

경로 B의 결정적 차이는 중간에 OTel Collector를 끼울 수 있다는 점입니다. 4장 개인정보 게이트를 self-hosted 없이 통과할 수 있는 유일한 방법입니다.

경로 A  Claude Code / Codex ── 플러그인 ──────────────────→ LangSmith (전문, 중간 개입 지점 없음)

경로 B  Claude Code ── OTLP ──→ [OTel Collector: 속성 필터·마스킹] ──→ LangSmith / 임의 OTLP 백엔드
                                 ↑ 여기서 아동 실명을 걸러낼 수 있다

경로 B  Codex ── OTLP ──→ (log event·metrics만; span 없음) → trajectory 판정에는 부족

2-2. 계층별 판정

아래 명령·경로는 langsmith-cli README(2026-09-08 기준)에서 확인한 것입니다. 단, 이 문서 작성 시점에 로컬에는 아직 설치하지 않았고 실제 실행은 미검증입니다.

# 1) 설치
curl -fsSL https://cli.langsmith.com/install.sh | sh

# 2) 인증 (trace setup은 API 키만 지원 — OAuth 프로필 불가)
export LANGSMITH_API_KEY="lsv2_pt_..."

# 3) 에이전트별 tracing 설정 — 변경 내용을 미리 보여주고 확인을 받는다
langsmith trace setup claude --project ppi-agent-claude
langsmith trace setup codex  --project ppi-agent-codex

# 프로젝트 로컬 범위로만 켜기 (./.claude/settings.local.json)
langsmith trace setup claude --scope project

# 4) 동작 확인
tail -f ~/.claude/state/hook.log

로컬 사전 조건은 충족되어 있습니다 — claude plugin과 codex plugin 서브커맨드가 두 CLI에 모두 존재합니다(각 --help로 확인).

선택 가능한 네 가지 태도

에이전트별 권고. Claude Code는 Collector 경유, Codex는 self-hosted 또는 범위 격리 — 또는 Phase 1처럼 Codex는 아예 업로드하지 않고 로컬 JSONL로만 지표를 계산합니다(10장).

어느 방식이든 보존 기간과 워크스페이스 권한을 먼저 정합니다. 트레이스에는 코드 전문이 포함되므로 사실상 저장소 사본입니다.

first_bad_turn: 7이 성립하려면 "7"이 세션 사이에서 같은 의미여야 합니다. LangSmith가 저장하는 것은 run 트리이므로, 선형 인덱스를 뽑는 규칙을 먼저 고정해야 합니다. 이 규칙이 없으면 9장의 지표는 전부 비교 불가능해집니다.

규칙 (제안)

1. turn = 사용자 프롬프트 1건 + 그에 이어지는 에이전트 행동 전체. 사용자 프롬프트 경계에서만 번호가 올라간다.
2. 한 turn 안의 툴 호출은 turn.step 부번호를 붙인다. 병렬 툴 호출은 같은 step, 다른 slot.
3. subagent는 부모 turn 번호를 상속하고 sub 접미사를 붙인다 — 별도 turn으로 세지 않는다.

두 에이전트의 원본 필드 (로컬 트랜스크립트에서 직접 확인)

모든 트레이스를 Judge에 보내는 설계는 비용으로 먼저 죽습니다. PPI에는 이미 확립된 반대 원칙이 있습니다 — 판정은 룰, LLM은 해석만(수업 로그 야간 트리아지). 여기에도 그대로 적용합니다.

핵심은 사람이 방향을 되돌린 지점이 First Bad Turn의 사실상 정답 라벨이라는 점입니다. 사용자가 에이전트의 진행 중간에 끼어들어 교정했다면, 잘못된 방향은 그 직전 turn에서 이미 정해져 있었습니다. 라벨링 비용이 0입니다.

후보 추출 시그널 (설계 제안 — 미구현)

LangSmith 쪽에서는 --filter DSL과 --error로 1차 축소가 가능하고, 위 시그널 중 원본 필드에 의존하는 것들은 로컬 JSONL에서 계산하는 쪽이 정확합니다.

langsmith trace list --project ppi-agent-claude --error --limit 50 --include-metadata
langsmith trace export ./traces --project ppi-agent-claude --limit 20 --full

출력 스키마

{
  "session_id": "3b84054d-...",
  "agent": "claude-code",
  "first_bad_turn": 7,
  "first_bad_step": "7.2",
  "category": "premature_hypothesis",
  "severity": 3,
  "reason": "런타임 근거 없이 codec으로 탐색을 좁혔다",
  "missing_evidence": ["readyState", "media.error", "codec metadata"],
  "better_action": "런타임 미디어 상태를 먼저 확인",
  "confidence": 0.72
}

평가 축은 5개입니다: Evidence Sufficiency · Hypothesis Validity · Tool Appropriateness · Premature Commitment · Recovery Quality (각 0~3).

편향 통제 — 이게 없으면 판정이 무의미하다

Judge 프롬프트 골자

You are evaluating a coding-agent trajectory PREFIX (turns 1..N).
You do NOT know whether the task eventually succeeded. Do not guess.

Find the earliest turn where the observable decision or action became
unjustified, or narrowed the search space without supporting evidence.

Judge only from observable data: messages, tool calls, tool results,
edits, tests, metadata. Do not infer hidden chain-of-thought.

If every turn is justified given the evidence available AT THAT TURN,
return first_bad_turn: null. Returning null is a correct answer.

Return the JSON schema above.

로컬 스크립트로 판정이 안정된 뒤에 옮깁니다. 순서를 뒤집으면 프롬프트를 고칠 때마다 서버 왕복이 생깁니다.

# 룰 기반 후보 추출을 온라인 evaluator로 (샘플링 가능)
langsmith evaluator upload evals.py \
  --name premature-edit --function check_premature_edit \
  --project ppi-agent-claude --sampling-rate 0.5

# LLM-as-judge 등록 (--model-config 필수)
langsmith evaluator create-llm \
  --name first-bad-turn --project ppi-agent-claude \
  --prompt prompt.json --schema schema.json --model-config model.json \
  --variable-mapping '{"input":"input.prompt","output":"output.trajectory"}'

성공률(Success Rate) 단독은 쓰지 않습니다. 사람이 여러 번 교정해서 결국 성공한 세션과 한 번에 성공한 세션이 같은 값으로 집계됩니다.

Phase 1의 설계 의도는 도구 없이도 성립하는 최소 가치를 먼저 확보하는 것입니다. 원본이 로컬 JSONL에 남으므로 LangSmith를 걷어내도 데이터는 남습니다.

결론. Phase 1은 로컬 JSONL + 스크립트로 시작합니다. 업로드를 켤 때는 Claude Code = 경로 B(Collector 경유), Codex = 범위 격리 또는 업로드 보류가 현재 제약에 가장 맞습니다. 개인정보 게이트를 self-hosted로 풀면 두 에이전트 모두 경로 A 단독으로 가도 됩니다.

• 미검증: langsmith-cli를 로컬에 설치하지 않았습니다. 3·8장 명령은 README(2026-09-08) 기준이며 실행 결과는 확인하지 않았습니다.
• 미검증: 플러그인이 실제로 어떤 필드까지 전송하는지(예: 훅이 주입한 시스템 컨텍스트, thinking 블록 포함 여부)는 켠 뒤 trace get --full로 직접 확인해야 합니다. 4장 판단이 바뀔 수 있습니다.
• 미검증: Claude Code의 traces는 beta이며(CLAUDE_CODE_ENHANCED_TELEMETRY_BETA), span 속성이 경로 A 플러그인만큼 상세한지 비교하지 않았습니다. 두 경로의 데이터 품질 대조가 Phase 0 과제입니다.
• 보고된 이슈(미확인): codex exec는 OTel metrics를 내보내지 않고 codex mcp-server는 telemetry를 전혀 내보내지 않는다는 보고가 있습니다(openai/codex#12913). 비대화형 실행을 수집 대상에 넣으려면 먼저 확인해야 합니다.
• 추정: 5장 turn 규칙과 6장 시그널은 로컬 트랜스크립트의 실제 필드로 확인했지만, 구현·튜닝은 하지 않았습니다.
• Judge 판정을 사람 대조 없이 지표로 쓰지 않습니다. 9장 Judge–Human Agreement가 관문입니다.
• 성공/실패 pairwise 비교는 같은 이슈의 페어가 자연 발생하지 않으므로, 동일 프롬프트를 의도적으로 재실행하는 리플레이 하네스가 먼저 필요합니다. Phase 3 이후 과제입니다.
• 런타임 핑퐁이(LiveKit·Realtime) 트레이스와 같은 프로젝트에 섞지 않습니다. 대상·판정 기준·개인정보 등급이 모두 다릅니다.