입력이 다음과 같을 때, 코딩 에이전트(coding agent)는 잘못된 문제에 대해 확신에 찬 패치(patch)를 생성할 수 있습니다:

업로드가 가끔 실패합니다. 수정해 주세요.

이 문장은 가장 작은 실패 입력(failing input), 정확한 에러(error), 환경(environment), 기대 결과(expected result), 빈도(frequency), 또는 보고자가 직접 재현했는지 여부조차 식별하지 못합니다.

첫 번째 지시사항이 "수정해 주세요"라면, 에이전트는 추측된 원인을 허구의 사실로 바꿀 여지가 생깁니다. 더 안전한 순서는 다음과 같습니다:

1. 관찰된 실패를 보존합니다.
2. 실제 환경을 기록합니다.
3. 기대 동작(expected behaviour)과 실제 동작(actual behaviour)을 명시합니다.
4. 실패 사례를 축소(reduce)합니다.
5. 재현 여부를 증명합니다.
6. 그러한 증거가 존재한 후에만 진단하고 수리합니다.

1. 관찰된 실패를 보존하세요

정확한 에러(error), 상태 코드(status code), 잘못된 출력(incorrect output), 영향을 받은 경로(route) 또는 명령(command), 타임스탬프(timestamp), 그리고 알려진 가장 작은 입력을 캡처하세요.

로그를 에이전트 컨텍스트(context)에 넣기 전에 비밀 정보(secrets)와 개인 데이터를 제거하세요. 만약 보고가 다른 사람으로부터 온 것이고 당신이 직접 재현하지 않았다면, 이를 묵묵히 사실로 격상시키지 말고 간접적인 정보(second-hand)로 표시하세요.

취약한 예:

CSV 임포트가 작동하지 않습니다.

유용한 예:

14:22 UTC에 POST /imports가 minimal.csv에 대해 HTTP 500을 반환했습니다.
응답: "column index out of range".
동일한 계정으로 one-column.csv는 성공적으로 임포트할 수 있습니다.

2. 증명 가능한 환경을 기록하세요

추측하지 말고 조사하세요:

• 리포지토리(repository) 및 커밋(commit);
• 런타임 버전(runtime version);
• 운영 체제(operating system) 또는 컨테이너 이미지(container image);
• 패키지 락파일(package lockfile);
• 관련 피처 플래그(feature flags);
• 로컬(local), 테스트(test), 스테이징(staging) 또는 프로덕션(production) 타겟.

당신의 노트북에서 프로덕션(production) 설정을 추론하지 마세요. 환경 차이는 종종 버그의 일부입니다.

3. 기대 동작과 실제 동작을 분리하세요

두 가지 관찰 가능한 문장을 작성하세요:

기대 동작(Expected): POST /imports가 가장 작은 유효한 2열 CSV를 수락하고 HTTP 201을 반환해야 합니다.
실제 동작(Actual): 동일한 피스처(fixture)가 "column index out of range"와 함께 HTTP 500을 반환합니다.

두 문장 모두 추측되는 근본 원인(root cause)을 포함해서는 안 됩니다.

“Expected: parser handles the off-by-one bug” (기대 결과: 파서가 off-by-one 버그를 처리함)라는 문구는 이미 진단을 내린 상태를 가정합니다. 당신은 아직 그 결론에 도달할 자격을 얻지 못했습니다.

4. 재현 단계 축소 (Reduce the reproduction)

보고된 경로(path)에서 시작하세요. 관련 없는 레코드, 서비스, 필드 및 단계를 하나씩 제거합니다.

여전히 실패하는 가장 작은 피스처 (fixture)를 유지하세요. 하나의 조건을 제거했을 때 실패가 멈춘다면, 해당 조건을 복구하고 경계값 (boundary)을 기록하세요.

유용한 축소 방법은 다음과 같습니다:

• 고객 내보내기 (customer export)를 정제된 두 줄짜리 피스처 (fixture)로 교체
• 관련 없는 네트워크 요청 제거
• 필요하지 않은 백그라운드 작업 (background jobs) 비활성화
• 전체 테스트 스위트 (suite) 대신 하나의 집중된 테스트 실행
• UI 저니 (UI journey)를 동일한 결함을 증명하는 가장 작은 직접 요청으로 교체

재현을 편리하게 만들기 위해 단순히 운영 데이터를 변형하지 마세요.

5. 반복 가능성 증명 (Prove repeatability)

안전한 경우, 최소한의 케이스를 최소 두 번 실행하세요.

만약 10번 중 2번 실패한다면, 90초 동안 2/10이라고 보고하세요. 이를 결정론적 (deterministic)이라고 부르지 마세요. 빈도와 지속 시간 또한 증거입니다.

유용한 인수인계 (handoff) 양식은 다음과 같습니다:

# 버그 재현 요약 (Bug Reproduction Brief)
- 대상 및 커밋 (Target and commit):
- 환경 (Environment):
...

재현과 수리를 분리하여 유지하세요

검증된 재현은 다음 단계를 위한 안정적인 계약 (contract)입니다. 이제 에이전트는 책임이 있는 코드를 조사하고, 가설의 순위를 매기며, 실패하는 회귀 테스트 (regression test)를 생성하고, 가장 작은 수정을 적용한 뒤, 해당 피스처 (fixture)가 통과함을 증명할 수 있습니다.

이러한 계약이 없다면, 테스트 통과 (green test)는 에이전트가 단지 자신의 가설을 테스트했다는 사실만을 증명할 뿐일 수 있습니다.

완전한 무료 워크플로우 설치

MIT 라이선스가 적용된 Bug Reproduction Brief는 설치 전에 공개되어 있으며 읽을 수 있습니다:

npx skills add skyestrela/ai-agent-skill-preview \
  --skill bug-reproduction-brief --agent codex --global --yes --copy

소스 및 기타 세 가지 무료 엔지니어링 워크플로우:

소스 및 기타 세 가지 무료 엔지니어링 워크플로우:

[https://github.com/skyestrela/ai-agent-skill-preview?utm_source=devto&utm_medium=article&utm_campaign=bug-reproduction-guide]

전체 Markdown 워크플로는 다음에서 직접 읽을 수 있습니다:

[https://ai-agent-skills-pack.vercel.app/preview/bug-reproduction-brief.md?utm_source=devto&utm_medium=article&utm_campaign=bug-reproduction-guide]

더 광범위한 엔지니어링 세트를 원한다면, £19 AI Agent Skills Pack에는 검토(review), 디버깅(debugging), TDD, 보안(security), API, 마이그레이션(migrations), 배포(deployment), 리팩터링(refactoring), PR 전송(PR shipping), 그리고 인시던트 분석(incident analysis)을 위한 10개의 편집 가능한 워크플로우가 포함되어 있습니다:

[https://ai-agent-skills-pack.vercel.app/?utm_source=devto&utm_medium=article&utm_campaign=bug-reproduction-guide]

무료 워크플로는 그 자체로 완성도가 높습니다. 유료 팩은 선택 사항이며, 구독 없이 일회성으로 판매됩니다.