작업 항목 시작

작업 항목 시작은(는) 무엇을 하나요?

붙여넣은 ADO 티켓을 다음으로 변환합니다: 새 브랜치(또는 올바르게 이어받은 브랜치), 이후 세션이 재개할 수 있는 컨텍스트 메모리, 근거 있는 코드베이스 탐색, 그리고 근본 원인 분석 또는 기능 레이아웃. 체크포인트에서 종료됩니다 — 결과를 제시하고 기다립니다. 이 스킬에서는 수정이나 기능 코드를 작성하지 않습니다. 사용자가 먼저 방향을 승인해야 합니다. 잘못된 RCA(Root Cause Analysis)를 빠르게 적용하면 전체 QA 회귀 테스트 한 사이클을 소모하게 되기 때문입니다.

0. 로컬 설정 로드

티켓을 파싱하기 전에 이 스킬의 폴더에 있는 config.local.md를 먼저 읽으십시오. 이 파일에는 이 스킬이 하드코딩하지 않기로 한 명사들이 들어 있습니다: 브랜치 접두사, 기준 브랜치, 프로젝트의 계층 문서, 조사 내용이 저장되는 위치, 코드 인덱스 블라인드 스팟, 참조할 가치가 있는 과거 메모리 등. 탐색 품질은 이러한 특정 사항에 달려 있으므로 건너뛰지 마십시오.

파일이 없는 경우(새 설치), 추론할 수 있는 것 — git remote show origin(HEAD 브랜치)에서 기준 브랜치, 사용자의 기존 브랜치(git branch --list "*/*")에서 접두사 — 을 추론하고 사용자에게 알린 후, config.local.md로 저장할 것을 제안하십시오(config.example.md 참조).

메모리 디렉토리는 시스템 프롬프트가 이 프로젝트에 대해 지정한 디렉토리이며, 리포지토리는 현재 작업 중인 리포지토리입니다. 둘 다 설정이 필요하지 않습니다.

1. 티켓 파싱

붙여넣은 내용에서 추출합니다. ADO 페이지의 복사-붙여넣기는 노이즈가 많습니다: 첫 번째 줄은 유형과 ID를 대문자로 표시합니다(USER STORY 12345, BUG 12346), 각 필드 레이블은 자체 줄에 있고 값은 다음 줄에 있습니다(State / Dev In Progress), 태그는 상단 근처에 있는 그대로의 줄로 나타나며, 무시해야 할 UI 크롬(Save, Follow, Click to add …, switch to HTML editor, 빈 TestRail 섹션)이 있습니다. 이미지와 첨부 파일은 붙여넣기에서 살아남지 못합니다.

• ID(숫자) 및 작업 항목 유형 — 버그 대 사용자 스토리 / 기능 / PBI / 작업. 유형이 명시되지 않은 경우 추론하고(재현 단계 + 예상/실제 ⇒ 버그; "~로서 나는 ~을 원한다" 또는 수락 기준 ⇒ 기능) 추론한 내용을 말합니다.
• 제목, 상태, 영역/반복(있는 경우)
• 버그: 재현 단계, 예상 vs. 실제, 빌드 번호, 플랫폼/장치/OS, 딥 링크, 언급된 로그 이름, 언급된 스크린샷
• 기능: 설명, 수락 기준, 연결된 디자인, 기능 플래그 / 실험 이름
• 토론/댓글: 이전 시도, QA 노트 및 날짜, PR 번호

ID가 없으면 무엇이든 생성하기 전에 ID를 물어보십시오 — ID가 브랜치와 메모리 이름을 결정합니다. 보이지 않는 것(스크린샷, 로그)은 참조되었지만 볼 수 없는 것으로 기록하여 내용을 추측하지 않고 체크포인트에서 요청할 수 있도록 하십시오.

2. 브랜치

