steve-swanson/review-work

Review Work

이 스킬은 코드를 리뷰하고, 결과를 로컬 웹 페이지에 표시하며, 사용자가 승인한 것만 수정합니다. 승인된 모든 수정 사항은 하나의 브랜치에 모여 하나의 풀 리퀘스트(PR)로 제출됩니다.

메인 에이전트(이 스킬을 실행하는 채팅)가 모든 것을 관리합니다. 메인 에이전트는 범위를 설정하고, 모든 헬퍼 에이전트의 모델을 선택하며, 모든 기록을 저장하고, 모든 결과를 검증합니다. 헬퍼 에이전트는 할당된 작업을 수행하고 결과를 보고합니다.

이 스킬은 plan-work 및 execute-work와 함께 작동합니다. 이들을 호출하거나 변경하지 않습니다.

여기서 사용되는 용어

• 리뷰 대상 브랜치: 리뷰 중인 브랜치입니다. PR은 이 브랜치로 다시 병합됩니다. 항상 develop 브랜치는 아닙니다.
• 리뷰 대상 커밋: 리뷰된 정확한 커밋 SHA입니다. 모든 파인딩은 이를 가리킵니다.
• 파인딩: 리뷰에서 발견된 하나의 문제 또는 질문으로, R001과 같은 ID를 갖습니다.
• 페이지: 사용자가 각 파인딩에 대해 수정, 수정 안 함, 또는 설명 요청을 선택하는 로컬 웹 페이지입니다.
• 배치: 제출을 한 번 클릭하여 전송되는 선택 사항입니다.
• 워크트리: 동일한 저장소를 자체 폴더에 추가로 체크아웃한 것입니다.
• 코디네이터 브랜치: 모든 수정 사항을 수집하는 하나의 브랜치(자체 워크트리 포함)입니다. PR이 됩니다. Conventional Branch 스타일인 <type>/<short-description>로 이름을 지정하고, 소문자와 하이픈을 사용합니다. 리뷰 수정 사항은 일반적으로 fix/입니다(예: fix/session-recovery). 모든 수정 사항에 더 잘 맞는 경우 refactor/, perf/, docs/, test/ 또는 chore/를 사용하십시오. 사용자나 저장소가 다른 규칙(예: AGENTS.md에 명시된 경우)을 지정하는 경우 이를 따릅니다. 이름에 integration을 절대 포함하지 마십시오.
• 태스크 브랜치: 하나의 헬퍼가 하나의 수정 사항을 만드는 단기 브랜치 및 워크트리입니다.
• 빨리 감기 병합: 브랜치를 앞으로만 이동시키고 병합 커밋을 추가하지 않는 병합입니다(git merge --ff-only).
• 실행 소유: 이 리뷰 실행에 의해 생성되었습니다. 정리는 실행 소유 브랜치와 워크트리만 건드립니다. 이름이 일치한다고 소유권이 증명되지는 않습니다.

사용자가 허용한 사항

• 이 스킬을 시작하면 리뷰 기록과 로컬 페이지 서비스가 허용됩니다.
• 다른 연결된 머신에 페이지를 표시하도록 선택하면 해당 머신에서 Review-work pages라는 T3 프로젝트(없는 경우 생성)에 하나의 페이지 호스트 스레드가 허용됩니다. 이는 review-work CLI만 실행합니다. 그곳의 코드는 절대 건드리지 않습니다. 리뷰가 완료되면 해당 스레드를 정리하고 Review-work pages 프로젝트(그 채팅을 삭제함)를 삭제하는 것이 허용됩니다. remote-page.md에 설명된 대로입니다. 다른 프로젝트는 절대 삭제하지 마십시오. 이 리뷰 채팅은 해당 프로젝트에 절대 없습니다. 이 채팅은 유지되며 최종 보고서를 받습니다.
• 수정 제출(페이지에서, 또는 채팅에서 명확한 "수정해 줘")은 태스크 워크트리, 커밋, 코디네이터 브랜치로의 병합, 안전한 정리, 푸시, 그리고 리뷰 준비가 완료된 하나의 PR을 허용합니다. 또한 해당 PR이 병합될 때까지 모니터링하고, 그런 다음 이 실행의 변경되지 않고 병합된 코디네이터 워크트리와 로컬 브랜치를 리뷰 머신에서 제거하는 것을 허용합니다.
• 사용자가 "로컬 전용" 또는 "PR 없음"이라고 말하면 그에 따릅니다.
• 절대 PR을 병합하거나, 자동 병합을 켜거나, 배포하지 마십시오.

