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:

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:

Step 5 — Reliability Target Setting

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

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 기준

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 ""