# Reliability

> Systematically review and improve AI agent reliability — identify failure patterns, assess error handling, design safeguards, and set reliability targets. Use when agents are producing inconsistent results, after incidents, or when preparing for production deployment.

- Skill: `kimsanguine/reliability` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kimsanguine/reliability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimsanguine/reliability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kimsanguine (https://skillmd.com/u/kimsanguine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimsanguine/reliability

---


# Reliability Review

> 에이전트 신뢰성 체계적 점검 및 개선

## Core Goal

- **에이전트의 "최악의 경우" 신뢰성을 정량화** — 평균이 아니라 백분위수(P95, P99)로 신뢰도 평가
- **실패 패턴을 분류하고 각각에 대한 safeguard 설계** — 입력 오류, 모델 오류, 통합 오류 등 유형별 방어책 구축
- **신뢰성 수준(Basic/Standard/High/Critical)을 비즈니스 요구에 맞추기** — 내부 도구는 95%, 고객 대면은 99.9% 같이 차등 목표 설정

---

## Trigger Gate

### Use This Skill When

- 에이전트를 프로덕션에 배포하기 전에 신뢰성 평가가 필요할 때
- incident 이후 비슷한 실패를 방지하기 위해 safeguard를 강화할 때
- 에이전트 성능이 불안정하거나 예측 불가능한 패턴을 보일 때
- SLA 보장(예: 99.5% uptime)이 필요한 고객 계약을 체결할 때

### Route to Other Skills When

- **incident** → 실제 장애가 발생한 후 근본 원인 분석과 신뢰성 개선 연결
- **이 스킬의 Pre-mortem 섹션** → 신뢰성 개선 계획의 리스크를 사전 분석할 때 (아래 "사전 위험 분석" 섹션)
- **metrics-design --step kpi** → 신뢰성을 KPI 대시보드(Success Rate, Error Rate)에 포함
- **metrics-design** (코호트 분석 섹션) → 신뢰성이 코호트(버전)별로 다르게 나타날 때 (버전 비교)

### Boundary Checks

- **기준선 데이터 부족** — 최소 1주일 이상 데이터 필요 (일일 변동성 흡수)
- **실패 분류의 표준화** — 팀마다 "에러"를 다르게 정의하면 신뢰성 측정 불가 → formula 명시
- **Safeguard 과도화** — 모든 가능한 실패에 방어책을 세우면 성능 저하 → 영향도 × 발생 확률로 우선순위화

---

## 개념

에이전트 신뢰성은 "평균적으로 잘 되는가"가 아니라 "최악의 경우에도 허용 가능한가"로 측정한다. 99%의 성공률은 100번 중 1번 실패를 의미하고, 실패 1번의 비용이 99번의 가치를 초과할 수 있다.

## Instructions

You are conducting a **reliability review** for: **$ARGUMENTS**

### Step 1 — Reliability Baseline

Collect current data:
```
Total executions (last 30 days): ___
Successful: ___ (___%)
Failed: ___ (___%)
Partially correct: ___ (___%)
```

### Step 2 — Failure Taxonomy

Classify all failures:

| Category | Count | Severity | Example |
|----------|-------|----------|---------|
| **Input Error** | | Low-High | Malformed input, missing data |
| **Model Error** | | Medium | Hallucination, wrong format |
| **Tool Error** | | Medium | API timeout, rate limit |
| **Logic Error** | | High | Wrong decision, missed edge case |
| **Output Error** | | Medium | Correct answer, wrong format |

### Step 3 — Failure Pattern Analysis

For each failure category:
```
Pattern: [description]
Frequency: [how often]
Root Cause: [why it happens]
Impact: [what goes wrong for the user]
Detection: [how we know it failed]
Recovery: [what happens after failure]
```

### Step 4 — Safeguard Design

For each high-impact failure, design a safeguard:

| Safeguard Type | When to Use | Example |
|---------------|------------|---------|
| **Input Validation** | Predictable bad inputs | Schema validation before execution |
| **Output Validation** | Format/content requirements | JSON schema check, range validation |
| **Confidence Gate** | Uncertain outputs | If confidence < 0.8, escalate to human |
| **Retry with Backoff** | Transient failures | Retry 3x with exponential backoff |
| **Fallback Path** | Critical failures | Switch to simpler model or manual flow |
| **Circuit Breaker** | Cascading failures | Stop after N consecutive failures |

### Step 5 — Reliability Target Setting

| Level | Success Rate | Meaning | Appropriate For |
|-------|-------------|---------|-----------------|
| Basic | 90% | 1 in 10 fails | Internal tools, non-critical |
| Standard | 95% | 1 in 20 fails | Regular business ops |
| High | 99% | 1 in 100 fails | Customer-facing, financial |
| Critical | 99.9% | 1 in 1000 fails | Safety, compliance |

Current level: ___
Target level: ___

### Step 6 — Improvement Roadmap

Prioritize by: Impact × Frequency × Ease of Fix
```
Quick Wins (this week):
- [ ] [safeguard 1]
- [ ] [safeguard 2]

Medium Term (this month):
- [ ] [improvement 1]
- [ ] [improvement 2]

Long Term (this quarter):
- [ ] [architecture change]
```

### Output

Reliability report card:
```
Agent: [name]
Period: [date range]
Reliability: [current%] → Target: [target%]
Top Failure: [category] ([count] occurrences)
New Safeguards: [count] implemented
Next Review: [date]
```

---

## Failure Handling

| 실패 상황 | 감지 | 대응 |
|---------|------|------|
| **신뢰성 기준선 편향** | "실패율 5%"라고 계산했으나 실패 정의가 팀마다 다름 | 실패의 정의를 formula로 명시화 (예: "응답이 0초 안에 없거나 오류 반환") → 재측정 |
| **Safeguard 성능 저하** | Confidence gate 추가 → 정확도는 올랐지만 응답 불가율 15% 증가 | 임계값 조정 (confidence threshold 하향) 또는 fallback path 개선 |
| **특정 입력에만 실패** | 대부분의 요청은 성공하는데 특정 패턴(예: 특수문자 포함)에서만 오류 | Input validation 강화, 실패 입력 타입별 분류, 패턴별 safeguard 설계 |
| **신뢰성 목표 달성 불가** | 99% 목표는 설정했으나 현재 95% → 4% gap을 닫을 방법 부족 | 1) 빠른 개선 가능한 것(Input validation) 먼저 시행 2) 장기 아키텍처 개선 분리 |
| **Safeguard 비용** | Retry with backoff 추가 → 토큰 비용 20% 증가 | 비용-신뢰성 트레이드오프 명시 (비용 +$100/월로 reliability 98% → 99% 달성), 의사결정 |