1단계: 리뷰할 대상을 확정

1. 저장소의 지침, 요구 사항, 상태, 브랜치 및 워크트리를 읽습니다. 커밋되지 않은 편집 내용과 다른 실행은 그대로 둡니다.
2. 저장소 경로, 공유 Git 폴더, 브랜치, 베이스, 리뷰된 커밋 SHA, 호스트(머신 이름) 및 채팅 ID를 기록합니다.
3. git show, diff 또는 깔끔한 관리형 체크아웃을 사용하여 커밋된 코드만 리뷰합니다. 커밋되지 않은 파일은 리뷰 대상이 아닙니다.
4. 범위를 선택합니다:
   • 피처 브랜치: 베이스와의 diff를 리뷰합니다. 베이스는 사용자, 프로젝트 규칙, 또는 PR 메타데이터에서 가져옵니다. 여전히 불명확하면 질문합니다.
   • develop: 현재 코드 전체를 리뷰합니다. 시작 날짜나 시작 커밋을 임의로 만들지 마십시오.
5. 사용자가 이미 말하지 않은 경우 **"인라인 또는 서브에이전트 병렬 처리?"**라고 질문합니다.
   • 인라인: 메인 에이전트가 직접 리뷰합니다. 수정은 여전히 헬퍼를 사용합니다.
   • 병렬 처리: 헬퍼가 병렬로 리뷰합니다. 한 번에 가장 많은 헬퍼를 요청하고, 유용한 독립적인 영역을 기반으로 숫자를 제안합니다. 자동: 용량이 허용하는 만큼 많은 유용한 헬퍼를 사용합니다. 용량을 알 수 없는 경우 제한은 4라고 말합니다. 나머지는 대기열에 넣습니다.
6. 워크트리를 생성하기 전에 현재 워크트리, 로컬 브랜치 및 관리형 첨부 파일의 스냅샷을 저장합니다. 이 실행이 생성하는 모든 워크트리(리뷰어, 수정자, 헬퍼, 재시도 및 그 자식, 변경되지 않았거나 중단된 것도 포함)의 목록을 유지합니다. cleanup.md를 참조하십시오.

2단계: 리뷰 기록 시작

• 이 스킬의 Node 24+ 및 scripts/review.mjs를 사용합니다. 명령어는 runtime.md에 있습니다.
• JSON 입력 파일과 함께 init을 한 번 실행합니다. 입력 파일은 프로젝트 외부에 보관합니다. 반환된 리뷰 폴더 경로를 저장하고 재사용합니다. 재개 시 새 실행을 절대 생성하지 마십시오.
• 기록은 <home>/.agents/state/review-work/에 저장됩니다. 런타임은 다른 파일보다 먼저 해당 위치에 .gitignore를 생성하므로 Git이 절대 추적하지 않습니다.
• 저장소의 식별자는 정리된 원격 URL과 실제 공유 Git 폴더입니다. 하나의 클론에 연결된 워크트리는 동일한 식별자를 공유합니다. 별도의 클론은 그렇지 않습니다. 각 실행에는 고유한 ID도 있으므로 동시에 실행되는 리뷰가 혼합되지 않습니다.
• 메인 에이전트와 해당 페이지 서비스만 기록을 씁니다. 데이터베이스, 서비스 또는 상태를 워크트리나 .worktreeinclude에 절대 복사하지 마십시오. 헬퍼는 결과를 반환하고, 메인 에이전트가 저장합니다. 헬퍼는 대용량 파일을 자체 임시 폴더에 넣습니다. 메인 에이전트가 이를 가져옵니다.

3단계: 모델 선택 후 리뷰

먼저 routing.md를 읽으십시오.