현재 작업 중인 리포지토리에서 git을 실행합니다(세션이 워크트리나 다른 클론에 있는 경우 해당 리포지토리를 사용하십시오 — 절대 cd로 떠나지 마십시오):

git status --porcelain

트리가 더티(dirty)하면 중지하십시오. 파일과 현재 브랜치를 나열하고 진행 방법(이월, 스태시, 또는 이전 브랜치에 커밋)을 물어보십시오. 한 항목의 커밋되지 않은 파일이 다음 항목의 커밋으로 누출됩니다. 사용자가 결정하며, 당신이 결정하지 않습니다.

클린하면:

git fetch origin
git branch --list "<prefix>/<id>*"; git branch -r --list "origin/<prefix>/<id>*"

ID에 대한 브랜치가 없으면 origin/<base>에서 <prefix>/<id>를 자르고 짧은 SHA를 기록합니다(git rev-parse --short HEAD).

<prefix>/<id> 또는 <prefix>/<id>-N이 이미 존재하는 경우(로컬 또는 원격), 결정하기 전에 가장 최신 브랜치를 살펴보십시오 — 동일한 ID가 세 가지 매우 다른 시점에 도착할 수 있습니다:

git log --oneline origin/<base>..<prefix>/<id>[-N]   # 병합되지 않은 커밋?
git log --oneline origin/<base> --grep=<id>           # "Merged PR NNNN: ... <id>" = 병합됨

ADO는 스쿼시 병합하므로, 병합된 브랜치는 여전히 커밋이 기준보다 "앞서" 있는 것으로 표시됩니다 — 기준 브랜치의 Merged PR 줄이 병합되었음을 알려줍니다. 티켓의 상태 및 가장 최신 QA 댓글의 날짜와 브랜치의 마지막 커밋을 함께 읽으십시오.

가장 최신 기존 브랜치	일반적인 티켓 상태	수행할 작업
origin/<base> 이후 커밋 없음(종종 현재 브랜치 — 사용자가 붙여넣기 전에 자른 경우)	새로 만들기 / 진행 중	재사용하십시오. 체크아웃하고 git merge --ff-only origin/<base>를 실행합니다.
병합됨(이 ID에 대한 Merged PR이 기준에 있음) 그리고 QA가 이후 실패함	활성 / 재개, 실패한 QA 댓글이 병합보다 최신	origin/<base>에서 다음 접미사를 자릅니다(-1, -2, …); 이전 시도는 최고의 탐색 자료가 됩니다.
병합되지 않은 커밋(푸시 여부), 또는 아직 열린 PR	PR 검토 / 테스트 준비 / 진행 중	진행 중 — 브랜치를 생성하지 마십시오. 브랜치에 무엇이 있는지(커밋, 푸시 여부, 기준에서 얼마나 뒤쳐져 있는지) 보고하고, 이를 탐색의 주제로 삼은 후, 재개할지 아니면 새 시도를 시작할지 물어보십시오.

신호가 일치하지 않는 경우(예: 상태는 새로 만들기이지만 병합되지 않은 브랜치가 있음), 진행 중으로 처리하고 물어보십시오 — 중복 브랜치를 만드는 것은 비용이 많이 드는 실수입니다. git fetch가 실패하면(VPN/인증), 그렇게 말하고 로컬 origin/<base>를 사용하며 기준이 오래되었을 수 있음을 알립니다.

푸시하거나 커밋하지 마십시오 — 사용자가 요청하지 않았습니다.

3. 컨텍스트 메모리(지금 작성하고 나중에 업데이트)

탐색 전에 상태 ⏳로 메모리를 작성하여, 세션이 조사 도중에 죽더라도 항목을 재개할 수 있도록 합니다. references/memory-template.md를 사용하십시오.

