오류 처리 및 복구

오류를 해석하고, 대응하고, 보고하는 방법을 이해하면 Verdent for VS Code로 생산적인 개발 세션을 유지하는 데 도움이 됩니다.

배울 내용

일반적인 오류 유형과 원인
오류 메시지를 효과적으로 해석하는 방법
체계적인 문제 해결 단계
기다려야 할 때와 조치를 취해야 할 때
Verdent 팀에 문제를 보고하는 방법

일반적인 오류 유형

포괄적인 오류 문서는 현재 작성 중입니다. 아래 정보는 가장 자주 발생하는 오류 범주를 다룹니다. 특정 오류 상황에 대해서는 support@verdent.ai로 문의하거나 Discord 커뮤니티를 방문하세요.

서버 과부하 오류

트래픽이 많은 시간대에 발생합니다
일시적인 용량 제한입니다
조치: 5~10분 기다린 후 다시 시도합니다

내부 서버 오류

백엔드 처리 문제입니다
일시적인 서비스 중단입니다
조치: 기다렸다가 다시 시도합니다. 보통 자동으로 해결됩니다

503 서비스 사용 불가

정상 상태인 업스트림 서버가 없습니다
일시적인 인프라 문제입니다
조치: 서비스가 복구될 때까지 기다립니다

요청 제한 오류

요청 할당량을 초과했습니다
API 스로틀링 보호입니다
조치: 요청 제한이 초기화될 때까지 기다리고, 요청 빈도를 줄입니다

잘못되었거나 만료된 자격 증명
세션 시간 초과 문제
조치: User Center에서 다시 인증하고, 구독이 활성 상태인지 확인합니다

네트워크 연결 문제
방화벽 또는 VPN이 연결을 차단함
회사 네트워크 제한
조치: 네트워크 연결을 확인하고, 다른 네트워크를 시도합니다

잘못된 설정 또는 환경설정
손상된 설정 파일
조치: 최근 설정 변경 사항을 검토하고, 설정을 확인합니다

파일 시스템 권한 부족
워크스페이스 접근 제한
조치: 파일/폴더 권한을 확인하고, 워크스페이스 접근 권한을 확인합니다

오류 메시지 해석

자세한 오류 메시지 해석 가이드는 작성 중입니다. 특정 오류 메시지가 발생하면 Feedback 버튼이나 Discord 커뮤니티를 통해 도움을 받으세요.

서버 측 오류는 일시적이며 보통 기다리면 해결됩니다. 몇 분 뒤 다시 시도하는 것 외에는 별도 조치가 필요하지 않습니다.

다음 키워드를 확인하세요:

"Overloaded" 또는 "at capacity"
"Internal server error" 또는 "backend processing"
"503 Service Unavailable" 또는 "no healthy upstream"
"Rate limit" 또는 "quota"

해야 할 일:

다시 시도하기 전에 5~10분 기다립니다
로컬 개발 작업을 계속합니다
지금까지 만든 코드 변경 사항을 검토합니다
현재 작업을 Git에 커밋합니다

일반 규칙: 오류 메시지에 서버 상태, 용량, 요청 제한이 언급되면 일시적인 문제입니다. 이런 문제는 자동으로 해결되는 인프라 문제입니다.

일시적인 서버 오류(502, 503, 504)는 보통 몇 분 안에 해결됩니다. 다시 시도하기 전에 2~3분 기다리세요.

에스컬레이션해야 할 때:

오류가 15분 이상 지속됩니다
Discord에서 장애 보고를 확인합니다
상태 페이지 업데이트를 확인합니다

클라이언트 측 오류는 사용자의 조치가 필요합니다. 기다린다고 해결되지 않습니다.

다음 신호를 확인하세요:

인증 또는 자격 증명 관련 메시지
설정 또는 환경설정 오류
파일 권한 오류
네트워크 연결 실패

해야 할 일:

