reopt-decision-traceability

---
name: reopt-decision-traceability
description: 에이전트 의사결정 과정을 사후 추적 가능하게 만들 때. 구조화된 로깅, 분산 트레이싱. 감사 요구 대응, 장애 시 원인 귀인.
---

# 의사결정 추적 (Decision Traceability)

OCLS 단계: **SHARPEN** · 판단 근거·선택 사유·협업 경로를 구조화된 로그로 남긴다.

## 핵심 규칙

- 모든 에이전트·모듈에 구조화된 의사결정 로그를 부여한다.
- 로그 필수 필드: 입력 컨텍스트, 선택한 행동과 근거, 거절한 대안, 호출 모듈과 결과, 핸드오프 대상과 사유.
- 로그 형태는 JSON 또는 OpenTelemetry span으로 표준화하고, trace ID로 에이전트 간 인과관계를 추적한다.
- 실시간 알림이 필요한 지표(가드레일 차단, 에스컬레이션)와 배치 분석이 적합한 지표(품질 분포, 비용 추세)를 구분한다.

## 판단 질문

**이 에이전트의 판단 근거를 사후에 설명할 수 있는가?**

## 적용 체크

1. 의사결정 로그에 필수 필드가 모두 포함되는가?
2. 로그 형태가 구조화(JSON/OTel)되어 있는가?
3. trace ID로 에이전트 간 인과관계를 따라갈 수 있는가?
4. 실시간 vs 배치 분석 경로가 분리되어 있는가?

## 코드 예시

```json
{
  "traceId": "tx-4521",
  "spanId": "resp-1",
  "parentSpanId": "intake-0",
  "agent": "response",
  "timestamp": "2026-04-17T10:23:11Z",
  "input": {
    "category": "배송지연",
    "sentiment": "frustrated",
    "priorResolutions": ["사과 메일"]
  },
  "decision": {
    "action": "쿠폰 제안",
    "reason": "3회차 지연 + 이전 대응이 사과만 → 보상 에스컬레이션",
    "rejectedAlternatives": [
      { "action": "재사과", "reason": "이미 시도" },
      { "action": "전액환불", "reason": "비용 과다" }
    ]
  },
  "toolCalls": [
    { "name": "coupon-generator", "result": { "value": "10%", "expiry": "30d" } }
  ],
  "handoff": null,
  "guardrails": { "triggered": [], "passed": ["PII", "cost-cap"] }
}
```

```typescript
// OpenTelemetry span 형태
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("response-agent");
await tracer.startActiveSpan("response.generate", async (span) => {
  span.setAttribute("customer.category", input.category);
  span.setAttribute("decision.action", "쿠폰 제안");
  span.setAttribute("decision.reason", reason);
  span.addEvent("alternatives-rejected", { count: 2 });
  // ...
  span.end();
});
```

## 안티패턴

**고객 상담**: 기록 없이 운영하면 "왜 이 고객에게 쿠폰이 발급되었는가"에 답할 수 없다. 감사 시 "에이전트가 자율 판단했다"는 답밖에 할 수 없고, 프롬프트 변경 전후의 의사결정 패턴 비교가 불가능해 개선이 시행착오에 의존한다.

**금융·규제 시스템**: 거래 승인·신용 판단 에이전트의 의사결정이 추적 불가하면 감독기관 요구에 대응할 수 없다. 결정 시점의 입력·적용 규칙·거절 대안을 모두 span으로 기록하고 최소 보존 기간(대개 5-7년) 이상 유지해야 한다.

## 호출 예시

```
"Response Agent에 Decision Traceability를 적용해줘.
OpenTelemetry span으로 입력 컨텍스트·선택 근거·거절 대안·핸드오프를
기록하고, trace ID를 상위 Intake Agent span과 연결해."
```

## 관련 패턴

- Module Contract — 계약 준수/위반 기록의 대상
- Evaluation and Guardrails — 평가의 입력 데이터