القائمة
도구 실패/API 오류 발생 시 4단계 근본 원인 분석 후 수정. 증상 수정이 아닌 원인 수정. superpowers의 systematic-debugging 기반.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
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 자동 처리.
| 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에서 도구 테스트 실패 시 이 스킬이 적용됨: