04 사람과 함께 조사하기

다음 학습자 수업에 대응하는 진행자용 안내서입니다: 04 사람과 함께 조사하기.

시간 배분

총 ~20분.

• 3분 — 부정적 피드백을 필터링하고 권위 있는 Chat 루트를 확인합니다.
• 4분 — 세 개의 스코어 config를 만들고, 이어서 첨부가 고정된 큐를 만듭니다.
• 4분 — 진단을 논의하기 전에 관찰 가능한 행동을 오픈 코딩합니다.
• 5분 — 트레이스 증거를 살펴보고 policy-v1/policy-v2 SQL을 나란히 실행합니다.
• 4분 — 수정 내용을 입력하고 승인·완료한 뒤 출처를 기록합니다.

진행자 사전 점검

학습자가 도착하기 전에, Module 03이 Boolean user-thumbs=false와 sql-execution-success=true를 가진 권위 있는 chat_turn 하나를 생성했는지 확인하세요. 해당 트레이스 ID는 비공개로 유지하고, 루트 출력에 질문, 생성된 SQL, 반환된 행(row), 결과가 포함되어 있는지 확인하세요.

리허설이 필요하다면 세 개의 스코어 config를 폐기 가능한 테스트 프로젝트에서 만들 수 있지만, 학습자의 최종 큐는 미리 만들지 마세요. 큐에 첨부되는 스코어 config ID 세트는 생성 시점에 고정되므로, 방 전체가 먼저 config를 만들고 세 개를 모두 첨부해야 합니다:

이 annotation 실습은 UI에서만 진행됩니다. 런타임 스크립트는 트레이스 스코어를 검증하고 이후 검토된 export를 승격시킬 수 있지만, 큐를 생성하거나 사람의 판단을 기록하거나 annotation 작업을 완료하지는 않습니다.

진행 대본

1. Tracing에서 user-thumbs = false로 필터링하고 Module 03 워크시트의 트레이스 ID와 일치하는지 확인하세요. 이렇게 말하세요: "피드백은 우리가 다음에 무엇을 조사할지를 결정할 뿐, 무엇을 결론 내릴지를 결정하지 않습니다."

2. 각 스코어 config마다 Settings → Scores → Create를 사용하세요. 그런 다음 Annotations → Queues → Create를 사용하여 큐 이름을 고유한 세션 접미사를 붙여 production-investigation-<session>으로 지정하고 세 config를 모두 첨부하세요.

3. 루트 chat_turn observation을 선택하고 Annotate 드롭다운을 열어 새 큐를 선택하세요. 자식 llm_call을 보여주되, 왜 잘못된 대상인지 설명하세요: 이 observation에는 엔드투엔드 구조화된 실행 결과가 없고, 논리적인 피드백 사건도 아닙니다.

4. 학습자에게 Module 03이 시드된 설정을 이미 공개했음을 알리고, 그 사전 지식을 잠시 접어두고 관찰 가능한 오픈 코딩을 연습하도록 요청하세요. 좋은 첫 메모의 예시는 다음과 같습니다:

   The SQL executed and returned a count. The observed count differs from the second
   reference count. The query uses a 90-day customer signup window, and the trace
   metadata reports policy-v1.

5. 방 전체가 그 메모를 기록한 후에만 전체 증거를 공개하세요: 발생한 메타데이터 policyversion=policy-v1, 가입일 기반 SQL/결과, 그리고 두 개의 스코어입니다. 소스 필드는 policy_version이며, OpenTelemetry adapter가 정제된 Langfuse 키 policyversion을 방출합니다.

6. 두 정책 정의를 나란히 실행하세요. policy-v1 참조는 다음과 같습니다:

   SELECT count() FROM v_customers
   WHERE signup_date >= today() - INTERVAL 90 DAY

   policy-v2 현재 정책 참조는 다음과 같습니다:

   SELECT uniqExact(customer_id) FROM v_orders
   WHERE order_ts >= now() - INTERVAL 30 DAY
   AND status NOT IN ('cancelled', 'returned')