• 메인 에이전트는 모든 리뷰 및 수정 작업에 대해 정확한 모델 및 노력을 선택합니다. 호스트가 이를 제공하는지 확인한 다음 작업을 시작하기 전에 선택 내용을 기록합니다. 헬퍼는 절대 Jev를 호출하거나 경로(모델, 노력 또는 옵션)를 선택하지 않습니다. 메인이 정확하고 고정된 할당을 제공하지 않는 한 헬퍼는 자체 헬퍼를 시작하지 않습니다.
• 채팅의 모델 패밀리를 유지합니다: GPT 채팅에서는 GPT 모델; Claude 채팅에서는 Claude Opus, Sonnet 또는 Haiku.
• 항상 최신 버전. 모델은 계층 이름(Astra, Sol, Terra, Opus, Sonnet, Haiku)으로 선택됩니다. 각 계층에 대해 런타임은 호스트의 모델 목록에서 최신 버전만 유지하고 이전 버전을 거부합니다. 절대 메모리에서 버전을 선택하지 마십시오. 추측보다 호스트의 모델 목록을 신뢰하십시오. 절대 모델 ID를 임의로 만들거나 조용히 공급자를 전환하지 마십시오. 패밀리를 알 수 없거나 필요한 모델이 없으면 질문하십시오.
• Jev는 먼저 모델을 선택한 다음 해당 모델이 지원하는 노력을 선택할 수 있습니다. 키가 필요합니다. 런타임의 자격 증명 검색을 사용하여 찾으십시오. 직접 파일을 열지 마십시오. 검색은 먼저 <home>/.config/jev/credentials.env를 확인합니다. (TYPESAFE_API_KEY가 권장 이름입니다). 사용 가능한 홈 키가 없으면 프로젝트의 실제 환경 변수 로딩 순서와 구성된 어댑터를 확인한 다음 해당 환경 파일 경로를 전달하십시오. 절대 키 파일이나 키 값을 출력, 저장 또는 source하지 마십시오. 전체 조회 순서는 routing.md에 있습니다.
• 구성된 Jev MCP 어댑터는 동일한 두 가지 선택을 할 수 있습니다. 먼저 실제 도구 스키마를 읽으십시오. jev_route 도구가 있다고 가정하지 마십시오. 어댑터가 없으면 런타임의 내장 직접 전송을 사용하십시오.
• 모든 모델에 대한 노력 상한: 리뷰 및 계획은 초고(extra-high)까지 가능하며, 최대(max) 또는 울트라(ultra)는 불가능합니다. 수정은 높음(High)까지 가능합니다. 런타임은 Jev 또는 메인에서 상한을 초과하는 모든 경로를 거부합니다.
• Jev가 없거나 사용할 수 없는 답변을 제공하는 경우 메인 에이전트가 동일한 규칙으로 결정합니다. 고정된 폴백 테이블은 없습니다.
  • 읽기 전용 목록 작업: 낮음(Low)으로 충분합니다.
  • 알고리즘 또는 어려운 추론: 높음(High) 또는 초고(extra-high).
  • 확실하지 않음: 높음(High).
  • 보안 리뷰 및 계획(로그인, 권한, 비밀, 암호화, 테넌트 격리, 신뢰 경계): 최신 GPT Astra 또는 최신 Claude Opus, 초고(extra-high). 해당 모델에 초고(extra-high)가 없으면 동일한 모델을 상한 미만의 최고 수준(최소 높음(High))에서 사용하십시오. 이전 버전으로 전환하지 마십시오. 헬퍼가 새로운 보안 범위를 발견하면 해당 부분을 중단하고 메인에 보고합니다. 계획된 구현은 보안 수정을 포함하여 아래 수정 경로를 사용합니다.
  • 더 높은 경로가 필요한 부분이 있는 인라인 리뷰: 사용자에게 이 채팅의 모델이나 노력을 변경하도록 요청하지 마십시오. 이 채팅은 자체 노력을 확인하거나 설정할 수 없습니다. 해당 부분(예: 보안 검사)을 하나의 리뷰 헬퍼에 제공하고, 헬퍼를 시작할 때 정확한 모델과 노력을 설정합니다(Claude Code에서는 Agent 도구의 model 및 effort, T3에서는 delegate_task 옵션). 먼저 경로를 기록합니다. 헬퍼는 파인딩을 반환하고 메인 에이전트가 저장합니다. 호스트가 필요한 모델과 노력으로 헬퍼를 시작할 수 없는 경우에만 사용자에게 질문합니다. 그런 다음 격차를 설명하고 이 채팅의 모델을 유지할 것을 제안합니다. 이 리뷰에 대해 한 번 선택을 기록하고 다시 질문하지 마십시오. 이는 병렬 처리 헬퍼에 대한 규칙을 절대 낮추지 않습니다.
