Antigravity Agent
1cfd3bbb56
Topic_CSS/Topic_HTML/Topic_JavaScript/Topic_Prompt/Topic_Comfyui 등 기존 카테고리 폴더를 정리하고, Topic_Graphic/Dev 등 신규 산출물과 Topics 내부 세션/메모리 기록을 동기화.
101 lines
6.3 KiB
Markdown
101 lines
6.3 KiB
Markdown
---
|
||
id: debugging-playbook
|
||
title: "디버깅 플레이북"
|
||
category: "Software_Engineering"
|
||
status: "draft"
|
||
verification_status: "applied"
|
||
canonical_id: ""
|
||
aliases: ["debugging playbook", "디버깅", "장애 모드", "failure mode", "복구 절차", "진단 단계"]
|
||
duplicate_of: ""
|
||
source_trust_level: "A"
|
||
confidence_score: 0.88
|
||
created_at: 2026-06-13
|
||
updated_at: 2026-06-13
|
||
review_reason: ""
|
||
merge_history: []
|
||
tags: ["debugging", "failure-modes", "diagnostics", "recovery", "astraai"]
|
||
raw_sources: ["AstraAI/src/core/errorHandler.ts", "AstraAI/src/core/services.ts", "AstraAI/src/retrieval/index.ts", "AstraAI/src/core/lock.ts", "AstraAI/src/lmstudio/lifecycleManager.ts"]
|
||
applied_in: ["AstraAI"]
|
||
github_commit: ""
|
||
---
|
||
|
||
# [[디버깅 플레이북]]
|
||
|
||
## 🎯 한 줄 통찰 (One-line insight)
|
||
디버깅은 "증상에서 근본 원인으로 좁혀 들어가는" 체계적 절차이며, 서브시스템별로 *흔한 장애 모드·진단 순서·복구·예방* 을 미리 정리하면 사람과 AI 에이전트 모두 빠르게 고친다.
|
||
|
||
## 🧠 핵심 개념 (Core concepts)
|
||
각 서브시스템: **흔한 장애 모드 / 근본 원인 / 진단 단계 / 복구 절차 / 예방**. 공통 원칙: 증상→가설→*측정으로 검증*→최소 변경.
|
||
|
||
## 📖 세부 내용 (Details · 서브시스템별)
|
||
|
||
### LLM 호출 / 엔진 ([[LLM 프로바이더 추상화]])
|
||
- **장애:** 빈 응답, timeout, 연결 거부(ECONNREFUSED), 404 모델 없음.
|
||
- **근본 원인:** 엔진 미실행, 모델 미로드, URL 오설정, 작은 모델의 빈 출력.
|
||
- **진단:** ErrorTranslator 카테고리 확인 → 엔진 상태(health) → 모델 목록 → fusionLog/로그.
|
||
- **복구:** 다른 로컬 엔진 폴백(자동), 모델 재선택(lifecycle 재로드), timeout 상향.
|
||
- **예방:** system 프롬프트 항상 채움(빈 응답↓), 폴백 경로 유지, 빈 응답을 soft failure 로 명시.
|
||
|
||
### 동시성 / 락 ([[동시성 제어 Lock Queue Transaction]])
|
||
- **장애:** 데드락, 락 누수, 갱신 손실, 락 타임아웃.
|
||
- **근본 원인:** release 누락(try/finally 없음), 동일성 비교 실수(L-02 토큰), 자원 직렬화 누락.
|
||
- **진단:** `getActiveLockCount()` 추세, 타임아웃 에러 위치, 같은 resourceId 경합 로그.
|
||
- **복구:** 타임아웃으로 깨운 뒤 재시도/안내, 프로세스 재시작(메모리 락 해제).
|
||
- **예방:** 락은 반드시 try/finally, 토큰 기반 정리, 무거운 작업은 missionId 직렬화.
|
||
|
||
### 검색 / RAG ([[RAG 검색 파이프라인]])
|
||
- **장애:** 관련 문서 누락(낮은 recall), 무관 문서 상위, 빈 결과.
|
||
- **근본 원인:** 토큰화/동의어 누락, 하이브리드 스케일 편향, 운영 로그 미제외, 인덱스 stale.
|
||
- **진단:** `fusionLog` 단계별 카운트, `rankBrainForEval`(recall@k), 토큰/예산 사용량, 청크 점수 분포.
|
||
- **복구:** 동의어 추가, blend α 조정, 인덱스 clear/재빌드, scopeFolders 점검.
|
||
- **예방:** 평가 하니스 정기 실행(프로덕션과 동일 경로), 정규화 일관, mtime 인덱스 무결성.
|
||
|
||
### 메모리 ([[5계층 메모리 시스템]])
|
||
- **장애:** 오래된 사실을 현재처럼 답함, 기억 미반영, 잘못된 계층 선택.
|
||
- **근본 원인:** `expiresAt` 미설정, 추출 실패(빈 catch 삼킴), 관련도 휴리스틱 오선별.
|
||
- **진단:** 계층별 buildContext 출력 확인, 만료 필드 점검, distillation 로그.
|
||
- **복구:** 만료 부여/엔트리 삭제(파일 직접 편집 가능 — 투명성), 재추출.
|
||
- **예방:** 시한부 지식에 expiresAt, 분류 규칙 명문화([[아키텍처 휴리스틱]]).
|
||
|
||
### 검증 / 환각 ([[Intelligence 검증 레이어]])
|
||
- **장애:** 환각(근거 없는 단정), 과도한 헤지, 위험 답변 미검수.
|
||
- **근본 원인:** 검색 근거 0인데 단정, 확신도 임계 오설정, JSON 파싱 실패.
|
||
- **진단:** 확신도 factor 분해(footer), 검색 청크 수, Critic 발동 여부, raw 응답 검사.
|
||
- **복구:** Epistemic Guard 강도↑(근거 없을 때), 임계 조정, 균형 괄호 파서 fallback.
|
||
- **예방:** "근거 없으면 확인 필요" 강제, 결정론 신호 항상, 파서 방어.
|
||
|
||
### 모델 수명 / 메모리(VRAM) ([[ADR-0004 순차 디스패치 채택]])
|
||
- **장애:** OOM, 모델 로드 실패, VRAM 미해제.
|
||
- **근본 원인:** 병렬 다중 모델 상주, 이전 모델 미언로드.
|
||
- **진단:** lifecycle 상태, 시스템 메모리, 모델 전환 로그.
|
||
- **복구:** 이전 모델 unload 후 재로드, idle timeout 단축, 순차 강제.
|
||
- **예방:** "한 번에 한 모델" 불변식, gpuOffloadRatio 등 로드 설정 조정.
|
||
|
||
### VS Code 확장 ([[VSCode 확장 구조와 생명주기]])
|
||
- **장애:** 활성화 실패, 명령 미등록, 자원 누수, 패널 안 열림.
|
||
- **근본 원인:** activate 예외, disposable 미등록, 웹뷰 타이밍.
|
||
- **진단:** activate console/OutputChannel 로그, subscriptions 등록 여부.
|
||
- **복구:** 확장 reload, deactivate 정리 확인.
|
||
- **예방:** 모든 자원 subscriptions 등록, best-effort 옵셔널 체이닝, 부트스트랩 비차단.
|
||
|
||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||
"로그를 보면 답이 있다" 는 빈 catch 가 로그를 삼키면 깨진다 — 그래서 빈 catch 는 이유 주석 + 가능하면 logError 동반이 원칙. 진단은 *측정* 으로 검증하라(추측으로 재시작 금지).
|
||
|
||
## 🛠️ 적용 사례 (Applied in summary)
|
||
ErrorTranslator(증상 분류), fusionLog/rankBrainForEval(검색 진단), 확신도 footer(검증 진단), lifecycle(VRAM) [S1~S5].
|
||
|
||
## 🔗 지식 그래프 (Knowledge Graph)
|
||
- **상위/루트:** [[AstraAI 아키텍처 개요]]
|
||
- **관련 개념:** [[교훈 라이브러리 Lessons Learned]], [[안티패턴 카탈로그]], [[소프트웨어 실패 라이브러리]], [[리팩토링 플레이북]]
|
||
- **참조 맥락:** 로컬 LLM/개발자가 장애를 만났을 때 서브시스템별 진단 순서로 참조.
|
||
|
||
## 📚 출처 (Sources)
|
||
- [S1] AstraAI/src/core/errorHandler.ts — 증상 분류
|
||
- [S2] AstraAI/src/core/services.ts — 엔진 폴백/빈 응답
|
||
- [S3] AstraAI/src/retrieval/index.ts — fusionLog/평가 경로
|
||
- [S4] AstraAI/src/core/lock.ts — 락 진단
|
||
- [S5] AstraAI/src/lmstudio/lifecycleManager.ts — 모델 수명/VRAM
|
||
|
||
## 📝 변경 이력 (Change history)
|
||
- 2026-06-13: AstraAI 서브시스템별 디버깅 절차 초안.
|