Menu
도구 실패/API 오류 발생 시 4단계 근본 원인 분석 후 수정. 증상 수정이 아닌 원인 수정. superpowers의 systematic-debugging 기반.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | systematic-debugging |
| description | 도구 실패/API 오류 발생 시 4단계 근본 원인 분석 후 수정. 증상 수정이 아닌 원인 수정. superpowers의 systematic-debugging 기반. |
원본: superpowers/systematic-debugging MCP 한국 법령 프로젝트에 맞게 커스터마이징
근본 원인을 찾기 전에 수정하지 않는다.
에러 메시지 정확히 읽기
재현 확인
# 직접 API 호출로 재현
.venv/bin/python -c "
from mcp_kr_legislation.apis.client import LegislationClient
from mcp_kr_legislation.config import legislation_config
client = LegislationClient(config=legislation_config)
result = client.search(target='TARGET', params={'query': 'QUERY', 'type': 'JSON'})
print(result)
"
최근 변경 확인
git diff HEAD~3 -- src/mcp_kr_legislation/tools/TARGET_TOOL.py
MCP 도구 실패의 일반적 원인:
| 증상 | 가능한 원인 | 확인 방법 |
|---|---|---|
| 404 Not Found | target 값 오류 | 공식 가이드 샘플 URL 직접 호출 |
| 빈 응답 (totalCnt: 0) | 검색어/파라미터 문제 | 다른 검색어 시도 |
| JSON 파싱 오류 | HTML 응답 반환됨 | type=JSON 파라미터 확인 |
| 타임아웃 | API 서버 과부하 | 시간 간격 후 재시도 |
| 필드 누락 | 응답 구조 변경 | 원본 JSON 출력 비교 |
반드시 공식 가이드에서 직접 확인:
# 샘플 URL 직접 테스트
http://www.law.go.kr/DRF/lawSearch.do?OC=test&target=TARGET&type=JSON&query=TEST
# 수정 후 회귀 테스트
.venv/bin/python -m pytest tests/ -v --tb=short
같은 문제에 대해 3번 이상 수정을 시도했다면:
needs_human 이슈로 기록agent_entry_prompt.md에서 도구 테스트 실패 시 이 스킬이 적용됨:
BM25 Okapi 알고리즘을 사용하여 법령/판례 API 결과를 관련도 순으로 재랭킹합니다. search_enhance_tools.py와 bm25_search.py 구현 시 참조.
법령/판례 캐시 데이터 관리 시 사용. 캐시 저장/로드, 만료 처리, 지식 그래프 동기화. 성능 최적화 및 API 호출 최소화를 위해 캐싱 구현 시 참조.
법제처 OPEN API를 MCP 프로젝트에 통합할 때 사용. lawSearch.do와 lawService.do 엔드포인트, target 파라미터로 기능 구분. 새로운 API 엔드포인트 통합 시 참조.
새 도구 개발 또는 버그 수정 시 실패하는 테스트를 먼저 작성하고, 구현 후 통과를 확인. superpowers의 test-driven-development 기반.
도구 개발/개선 완료 선언 전 반드시 실제 API 호출 테스트를 수행하고 증거를 기록할 때 사용. superpowers의 verification-before-completion 기반.
Tool에서 API 호출 시 컨텍스트 처리. streamable-http와 stdio transport 모두 지원. with_context() 패턴으로 전역 컨텍스트 fallback 자동 처리.