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

6.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)

각 서브시스템: 흔한 장애 모드 / 근본 원인 / 진단 단계 / 복구 절차 / 예방. 공통 원칙: 증상→가설→측정으로 검증→최소 변경.

📖 세부 내용 (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)

상위/루트: ConnectAI 아키텍처 개요
관련 개념: 교훈 라이브러리 Lessons Learned, 안티패턴 카탈로그, 소프트웨어 실패 라이브러리, 리팩토링 플레이북
참조 맥락: 로컬 LLM/개발자가 장애를 만났을 때 서브시스템별 진단 순서로 참조.

📚 출처 (Sources)

[S1] ConnectAI/src/core/errorHandler.ts — 증상 분류
[S2] ConnectAI/src/core/services.ts — 엔진 폴백/빈 응답
[S3] ConnectAI/src/retrieval/index.ts — fusionLog/평가 경로
[S4] ConnectAI/src/core/lock.ts — 락 진단
[S5] ConnectAI/src/lmstudio/lifecycleManager.ts — 모델 수명/VRAM

📝 변경 이력 (Change history)

2026-06-13: ConnectAI 서브시스템별 디버깅 절차 초안.

6.3 KiB Raw Blame History