• 버그 → bug-<id>-context.md, 기능/스토리/작업 → feature-<id>-context.md
• 이 ID에 대한 메모리가 이미 존재하는 경우, 새로 만들지 말고 업데이트하십시오 — 그리고 git 상태가 이제 모순되는 내용을 수정하십시오.
• MEMORY.md에 한 줄 포인터를 추가하십시오. 이것이 없으면 이후 세션이 메모리를 찾을 수 없습니다.

4. 코드베이스 탐색

목표는 티켓이 닿는 실제 코드 경로와 주변 히스토리를 찾는 것입니다 — RCA/레이아웃이 추측이 아닌 파일:라인을 인용할 수 있을 만큼 충분히.

• 코드 인덱스가 있으면 사용하십시오(CodeGraph, LSP): 티켓의 명사(페이지, 컨트롤, 서비스, DTO)에 대한 컨텍스트 쿼리로 시작한 다음, 표면화된 내용에 대해 한 번의 explore 호출을 수행합니다. 의심스러운 심볼에 대한 호출자/영향을 확인합니다. 설정에서 인덱스의 블라인드 스팟(파싱하지 않는 파일 유형)을 확인하고 대신 grep하십시오.
• 라우트 및 UI 이름: 티켓의 페이지 라우트, 컴포넌트 이름, CSS 클래스 및 딥 링크 체계는 좋은 grep 용어입니다.
• 이전 작업: git log --oneline --all --grep=<id>, git log --oneline -20 -- <의심 파일>, 프로젝트의 docs/investigations 폴더(설정) 및 동일한 영역에 대한 기록이 있는 메모리 디렉토리. 동일한 증상에 대한 이전 수정이 QA에서 실패했다면 찾을 수 있는 가장 가치 있는 것입니다.
• 통과 사례와 실패 사례를 비교하십시오. QA가 통과하는 사례와 실패하는 하나의 사례를 나열할 때, 메커니즘을 결정하기 전에 코드에서 실제로 다른 점(호스트 페이지, 데이터 경로, 타이밍)을 찾으십시오.
• 모든 호스트/플랫폼: UI가 여러 호스트(모바일 셸, 웹)에서 공유되는 경우 티켓이 플랫폼별인지, 코드가 그런지 확인하십시오.
• 탐색 중에는 빌드하지 마십시오. 여기서는 코드를 읽는 것으로 충분합니다. 빌드는 느리고 구현에 속합니다.

많은 폴더에 걸친 광범위한 검색에는 Explore 하위 에이전트로 충분합니다. 알려진 영역의 경우 직접 수행하십시오.

5a. 버그 → 근본 원인 분석

가능하면 superpowers:systematic-debugging 스킬의 방법을 사용하십시오. 기준은 측정, 추측 아님입니다: 메커니즘과 정확한 파일:라인을 명명하고, 보고된 증상을 정확히 생성하며 다른 증상은 생성하지 않는 이유(실패 사례가 실패하고 통과 사례가 통과하는 이유)를 설명하십시오.

• 재현 단계의 사용자 작업에서 잘못된 상태까지의 경로를 추적하십시오. 관련 줄을 인용하십시오.
• 장치 없이 가능한 경우 재현하십시오: 상태/마크업에 대한 컴포넌트 테스트, 레이아웃/스크롤/CSS 문제에 대한 헤드리스 브라우저 정적 복제(설정은 기존 하네스를 설명하는 메모리를 가리킬 수 있음). 재현할 수 없으면 솔직히 말하고, 자신의 확신 수준을 밝히며, 이를 확인할 증거(예: QA의 특정 로그 라인 또는 스크린샷)가 무엇인지 말하십시오.
• 근본 원인을 기여 요인 및 다른 티켓에 속하는 인접 문제와 분리하십시오.
• 수정 방향(또는 2~3가지 옵션과 권장 사항)과 이를 고정할 회귀 테스트를 제안하십시오 — 하지만 아직 작성하지 마십시오.
• 진행 중인 항목(2단계): RCA는 이미 브랜치에 있는 수정 사항에 대한 검토가 됩니다 — 가장 최신 QA 실패를 해결하는지, 장치에서 실패하게 만들 잔여 위험은 무엇인지. 재개를 권장하고, 어떤 QA 결과가 새 시도를 정당화할지 말하십시오.