---

## Quality Gate

- [ ] 현재 신뢰성 기준선(Success Rate, Error Rate)이 명확하게 정의되고 측정되었는가? (Yes/No)
- [ ] 실패가 5가지 이상의 카테고리(Input, Model, Tool, Logic, Output)로 분류되었는가? (Yes/No)
- [ ] 각 실패 카테고리별로 패턴 분석(Frequency, Root Cause, Impact, Detection, Recovery)이 완료되었는가? (Yes/No)
- [ ] 높은 영향도(High impact) 실패 각각에 대해 safeguard가 설계되었는가? (Yes/No)
- [ ] 신뢰성 목표 수준(Basic/Standard/High/Critical)이 비즈니스 요구와 정렬되었는가? (Yes/No)
- [ ] 현재 수준 → 목표 수준까지의 로드맵(Quick Wins, Medium Term, Long Term)이 명시되었는가? (Yes/No)

---

## Examples

### Good Example

```
신뢰성 리뷰: 내부 업무 효율화 에이전트

기준선 (30일):
├── 총 실행: 2,400건
├── 성공: 2,280건 (95%)
├── 실패: 120건 (5%)
└── 부분 성공: 0건

실패 분류:

| 카테고리 | 개수 | 원인 예시 | 심각도 |
|---------|------|---------|-------|
| Input Error | 30 | 잘못된 형식(JSON 미형성) | Low |
| Model Error | 60 | 환각, 형식 오류 | Medium |
| Tool Error | 20 | API timeout | High |
| Logic Error | 8 | 조건 검사 누락 | High |
| Output Error | 2 | 너무 긴 응답 | Low |

Safeguard 설계:

High Impact 3가지:
1. Model Error (60개) → Confidence gate (threshold 0.7)
   - Expected: 실패 60→ 40 (667% 개선 예상 시간: 5일)

2. Tool Error (20개) → Retry with exponential backoff
   - Expected: 실패 20→ 5 (timeout 복구율 75%)

3. Input Error (30개) → JSON schema validation
   - Expected: 실패 30→ 2 (거의 전부 사전 차단)

목표 수준: High (99%)
- 현재: 95%
- 3주 후: 98% (safeguard 1,3 적용)
- 6주 후: 99% (safeguard 2까지 추가)
```