• 동작 및 파일별로 리뷰를 분할합니다. 파일 간의 흐름을 따릅니다. 코드가 중단되는 방식을 찾으십시오: 잘못된 결과, 규칙 위반, 데이터 손실, 누락된 검사 및 호환성 중단. 각 문제를 요구 사항 및 실제 실행되는 코드와 비교 확인하십시오. 중복을 병합합니다.
• 적용 범위를 기록합니다: 확인한, 건너뛴, 및 완료할 수 없는 대상(경로, SHA, 이유 및 증명 포함). "파인딩 없음"이 모든 파일을 확인했음을 의미하지는 않습니다. 중요한 적용 범위가 설명되지 않은 경우 (확인됨, 건너뜀 또는 완료되지 않음으로 기록되지 않음) 리뷰를 완료했다고 말하지 마십시오.

4단계: 사람이 이해할 수 있는 파인딩 작성

사용자는 파인딩 텍스트만으로 결정하므로 텍스트는 짧고 정확하며 평이해야 합니다. writing-findings.md를 읽으십시오. 모든 리뷰어 헬퍼에게 해당 경로를 제공하고 따르라고 지시하십시오.

issue, question, suggestion 및 nitpick과 같은 Conventional Comments 레이블을 사용하십시오. 각 파인딩을 blocking 또는 non-blocking으로 표시하십시오. 각 파인딩은 네 부분으로 구성됩니다:

• 제목: 무엇이 잘못되었는지, 80자 이내의 평이한 문장으로 작성합니다. "Non-idempotent invoice creation path"가 아니라 "Retrying a payment can create two invoices"와 같이 작성합니다.
• 중요한 이유(discussion): 누가 또는 무엇이, 언제, 얼마나 자주 피해를 입는지 설명합니다.
• 증명(evidence, 선택적 코드 excerpt 포함): path:line, 코드 경로 또는 단계, 그리고 어떻게 알게 되었는지 설명합니다.
• 수정 아이디어(suggestion): 작은 수정(Small fix), 중간 수정(Medium fix) 또는 큰 수정(Large fix)으로 시작한 다음 무엇을 변경해야 하는지 설명합니다.

확실하지 않은 경우 question을 작성하십시오. 추측을 확인된 issue로 제시하지 마십시오. 각 파인딩에 안정적인 ID, 경로 및 줄, 그리고 리뷰된 SHA를 제공하십시오.

파인딩을 로드하기 전에 각 파인딩에 대해 writing-findings.md의 명확성 검사를 실행하십시오. 실패하는 것은 다시 작성하고 모든 사실을 유지하십시오.

5단계: 페이지 표시 및 결정 수집

1. 파인딩과 적용 범위를 로드한 다음 페이지를 시작합니다. 하나의 페이지가 전체 리뷰를 제공합니다(이후 라운드 포함).

2. 각 파인딩에 대해 사용자는 수정, 수정 안 함 또는 설명 요청을 선택하고 각각에 메모를 추가할 수 있습니다. 선택 사항은 초안으로 저장됩니다. 선택을 전환해도 메모는 유지됩니다.

3. 제출만 배치를 보냅니다. 부분 배치는 괜찮습니다. 결정되지 않은 파인딩은 열린 상태로 유지됩니다. 제출된 선택은 페이지에서 잠깁니다. 변경 사항은 채팅에서 발생합니다.

