04 사람과 함께 조사하기

시작점

Module 03에서는 How many active customers do we have?에 대해 의도적인 불일치가 있는 하나의 공식 Chat trace를 생성했습니다.

해당 trace ID/URL과 워크시트에 기록한 두 개의 참조 카운트를 계속 보관하세요. Module 03의 평점이 없는 curl 진단 결과는 사용하지 마세요.

사람의 조사가 필요한 이유

썸다운은 팀이 어디를 봐야 할지 알려줄 뿐, 무엇이 실패했는지는 알려주지 않습니다. 사용자가 다른 것을 의도했을 수도 있고, 요청이 모호했을 수도 있고, 생성된 SQL이 유효하지 않았을 수도 있고, 두 가지 비즈니스 정의가 서로 다를 수도 있습니다. 모든 부정적 신호를 곧바로 골든 데이터셋으로 승격시키면 추측이 그라운드 트루스가 되어 버립니다.

이 모듈에서는 리뷰어가 먼저 관찰 가능한 사실을 기록하고, 가능한 설명들을 검증한 다음에야 진단과 수정을 기록합니다. 썸다운이 아니라 그 검토된 결정이야말로 Module 05로 전달되는 그라운드 트루스입니다.

목표

Module 03의 루트 chat_turn에 대해 production-investigation-<session> annotation 작업 하나를 완료하세요. 완료된 작업에는 observation, failure category, 정확한 수정 SQL, 골든 데이터셋 승인, production provenance가 모두 포함되어야 합니다.

1단계 — 정확한 피드백 사고 찾기

Langfuse에서 Tracing을 열고 Boolean score user-thumbs = false로 필터링합니다. 다음 조건을 모두 만족하는 trace를 여세요.

• 이름/루트 observation이 chat_turn일 것;
• 질문이 How many active customers do we have?일 것;
• Module 03에서 기록한 승자 config_id와 trace ID와 일치할 것;
• 메타데이터가 policyversion=policy-v1일 것; 그리고
• score가 sql-execution-success=true와 user-thumbs=false일 것.

서빙 소스는 policy_version을 내보내지만, OpenTelemetry 어댑터가 밑줄(underscore)을 제거하기 때문에 Langfuse 메타데이터 키는 policyversion이 됩니다.

2단계 — 세 가지 리뷰 score config 만들기

이 설정은 의도적으로 UI 전용 human-review 단계입니다. 워크숍 리포지토리에는 이 annotation 작업을 대신 생성하거나 완료해 주는 명령이 없습니다.

큐를 만들기 전에 Settings → Scores → Create를 열고 다음 config들을 만드세요.

이름과 하이픈 표기를 정확히 그대로 사용하세요. config를 먼저 만드는 것이 가장 안전한 방법인데, 이는 큐에 첨부된 score-config ID 집합이 큐 생성 시점에 고정되기 때문입니다. 만약 어떤 config가 그 첨부 집합에서 빠졌다면, 새로운 suffix로 새 큐를 만드세요. score config 자체는 수정 가능합니다: 지원되는 이름, 스키마, 카테고리 변경은 감사 가능한(audited) score-config 업데이트로 이루어져야 하며, 그런 수정은 이미 존재하는 score를 다시 쓰지 않습니다.

3단계 — 큐를 만들고 논리적 루트를 대상으로 지정

Annotations → Queues → Create를 열고 다음을 수행합니다.

1. <session>을 짧고 고유한 워크숍 식별자로 바꿔 production-investigation-<session>으로 이름을 지정합니다.
2. 2단계의 세 score config를 모두 첨부합니다.
3. 큐를 생성합니다.
4. Module 03의 trace로 돌아가 루트 chat_turn observation을 선택하고, Annotate 드롭다운을 열어 이 큐를 선택합니다.
5. 새 작업을 열어 대상이 chat_turn이고 llm_call이 아닌지 확인합니다.

큐는 생성 후에는 첨부된 score-config ID를 변경할 수 없습니다. 그 첨부 집합이 잘못된 경우에만 다시 만드세요; 이미 첨부된 config에 대해 지원되는 수정이 필요하면 감사 가능한 score-config 업데이트를 사용하세요.

4단계 — 관찰할 수 있는 것을 오픈코드로 작성

Module 03은 의도적으로 시드된 설정을 공개했습니다. 이 조사에서는 그 사전 워크숍 지식을 잠시 접어두고, 리뷰어가 미지의 사고에 사용할 만한 워크플로를 연습하세요: 원인을 지목하기 전에 질문, 생성된 SQL, 반환된 카운트, 모델/프롬프트, 그리고 두 score를 모두 살펴봅니다. observed-issue에 증거만 담은 노트를 입력하세요. 예:

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

