triage

triage 스킬 개요

triage가 하는 일

triage는 들어오는 이슈를 역할 기반 상태 머신으로 분류하고 흐름을 나누는 GitHub 이슈 triage 스킬입니다. 보고 내용을 분류하고, 추가 정보가 필요한지 판단하며, 작업을 AFK 에이전트나 사람 maintainer에게 적절히 넘길 수 있게 도와줍니다. Issue Tracking용 triage 스킬이 필요하다면, 이 스킬은 추측을 줄이고 이슈 처리를 일관되게 유지하는 데 초점을 둡니다.

누구에게 가장 잘 맞는가

이 triage 스킬은 이슈 큐가 많고, 반복 가능한 접수 프로세스가 필요하거나, 지저분한 버그 리포트를 실행 가능한 작업으로 구조화하고 싶을 때 특히 잘 맞습니다. bug와 enhancement를 먼저 구분한 뒤, 각 이슈를 needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix 중 하나로 넘겨야 하는 경우에 특히 유용합니다.

무엇이 다른가

가장 큰 차별점은 명시적인 상태 머신과 역할 규율입니다. 이 스킬은 단순히 “이슈를 요약”하는 데 그치지 않고, 반드시 하나의 category role과 하나의 state role을 기대합니다. 또한 모든 triage 댓글이나 이슈 메시지는 disclosure disclaimer로 시작해야 한다는 강한 요구사항이 있습니다. 예측 가능한 출력, 정책을 고려한 라우팅, 그리고 다른 agent에게 깔끔하게 넘길 수 있는 triage 워크플로우가 필요하다면 이 점이 중요합니다.

triage 스킬 사용 방법

설치와 첫 번째 읽기

다음 명령으로 설치합니다:

npx skills add mattpocock/skills --skill triage

triage를 설치했다면 먼저 SKILL.md를 읽고, 그다음 AGENT-BRIEF.md와 OUT-OF-SCOPE.md를 읽으세요. 이 파일들은 지속적으로 참고할 수 있는 brief 형식과 거절된 아이디어가 어떻게 기록되는지를 설명합니다. 실제 triage 품질에 가장 큰 영향을 주는 두 부분이 바로 이 내용입니다. 이 repo에는 보조 스크립트나 추가 참고 폴더가 없으므로, 이 세 파일이 사실상 실무의 핵심입니다.

스킬에 맞는 입력을 주기

triage는 이슈 제목, 본문, 기존 라벨, 그리고 triage 패스의 정확한 목적을 함께 줄 때 가장 잘 작동합니다. 좋은 입력은 스킬이 분류를 원하는지, 추가 정보가 필요한지, agent brief가 필요한지, 아니면 최종 거절 판단이 필요한지 구분할 수 있게 해줍니다.

좋은 프롬프트 예시:

• “이 GitHub 이슈를 triage해 주세요. bug 또는 enhancement로 분류하고, 올바른 state role을 선택한 뒤 AFK agent에게 넘길지 사람에게 남길지 말해 주세요.”
• “여기에 이슈 스레드와 현재 라벨이 있습니다. triage 상태 머신을 적용하고, 필수 disclaimer가 포함된 댓글을 초안으로 작성해 주세요.”
• “이 이슈는 설명이 부족해 보입니다. needs-info와 ready-for-agent 중 어디에 속하는지 판단하고, 부족한 acceptance criteria를 설명해 주세요.”

라벨이 아니라 워크플로우로 보기

실용적인 triage 가이드는 결과를 단순한 분류가 아니라 라우팅으로 보는 것입니다. 먼저 이슈가 버그인지 enhancement인지 확인합니다. 그다음 실행 가능한지, 신고자 입력이 막혀 있는지, 아니면 명확히 scope 밖인지 점검합니다. agent 작업으로 넘길 수 있는 상태라면, brief에는 파일 경로나 구현 단계보다 동작 기대치와 acceptance criteria가 들어가야 합니다.

저장소 규칙을 확인하기