5b. 기능 → 레이아웃 및 정교화

가능하면 superpowers:brainstorming 스킬을 디자인 논의에 사용하십시오.

먼저 수락 기준이 충분한지 판단하십시오. 다음의 경우 충분합니다:

• 모든 AC를 구체적인 테스트 어설션으로 전환하고 수정할 파일에 매핑할 수 있으며,
• UI 상태(로딩, 빈 상태, 오류, 비활성화), 플랫폼별 동작, 분석 이벤트 및 기능 플래그가 지정되었거나 명확히 적용되지 않는 경우.

충분하다면 질문을 위해 질문하지 마십시오 — 기능을 레이아웃하십시오. 충분하지 않다면 정교화가 필요합니다: 갭에 대해서만 물어보고, 하나의 AskUserQuestion으로 배치하십시오(최대 4개 질문, 구체적인 옵션, 권장 기본값을 첫 번째로). 모호한 AC를 추측하면 재작업이 발생합니다.

묻기 전에 각 갭을 정렬하십시오: 답변이 디자인을 변경한다면(무엇이 표시되는지, 데이터가 어디서 오는지, 사용자가 탭할 때 무엇을 보는지) 질문입니다. 명백한 하우스 컨벤션이 있는 경우 — 기능 플래그 키, 분석 이벤트 이름, DI 등록 — 관례적인 값을 선택하고, 레이아웃에 **Assumed:**로 기록하여 사용자가 한눈에 수정할 수 있도록 하고 질문하지 마십시오. 4개 질문 배치가 전체 요청입니다. 그 뒤에 "또한, 확인해 주세요…" 꼬리는 없습니다. 옵션 없는 추가 질문일 뿐이기 때문입니다.

레이아웃은 다음을 포함합니다:

• 수정/추가할 파일, 프로젝트의 계층별로 배치(설정은 이를 정의하는 문서를 가리킴), 각 호스트의 DI 등록 포함
• 데이터 흐름: 데이터가 어디서 오는지, 어떤 서비스가 상태를 소유하는지, 어떻게 컴포넌트에 도달하는지
• AC → 테스트 매핑, 각각의 테스트 프로젝트 이름 지정
• 플랫폼 차이점, 분석/플래그, 위험 및 미해결 질문

6. 체크포인트

찾은 내용으로 메모리 파일을 업데이트하고(상태 🔄, 근본 원인 또는 레이아웃 요약, 미해결 질문), 사용자에게 제시합니다:

버그:

## Bug <id>: <title>
Branch: <prefix>/<id> (from origin/<base> @ <sha>)   — 또는: <branch>에서 진행 중, 새 브랜치 없음
Memory: bug-<id>-context.md

### Root cause
<메커니즘, file:line, 증상과 일치하는 이유> — Confidence: <high/medium/low + 높이기 위한 방법>

### Evidence
<코드 인용, 재현 결과, 히스토리: 이전 PR/시도>

### Proposed fix
<방향 또는 옵션 + 권장 사항; 추가할 회귀 테스트; 수정할 파일>

### Need from you
<누락된 스크린샷/로그, 결정>

기능:

## Feature <id>: <title>
Branch / Memory: ...

### What the ACs say vs. what's missing
### Proposed layout (files, data flow, AC → tests, every platform, Assumed: …)
### Questions  (또는 "None — ACs are sufficient")

그런 다음 멈추고 승인을 기다리십시오. RCA 또는 레이아웃이 5개 이상의 파일에 걸쳐 있거나 아키텍처를 변경하는 경우, 프로젝트의 docs/investigations 폴더(설정)에 기록하겠다고 제안하십시오 — 제안만 하고 자동 생성하지 마십시오.