인증 오류: User Center에서 다시 인증하고, 구독이 활성 상태인지 확인합니다
설정 오류: 최근 설정 변경 사항을 검토하고, 설정 파일을 확인합니다
권한 오류: 파일/폴더 권한을 확인하고, 워크스페이스 접근 권한을 확인합니다
네트워크 오류: 인터넷 연결을 테스트하고, 다른 네트워크를 시도하고, VPN/방화벽을 확인합니다

일반 규칙: 오류가 인증, 설정, 권한, 로컬 설정을 언급하면 사용자가 수정 조치를 취해야 합니다.

문제 해결 단계:

전체 오류 메시지를 읽고 구체적인 안내를 확인합니다
어떤 구성 요소가 오류를 보고했는지 확인합니다(인증, 설정, 권한, 네트워크)
오류 유형에 따라 대상 조치를 취합니다
원래 작업을 다시 시도해 수정 여부를 확인합니다

오류 컨텍스트 읽기

오류가 발생하면:

전체 오류 메시지를 읽습니다 - 세부 정보를 건너뛰지 마세요
오류 코드를 기록합니다 - 특정 코드는 문제 진단에 도움이 됩니다
구성 요소를 식별합니다 - 어떤 시스템이 오류를 보고했는지 확인합니다(서버, API, 로컬)
발생 시점을 확인합니다 - 즉시 발생했는지, 지연 후 발생했는지 확인합니다

체계적인 문제 해결

Verdent가 예상과 다르게 동작하면, 영향이 가장 적은 조치부터 다음 단계를 순서대로 진행합니다.

초기 대응

기다리며 관찰하기

동작이 지속적인지 간헐적인지 확인합니다. 어떤 조치가 예상치 못한 동작을 유발했는지 기록합니다. 바로 무언가가 고장 났다고 가정하지 마세요. 많은 문제는 일시적입니다.

기본 재시작

Verdent for VS Code를 재시작합니다(VS Code를 닫았다가 다시 엽니다). 멈춘 상태나 성능 문제가 자주 해결됩니다. 가장 간단한 첫 문제 해결 단계입니다.

단계별 문제 해결

기본 재시작으로 문제가 해결되지 않으면:

체계적인 문제 해결 단계를 순서대로 따르세요. 단계를 건너뛰면 근본 원인을 놓칠 수 있습니다.

네트워크 연결 확인

다른 웹사이트로 인터넷 연결을 테스트합니다. 방화벽/VPN 문제를 배제하기 위해 다른 네트워크(모바일 핫스팟)를 시도합니다. 회사 네트워크가 연결을 차단하는지 확인합니다.

설정 확인

여전히 인증된 상태인지 확인합니다. User Center에서 구독이 활성 상태인지 확인합니다. 동작에 영향을 줄 수 있는 최근 설정 변경 사항을 검토합니다.

도움 요청

Discord 커뮤니티에서 비슷한 보고가 있는지 확인합니다: https://discord.com/invite/NGjXEZcbJq. Feedback 버튼을 사용해 문제를 보고합니다. 예상치 못한 동작 설명과 재현 단계를 포함합니다.

하지 말아야 할 것

일시적인 문제에 대해서는 다음 조치를 피하세요:

Verdent를 바로 다시 설치하지 마세요
VS Code 캐시나 애플리케이션 데이터를 지우지 마세요
일시적인 문제 때문에 시스템 설정을 변경하지 마세요
다른 애플리케이션도 영향을 받는 경우가 아니라면 컴퓨터를 재시작하지 마세요

Manual Accept Mode에서는 정확한 명령을 신중히 검토하지 않고 파괴적인 작업(rm, DROP, DELETE)을 승인하지 마세요.

이유는 무엇인가요? 이런 조치는 시간이 많이 들고 문제를 해결하는 경우가 드뭅니다. 대부분의 문제는 간단한 재시작이나 일시적인 서버 문제가 해소될 때까지 기다리는 것으로 해결됩니다.

기다릴 때와 조치할 때

기다릴지 조치할지 이해하면 불필요한 문제 해결 시간을 줄일 수 있습니다.

이런 오류는 자동으로 해결됩니다. 기다렸다가 다시 시도하는 것 외에는 조치가 필요하지 않습니다.

