diagnose
작성자 mattpocockdiagnose는 잡기 어려운 버그, 불안정한 테스트, 성능 회귀를 위한 구조화된 디버깅 워크플로입니다. 문제를 재현하고, 실패하는 케이스를 최소화하고, 한 번에 하나씩 가설을 세우고, 계측을 추가하고, 근본 원인을 수정한 뒤, 회귀 테스트로 고정할 수 있도록 돕습니다. “디버그해줘”만으로는 부족할 때 diagnose 가이드를 사용하세요.
이 스킬의 점수는 74/100으로, 체계적인 버그 진단 워크플로가 필요한 사용자에게는 충분히 추천할 만하지만, 아직 매우 다듬어진 설치 판단 페이지 수준은 아닙니다. 저장소에는 일반적인 프롬프트보다 훨씬 적은 추측으로도 에이전트가 활용할 수 있는 구체적인 프로세스 안내가 들어 있으며, 특히 결정적 피드백 루프를 만들고 재현 방법을 선택하는 부분에서 유용합니다.
- 프론트매터에 어려운 버그, throwers/failures, 성능 회귀에 대한 명확한 트리거와 범위가 제시되어 있음.
- Reproduce → minimise → hypothesise → instrument → fix → regression-test의 운영 지침이 강하며, 패스/페일 루프를 만드는 구체적인 방법까지 포함되어 있음.
- 실행 가능한 human-in-the-loop 셸 템플릿이 있어, 대화형 재현 워크플로에서 에이전트가 트리거하기 쉽다는 장점이 있음.
- 보이는 근거는 진단 방법론에 치우쳐 있으며, 발췌본만으로는 전체 end-to-end 워크플로가 보이지 않기 때문에 설치 후 사용자는 일부 실행 세부를 직접 채워 넣어야 할 수 있음.
- SKILL.md에 실험적/테스트 신호가 있고 설치 명령이 없어, 더 성숙한 스킬보다 바로 쓰기 쉬운 수준은 아닐 수 있음.
diagnose skill 개요
diagnose는 어떤 용도인가
diagnose skill은 버그 원인이 잘 잡히지 않거나, 테스트가 불안정하거나, 성능이 갑자기 떨어졌을 때 원인을 안정적으로 분리해내기 위한 구조화된 디버깅 워크플로입니다. 단순히 debug this라고 던지는 수준보다 더 많은 것을 원하는 에이전트와 개발자에게 적합합니다. 증상에서 재현까지, 다시 가설 설정과 계측, 수정, 회귀 테스트까지 이어지는 재현 가능한 경로가 필요할 때 특히 잘 맞습니다.
누가 설치해야 하나
실패가 간헐적이거나, 환경에 따라 달라지거나, UI나 프로덕션에 가까운 흐름에서만 드러나는 코드베이스를 자주 다룬다면 diagnose skill을 설치하는 것이 좋습니다. 빠르게 코드만 훑어서는 충분하지 않고, 구현에 손대기 전에 통과/실패 신호를 명확히 만들기 위한 엄격한 방식이 필요한 Debugging 작업에 특히 유용합니다.
무엇이 다른가
diagnose skill의 핵심은 먼저 빠른 피드백 루프를 만드는 데 있습니다. 이것이 가장 큰 차별점입니다. 성급하게 코드를 바꾸기보다 재현 가능성과 관찰 가능성을 우선합니다. 또한 프로젝트의 용어집과 ADR을 활용하도록 유도해, 에이전트가 모듈의 의도를 추측하지 않고 도메인 언어에 맞춰 움직이도록 합니다.
diagnose skill 사용하는 법
diagnose skill 설치하기
리포지토리의 skill 설치 경로를 사용한 뒤, 로컬 skills 디렉터리에 skill 파일이 제대로 들어왔는지 확인하세요. 이 리포지토리에서 문서화된 설치 명령은 다음과 같습니다:
npx skills add mattpocock/skills --skill diagnose
설치가 끝나면 SKILL.md부터 열고, 워크플로를 구성하는 보조 파일들을 확인하세요. 특히 중요한 리포지토리 경로는 scripts/hitl-loop.template.sh와, 용어·아키텍처·테스트 경계를 설명하는 프로젝트별 문서들입니다.
모호한 버그를 좋은 diagnose 프롬프트로 바꾸기
diagnose skill은 입력에 구체적인 증상, 발생 위치, 성공 기준이 들어갈 때 가장 잘 작동합니다. 약한 프롬프트는 “diagnose this”에 그칩니다. 더 나은 프롬프트는 이렇게 씁니다:
“staging에서 export 버튼이 가끔 실패하는 이유를 diagnose해 주세요. 브라우저에서 재현하고, 최소 단계로 줄인 뒤, 서버 문제인지 클라이언트 문제인지 식별하고, 가능하면 회귀 테스트도 추가해 주세요.”
diagnose를 쓸 때는 다음 정보를 포함하세요:
- 관찰된 실패 양상
- 문제가 발생하는 환경
- 이미 확인된 정상 사례나 비정상 사례
- 테스트, dev server, browser harness를 돌릴 수 있는지 여부
먼저 읽어야 할 추천 워크플로와 파일
먼저 SKILL.md를 읽어 루프의 구조를 이해한 다음, 버그 재현에 사람의 개입이 필요하다면 scripts/hitl-loop.template.sh를 보세요. 이 스크립트는 사용자가 몇 단계를 직접 클릭해 보거나, 에러를 캡처하거나, 동작을 확인해야 하는 상황에서 특히 유용합니다. 에이전트는 그 결과를 파싱해 다음 판단을 이어갈 수 있습니다.
실무적으로는 다음 순서가 좋습니다:
- 가장 좁은 실패 시나리오를 찾는다
- 결정적인 신호를 만든다
- 가설은 한 번에 하나씩 검증한다
- 신호가 불분명한 지점에만 계측을 넣는다
- 수정 사항은 회귀 테스트나 재실행 가능한 harness로 고정한다
결과를 눈에 띄게 개선하는 팁
Debugging 결과에서 diagnose를 더 잘 활용하려면, 사용할 수 있는 도구가 무엇인지 에이전트에게 분명히 알려주세요. 예를 들어 unit tests, CLI commands, HTTP requests, browser automation, 캡처한 traces 재생 가능 여부를 명시하면 좋습니다. 버그가 deterministic인지, flaky인지, 성능 문제인지도 함께 적어야 합니다. 그에 따라 루프의 설계 방식이 달라지기 때문입니다. 관찰 가능한 신호가 구체적일수록, 에이전트가 추측에 쓰는 시간이 줄어듭니다.
diagnose skill FAQ
diagnose는 일반 debug 프롬프트보다 나은가?
대체로 그렇습니다. 특히 문제가 재현이 어렵거나 여러 계층에 걸쳐 있을 때 더 그렇습니다. 일반 프롬프트는 곧바로 코드 수정으로 뛰어들 수 있지만, diagnose는 먼저 증거를 만들도록 설계되어 있어 flaky bug와 regression에 더 안전합니다.
언제 diagnose를 쓰지 말아야 하나?
문법 오류가 명확하거나, 눈에 보이는 null check 문제이거나, 한 파일 안에서 끝나는 작은 수정처럼 실패 원인이 이미 충분히 설명된 경우에는 쓰지 않는 편이 낫습니다. 그런 상황에서는 완전한 diagnose 가이드의 오버헤드가 과할 수 있습니다.
diagnose skill은 초보자에게도 친절한가?
증상을 명확히 설명하고 제안된 점검을 실행할 수 있다면 그렇습니다. 특히 버그가 어디에 있는지 확신이 없을 때 유용합니다. 깊은 사전 지식이 없어도 조사 과정을 구조화해 주기 때문입니다.
diagnose는 모든 stack에 맞는가?
대부분의 stack에는 맞습니다. test, script, browser check, replayable input으로 성공과 실패를 드러낼 수 있다면 잘 작동합니다. 반대로 성공/실패를 결정적으로 관찰할 방법이 전혀 없는 시스템에서는 덜 유용합니다. 이 skill 자체가 신뢰할 수 있는 피드백 루프에 의존하기 때문입니다.
diagnose skill 개선하기
skill에 더 강한 시작 신호 주기
가장 큰 개선은 재현 정보의 질을 높이는 데서 나옵니다. “앱이 깨졌어요”라고만 하지 말고, 정확한 동작, 데이터 형태, 기대 결과와 실제 결과를 함께 주세요. 로그, 실패하는 URL, payload 샘플, 최소 fixture가 있다면 처음부터 포함하는 것이 좋습니다.
원인 추정 전에 모호함 제거하기
가능한 실패가 여러 개라면, 먼저 어떤 실패를 diagnose할지 지정하세요. 예를 들어 “버튼을 눌러도 아무 일도 안 일어남”, “request가 500을 반환함”, “페이지가 느림”은 서로 분리해서 다뤄야 합니다. diagnose는 초기 문제 진술이 하나의 관찰 가능한 실패 양상과 정확히 대응할 때 가장 잘 작동합니다.
첫 번째 결과로 다음 실험을 고르기
첫 결과를 받은 뒤에는 세 가지 질문 중 하나에 답하면서 diagnose skill 결과를 더 좋게 만들 수 있습니다. 재현이 결정적으로 바뀌었는지, 가설이 탐색 범위를 좁혔는지, 아니면 다른 신호가 필요한지 확인하세요. 출력이 여전히 모호하다면, 넓은 설명을 다시 요청하기보다 더 작은 harness, 다른 test seam, 또는 browser/CLI replay 경로를 요청하는 편이 낫습니다.