기본 Skill 5 - bug-triage

Codex가 오류를 보자마자 추측으로 코드를 여러 곳 수정하는 것을 막고 다음 순서로 처리하게 한다.

 

경로 : .agents/skills/bug-triage/SKILL.md

 

---
name: bug-triage
description: 오류, 테스트 실패, 비정상 동작, 프로그램 중단, 예상하지 못한 API 응답 또는 성능 저하 문제를 증거에 기반하여 분석하고 필요한 경우 최소 범위로 수정한다. 실패 경로를 추적하고, 원인 가설을 검증하며, 근본 원인을 확인하고, 회귀 테스트를 추가한다. 새로운 기능 개발이나 광범위한 리팩터링 작업에는 사용하지 않는다.
---

# 목적

추측에 따라 여러 코드를 수정하지 않고, 확인된 증거를 바탕으로 결함의 원인을 분석한다.

# 기본 행동

- 기본 동작은 문제의 원인을 분석하는 것이다.

- 사용자가 명시적으로 수정을 요청하지 않았다면 코드를 수정하지 않는다.

- 확인된 증거와 아직 검증되지 않은 가정을 명확히 구분한다.

- 문제를 재현하지 못했다면 근본 원인이 확인되었다고 주장하지 않는다.

- 여러 개의 추측성 변경보다 하나의 작고 검증 가능한 수정안을 우선한다.

# 필수 확인 자료

문제 분석을 시작하기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`를 읽는다.

2. 문제가 발생한 모듈에 적용되는 가장 가까운 `AGENTS.md`를 읽는다.

3. 버그 신고 내용, 수용 기준, 오류 로그가 있다면 확인한다.

4. 관련 소스코드와 테스트코드를 확인한다.

5. 문제를 재현할 수 있는 명령 또는 사용자 작업 흐름을 파악한다.

# 작업 절차

## 1. 결함 내용 다시 정리

다음 내용을 정리한다.

- 원래 기대한 동작
- 실제로 발생한 동작
- 문제가 발생한 환경
- 확인 가능한 경우 문제가 발생한 버전 또는 Branch
- 문제 재현 절차
- 오류 메시지 또는 잘못된 출력 결과
- 문제 발생 빈도와 발생 조건

사용자가 신고한 실제 문제를 임의로 다른 문제로 해석하거나 바꾸지 않는다.

확인된 내용과 아직 확인되지 않은 내용을 구분해서 작성한다.

## 2. 문제 재현

가능한 가장 작고 신뢰할 수 있는 방법으로 문제를 재현한다.

다음 우선순위로 재현 방법을 선택한다.

1. 현재 실패하고 있는 기존 테스트

2. 해당 문제만 검증하는 집중된 자동 테스트

3. 로컬 환경의 API 또는 UI를 이용한 재현

4. 문제만 분리한 최소 재현 코드 또는 최소 재현 환경

재현할 때 사용한 정확한 명령이나 작업 순서와 실제 결과를 기록한다.

문제를 재현하지 못한 경우에는 다음 내용을 보고한다.

- 어떤 재현 방법을 시도했는지
- 어떤 결과가 나왔는지
- 재현에 필요한 어떤 조건이 부족한지
- 현재 확인할 수 있는 로그나 코드상의 증거
- 아직 검증되지 않은 원인 가설

재현하지 못한 상태에서는 추정한 원인을 확정된 사실로 표현하지 않는다.

## 3. 오류 발생 범위 좁히기

정상적인 값이나 동작이 어느 지점부터 잘못되기 시작하는지 확인한다.

웹 요청과 관련된 문제라면 필요한 범위에서 다음 흐름을 추적한다.

- 사용자가 화면에 입력한 값
- React의 로컬 상태
- API 요청 Payload
- 서버의 네트워크 응답
- Controller가 받은 입력값
- 입력값 검증 결과
- Application Service의 처리
- Transaction 범위
- Repository Query
- 데이터베이스 조회 또는 저장 결과
- API 응답 객체 변환
- React 화면 렌더링 결과

예를 들어 다음과 같이 추적한다.

```text
사용자 입력값은 정상
→ React State도 정상
→ API 요청 Payload도 정상
→ Controller 입력값도 정상
→ Repository Query에서 검색 조건이 누락됨
→ 잘못된 조회 결과 반환

 

사용 예시

 

원인 분석

$bug-triage

사용자 조회 화면에서 두 번째 페이지로 이동하면
검색 조건이 사라진다.

아직 코드는 수정하지 마라.

1. 재현
2. 데이터 흐름 추적
3. 원인 가설 검증
4. 근본 원인
5. 최소 수정안
6. 회귀 테스트 계획

순서로 보고해라.

 

수정

$bug-triage

사용자 조회 화면의 페이지 이동 시 검색 조건이 사라지는
문제를 재현하고 수정해라.

조건:
- 상태관리 라이브러리는 추가하지 않는다.
- 관련 없는 화면은 변경하지 않는다.
- 회귀 테스트를 추가한다.
- 프런트엔드 검사 명령을 실행한다.
- 확인되지 않은 원인은 사실처럼 보고하지 않는다.