이 문구는 아직 모델, SQL 엔진, 사용자, 정책 중 무엇이 잘못됐는지 주장하지 않습니다. 이러한 분리는 증거를 확인하기 전에 시드된 진단이 리뷰에 몰래 끼어드는 것을 막아 줍니다.

5단계 — 전체 trace 증거 검사

여전히 루트 chat_turn에서 다음을 확인하세요.

• 메타데이터 policyversion=policy-v1;
• 생성된 SQL이 v_customers와 90일 signup_date 윈도우를 사용함;
• 구조화된 결과에 Module 03에서 관찰된 trace 카운트가 포함됨;
• 운영 score가 Boolean sql-execution-success=true임; 그리고
• 사용자 신호가 Boolean user-thumbs=false임.

생성된 SQL은 릴리스가 제공한 policy-v1 지침과 일치합니다. 성공적인 실행 score 역시 의도적으로 좁게 설정된 범위 안에서는 맞습니다. 이 시점까지는 어느 쪽 사실도 그 배포된 정책이 현재 거버넌스 정의와 일치하는지는 확인해 주지 않습니다.

6단계 — 두 정책 정의를 나란히 테스트

ClickHouse_Demos/workshops/agent_arena에서 동일한 환경 내에서 두 개의 읽기 전용 정의를 모두 실행하세요.

source .env
.venv/bin/python - <<'PY'
from arena.config import load_config
from agents.chclient import ROClickHouseClient

queries = {
    "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')""",
}
client = ROClickHouseClient(load_config().clickhouse)
for version, sql in queries.items():
    result = client.query(sql)
    print(f"{version}: {result.rows[0][0]}")
PY

두 카운트는 워크시트 값과 일치해야 하며 서로 달라야 합니다. 이제 오래된 (stale) 배포 비즈니스 정의를 진단할 충분한 증거가 확보되었습니다: trace는 policy-v1을 표시하고, 그 SQL은 해당 정책을 따르며, 검증된 현재 쿼리는 policy-v2를 구현합니다.

7단계 — Annotate, 수정, 승인, 완료

annotation 작업으로 돌아가 다음을 기록하세요.

Corrected Output을 plain-text mode로 전환한 다음, 다음의 정확한 원본 SQL을 입력하세요.

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

Langfuse는 이 수정 사항을 기록할 뿐, SQL을 실행하지 않습니다. 6단계의 읽기 전용 ClickHouse client가 승인 전에 정확히 이 텍스트를 성공적으로 실행한 상태여야 합니다. 수정 사항을 편집한다면, 동일한 client로 그 텍스트를 다시 실행하세요. 그런 다음 Complete(또는 Complete + next)를 선택하세요. 형식이 잘못되었거나 실행 불가능하거나 검증되지 않은 수정 사항은 골든 그라운드 트루스로 승인해서는 안 됩니다.

8단계 — Module 05 provenance 기록

다음 값들을 워크시트에 복사하세요. ID는 워크숍 프로젝트 내부에만 비공개로 유지하세요.

source_trace_id, failure_category, source_policy_version은 production 기반 골든 레코드에 필수입니다. annotation_id는 런타임에서는 선택 사항이지만, UI에 노출되면 결정을 감사 가능하게 유지하기 위해 기록하세요.

완료 여부 확인 방법

• user-thumbs=false인 단일 Module 03 Chat trace를 조사했습니다.
• annotation 대상은 루트 chat_turn이며, 절대 자식 llm_call이 아닙니다.
• 큐 이름은 production-investigation-<session>이며, 세 가지 올바른 타입의 score config를 모두 포함합니다.
• observed-issue는 진단보다 먼저 관찰된 행동을 기록합니다.
• 오래된 SQL과 현재 SQL을 나란히 실행하여 서로 다른 카운트임을 확인했습니다.
• 완료된 작업에는 stale-business-policy, 정확한 수정 SQL, approved-for-golden=true가 기록되어 있습니다.
• 워크시트는 실제 trace ID나 프로젝트 URL을 공개하지 않으면서 Module 05를 위한 production provenance를 보존합니다.
• 썸다운이 사람의 검토를 우선시하지만 그 자체로는 그라운드 트루스가 되지 않는 이유를 설명할 수 있습니다.

Module 05 — 루프 닫기로 이동하여 검토된 수정 사항을 승격하고, 정책 버전을 비교하며, 동일한 종류의 실패가 온라인에서 재발하지 않도록 방지하세요.