qa-handoff

지금 작업의 남은 실측·검증을 QA 에이전트에게 넘기는 핸드오프 문서를 한국어로 써서 OS 임시 폴더에 둔다. 섹션은 "지금 상황 / 테스트 환경 / 테스트할 것 / 주의할 것 / 결과 기록". 트리거 - "/qa-handoff", "QA 에이전트한테 넘길 거 문서화", "QA 인계 문서 써줘", "테스트할 거 정리해서 넘겨줘".

SKILL.md

GitHub

qa-handoff: QA 에이전트 인계 문서

지금 대화에서 하던 작업 중 아직 실측하지 않은 것을, 맥락 없이 시작하는 QA 에이전트가 바로 테스트할 수 있게 문서 하나로 넘긴다. 독자는 QA 에이전트(개발자 독자)다.

저장 위치

레포 안에 두지 않는다. /handoff 스킬과 같이 OS 임시 폴더($TMPDIR, macOS에서는 /var/folders/.../T/)에 둔다.

  • 파일명: qa-handoff-<몰·프로젝트>-<주제>-<YYYYMMDD>.md (예: qa-handoff-atem-ga-taxonomy-20261016.md)
  • 경로는 echo "$TMPDIR"로 확인하고, 사용자에게는 전체 절대경로로 알려 준다.

작업 순서

  1. ko-doc 스킬을 로드한다. 문체 규칙(본문 서술어 종결, 표 셀 판정어(부연), 화살표·가운뎃점·대시 금지)은 그 스킬을 따른다.
  2. 넘길 범위를 정한다. 인자가 있으면 그것을, 없으면 대화에서 "남음", "대기", "미실측"인 것을 모은다. 이미 끝난 케이스는 넣지 않는다.
  3. 근거를 확인한다. 테스트 URL, 측정 ID, 요청 경로, 파일 경로는 대화 기억이 아니라 파일과 문서에서 다시 읽어 적는다. 전제 조건 중 사용자가 했다고 말하지 않은 것은 "미확인. 실측 전에 사용자에게 확인"으로 적는다.
  4. 아래 구조로 쓴다. 문체와 상세 수준은 references/example-ga-taxonomy.md를 기준으로 삼는다(사용자가 "섹션이랑 문구 다 좋다"고 확정한 예).
  5. python3 ~/.claude/skills/ko-doc/scripts/lint.py <파일>을 돌려 걸린 곳을 고친다.
  6. 사용자에게 저장 경로, 넘기는 케이스 요약, 미확인 전제 조건을 알린다.

문서 구조

섹션 담을 것
첫 문단 무엇을 넘기는지, QA가 무엇을 하고 결과를 어디에 적는지, 기준 날짜. 이미 끝난 케이스가 기록된 문서 경로를 적어 다시 재지 않게 한다
지금 상황 끝난 것과 남은 것 한두 문장, 남은 것의 동작 원리(어디서 무엇이 나가는지), 전제 조건 표(준비 항목과 상태)
테스트 환경 URL, 계정·속성 ID, 확인할 요청 경로 표. UA·뷰포트 같은 재현 조건. 브라우저 사용 규칙은 요약하고 원본 문서 경로를 가리킨다
테스트할 것 주제별 하위 섹션마다 케이스 표(케이스, 조건, 확인할 것). 케이스마다 공통으로 볼 항목은 표 아래 목록으로. 실패했을 때 어디부터 볼지 한 문단
주의할 것 부수효과가 있는 행동(실주문, 가입, 결제)의 사전 고지와 뒷정리, 사용자가 직접 할 일(로그인 등), 범위 밖 항목과 그 이유, 코드를 고치지 말고 보고할 것
결과 기록 결과를 적을 문서와 위치, 남길 근거(시각, 주문번호 등), 끝난 뒤 갱신할 다른 문서

지킬 것

  • 레포 문서에 이미 있는 내용은 복사하지 않고 경로로 가리킨다.
  • 비밀번호, 토큰, API 시크릿 값, 개인정보는 넣지 않는다. 시크릿은 이름(ARN 키 이름 등)만 적는다.
  • QA가 코드나 서버를 바꾸는 일은 넣지 않는다. 배포·업로드처럼 사람이 하는 단계는 "사용자가 한다"고 적는다.