부록 C. 트러블슈팅

진단 원칙

문제를 해결하려고 캐시를 지우거나 재설치하기 전에, 현재 상태를 작게 확인한다. 토큰·비밀번호·개인정보가 포함된 설정 파일과 로그는 공유하지 않는다.

증상	먼저 확인할 것	피할 행동
실행이 안 됨	공식 설치 문서, 실행 경로, 지원 환경	과거 패키지 이름을 무작정 재설치
인증 오류	현재 인증 방식, 조직 권한, 계정 상태	API 키·세션 값을 대화에 붙여 넣기
지침이 적용되지 않음	현재 지침 파일 위치, 작업 디렉터리, 우선순위	다른 프로젝트 설정을 덮어쓰기
MCP가 연결 안 됨	서버 제공자, 전송 방식, 최소 권한, 인증 상태	임의의 패키지·토큰을 설정 파일에 추가
결과가 이상함	입력 범위, 프로젝트 지침, 테스트·원본	검증 없이 자동 수정·배포

최소 진단 순서

1. 문제가 난 시점과 수행한 한 가지 작업을 적는다.
2. 버전·작업 디렉터리·현재 인증 방식처럼 민감하지 않은 상태를 확인한다.
3. 공식 문서에서 동일 증상과 현재 설정 형식을 찾는다.
4. 공개 또는 테스트 프로젝트에서 가장 작은 재현 단계를 만든다.
5. 한 번에 한 설정만 바꾼 뒤 결과를 비교한다.
6. 해결되지 않으면 민감 정보를 가린 오류 메시지와 재현 절차만 공유한다.

MCP 관련 점검

MCP 서버는 이름이 같아도 로컬·프로젝트·사용자 설정에서 서로 다른 정의가 있을 수 있다. 공식 문서에서 서버 URL·패키지·인증 방법을 다시 확인하고, 읽기 전용 호출부터 테스트한다. 프로젝트 설정에는 환경변수 참조만 남기고 실제 토큰은 넣지 않는다.

복구 기준

변경 전 상태로 돌아갈 수 없다면 다음 변경을 멈춘다. 설정과 코드의 변경 목록, 마지막으로 성공한 검증, 담당자에게 물어볼 권한 문제를 분리해 기록한다. 삭제·대량 변경·권한 확대는 승인자와 복구 방법이 확인된 뒤에만 진행한다.