7. 그 비교를 마친 후에만 진단을 적용하세요: failure-category=stale-business-policy를 기록하고, Corrected Output을 plain-text mode로 전환한 뒤 현재 원문 쿼리를 그대로 붙여넣으세요. Langfuse는 SQL을 실행하지 않으므로, approved-for-golden=true를 설정하고 작업을 완료하기 전에 6단계의 읽기 전용 클라이언트로 정확한 텍스트를 검증하세요.

8. Module 05를 위해 source_trace_id, failure_category, source_policy_version, 수정 내용, 그리고 선택적인 annotation 작업 ID를 보존하세요.

그럴듯하지만 잘못된 세 가지 진단

• "모델이 프롬프트를 무시했다." 트레이스의 SQL은 명시적인 policy-v1 컨텍스트를 그대로 따릅니다. 실패의 원인은 배포된 정책이 오래되었다는 점이며, 주어진 지시를 따르지 않은 것이 아닙니다.
• "sql-execution-success가 고장 났다." SQL은 실행되었으므로, 운영 지표 evaluator는 올바르게 true를 반환했습니다. 이 evaluator의 설계는 통제된 비즈니스적 의미를 검증하지 않습니다.
• "싫어요(thumbs-down)가 SQL이 틀렸다는 증거다." 피드백은 검토할 가치가 있는 트레이스를 식별해 줄 뿐입니다. 사용자의 의도를 명확히 하거나 검증된 대체 쿼리를 제공하지는 않으며, 이는 나란히 진행하는 정책 비교와 인간 검토가 담당합니다.

학습자가 트레이스를 오픈 코딩하기 전까지는 이 대안들을 계속 보여주세요. 시드된 정답은 진행자가 이미 알고 있지만, 조사 과정은 여전히 실제 증거 우선 검토를 모델링해야 합니다.

루트 observation 대상 지정

트레이스에는 관련된 observation이 두 개 있습니다:

학습자가 실수로 자식 observation을 추가한 경우, 이를 프로덕션 조사로서 완료하지 마세요. 루트 chat_turn을 올바른 큐에 추가하고, 잘못 만든 작업은 프로젝트의 보관 정책에 따라 남겨두거나 삭제하세요. source_trace_id로는 자식 observation ID가 아니라 트레이스 ID를 보존하세요.

고정된 큐 첨부와 재설정에 안전한 이름 짓기

Langfuse는 큐가 생성될 때 큐에 첨부되는 스코어 config ID 집합을 고정합니다. 큐는 나중에 빠진 config를 추가로 첨부할 수 없으므로, 모든 config를 먼저 만드는 것이 가장 안전한 방법입니다. 스코어 config 자체는 수정 가능합니다: 지원되는 이름, 스키마, 또는 카테고리 값 편집은 감사(audit) 기록이 남는 스코어 config 업데이트를 통해야 하며, 그 업데이트는 기존 스코어를 다시 쓰지 않습니다.

다음과 같은 재설정에 안전한 접미사를 사용하세요:

production-investigation-<session>-retry-1

큐가 config를 빠뜨렸거나 잘못된 config ID를 첨부한 경우, 세 개의 올바른 ID를 모두 가진 새 접미사 큐를 만들고 권위 있는 루트를 다시 추가한 뒤, 이전 큐를 명확히 superseded(대체됨)로 표시하세요(프로젝트 정책상 허용되는 경우에만 제거하세요). 이미 첨부된 config에 대해 지원되는 편집이 필요한 경우에는 큐를 재생성하는 대신 감사 기록이 남는 스코어 config 업데이트를 사용하세요. 완료된 큐 이름을 어떤 작업이 그 결정을 제공했는지 모호하게 만드는 방식으로 재사용하지 마세요.

수정된 출력(Corrected Output)의 신뢰성

