reopt-decision-traceability

---
name: reopt-decision-traceability
description: When agent decision paths must be traceable after the fact. Structured logging, distributed tracing. Responding to audit requirements; attributing the cause of an incident.
---

# 의사결정 추적 (Decision Traceability)

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

## 핵심 규칙

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

## 판단 질문

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

## 적용 체크

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

## 코드 예시

```json
{
  "traceId": "tx-4521",
  "spanId": "resp-1",
  "parentSpanId": "intake-0",
  "agent": "response",
  "timestamp": "2026-04-17T10:23:11Z",
  "input": {
    "category": "shipping-delay",
    "sentiment": "frustrated",
    "priorResolutions": ["apology email"]
  },
  "decision": {
    "action": "offer coupon",
    "reason": "3번째 지연 + 이전 처리가 사과 메일뿐 → 보상 단계 상향",
    "rejectedAlternatives": [
      { "action": "re-apology", "reason": "이미 시도함" },
      { "action": "full refund", "reason": "비용 과다" }
    ]
  },
  "toolCalls": [
    { "name": "coupon-generator", "result": { "value": "10%", "expiry": "30d" } }
  ],
  "handoff": null,
  "guardrails": { "triggered": [], "passed": ["PII", "cost-cap"] }
}
```

```typescript
// OpenTelemetry 스팬 형태
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", "offer coupon");
  span.setAttribute("decision.reason", reason);
  span.addEvent("alternatives-rejected", { count: 2 });
  // ...
  span.end();
});
```

## 안티패턴

**고객 응대**: 기록 없이 운영하면 "이 고객에게 왜 쿠폰이 발급되었는가"에 답할 수 없다. 감사 때 "에이전트가 알아서 결정했다"는 답밖에 못 한다. 프롬프트 변경 전후의 의사결정 패턴도 비교할 수 없어 개선이 시행착오에 그친다.

**금융/규제 시스템**: 거래 승인이나 신용 판단 에이전트가 추적 불가능하면 규제 기관의 요청에 답할 수 없다. 입력, 적용 규칙, 거부된 대안을 스팬으로 기록하고, 규제 최소 보관 기간(보통 5~7년) 동안 보존하라.

## 호출 예시

```
"Response Agent에 의사결정 추적을 적용해줘.
입력 컨텍스트, 선택 근거, 거부된 대안, 핸드오프를 OpenTelemetry 스팬으로
기록하고, trace ID로 부모인 Intake Agent 스팬과 연결해줘."
```

## 관련 패턴

- 모듈 계약 — 준수/위반 기록이 참조하는 기준
- 평가와 가드레일 — 평가의 입력 데이터