reopt-evaluation-and-guardrails

---
name: reopt-evaluation-and-guardrails
description: When agent output needs quality and safety validation. Deciding whether to place guardrails before or after execution. Designing an evaluation pipeline, hallucination detection, blocking forbidden actions.
---

# 평가와 가드레일 (Evaluation and Guardrails)

OCLS 단계: **SHARPEN** · 허용 가능한 판단과 위험한 판단을 평가 기준과 안전 규칙으로 구분한다.

## 핵심 규칙

- 모든 에이전트와 모듈에 정량적 평가 기준(성공률, 응답 품질 점수, 비용 효율)과 안전 가드레일(비용 상한, 권한 범위, 금지 행동 목록)을 함께 부여한다.
- 가드레일은 실행 전에, 평가는 실행 후에 작동한다.
- 평가 점수가 임계치 이하이면 자동 경보 또는 실행 중단 정책을 적용한다.
- 비결정적 에이전트에는: 도구성 사용은 pass@k(k번 시도 중 1번이라도 성공), 일관성이 요구되는 고객 대면 서비스는 pass^k(k번 모두 성공)를 사용한다.
- 평가를 역량 평가(통과율 낮은 어려운 과제)와 회귀 평가(100% 유지, 회귀 감지)로 분리한다. 역량이 안정되면 회귀 평가로 "졸업"시킨다.

## 판단 질문

**우리는 어떤 기준으로 품질과 위험을 측정하는가?**

## 적용 체크

1. 정량적 평가 기준(점수, 임계치)이 정의되어 있는가?
2. 사전 가드레일과 사후 평가가 모두 적용되어 있는가?
3. 임계치 위반 시 자동 조치(경보, 차단)가 있는가?
4. 역량 평가와 회귀 평가의 경계가 선언되어 있는가?

## 코드 예시

```typescript
// 사전 가드레일 (실행 전)
function preGuard(input: RequestInput): GuardResult {
  if (detectPII(input.text)) return { block: true, reason: "PII detected" };
  if (input.text.length > 5000) return { block: true, reason: "input too long" };
  if (estimateCost(input) > 0.5) return { block: true, reason: "cost cap" };
  return { block: false };
}

// 사후 평가 (실행 후)
interface EvalCriteria {
  relevance: { min: 0.8 };
  toneConsistency: { min: 0.7 };
  hallucination: { max: 0 };
}

async function evaluate(response: Response, graders: Grader[]): Promise<Score> {
  const results = await Promise.all(graders.map((g) => g.grade(response)));
  return aggregate(results);
}

// 역량 평가: 어려운 케이스 — 낮은 통과율에서 시작
const capabilityEval = new EvalSet("hard-legal-cases", { target: 0.6 });
// 회귀 평가: 통과한 케이스 — 100% 유지 필요
const regressionEval = new EvalSet("passed-cases", { target: 1.0 });
```

## 안티패턴

**고객 응대**: 기준 없이 운영하면 "고객 불만이 늘었는데 이유를 모른다"가 반복된다. 가드레일 없이 운영하면 카드 번호를 응답에 그대로 실어 보내거나, 존재하지 않는 환불 정책을 만들어내는 사고를 사후에야 발견한다.

**코딩 에이전트**: 평가 없이 코드 생성을 반복하면 모델 업그레이드의 영향을 판단할 데이터가 없다. 테스트 통과율과 보안 취약점 감지율을 회귀 평가로 잠가두면 회귀가 생기는 즉시 잡아낸다.

## 호출 예시

```
"Response Agent에 평가와 가드레일을 추가해줘.
사전 가드레일: PII, 비용, 길이 검사.
사후 평가: relevance ≥ 0.8, tone consistency ≥ 0.7, hallucination = 0.
역량 평가(어려운 케이스)와 회귀 평가(통과 케이스)를 분리해줘."
```

## 관련 패턴

- 모듈 계약 — 계약 위반 감지의 기준
- 인간 승인 — 평가 실패 시의 에스컬레이션 경로
- 의사결정 추적 — 평가 결과의 기록