Diagnose와 Triage: 먼저 피드백 루프를 구축하고, 누구에게 맡길지 결정하기

두 가지 스킬을 함께 설명하는 이유

/diagnose와 /triage는 README에서 두 개의 독립적인 스킬이지만, 동일한 엔지니어링 문제의 두 가지 측면을 해결합니다.

• /diagnose는 이 버그가 무엇인지, 어떻게 재현하고, 어떻게 수정되었음을 증명할 수 있는지에 관심을 가집니다.
• /triage는 이 이슈가 현재 정보를 기다려야 하는지, 에이전트에게 맡겨야 하는지, 사람에게 맡겨야 하는지, 아니면 처리하지 않아야 하는지에 관심을 가집니다.

하나는 사실을 담당하고, 다른 하나는 프로세스를 담당합니다. 실제 프로젝트에서는 이 두 가지가 종종 연결됩니다. 먼저 버그 이슈를 분류하고, 정보가 부족하면 needs-info로 전환합니다. 정보가 충분하면 diagnose를 사용하여 피드백 루프를 구축합니다. 재현이 명확해지면 ready-for-agent로 할지 ready-for-human으로 할지 결정합니다.

/diagnose의 핵심: 피드백 루프가 전부입니다.

/diagnose에서 가장 기억해야 할 문장은 먼저 에이전트가 실행할 수 있는 pass/fail 신호를 구축하라는 것입니다.

Matt는 진단을 6단계로 나눕니다.

이는 많은 사람들이 버그를 디버깅하는 순서와 반대입니다. 일반적인 디버깅 프로세스는 코드를 보고, 원인을 추측하고, 수정하고, 페이지를 새로 고치는 것입니다. Matt는 반대로, 먼저 버그를 반복 가능한 기계 신호로 만든 다음 가설을 논의합니다.

좋은 피드백 루프란 무엇인가?

/diagnose는 우선순위가 높은 순서대로 피드백 루프를 제공합니다.

여기에는 매우 엄격한 판단이 있습니다. 루프가 없으면 가설 단계로 넘어가지 마십시오. 신호가 없으면 모든 분석은 "그렇게 보이는" 것으로 변질됩니다.

비결정적 버그는 어떻게 처리해야 하는가?

/diagnose는 간헐적인 버그에 대해서도 실용적인 태도를 취합니다. 목표는 처음부터 100% 재현하는 것이 아니라, 재현율을 디버깅 가능한 수준으로 높이는 것입니다.

예를 들어:

• 100번 반복하여 트리거
• 동시 트리거
• sleep을 주입하여 경쟁 조건 창 확대
• 무작위 시드 또는 시간 고정
• 환경 변수 및 외부 종속성 축소

1%의 간헐적인 버그는 디버깅하기 어렵지만, 50%의 간헐적인 버그는 이미 디버깅 가능한 대상입니다. 이 접근 방식은 프런트엔드 비동기, 메시지 큐, 결제 콜백, 스트리밍 출력에 매우 유용합니다.

가설은 반증 가능해야 한다.

Matt는 검증을 시작하기 전에 3-5개의 가설을 나열하고, 각 가설에 대한 예측을 작성하도록 요구합니다.

만약 X가 원인이라면, Y를 변경한 후 버그가 사라져야 합니다.
또는 Z를 관찰할 때 특정 특징이 나타나야 합니다.

이는 에이전트가 첫 번째 그럴듯한 설명에 갇히는 것을 방지합니다. 더 중요한 것은, 특정 실험이 정보 가치가 있는지 판단할 수 있게 해줍니다.

나쁜 가설:

캐시 문제일 수 있습니다.

반증 가능한 가설:

만약 브라우저 캐시로 인해 오래된 스크립트가 실행된다면, 캐시를 비활성화하고 강제 새로 고침을 한 후 콘솔의 오래된 번들 해시가 사라지고 버튼 클릭 이벤트도 복구되어야 합니다.

후자만이 검증할 가치가 있습니다.

수정 단계에서 가장 흔히 저지르는 실수

/diagnose는 올바른 테스트 표면이 있다면, 최소 재현을 실패 테스트로 전환한 다음 코드를 수정하도록 요구합니다.

핵심은 "올바른 테스트 표면"입니다. 단순히 유닛 테스트를 추가하는 것이 회귀 테스트가 아닙니다. 올바른 테스트 표면은 실제 버그 패턴을 커버해야 합니다.

• 버그가 여러 호출자의 조합으로 트리거되는 경우, 단일 함수만 테스트해서는 안 됩니다.
• 버그가 실제 페이로드 구조로 트리거되는 경우, 수동으로 작성된 장난감 객체만 테스트해서는 안 됩니다.
• 버그가 브라우저 이벤트 순서로 트리거되는 경우, 순수 함수만 테스트해서는 안 됩니다.

올바른 테스트 표면을 찾을 수 없다면, 그 자체가 결론입니다. 코드 구조가 버그를 고정할 수 있는 여지를 남기지 않았다는 것입니다. 수정 후에는 이 정보를 /ko/docs/notes/matt-pocock-skills/improve-codebase-architecture에 전달해야 합니다.

/triage의 핵심: 이슈는 상태 머신이다.

