QA 세션
대화형 QA 세션을 실행합니다. 사용자가 겪고 있는 문제를 설명합니다. 에이전트는 명확히 하고, 코드베이스를 탐색하여 컨텍스트를 파악하며, 내구성이 있고 사용자 중심이며 프로젝트의 도메인 언어를 사용하는 GitHub 이슈를 등록합니다.
사용자가 각 이슈를 제기할 때
1. 듣고 간단히 명확히 하기
사용자가 자신의 언어로 문제를 설명하도록 하세요. 다음에 초점을 맞춰 최대 2~3개의 짧은 명확화 질문을 하세요.
- 예상한 것과 실제 발생한 것
- 재현 단계 (명확하지 않은 경우)
- 일관적인지 또는 간헐적인지
과도하게 인터뷰하지 마세요. 설명이 이슈를 등록하기에 충분히 명확하면 넘어가세요.
2. 백그라운드에서 코드베이스 탐색
사용자와 대화하는 동안 백그라운드에서 에이전트(subagent_type=Explore)를 시작하여 관련 영역을 이해합니다. 목표는 수정 사항을 찾는 것이 아니라 다음을 수행하는 것입니다.
- 해당 영역에서 사용되는 도메인 언어 학습 (UBIQUITOUS_LANGUAGE.md 확인)
- 기능이 무엇을 해야 하는지 이해
- 사용자 대면 동작 경계 식별
이 컨텍스트는 더 나은 이슈를 작성하는 데 도움이 되지만, 이슈 자체는 특정 파일, 줄 번호 또는 내부 구현 세부 사항을 참조해서는 안 됩니다.
3. 범위 평가: 단일 이슈 또는 분할?
등록하기 전에 이것이 단일 이슈인지 여러 이슈로 분할해야 하는지 결정하세요.
다음과 같은 경우 분할하세요.
- 수정 사항이 여러 독립적인 영역에 걸쳐 있는 경우 (예: "양식 유효성 검사가 잘못되었고 성공 메시지가 누락되었으며 리디렉션이 작동하지 않음")
- 서로 다른 사람이 병렬로 작업할 수 있는 명확히 분리 가능한 관심사가 있는 경우
- 사용자가 여러 가지 뚜렷한 실패 모드나 증상을 가진 것을 설명하는 경우
다음과 같은 경우 단일 이슈로 유지하세요.
- 한 곳에서 잘못된 하나의 동작인 경우
- 증상이 모두 동일한 근본 동작으로 인해 발생하는 경우
4. GitHub 이슈 등록
gh issue create로 이슈를 생성하세요. 사용자에게 먼저 검토를 요청하지 말고 그냥 등록하고 URL을 공유하세요.
이슈는 내구성이 있어야 합니다. 즉, 주요 리팩터링 후에도 여전히 이해할 수 있어야 합니다. 사용자 관점에서 작성하세요.
단일 이슈의 경우
다음 템플릿을 사용하세요.
## 발생 상황
[사용자가 경험한 실제 동작을 평이한 언어로 설명]
## 예상한 상황
[예상된 동작 설명]
## 재현 단계
1. [개발자가 따를 수 있는 구체적이고 번호가 매겨진 단계]
2. [내부 모듈 이름이 아닌 코드베이스의 도메인 용어 사용]
3. [관련 입력, 플래그 또는 구성 포함]
## 추가 컨텍스트
[이슈 프레이밍에 도움이 되는 사용자 또는 코드베이스 탐색의 추가 관찰 — 예: "이 문제는 파일 시스템 레이어가 아닌 Docker 레이어를 사용할 때만 발생합니다" — 도메인 언어를 사용하지만 파일을 인용하지 마세요]
분할의 경우 (여러 이슈)
차단 항목을 먼저 작성하여 종속성 순서로 이슈를 생성하므로 실제 이슈 번호를 참조할 수 있습니다.
각 하위 이슈에 대해 다음 템플릿을 사용하세요.
## 상위 이슈
#<상위-이슈-번호> (추적 이슈를 생성한 경우) 또는 "QA 세션 중 보고됨"
## 문제점
[이 특정 동작 문제 설명 — 전체 보고서가 아닌 이 부분만]
## 예상한 상황
[이 특정 부분에 대한 예상 동작]
## 재현 단계
1. [이 이슈에 특화된 단계]
## 차단 항목
- #<이슈-번호> (다른 이슈가 해결될 때까지 이 이슈를 수정할 수 없는 경우)
차단 항목이 없으면 "없음 — 즉시 시작 가능"입니다.
## 추가 컨텍스트
[이 부분과 관련된 추가 관찰]
분할을 생성할 때:
- 두꺼운 이슈보다 얇은 이슈를 선호하세요. 각 이슈는 독립적으로 수정 및 검증 가능해야 합니다.
- 차단 관계를 정직하게 표시하세요. 이슈 B가 이슈 A가 수정될 때까지 실제로 테스트할 수 없는 경우 그렇게 말하세요. 독립적인 경우 둘 다 "없음 — 즉시 시작 가능"으로 표시하세요.
- 종속성 순서로 이슈를 생성하세요. "차단 항목"에서 실제 이슈 번호를 참조할 수 있도록.
- 병렬 처리를 최대화하세요. 목표는 여러 사람(또는 에이전트)이 동시에 다른 이슈를 가져갈 수 있도록 하는 것입니다.
모든 이슈 본문에 대한 규칙
- 파일 경로나 줄 번호 없음 — 이는 구식이 됩니다.
- 프로젝트의 도메인 언어 사용 (UBIQUITOUS_LANGUAGE.md가 있으면 확인)
- 코드가 아닌 동작 설명 — "applyPatch()가 42번 줄에서 throw됨"이 아닌 "동기화 서비스가 패치 적용에 실패함"
- 재현 단계는 필수 — 결정할 수 없으면 사용자에게 물어보세요.
- 간결하게 유지 — 개발자가 30초 안에 이슈를 읽을 수 있어야 합니다.
등록 후 모든 이슈 URL을 (차단 관계 요약과 함께) 출력하고 "다음 이슈, 아니면 끝?"이라고 물어보세요.
5. 세션 계속
사용자가 끝났다고 말할 때까지 계속하세요. 각 이슈는 독립적입니다. 배치로 처리하지 마세요.