investigate

investigate skill 개요

investigate skill이 하는 일

investigate skill은 무엇인가가 깨졌거나, 들쭉날쭉하거나, 예상과 다르게 동작할 때 체계적으로 디버깅하고 근본 원인을 분석하는 데 쓰입니다. 단순한 임시 처방보다 더 깊은 이해가 필요한 사용자, 즉 오류가 왜 발생했는지, 무엇이 바뀌었는지, 어떤 수정이 안전한지 알고 싶은 사람을 위해 설계되었습니다. investigate는 그런 작업을 구조화해 줍니다.

누가 사용하면 좋은가

코드 리뷰, 장애 초기 대응, 버그 수정, “어제는 됐는데 오늘은 안 된다”는 상황에서 investigate skill을 사용하세요. 에이전트가 추측을 멈추고 증거를 수집한 뒤, 코드 변경 전에 증상에서 확인된 원인으로 거슬러 올라가야 할 때 특히 잘 맞습니다.

눈에 띄는 점

핵심 차별점은 “근본 원인 없이는 수정도 없다”는 원칙입니다. 이 때문에 investigate skill은 일반적인 디버그 프롬프트보다 훨씬 더 엄격하게 작동합니다. 바로 편집으로 뛰어들지 않고, 작업 흐름을 조사, 분석, 가설, 구현 순으로 밀어줍니다. 또한 능동 트리거를 지원하므로, 에이전트 워크플로에서 오류나 스택 트레이스가 보이는 즉시 skill을 활성화해야 할 때 유용합니다.

investigate skill 사용 방법

설치하고 실행하기

다음 명령으로 investigate skill을 설치하세요:

npx skills add garrytan/gstack --skill investigate

스택 트레이스, 500 오류, 회귀, 예상 밖의 출력처럼 실패 상태가 분명하게 드러나는 프롬프트에서 사용하세요. 가장 좋은 결과를 내려면, 어떤 증상이 나타나는지, 어디에서 보이는지, 그리고 “정상 동작”이 어떤 모습이어야 하는지를 함께 적어 주세요.

올바른 시작 입력을 주기

좋은 investigate 사용 프롬프트에는 다음이 포함됩니다:

• 정확한 오류 메시지 또는 로그 발췌
• 이를 유발하는 명령, 엔드포인트, 또는 사용자 행동
• 최근에 바뀐 내용
• 이미 확인해 본 것
• 영향 범위와 긴급도

예: “최근 merge 이후 npm test가 CI에서 실패하는 이유를 investigate해 주세요. main과 HEAD를 비교하고, auth middleware의 최근 변경을 살펴본 뒤, 근본 원인이 확인되기 전에는 코드 변경을 제안하지 마세요.”

먼저 읽어야 할 파일

먼저 SKILL.md를 읽고, 그다음 템플릿화된 동작이나 라우팅 로직이 있으면 SKILL.md.tmpl을 확인하세요. 이 repository에는 별도의 rules/, resources/, scripts/ 폴더가 없으므로, 핵심 가치는 skill 파일 자체와 그 안의 인라인 참조에 있습니다. Code Review용 investigate라면, 편집 전에 트리거 문구와 안전하게 수행할 수 있는 작업의 경계를 특히 주의 깊게 보세요.

출력 품질을 높이는 워크플로 팁

investigate를 자유로운 대화가 아니라 의사결정 워크플로로 다루세요. 에이전트에게 다음 순서로 진행하도록 요청하면 좋습니다:

1. 실패 양상을 식별한다.
2. 이를 뒷받침할 증거를 모은다.
3. 검증 가능한 가설을 하나 또는 둘 만든다.
4. 가장 가능성 높은 원인을 확인한다.
5. 가장 작고 안전한 수정만 구현한다.

1단계를 건너뛰면 skill이 분석은 내놓을 수 있지만, 코드 리뷰나 장애 대응에는 덜 유용해집니다.

investigate skill FAQ

investigate는 버그에만 쓰는 건가요?

아니요. investigate skill은 회귀, 배포 실패, 연동 깨짐, 원인이 불분명한 동작 변화에도 잘 맞습니다. “왜 이런 일이 생기는지 알아내라”는 작업이라면, investigate가 보통 가장 좋은 출발점입니다.

일반 프롬프트와 무엇이 다른가요?

일반 프롬프트는 바로 수정안을 요청할 수 있습니다. 반면 investigate skill은 더 구조적입니다. 먼저 근본 원인을 생각하게 만들어, 불안정한 편집을 줄이고 최종 변경을 코드 리뷰에서 설명하기 쉽게 만듭니다.

초보자에게도 좋은가요?

네, 사용자가 증상과 약간의 맥락만 제공할 수 있다면 그렇습니다. 초보자는 추측을 줄여 준다는 점에서 이 skill의 도움을 크게 받는 편이지만, 로그, 재현 절차, 실패한 명령처럼 구체적인 증거는 여전히 공유해야 합니다.

언제는 쓰지 말아야 하나요?

이미 어떤 변경을 해야 하는지 정확히 알고 있거나, 실패 원인 진단이 필요 없는 단순한 콘텐츠 편집을 할 때는 investigate를 쓰지 마세요. 그런 경우에는 더 단순한 작업 프롬프트가 빠릅니다.

investigate skill을 더 잘 쓰는 방법

불평만 하지 말고 증거를 주세요

품질을 가장 크게 끌어올리는 방법은 입력을 더 날카롭게 만드는 것입니다. “앱이 깨졌어요” 대신 실패하는 요청, 오류 텍스트, 파일 경로, 환경, 마지막으로 정상 동작하던 상태를 제공하세요. investigate skill은 각 가설을 관찰 가능한 증거에 연결할 수 있을 때 가장 잘 작동합니다.

탐색 범위를 좁히세요

문제가 Code Review에 있다면, 의심되는 하위 시스템과 변경 구간을 먼저 특정하세요. 예를 들어 “auth에 집중하고, 마지막 두 커밋만 보면서, bug가 staging에서도 재현되는지 확인해 주세요”처럼 요청하면 investigate가 너무 넓게 퍼지지 않고, 빠르게 근본 원인을 찾을 가능성이 높아집니다.

첫 답변 이후에 반복하세요

첫 답변이 명확하지 않다면, 더 넓은 재작성보다 더 좁은 조사 요청을 하세요. 좋은 후속 질문은 이런 것들입니다: “신뢰도와 함께 상위 3개 가설을 나열해 주세요”, “각 가설을 반증할 증거가 무엇인지 보여 주세요”, “입력에서 출력까지 실패 경로를 추적하되 코딩은 시작하지 마세요.”