서버 과부하 또는 용량 오류:

"Overloaded" 또는 "at capacity" 메시지
트래픽이 많은 시간대
일시적인 서비스 중단

요청 제한:

"Rate limit" 또는 "quota exceeded" 메시지
짧은 시간 동안 너무 많은 요청
API 스로틀링 보호

간헐적인 연결 문제:

다시 시도하면 성공하는 가끔의 요청 실패
네트워크 일시 장애
짧은 연결 끊김

기다리는 동안 할 일:

로컬 개발 작업을 계속합니다
지금까지 만든 코드 변경 사항을 검토합니다
다음 단계나 할 일을 계획합니다
현재 작업을 Git에 커밋합니다

얼마나 기다릴까요:

표준 대기 시간: 5~10분
10분 후에도 계속 실패하면 문제 해결로 전환합니다
Discord에서 광범위한 문제 보고가 있는지 확인합니다

이런 오류는 기다린다고 해결되지 않습니다. 반드시 수정 조치를 취해야 합니다.

인증 실패:

세션 만료 → User Center에서 다시 인증합니다
잘못된 자격 증명 → 구독이 활성 상태인지 확인합니다
재인증 필요 → User Center를 확인합니다

지속적인 오류(10분 이상):

여러 번 다시 시도한 뒤에도 같은 오류가 반복됨 → 문제 해결을 시작합니다
일관된 실패 패턴 → 설정을 확인합니다
재시작 후에도 오류가 지속됨 → 환경을 확인합니다

설정 문제:

최근 설정이 변경됨 → 변경 사항을 검토하고 되돌립니다
새 설정 또는 설치 → 설정 파일을 확인합니다
네트워크 환경 변경 → 연결을 테스트합니다

권한 오류:

파일 시스템 접근 거부 → 파일/폴더 권한을 확인합니다
워크스페이스 제한 → 워크스페이스 접근 권한을 확인합니다
폴더 권한 → 필요한 권한을 부여합니다

네트워크 문제:

전혀 연결할 수 없음 → 인터넷 연결을 테스트합니다
VPN 또는 방화벽이 차단함 → 다른 네트워크를 시도합니다
회사 네트워크 제한 → IT 지원팀에 문의합니다

판단 규칙:

서버/요청 제한 오류 → 기다립니다
인증/설정/권한/네트워크 → 즉시 조치합니다
확실하지 않나요? → 먼저 5~10분 기다리고, 지속되면 조치합니다

오류 컨텍스트 제공

도움을 요청하거나 문제를 보고할 때는 더 빠른 진단을 위해 충분한 컨텍스트를 포함하세요.

필수 정보

오류 세부 정보:

정확한 오류 메시지 텍스트(바꿔 쓰지 말고 복사해 붙여넣기)
제공된 경우 오류 코드
오류가 발생한 타임스탬프
빈도(한 번만 발생, 간헐적, 지속적)

환경:

Verdent for VS Code 버전
VS Code 버전
운영 체제 및 버전
네트워크 환경(집, 회사, VPN)

재현 단계:

무엇을 하려고 했는지
사용한 정확한 프롬프트 또는 명령
관련 파일 또는 컨텍스트
오류 전에 수행한 조치

컨텍스트:

사용 중이던 실행 모드
워크스페이스의 크기와 복잡도
최근 설정 변경 사항
이전에 성공했던 유사 작업

오류 보고 예시

좋은 오류 보고 형식:

Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally

효과적인 이유

정확한 오류 메시지 텍스트
완전한 환경 세부 정보
명확한 재현 단계
정상 동작한 상황과의 비교
패턴에 대한 추가 컨텍스트

문제 보고

위치: Verdent 패널의 상단 바

기능:

문제와 제안을 제출할 수 있는 팝업 오버레이를 엽니다
Verdent 팀으로 바로 이어지는 채널입니다
버그 보고와 기능 요청에 가장 적합합니다

사용할 때:

명확한 재현 단계가 있는 확인된 버그
구체적인 사용 사례가 있는 기능 요청
팀과 직접 소통이 필요할 때
조사가 필요한 긴급하지 않은 문제