4. 먼저 하네스를 확인하십시오. 이 채팅은 셸에 T3CODE_THREAD_ID 또는 T3CODE_CLI_PATH가 설정되어 있거나 t3_environment_links와 같은 T3 도구를 사용할 수 있는 경우 T3 Code에서 실행됩니다. 그렇지 않은 경우:

   • 이 머신에서 deliveryMode: "terminal"로 페이지를 표시합니다.
   • 아래 페이지 호스트 선택을 건너뛰고 다른 머신을 제공하지 마십시오. remote-page.md를 읽지 마십시오.
   • 항목 5에서 일반 터미널 표현을 사용합니다.

   T3에서 채팅의 시작 위치에 따라 페이지를 표시할 위치를 선택합니다. 이 선택을 인라인/병렬 처리 선택과 분리하여 유지하십시오.

   • 이 채팅에서 이미 명시적으로 선택한 페이지 호스트를 존중합니다. 재개 시 재사용하고, 사용자가 변경하거나 해당 호스트를 사용할 수 없는 경우에만 다시 질문합니다.
   • 채팅이 리뷰 머신에서 로컬로 시작된 경우 질문 없이 해당 머신에 페이지를 표시합니다. 사용자의 진술 또는 시작 장치를 식별하는 호스트 제공 클라이언트-원본 메타데이터에서 이를 확인합니다. 에이전트의 호스트 이름, 작업 디렉토리, 실행 환경 또는 creationSource(web, mobile 또는 mcp)는 사용자가 채팅을 시작한 위치를 증명하지 않습니다.
   • 채팅이 원격으로 시작되었거나 시작 위치가 불확실한 경우 페이지를 표시할 위치를 한 번 질문합니다. 사용자가 로컬인지에 대한 별도의 질문 없이 직접 페이지 호스트를 질문합니다. t3_environment_links를 호출하고 이 머신 plus 실제 레이블을 사용하는 모든 연결된 머신 중 전체 액세스 권한이 있는 머신을 제공합니다. OS 때문에 머신을 생략하지 마십시오. 호스트를 조용히 숨기는 대신 알려진 기능/액세스 차단기를 설명합니다. 질문 도구가 모든 선택 사항을 맞출 수 없는 경우 질문에 적격 호스트를 모두 나열하고 호스트 이름을 수락합니다.
   • 사용자의 머신이 알려져 있고 적격한 경우 권장합니다. 화면 잠금 제한이 선택에 영향을 미치는 경우에만 설명합니다: T3의 스트리밍된 브라우저는 리뷰 머신의 화면이 잠기면 중지됩니다. 선택한 호스트와 시작 위치 증거(또는 unknown)를 리뷰 노트에 저장합니다.
   • 다른 머신에서: remote-page.md를 따릅니다. 페이지는 사용자의 자체 브라우저에서 열리고 제출은 선택 사항을 이 채팅으로 다시 보냅니다. 전체 액세스 T3 링크가 필요합니다. 이 머신이 잠겨 있는 동안에도 작동합니다.

5. 항상 호스트 및 페이지 링크를 제공합니다.

   • T3에서, 이 머신에서: T3 브라우저가 페이지를 열 수 있습니다. **"제출하면 이 대화가 자동으로 재개됩니다."**라고 말합니다. 페이지는 로컬 t3 thread send 명령을 사용합니다. 공개 웹훅이나 터널이 필요하지 않습니다.
   • T3에서, 다른 머신에서: 어떤 머신이 페이지를 표시하는지 말하고 **"제출하면 선택 사항을 이 채팅으로 다시 보냅니다."**라고 말합니다.
   • 일반 터미널에서: 다음과 같이 말합니다.
     1. 리뷰 페이지를 엽니다.
     2. 각 파인딩에 대한 선택을 하고 원하는 경우 메모를 추가한 다음 제출을 클릭합니다.
     3. 이 채팅으로 돌아옵니다.

6. 제출 시(local t3 thread send 또는 원격 페이지의 경우 HTTP POST) 메인 에이전트가 사용자 확인을 위해 각 수정 배치를 검토하는 채팅으로 돌아갑니다. 일반 터미널 제출은 로컬 파일 시스템 신호입니다. 채팅에 사용자를 기다리는 중이라고 말하는 일반 프롬프트가 표시됩니다. 직접 채팅에 다시 참여하지 마십시오. 사용자가 계속 진행하도록 트리거됩니다.

6단계: 각 수정 배치 실행