이 수정 내용은 향후 golden ground truth가 되므로, 문법과 정책 모두가 중요합니다. 원문 SQL을 붙여넣기 전에 Corrected Output을 plain-text mode로 전환하세요. Langfuse는 텍스트를 저장하지만 실행하지는 않습니다. 승인 전에 6단계의 읽기 전용 ClickHouse 클라이언트로 정확한 텍스트를 실행해 보세요. 겉보기에는 맞아 보여도 형식이 잘못되었거나, 원시(raw) 테이블을 참조하거나, 여러 문장을 포함하거나, ClickHouse에서 실행에 실패하는 쿼리는 승인되지 않은 상태로 남겨야 합니다.

잘못된 형식의 SQL에 대해서는:

1. approved-for-golden=false로 설정하거나 그대로 둡니다;
2. 승인된 상태로 작업을 완료하지 않습니다;
3. 허용된 v_* 뷰에 맞게 수정 내용을 고칩니다;
4. 다시 실행하여 결과를 확인합니다; 그리고
5. 검증이 끝난 후에만 승인하고 완료합니다.

누군가 잘못된 형식의 수정 내용을 완료 처리한 경우, 감사 기록을 조용히 지우는 대신 새 큐/작업 접미사를 만들어 검토를 다시 진행하세요. Module 05의 승격 명령어도 읽기 전용 SQL을 검증하고 실행하지만, 그 안전장치가 인간 검토를 대체하지는 않습니다.

흔한 실패 사례

• 필터링 후 트레이스가 없음 — 스코어 유형이 Boolean인지, 필터가 user-thumbs=false인지 확인하세요. 예전 스코어 이름을 검색하지 마세요. 등급이 매겨지지 않은 curl 진단용 트레이스를 선택하지 말고 워크시트의 트레이스 ID와 일치시키세요.
• 잘못된 대상 — 작업에 전사 내용/SQL만 보이는 것은 llm_call이 추가되었기 때문입니다. 트레이스로 돌아가 루트 chat_turn을 추가하세요.
• 큐 차원이 누락됨 — 큐가 필수 첨부 config ID 없이 생성되었습니다. 새 접미사 큐를 만드세요. 불완전한 검토 폼으로 계속 진행하지 마세요. 이미 첨부된 config에 대한 지원되는 편집에는 큐 재생성이 아니라 감사 기록이 남는 config 업데이트를 사용하세요.
• 정책 메타데이터가 없는 것처럼 보임 — 소스 policy_version이 아니라 발생한 policyversion을 찾으세요. 그런 다음 루트의 policy-v1 태그를 확인하세요.
• 카운트가 예상치 못하게 일치함 — 진단을 멈추세요. Module 03의 시나리오 사전 점검을 다시 실행하고, 대조 없이 데이터 스냅샷에서 증거를 조작하지 마세요.
• 수정 내용이 원문 SQL이 아니라 서식이 입혀진 형태임 — Corrected Output을 plain-text mode로 전환하고 쿼리만 붙여넣으세요.
• 수정 내용이 실행되지 않음 — Langfuse는 이를 잡아내지 못합니다. 승인을 false로 유지하고, 수정한 뒤, 작업을 완료하기 전에 6단계의 클라이언트로 정확한 텍스트를 다시 실행하세요.

완료와 인수인계

Module 05로 넘어가기 전에, 완료된 작업이 권위 있는 chat_turn에 대한 것인지, 진단 전에 관찰 내용이 기록되었는지, 수정 내용이 정확한 현재 정책 SQL인지, 그리고 작업이 승인되었는지 확인하세요. 학습자 워크시트에는 다음이 반드시 포함되어야 합니다:

source=production-feedback
source_trace_id=<authoritative Chat trace ID>
failure_category=stale-business-policy
source_policy_version=policy-v1
annotation_id=<task ID when available>

부정적인 사용자 스코어는 트리아지 신호로서 프로덕션 트레이스에 계속 남아 있습니다. 인간 annotation은 검토된 ground truth를 제공합니다. Module 05는 수정 내용을 승격하고 예방적 evaluator를 구축할 때 이 두 출처를 모두 보존할 것입니다.