Files

T

Antigravity Agent e2c5471046 wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 09:55:38 +09:00

8.3 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

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

🎯 한 줄 통찰 (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, 보안 저장소.

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: 패턴별 실패 지식 라이브러리 초안.

8.3 KiB Raw Blame History