포함할 내용:

문제에 대한 명확한 설명
오류 메시지(정확한 텍스트)
재현 단계
예상 동작과 실제 동작
Verdent 버전 및 플랫폼
문제가 시작된 시점

링크: https://discord.com/invite/NGjXEZcbJq

제공하는 것:

Verdent 사용자와 팀원이 활동하는 커뮤니티
실시간 문제 해결 지원
스크린샷과 함께 문제 공유
경험 많은 사용자에게 도움 받기
커뮤니티 토론과 우회 방법

사용할 때:

즉시 논의가 필요한 긴급한 문제
여러 번의 문답이 필요한 복잡한 문제 해결
모범 사례에 대한 커뮤니티 의견
공식 보고를 제출하기 전의 간단한 질문
우회 방법을 커뮤니티와 공유할 때

문제 유형	Feedback 버튼 사용	Discord 사용
재현 단계가 있는 확인된 버그	✓
기능 요청	✓
긴급한 문제 해결 필요		✓
논의가 필요한 복잡한 문제		✓
간단한 질문		✓
커뮤니티 의견을 원함		✓
공식 버그 보고	✓
일반적인 도움		✓

보고하지 않아도 되는 것:

일시적인 서버 오류(10분 미만)
트래픽이 많은 시간대
이미 문서화된 문제
예상된 동작

대신 이렇게 하세요: 일시적인 문제는 기다리고, Discord에서 최근 보고를 확인하고, 문서를 검토합니다.

예방 모범 사례

사전 예방적인 습관은 오류 발생 빈도를 줄이고, 오류가 발생했을 때 복구를 더 쉽게 만듭니다.

프롬프트에 구체적인 언어를 사용하고 관련 파일 컨텍스트를 포함하면 많은 일반적인 오류를 발생 전에 예방할 수 있습니다.

작업을 시작하기 전에

1. 설정 확인

User Center에서 인증 상태를 확인합니다
구독이 활성 상태인지 확인합니다
안정적인 네트워크 연결을 확보합니다
최근 설정 변경 사항을 검토합니다

2. Git 초기화

허용 범위가 넓은 모드를 사용하기 전에 항상 버전 관리를 준비합니다
깔끔한 시작점을 위해 현재 작업을 커밋합니다
문제가 발생했을 때 되돌릴 수 있는 옵션을 제공합니다

3. 크레딧 잔액 확인

계획한 작업에 충분한 크레딧이 있는지 확인합니다
복잡한 작업을 시작하기 전에 필요하면 크레딧을 충전합니다
크레딧 소진으로 작업 중단이 발생하지 않게 합니다

개발 중

1. 적절한 실행 모드 사용

익숙하지 않은 코드에는 Manual Accept
복잡한 변경에는 Plan Mode
Auto-Run은 Git 안전망이 있을 때만 사용
위험 수준에 맞는 모드를 선택합니다

2. 성능 모니터링

응답 품질 저하를 주시합니다
응답 시간이 느려지는지 기록합니다
성능이 떨어지면 새 세션을 시작합니다
컨텍스트 사용량을 직접 추적합니다

3. 명확하고 구체적인 프롬프트

요청 오해로 인한 오류를 줄입니다
관련 컨텍스트와 제약 조건을 포함합니다
기존 패턴을 참조합니다
범위를 명확히 지정합니다

오류 후

1. 패턴에서 배우기

무엇이 오류를 유발했는지 기록합니다
재현 가능한 조건을 식별합니다
유발 요인을 피하도록 워크플로를 조정합니다
발견한 내용을 커뮤니티와 공유합니다

2. 우회 방법 문서화

효과적인 해결책을 메모해 둡니다
팀원과 공유합니다
커뮤니티 지식에 기여합니다
수정을 위해 Verdent 팀에 보고합니다

3. 설정 업데이트

경험을 바탕으로 설정을 조정합니다
자신의 워크플로에 맞게 최적화합니다
문제를 예방하도록 규칙을 구성합니다
AGENTS.md 문서를 유지 관리합니다