출력 품질에 실제로 큰 영향을 주는 두 가지가 있습니다. 하나는 disclaimer 요구사항이고, 다른 하나는 “정확히 하나의 category role과 하나의 state role” 규칙입니다. 이슈의 상태가 애매하다면, 스킬은 충돌을 표시하고 다른 것을 바꾸기 전에 maintainer에게 확인하라고 안내합니다. 이럴 때는 억지로 라벨을 붙이기보다 멈추고 맥락을 확인하는 것이 맞습니다.

triage 스킬 FAQ

triage는 GitHub 이슈 라벨용인가요?

아니요. 이 스킬은 GitHub 스타일 이슈 트래킹을 중심으로 설계되었지만, 핵심 역할은 이슈 상태를 판단하고 작업을 라우팅하는 데 있습니다. tracker에서 다른 라벨 문자열을 쓴다면 canonical roles는 그대로 중요하며, 작업 전에 먼저 시스템에 맞게 매핑해야 합니다.

일반 프롬프트만 잘 쓰면 굳이 필요 없지 않나요?

일반 프롬프트로도 이슈 하나는 분류할 수 있습니다. 하지만 triage 스킬은 반복 가능한 상태 모델, brief 작성 패턴, 그리고 out-of-scope 처리 방식을 함께 제공합니다. 하나의 요약이 아니라 여러 이슈에 걸쳐 일관된 판단이 필요할 때 특히 유용합니다.

triage는 초보자도 쓰기 쉬운가요?

기본적인 이슈 라벨 개념을 이미 알고 있다면 네, 그렇습니다. triage 스킬은 어떤 state가 있는지, 각 전환이 무엇을 의미하는지 알려주기 때문에 맞춤형 policy 프롬프트를 직접 쓰는 것보다 사용하기 쉽습니다. 초보자가 가장 흔히 하는 실수는 이슈 맥락을 건너뛰고, 본문도 없고 대화도 없고 현재 상태도 없는 상태에서 라벨만 달라고 하는 것입니다.

triage를 쓰지 말아야 할 때는 언제인가요?

깊은 구현 계획이나 코드 리뷰에는 triage를 쓰지 마세요. 이 스킬은 접수, 라우팅, 준비도 판단을 위한 것입니다. 이미 충분히 상세한 spec이 있고 design이나 coding 도움이 필요하다면, 다른 스킬이나 직접적인 구현 프롬프트가 더 적합합니다.

triage 스킬 개선 방법

더 풍부한 이슈 맥락을 제공하기

전체 이슈 본문, 보이는 댓글, 현재 라벨, maintainer 메모까지 함께 주면 triage 스킬의 결과가 더 좋아집니다. 제목만 덜렁 있는 경우에는 보고가 재현 가능한지, 이미 답변된 내용인지, 핵심 정보가 빠졌는지 판단하기 어려워 라우팅 품질이 떨어지기 쉽습니다.

정말 필요한 결정을 분명히 요청하기

목표가 “ready for agent”라면 그렇게 말하세요. 목표가 “wontfix로 닫아야 하는가”라면 그것도 직접적으로 말하는 편이 좋습니다. triage는 결정 경계를 구체적으로 제시할수록 강해집니다. 그래야 스킬이 일반적인 요약이 아니라 올바른 state에 맞춰 최적화할 수 있습니다.

handoff 품질 높이기

이슈를 ready-for-agent로 옮길 때는, 행동, 제약, acceptance criteria를 지속 가능한 언어로 적은 agent brief를 요청하세요. 정말 필요한 경우가 아니라면 파일 단위 구현 지시를 요구하지 않는 편이 좋습니다. 저장소 가이드는 코드베이스가 바뀌어도 살아남는 behavioral contract를 더 선호합니다.

첫 번째 판단을 바탕으로 다듬기

첫 triage 패스가 너무 조심스럽게 나온다면, 다음 셋 중 하나를 추가해 다시 요청하세요: 재현 단계, 기대 동작과 실제 동작의 차이, 또는 이 이슈가 사용자에게 왜 중요한지. 이런 정보는 종종 이슈가 needs-info, ready-for-human, wontfix 중 어디에 들어갈지 가르는 결정적 요소가 됩니다. 그리고 두 번째 패스에서는 triage 스킬이 더 분명한 판단을 내리게 해줍니다.