/triage는 AI가 단순히 "이슈를 봐주는" 것이 아닙니다. 이슈를 작은 상태 머신으로 간주합니다.

각 이슈는 동시에 다음을 가져야 합니다.

• 카테고리: bug 또는 enhancement
• 상태: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix

이 상태 세트의 가치는 유지보수자가 다음 질문에 빠르게 답할 수 있도록 하는 데 있습니다.

• 아직 아무도 보지 않은 것은 무엇인가?
• 보고자가 정보를 보충해야 하는 것은 무엇인가?
• AFK 에이전트에게 맡길 수 있을 만큼 명확한 것은 무엇인가?
• 사람이 직접 해야 하는 것은 무엇인가?
• 닫아야 하고 그 이유를 기록해야 하는 것은 무엇인가?

ready-for-agent의 기준

ready-for-agent는 이 프로세스에서 가장 중요한 상태입니다. 이는 "이 작업을 AI가 시도해 볼 수 있다"는 의미가 아니라,

작업이 부재중인 에이전트가 독립적으로 수령, 구현, 검증할 수 있을 만큼 명확하다.

이는 일반적으로 이슈에 다음이 포함되어 있음을 의미합니다.

• 배경 및 문제 진술
• 관련 코드 경로 또는 모듈
• 명확한 수락 기준
• 알려진 제약 사항
• 버그인 경우, 재현 방법이 있는 것이 좋습니다.
• 추가적인 제품/디자인 판단이 필요하지 않습니다.

이러한 것들이 부족하다면 needs-info 또는 ready-for-human이어야 하며, 에이전트에게 억지로 넘겨서는 안 됩니다.

needs-info는 구체적인 질문을 해야 한다.

/triage가 needs-info에 제공하는 템플릿은 매우 단순하지만, 핵심은 질문이 구체적이어야 한다는 것입니다.

## Triage Notes

**지금까지 확인된 사항:**

- ...

**(@reporter)님께 필요한 추가 정보:**

- ...

나쁜 질문:

더 많은 정보를 제공해 주십시오.

좋은 질문:

문제를 트리거한 브라우저 버전, 오류 페이지 URL, 클릭 순서, 그리고 Network 패널의 `/api/orders/:id` 응답 본문을 제공해 주십시오.

AI는 예의 바른 헛소리를 쉽게 쓸 수 있지만, 이 스킬은 "우리가 이미 알고 있는 것"과 "아직 부족한 것"을 분리하도록 강요합니다.

wontfix도 기록해야 한다.

/triage는 개선 사항에 대한 wontfix에 대해 흥미로운 디자인을 가지고 있습니다. 단순히 이슈를 닫는 것이 아니라, 거부 이유를 .out-of-scope/ 지식 기반에 작성하고, 댓글에 링크를 추가합니다.

이렇게 하면 다음에 유사한 요구 사항이 발생할 때 AI가 동일한 논의를 다시 시작하지 않습니다. AI는 먼저 .out-of-scope/를 읽고 유지보수자에게 "이 방향은 이전에 X라는 이유로 거부되었습니다"라고 상기시킬 수 있습니다.

이는 ADR의 정신과 매우 유사합니다. 모든 결정을 기록하는 것이 아니라, 미래에 혼란을 야기하고 반복적으로 나타날 결정만 기록합니다.

두 가지 스킬의 협력 방법

일반적인 버그 이슈는 다음과 같이 진행될 수 있습니다.

1. /triage가 이슈, 댓글, 태그 및 관련 코드를 읽습니다.
2. bug + needs-triage로 판단합니다.
3. 먼저 재현을 시도합니다. 단계가 부족하면 needs-info로 전환합니다.
4. 정보가 충분하면 /diagnose를 시작합니다.
5. /diagnose는 재현 루프를 구축하고, 가설을 나열하고, 근본 원인을 찾습니다.
6. 수정 경로가 명확하고 테스트 표면이 명확하면 이슈는 ready-for-agent로 변경됩니다.
7. 제품 판단, 외부 권한, 수동 검증이 필요한 경우 이슈는 ready-for-human으로 변경됩니다.
8. 수정 후 근본 원인과 회귀 테스트를 이슈 또는 PR에 다시 작성합니다.

이 프로세스의 핵심은 "AI가 자동으로 버그를 수정하는 것"이 아니라, 이슈를 모호한 설명에서 실행 가능한 작업 패키지로 전환하는 것입니다.

나의 사용 제안

한 가지만 기억한다면:

/diagnose는 먼저 "어떻게 망가졌는지 증명할 수 있는가"를 묻고, /triage는 먼저 "지금 어떤 상태에 있어야 하는가"를 묻습니다.

이 두 가지 질문은 많은 저품질 AI 프로그래밍을 막을 수 있습니다.

• 재현 없이 수정
• 수락 없이 작업 시작
• 근본 원인 없이 리팩토링
• 정보 없이 에이전트에게 떠넘기기

Matt의 이 두 가지 스킬은 화려하지 않지만, 실제 팀에서 숙련된 엔지니어가 하는 일과 매우 유사합니다. 먼저 사실을 수렴하고, 그 다음 프로세스를 진행합니다.

참고 자료

다음 글: TDD: Red-Green-Refactor를 사용하여 AI가 작은 단계를 밟도록 강제하기.