qa-handoff
지금 작업의 남은 실측·검증을 QA 에이전트에게 넘기는 핸드오프 문서를 한국어로 써서 OS 임시 폴더에 둔다. 섹션은 "지금 상황 / 테스트 환경 / 테스트할 것 / 주의할 것 / 결과 기록". 트리거 - "/qa-handoff", "QA 에이전트한테 넘길 거 문서화", "QA 인계 문서 써줘", "테스트할 거 정리해서 넘겨줘".
SKILL.mdskills/qa-handoff/SKILL.md
GitHubqa-handoff: QA 에이전트 인계 문서
지금 대화에서 하던 작업 중 아직 실측하지 않은 것을, 맥락 없이 시작하는 QA 에이전트가 바로 테스트할 수 있게 문서 하나로 넘긴다. 독자는 QA 에이전트(개발자 독자)다.
저장 위치
레포 안에 두지 않는다. /handoff 스킬과 같이 OS 임시 폴더($TMPDIR, macOS에서는 /var/folders/.../T/)에 둔다.
- 파일명:
qa-handoff-<몰·프로젝트>-<주제>-<YYYYMMDD>.md(예:qa-handoff-atem-ga-taxonomy-20261016.md) - 경로는
echo "$TMPDIR"로 확인하고, 사용자에게는 전체 절대경로로 알려 준다.
작업 순서
ko-doc스킬을 로드한다. 문체 규칙(본문 서술어 종결, 표 셀 판정어(부연), 화살표·가운뎃점·대시 금지)은 그 스킬을 따른다.- 넘길 범위를 정한다. 인자가 있으면 그것을, 없으면 대화에서 "남음", "대기", "미실측"인 것을 모은다. 이미 끝난 케이스는 넣지 않는다.
- 근거를 확인한다. 테스트 URL, 측정 ID, 요청 경로, 파일 경로는 대화 기억이 아니라 파일과 문서에서 다시 읽어 적는다. 전제 조건 중 사용자가 했다고 말하지 않은 것은 "미확인. 실측 전에 사용자에게 확인"으로 적는다.
- 아래 구조로 쓴다. 문체와 상세 수준은
references/example-ga-taxonomy.md를 기준으로 삼는다(사용자가 "섹션이랑 문구 다 좋다"고 확정한 예). python3 ~/.claude/skills/ko-doc/scripts/lint.py <파일>을 돌려 걸린 곳을 고친다.- 사용자에게 저장 경로, 넘기는 케이스 요약, 미확인 전제 조건을 알린다.
문서 구조
| 섹션 | 담을 것 |
|---|---|
| 첫 문단 | 무엇을 넘기는지, QA가 무엇을 하고 결과를 어디에 적는지, 기준 날짜. 이미 끝난 케이스가 기록된 문서 경로를 적어 다시 재지 않게 한다 |
| 지금 상황 | 끝난 것과 남은 것 한두 문장, 남은 것의 동작 원리(어디서 무엇이 나가는지), 전제 조건 표(준비 항목과 상태) |
| 테스트 환경 | URL, 계정·속성 ID, 확인할 요청 경로 표. UA·뷰포트 같은 재현 조건. 브라우저 사용 규칙은 요약하고 원본 문서 경로를 가리킨다 |
| 테스트할 것 | 주제별 하위 섹션마다 케이스 표(케이스, 조건, 확인할 것). 케이스마다 공통으로 볼 항목은 표 아래 목록으로. 실패했을 때 어디부터 볼지 한 문단 |
| 주의할 것 | 부수효과가 있는 행동(실주문, 가입, 결제)의 사전 고지와 뒷정리, 사용자가 직접 할 일(로그인 등), 범위 밖 항목과 그 이유, 코드를 고치지 말고 보고할 것 |
| 결과 기록 | 결과를 적을 문서와 위치, 남길 근거(시각, 주문번호 등), 끝난 뒤 갱신할 다른 문서 |
지킬 것
- 레포 문서에 이미 있는 내용은 복사하지 않고 경로로 가리킨다.
- 비밀번호, 토큰, API 시크릿 값, 개인정보는 넣지 않는다. 시크릿은 이름(ARN 키 이름 등)만 적는다.
- QA가 코드나 서버를 바꾸는 일은 넣지 않는다. 배포·업로드처럼 사람이 하는 단계는 "사용자가 한다"고 적는다.