### Bad Example

```
"에이전트의 신뢰성이 좋지 않은 것 같다"

❌ 문제점:
- "신뢰성"의 정의가 주관적 (기준선 없음)
- 실패 분류 없음 (어떤 실패가 몇 개인지 모름)
- Safeguard 미설계 (대응 방법 불명확)
- 목표 수준 미설정 (뭐가 "좋은" 신뢰성인지 불명확)
- 개선 로드맵 없음

→ 재작업: 기준선 수집 → 실패 분류 → 패턴 분석 → safeguard 설계 → 목표 설정 → 로드맵 수립
```

---

---

## 사전 위험 분석 (Pre-mortem)

배포 전 "이 에이전트가 3개월 후 완전히 실패했다고 가정하자. 왜 실패했을까?"로 시작하는 FMEA 체크리스트.

### Pre-mortem Exercise

배포 전 최소 5개의 실패 시나리오를 도출한다:
```
"The agent failed because..."
1. ___ (모델 실패 — 환각, 컨텍스트 윈도우 오버플로우, prompt injection)
2. ___ (데이터 실패 — upstream API 변경, PII 유출, 데이터 드리프트)
3. ___ (통합 실패 — API rate limit, 인증 토큰 만료, 버전 불일치)
4. ___ (비즈니스 실패 — 비용 초과, 낮은 사용자 채택, 규제 위반)
5. ___ (운영 실패 — 모니터링 부재, 알림 미설정, 대응 절차 없음)
```

### RPN 기반 우선순위화

**RPN** = Severity × Probability × Detection (각 1-10)
- Detection: 1 = 쉽게 감지, 10 = 감지 불가능
- RPN > 100 고위험: 재설계 또는 완화 조치 필수
- RPN 50-100 중위험: Yellow alert 설정 + 제한된 범위로 시작
- RPN < 50 저위험: 모니터링으로 충분

### 배포 Go/NoGo 기준

| RPN 범위 | 의사결정 | 조건 |
|:--------:|---------|------|
| < 50 | GO | 모니터링 설정으로 충분 |
| 50-100 | CONDITIONAL GO | Prevention 구현 + Yellow alert 필수 |
| > 100 | NO-GO | Prevention 전략 완성 + Red alert 구현 후 재검토 |

### Pre-mortem 체크리스트

- [ ] 5개 이상의 실패 시나리오가 도출되었는가?
- [ ] 모델·데이터·통합·비즈니스 4가지 카테고리가 모두 포함되었는가?
- [ ] RPN > 100 고위험 항목 각각에 Prevention/Detection/Response/Recovery 전략이 있는가?
- [ ] 배포 Go/NoGo 기준이 명시되었는가?
- [ ] 분기별 재검토 일정이 예정되었는가?

---

## Further Reading
- Google SRE Book — Site Reliability Engineering principles
- Anthropic, "Building Effective Agents" (2024) — Error handling patterns
- Gary Klein, "Performing a Project Premortem" — HBR, 2007
- IEC 60812 — FMEA standard methodology

## Contextual Knowledge (auto-loaded)

> 보조 파일이 존재할 때만 자동 로드됩니다. 파일이 없으면 건너뜁니다.

### Good Example
!`cat examples/good-01.md 2>/dev/null || echo ""`

### Bad Example
!`cat examples/bad-01.md 2>/dev/null || echo ""`

### Domain Context
!`cat context/domain.md 2>/dev/null || echo ""`

### Test Cases
!`cat references/test-cases.md 2>/dev/null || echo ""`

### Troubleshooting
!`cat references/troubleshooting.md 2>/dev/null || echo ""`