---
id: software-failure-library
title: "소프트웨어 실패 라이브러리"
category: "Software_Engineering"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["failure library", "실패 라이브러리", "failure modes", "장애 모드 카탈로그", "how things break"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.89
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["failure", "engineering", "debugging", "patterns", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI 사후기록(lock/retrieval/dispatcher 등)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[소프트웨어 실패 라이브러리]]

## 🎯 한 줄 통찰 (One-line insight)
모든 아키텍처 패턴은 *특유의 방식으로 깨진다* — 패턴별 (장애 모드 → 증상 → 근본 원인 → 진단 → 복구 → 예방)을 알면, AI/개발자가 실패를 *조기에 인식하고 회피* 할 수 있다. 이것이 패턴 카탈로그의 어두운 쌍둥이다.

## 🧠 핵심 개념 (Core concepts)
각 패턴 항목 = **Failure Modes / Symptoms / Root Causes / Debugging / Recovery / Prevention**. 패턴 카드의 "실패 사례" 와 [[디버깅 플레이북]] 을 패턴 축으로 재구성.

## 📖 세부 내용 (Details · 패턴별 실패)

### [[RAG Pattern]] / [[Caching Pattern]]
- **Failure Modes:** 낮은 recall, 무관 상위, stale 결과, 빈 결과.
- **Symptoms:** "분명 있는데 못 찾음", 엉뚱한 인용, 옛 데이터 제공.
- **Root Causes:** 동의어 미확장, 하이브리드 부분 정규화(편향), 청크 과대, 인덱스 stale, 무효화 누락.
- **Debugging:** fusionLog 단계 카운트, recall@k 평가, 점수 분포, mtime 비교.
- **Recovery:** 동의어 추가, α 조정, 인덱스 재빌드, 캐시 무효화.
- **Prevention:** 평가 하니스 정기 실행(프로덕션 동일 경로), 동일 스케일 정규화, 변경 감지 무효화.

### [[Memory Pattern]]
- **Failure Modes:** 옛 사실 재현, 기억 미반영, 잘못된 계층.
- **Symptoms:** 만료 지식이 현재처럼, 사용자 정보 망각.
- **Root Causes:** expiresAt 미설정, 추출 빈 catch 삼킴, 관련도 오선별, 분류 모호.
- **Debugging:** 계층별 컨텍스트 출력, 만료 필드, distillation 로그.
- **Recovery:** 만료 부여/엔트리 삭제(파일 편집), 재추출.
- **Prevention:** 시한부엔 만료, 분류 규칙 명문화, 증류로 정리.

### [[Agent Orchestration Pattern]] / [[Reflection Pattern]] / [[Critic Pattern]]
- **Failure Modes:** "방법론만 생성", 환각 통과, OOM, latency 폭증, 무한 루프.
- **Symptoms:** 실제 산출물 없음, 근거 없는 단정, 모델 로드 실패, 느림.
- **Root Causes:** 에이전트 남발(hop 손실), 병렬 다중 상주, 무조건 LLM 검수, 종료 조건 부재, JSON 직접 파싱.
- **Debugging:** 단계 인디케이터, peer-context 길이, 확신도 factor, raw 응답, lifecycle.
- **Recovery:** 단일 작성자 전환, 순차+한 모델, 조건부 검수, 라운드 상한, 균형 괄호 파서.
- **Prevention:** "에이전트 추가 전 정보 손실 점검", 자원 기준 동시성, 결정론 우선 검증.

### [[Tool Calling Pattern]] / [[Command Pattern]]
- **Failure Modes:** 임의 명령 실행, 경로 탈출, 무한 호출, undo 불완전.
- **Symptoms:** 보안 사고, 권한 밖 파일 접근, 반복 실행.
- **Root Causes:** 모델 출력 미검증, 경로 미검증, 승인 게이트 부재, 멱등성 부재.
- **Debugging:** 액션 파싱 로그, 검증 결과, 승인 큐 상태.
- **Recovery:** 화이트리스트 제한, 승인 요구, 롤백.
- **Prevention:** 모델 출력을 신뢰 안 된 입력으로, validatePath/sanitize, 승인 게이트.

### [[State Management Pattern]] / [[React State Pattern]] / [[Data Flow Pattern]]
- **Failure Modes:** 동기화 버그, stale 파생, 불필요 리렌더, 역류.
- **Symptoms:** 같은 데이터 불일치, 화면-데이터 어긋남, 성능 저하.
- **Root Causes:** 중복 상태, 파생값 저장, 서버/클라 상태 혼동, 전역 남용, 경계 정규화 누락.
- **Debugging:** 상태 출처 추적, 변경 로그, 리렌더 프로파일.
- **Recovery:** 단일 출처로 통합, 파생은 계산, 서버 상태 분리.
- **Prevention:** SSOT, 단방향 흐름, 경계 정규화.

### [[Async Concurrency Pattern]] / [[Background Worker Pattern]] / [[Background Task Pattern]]
- **Failure Modes:** 데드락, 락 누수, 좀비 작업, OOM, 중복 실행, UI 멈춤.
- **Symptoms:** 멈춤, 메모리 증가, 같은 작업 N번, 응답 없음.
- **Root Causes:** release 누락, 취소 미전파, 무한 병렬, 재진입, 객체 동일성 비교(L-02), dispose 누락.
- **Debugging:** active lock 수, 타임아웃 위치, 큐 길이, 메모리 추세.
- **Recovery:** try/finally release, 동시성 상한, 재진입 가드, 토큰 정리.
- **Prevention:** 락은 try/finally, AbortSignal 전파, 하드웨어 기준 동시성, 멱등성.

### [[Event Bus Pattern]] / [[IPC Pattern]] / [[Plugin Architecture Pattern]]
- **Failure Modes:** 추적 불가 흐름, 리스너 누수, 직렬화 실패, 플러그인이 코어 크래시.
- **Symptoms:** "누가 이걸 했지?", 중복 핸들러, 통신 행, 앱 죽음.
- **Root Causes:** 리스너 해제 누락, 외부 입력 미검증, 함수/순환 직렬화, 플러그인 격리 부재, 이벤트 이름 오타.
- **Debugging:** 리스너 목록, 메시지 로그, 직렬화 검증, 플러그인 로드 로그.
- **Recovery:** 해제 추가, 입력 검증, 명시 타입(enum), 플러그인 try/catch 격리.
- **Prevention:** 이벤트 카탈로그, 신뢰 경계 검증, 안정된 확장 계약.

### [[Repository Pattern]] / [[Local Storage Pattern]] / [[이벤트 소싱 스토어 패턴]] / [[Offline Sync Pattern]]
- **Failure Modes:** 데이터 손실/중복, 파일 폭증, 마이그레이션 크래시, 충돌 미해소.
- **Symptoms:** 불일치, 업데이트 후 크래시, 동기화 후 데이터 사라짐.
- **Root Causes:** 멱등 키 부재, LWW 손실, compaction 부재, 스키마 버전 무시, 손상 줄 미격리, 민감정보 평문.
- **Debugging:** 줄 단위 파싱 검사, 버전 필드, outbox 순서, 충돌 로그.
- **Recovery:** 멱등 키 도입, 충돌 해소(버전 벡터/사용자), 스냅샷, 부분 격리 파싱.
- **Prevention:** 변경에 고유 id, 데이터 성격별 매체, 손상 줄 skip, 보안 저장소.

### [[JWT Authentication Pattern]] / [[Push Notification Pattern]] / [[Navigation Pattern]] / [[Infinite Scroll Pattern]]
- **Failure Modes:** 토큰 탈취 지속, 알림 미수신, 딥링크 깨짐, 목록 중복/렉.
- **Symptoms:** 로그아웃 안 됨, 알림 안 옴, 뒤로가기 길 잃음, 스크롤 끊김.
- **Root Causes:** localStorage 저장/회전 부재, 전달 보장 가정, 객체 라우트 인자, offset 페이징/가상화 부재.
- **Debugging:** 토큰 수명/저장 위치, 전송 로그, 라우트 직렬화, 요청 중복.
- **Recovery:** httpOnly+회전, 중요 데이터는 동기화로, 커서 페이징, 가상화.
- **Prevention:** 짧은 만료+회전, 알림은 유도만, 직렬화 가능 라우트, 커서+가상화.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
실패 모드는 *맥락 의존* — 같은 증상도 원인이 다를 수 있다. "증상→가설→*측정으로 검증*→최소 변경" 순서를 지키고, 추측만으로 재시작/롤백하지 마라([[디버깅 플레이북]]).

## 🛠️ 적용 사례 (Applied in summary)
AstraAI 가 실제로 겪은 실패(락 동일성, 하이브리드 스케일, 에이전트 hop 손실, OOM)가 각 항목의 근거. → [[교훈 라이브러리 Lessons Learned]].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[디버깅 플레이북]], [[교훈 라이브러리 Lessons Learned]], [[안티패턴 카탈로그]]
- **참조 맥락:** 작은 모델이 패턴을 적용할 때 "이 패턴이 어떻게 깨지는가" 를 함께 학습해 회피.

## 📚 출처 (Sources)
- [S1] 일반 소프트웨어 장애/디버깅 지식
- [S2] AstraAI 사후기록(lock.ts, retrieval/index.ts, dispatcher.ts 등) — 실증 근거

## 📝 변경 이력 (Change history)
- 2026-06-13: 패턴별 실패 지식 라이브러리 초안.