1. 수정할 파인딩을 식별하고(blocking 및 non-blocking을 자체 배치에서 허용된 대로 처리), 사용자가 말한 대로 메모를 통합합니다.
2. 수정을 하기 전에 코디네이터 브랜치(및 워크트리)의 유효성을 검사하고, 필요한 경우 리베이스하거나(변경 사항 충돌 없음) 생성합니다.
3. 한 번에 하나의 수정을 수행합니다. 각 수정에 대해:
   • 수정하려는 파일을 코디네이터 워크트리(변경 사항을 사용할 수 있음)에 복사하거나 리뷰 워크트리(깔끔한 리뷰 SHA 사용)에서 태스크 워크트리로 복사합니다. 태스크 워크트리는 git worktree add 및 리뷰 중인 브랜치에서 분기된 새 브랜치로 시작합니다. 완료, 커밋, 병합 및 정리 후에는 사라집니다.
   • 답을 git show하거나 리뷰에서 코드를 한 줄씩 다시 확인하십시오.
   • 수정 중인 버그를 다시 도입하지 마십시오. 예를 들어, 잘못된 경계 검사는 수정이 아니라 n-1 오류를 다시 도입해서는 안 됩니다.
   • 수정 제안이 하나의 파인딩에 대해 여러 파일에 걸쳐 있는 경우 하나의 태스크 브랜치와 워크트리에서 모든 파일을 수정합니다. 해당 변경 사항을 하나의 커밋으로 커밋합니다. 한 파인딩에 대해 여러 헬퍼가 작업하는 것을 허용하지 마십시오.
   • 코디네이터 브랜치가 병합으로 업데이트를 잃은 경우(동일한 리뷰에서 다른 배치로 인해) git merge --ff-only로 따라잡습니다. 충돌이 있는 경우 중단하고 메인에 보고합니다. 메인은 다음 수정을 위해 코디네이터를 재설정할 수 있습니다.
   • 수정이 가능한지 확실하지 않은 경우 코드 리뷰를 준수하면서 조정하는 방법을 파악하고 제안과 함께 t3 thread send 또는 동등한 메커니즘을 통해 확인을 위해 채팅으로 돌아갑니다. 그런 다음 해당 배치를 완료합니다.
   • 배치의 각 수정에 대해 태스크 브랜치를 생성하고, 수정을 적용하고, 변경 사항을 커밋하고, 수정이 올바른지 확인합니다. 이것이 마지막 수정이면 코디네이터에 병합하고 태스크를 정리합니다. 그렇지 않으면 계속 진행합니다.
4. 각 배치 후에 파인딩 기록에서 수정된 파인딩을 Fixed로 표시하고 관련 기록을 저장합니다.
5. 끊어진 워크트리, 태스크 브랜치 또는 정리해야 할 기타 아티팩트를 기록합니다. 이것들은 다음 제출 시 정리되거나 배치가 완전히 끝난 후 정리됩니다.

7단계: PR 및 보고

1. 마지막 배치가 제출되고 모든 수정이 완료되면 변경되지 않은 워크트리와 브랜치를 포함하여 이 실행이 생성한 모든 워크트리와 태스크 브랜치가 정리되었는지 확인합니다. cleanup.md에 따라 정리되지 않은 항목을 정리합니다.
2. PR이 준비되었습니다:
   • 로컬 전용 모드가 아니면 git push합니다.
   • 리뷰 대상 브랜치를 대상으로 하는 초안 PR을 생성합니다. PR 설명에는 다음이 포함됩니다:
     • "이 PR은 Review-work 스킬로 리뷰된 [SHA]의 수정 사항을 수집합니다."
     • 검토된 SHA 및 리뷰 범위에 대한 간략한 설명.
     • 각 수정 사항: 수정된 파인딩 ID(있는 경우), 제목 및 간략한 요약.
     • 리뷰가 적용된 영역, 건너뛴 영역 및 완료되지 않은 영역.
3. 사용자가 수동 개입 없이 PR에 레이블을 지정하고 검토자를 설정하도록 초안을 생성합니다. (사용자가 요청하지 않는 한 PR을 검토자에게 할당하지 마십시오.)
4. 이 리뷰 채팅에 최종 보고서를 제공합니다. 메시지는 채팅이 리뷰를 재개하거나 로컬 모드가 아닌 경우 리뷰 완료를 확인하는 것으로 끝납니다. 동기화되지 않은 경고(예: 끊어진 워크트리, 일치하지 않는 브랜치, 병합되지 않은 수정 사항 또는 손상된 기록)가 있는지 확인합니다.
5. 채팅 기록에 합산 결과를 요약하지 마십시오(예: 총 파인딩, 분류, 적용 범위). 사용자는 페이지를 참조합니다. 대신 정리 및 PR 상태를 보고합니다.