quidmonkey/pr

/pr

현재 세션의 현재 브랜치에서 다음 순서로 실행됩니다:

1. 사전 점검
2. 코드 리뷰 및 수정
3. 문서 리뷰 및 수정
4. 보안 리뷰 및 수정
5. 의사 결정 기록
6. 푸시 및 PR 열기

각 단계는 다음 단계가 시작되기 전에 통과해야 합니다.

호출: /pr [base] [effort] [--draft]

• base: PR의 대상 브랜치입니다. 기본값: 저장소의 기본 브랜치.
• effort: /code-review에 전달됩니다. low, medium, high, xhigh 중 하나입니다. 기본값: high. 사용자가 직접 입력하지 않는 한 max를 사용하지 마십시오.
• --draft: PR을 드래프트로 엽니다.

규칙

• 어떤 곳에도 귀속 정보를 표시하지 않습니다. 커밋, PR 제목, PR 본문에 Co-Authored-By 트레일러, "Generated with Claude Code" 문구, Claude 또는 에이전트에 대한 언급을 포함하지 않습니다. 이는 기본 귀속 지침을 재정의합니다.
• 모든 git 훅을 존중합니다. git commit 또는 git push에 --no-verify나 -n을 절대 전달하지 않습니다. 훅을 건너뛰는 환경 변수(SKIP=, HUSKY=0, LEFTHOOK=0, PRE_COMMIT_ALLOW_NO_CONFIG=)를 설정하지 않으며, core.hooksPath를 변경하지 않고, 훅 파일이나 훅 구성을 편집하거나 삭제하지 않습니다. 훅을 통과시키기 위해 린트 규칙을 비활성화하지 않습니다.
• 설치된 훅이 모든 커밋에서 실행되도록 일반 git commit으로 커밋합니다. 훅이 실패하면 출력을 읽고 코드의 근본 원인을 수정한 후 다시 커밋합니다(--amend는 사용하지 않음: 거부된 커밋은 생성되지 않았습니다). 훅이 파일을 재작성한 경우(포맷터), 스테이징 후 다시 커밋합니다. 동일한 훅이 3번 시도 후에도 계속 실패하면 중단하고 보고합니다.
• /pr을 입력하면 이 브랜치에 대한 푸시 및 PR 생성을 승인하는 것으로 간주합니다. 푸시나 PR 생성 전에 "진행해도 될까요?"라고 묻지 않습니다.
• 기본 브랜치에 푸시, 커밋 또는 재작성하지 않습니다. 강제 푸시하지 않습니다.
• 수정 커밋을 사용자의 커밋과 분리하여 유지합니다. 사용자의 커밋을 스쿼시, 리베이스 또는 수정하지 않습니다.
• 커밋 메시지: 짧은 요약 줄 뒤에 변경 사항당 하나의 글머리 기호를 사용합니다. 메시지 어디에도 큰따옴표나 백틱을 사용하지 않습니다. 식별자는 일반 텍스트로 작성하고 인용이 필요한 경우 작은따옴표를 사용합니다.
• 발견 사항을 근본 원인에서 수정하고 각 변경 사항을 최소화하며 테스트를 진실의 원천으로 취급합니다. 테스트를 통과시키기 위해 테스트를 변경하지 않습니다.
• 브랜치가 변경한 내용에 대해서만 작업합니다. "범위"를 참조하세요.
• 이 스킬이 작성하는 모든 산문(문서, 커밋 메시지, PR 제목 및 본문)은 "작성"을 따릅니다.
• 중단 시 보고하고 더 이상 아무것도 하지 않습니다. "중단 및 보고"를 참조하세요.

범위

이 스킬은 브랜치 자체의 작업을 검토하고 수정하며, 코드베이스의 나머지 부분은 검토하지 않습니다. 브랜치의 작업은 git diff origin/<base>...HEAD의 모든 내용과 이 실행에서 추가된 수정 커밋입니다.

작업을 수행하기 전에 모든 리뷰의 모든 발견 사항을 세 그룹으로 분류합니다:

1. 브랜치에 의해 도입됨. 결함이 있는 코드가 diff에 추가되거나 변경되었거나, 브랜치의 변경으로 인해 실패하는 경우(예: 브랜치가 기존 함수를 손상시키는 방식으로 호출). 수정합니다. 수정하는 데 사용자만이 결정할 수 있는 사항(의도된 동작, 브랜치가 의도적으로 선택한 API 선택)이 필요한 경우, 대신 그룹 2로 처리합니다.
2. 기존에 존재하며, 브랜치의 작업과 관련됨. 결함이 있는 코드가 이미 기본 브랜치에 있었지만, 브랜치가 편집하는 함수에 있거나, 새 브랜치 코드가 이를 호출하거나 의존하는 경우 스스로 수정하지 마십시오. 문제를 지적하고 사용자에게 문의하십시오("사용자에게 문의" 참조).
3. 기존에 존재하며, 브랜치와 무관함. 그 외 모든 것. 변경하지 말고, 문의하지 말고, PR에 포함하지 마십시오. 세션 보고서에서도 제외하십시오.

발견 사항이 그룹 2와 3 사이에 있는 경우, 그룹 2에 넣습니다.

심각도

인간 리뷰어가 하듯이 높음 및 중간 심각도 발견 사항에 대해서만 조치합니다. 모든 그룹의 낮음 심각도 발견 사항은 건너뜁니다: 수정하지 말고, 문의하지 말고, PR에 포함하지 마십시오. 리뷰에서 이미 낮음 심각도 그룹 1 발견 사항을 수정했고 수정 사항이 작고 검사를 통과하면 유지하고, 그렇지 않으면 되돌립니다.

• 높음: 일반 사용 또는 현실적인 공격자가 접하게 될 버그 또는 취약점. 데이터 손실, 정상 입력 시 충돌, 인젝션, 인증 우회, 비밀 노출.
• 중간: 있을 법한 경우의 실제 버그, 문서화된 동작 위반, 신뢰 경계에서의 누락된 검사, 또는 버그를 숨기는 테스트.
• 낮음: 특이한 설정이 필요한 에지 케이스(이미 쓰기 액세스 권한이 있는 사람이 심은 파일, 로컬 도구의 경합 조건, 지원되지 않는 플랫폼), 심층 방어, 스타일, 명명, 중복 및 미세 최적화.

리뷰에서 심각도를 제공하지 않거나 동의하지 않는 경우, 이러한 정의를 사용하여 직접 판단합니다. 발견 사항이 두 수준 사이에 있는 경우, 더 높은 수준을 선택합니다.

사용자에게 문의

단계의 높음 또는 중간 그룹 2 발견 사항을 모두 수집하고, 해당 단계 라운드가 끝날 때 (커밋 전에) 한 번에 문의합니다. AskUserQuestion 도구를 사용하며, 호출당 최대 4개의 질문을 일괄 처리합니다. 각 질문은 파일, 줄 번호 및 문제를 한 문장으로 명시하고 다음 옵션을 제공합니다:

• 이 브랜치에서 수정: 지금 이 단계의 수정 커밋에서 수정합니다.
• 그대로 두고 PR에 기록: 코드를 변경하지 않습니다. PR 본문의 "리뷰어를 위한 참고 사항" 아래에 나열합니다.
• 그대로 둠: 코드를 변경하지 않고 PR에 언급하지 않습니다.
• 중단: 실행을 중단하고 보고합니다("중단 및 보고" 참조).

각 답변을 따릅니다. 사용자가 답변한 그룹 2 발견 사항은 열려 있는 것으로 간주되지 않으므로 실행이 중단되지 않거나 다음 라운드에 다시 나타나지 않습니다. 이후 리뷰에서 다시 보고되는 경우 동일한 답변을 적용합니다.

리뷰 스킬 브리핑

code-review 또는 security-review를 호출할 때 인수에 다음을 추가합니다: 저장소 경로, 기본 브랜치(origin/<base>), 그리고 "브랜치가 도입한 높음 및 중간 심각도 문제만 수정하십시오. 기존 문제는 수정하지 말고 보고하십시오. 각 발견 사항에 대해 심각도(높음, 중간 또는 낮음)를 제공하고 기존 문제인지 여부를 명시하십시오. 문서(README, docs/, CHANGELOG)는 편집하지 마십시오. 이후 단계에서 처리합니다." 그런 다음 리뷰가 수행한 문서 편집이나 범위 외 수정 사항을 발견 사항을 분류하기 전에 되돌립니다(해당 헝크만 git restore 사용).

작성

팀원에게 메모를 남기는 엔지니어처럼 작성합니다: 짧고, 평이하며, 구체적으로.

• 무엇이 변경되었고 왜 변경되었는지 구체적인 용어(파일, 함수, 동작, 숫자)로 말합니다. 리뷰어가 조치할 수 없는 내용은 건너뜁니다.
• 짧은 문장, 각 문장에 하나의 아이디어. 평이한 동사 사용: "is", "has", "adds", "fixes", "removes".
• 불필요한 표현이나 얼버무리지 않습니다: "in order to"는 "to", "due to the fact that"는 "because", "could potentially"은 사용 금지.
• 금지어: additionally, delve, leverage, crucial, pivotal, vital, enhance, robust, seamless, seamlessly, comprehensive, intricate, landscape, tapestry, testament, underscore, showcase, foster, streamline, elevate, empower, boasts, vibrant, rich, cutting-edge, game-changer, holistic, synergy, utilize.
• "serves as" 또는 "stands as" 사용 금지("is" 사용), "not just X, but Y" 패턴 금지, 리듬을 위한 세 가지 항목 나열 금지, "..., ensuring X" 또는 "..., highlighting Y"와 같은 "-ing" 꼬리 사용 금지.
• 이모지, 줄표(em dash), 기계적인 굵게, 제목의 Title Case, 둥근 따옴표(curly quotes), 마무리 요약이나 긍정적인 끝인사 사용 금지.
• 문서나 PR 설명에서 리뷰 과정을 설명하지 않습니다("ran code review", "addressed findings"). 수정 커밋이 이미 기록합니다.

텍스트를 사용하기 전에 다시 읽고 정보를 전달하지 않는 모든 단어를 제거합니다.

1. 사전 점검

다음을 실행하고 필요한 수정과 함께 첫 번째 실패 시 중단합니다:

1. git rev-parse --show-toplevel이 성공하고 git remote get-url origin이 존재합니다.
2. gh auth status가 통과합니다. 실패하면 사용자에게 ! gh auth login을 실행하라고 알립니다.
3. 기본 브랜치: base 인수, 또는 gh repo view --json defaultBranchRef -q .defaultBranchRef.name. git fetch origin <base>를 실행합니다.
4. 현재 브랜치(git branch --show-current)가 비어 있지 않고(detached HEAD 아님), <base>가 아닙니다.
5. git rev-list --count origin/<base>..HEAD가 0보다 큽니다.
6. git status --porcelain이 비어 있습니다. 비어 있지 않으면 변경된 파일을 표시하고 먼저 커밋할지(사용자 자신의 커밋으로, 훅을 통해) 아니면 중단할지 묻습니다. 스태시하거나 폐기하지 마십시오.
7. gh pr view --json url,state,isDraft,body를 실행하여 브랜치에 이미 PR이 있는지 확인합니다. 6단계를 위해 결과를 기억합니다.

검사 실행

모든 수정 라운드 후, 커밋 전에(git 훅은 커밋 시 실행되므로 여기서 실행하지 마십시오):

• 프로젝트의 테스트 명령이 명백한 경우(Makefile 타겟, pyproject.toml, package.json 스크립트) 실행합니다. 린트가 훅과 별개인 경우 린트도 실행합니다.
• 근본 원인에서 실패를 수정하고 깨끗해질 때까지 다시 실행합니다.

2. 코드 리뷰 및 수정

첫 번째 라운드 전에, 기록된 결정 사항과 변경된 코드를 다루는 문서를 읽습니다:

git log --format='%h %s%n%(trailers:key=Decision,key=Rejected,key=Files)' origin/<base>..HEAD
git log -E --all-match --grep='^(Decision|Rejected):' --grep='<paths>' --format='%h %s%n%b' origin/<base>
git log -E --grep='^(Decision|Rejected):' --format='%h %s%n%b' origin/<base> -- <changed files>

첫 번째는 브랜치의 결정 사항을 나열합니다. 나머지 두 개는 브랜치의 변경된 파일을 다루는 기본 브랜치에 이미 있는 결정 사항을 찾습니다(git diff --name-only origin/<base>...HEAD). 두 번째는 Files: 줄에 변경된 파일을 명명하는 결정 레코드를 찾습니다. <paths>는 변경된 파일을 |로 연결한 것이며, 각 .은 \.로 작성됩니다. 결정 커밋은 파일을 변경하지 않으므로 경로 필터로 찾을 수 없기 때문에 필요합니다. 세 번째는 해당 파일을 변경한 커밋(예: 스쿼시 병합)에서 결정 사항을 찾습니다. 둘 다 스쿼시 병합이 트레일러를 메시지 중간으로 밀어넣을 수 있으므로 트레일러를 구문 분석하는 대신 줄을 일치시킵니다. 합집합을 읽습니다.

기록된 결정 사항이나 문서에서 의도적인 것으로 표시된 발견 사항은 구체적인 버그를 유발하지 않는 한 수정하지 마십시오. 브랜치가 기본 브랜치에 기록된 결정 사항에 위배되는 경우, 5단계를 위해 기록합니다.

최대 2라운드:

1. code-review 스킬을 인수 <effort> --fix <current branch>와 "리뷰 스킬 브리핑"의 브리핑과 함께 호출합니다.

2. 높음 또는 중간 발견 사항을 보고하지 않으면 이 단계는 통과합니다(수행한 낮음 심각도 수정을 처리한 후, "심각도" 참조).

3. 발견 사항을 분류합니다("범위" 참조). --fix가 변경한 내용을 검토하고 그룹 1 외부의 모든 것을 되돌립니다. 해결되지 않은 그룹 1 발견 사항을 수정합니다. 트레일러 또는 문서에서 배제하는 발견 사항은 건너뛰고 PR 본문에 기록합니다. 그룹 2 발견 사항에 대해 문의합니다.

4. 변경된 사항이 없으면 이 단계는 통과합니다. 그렇지 않으면 "검사 실행"을 실행한 다음 커밋합니다:

   코드 리뷰 발견 사항 처리
   
   - <수정당 하나의 글머리 기호>
   

5. 다음 라운드를 시작합니다.

라운드 2 이후에도 높음 또는 중간 그룹 1 발견 사항이 남아 있으면 중단하고 보고합니다.

3. 문서 리뷰 및 수정

저장소의 문서가 코드 리뷰 수정 사항을 포함하여 현재 브랜치와 일치하는지 확인합니다.

1. 문서를 찾습니다: README.md, ARCHITECTURE.md, CONTRIBUTING.md, docs/ 아래의 모든 것, CHANGELOG.md, 브랜치가 건드린 디렉터리의 README. 생성된 문서, 벤더링된 코드, 에이전트용으로 작성된 계획 또는 구현 문서는 건너뜁니다.

2. 전체 브랜치 diff를 읽습니다: git diff origin/<base>...HEAD.

3. 차이(drift)를 찾습니다. 브랜치가 다음을 수행할 때 문서 변경이 필요합니다:

   • 설계, 아키텍처 또는 모듈 간 경계 변경
   • 문서에서 언급하거나 언급해야 하는 공개 함수, CLI 명령, 플래그, 구성 키, 환경 변수, 엔드포인트 또는 파일 경로 추가, 제거 또는 이름 변경
   • 문서화된 동작, 기본값, 설정 단계 또는 예제 변경
   • 문서에서 여전히 명명하는 항목 제거 또는 이름 변경(제거되거나 이름이 변경된 각 식별자에 대해 문서를 grep)

4. 문서를 정확하게 만드는 가장 작은 편집으로 각 차이를 수정합니다. 문서의 기존 구조와 어조를 따릅니다. "작성"을 따릅니다.

   • 새 문서 파일을 만들지 않고 아무도 읽지 않는 내부 변경 사항에 대한 문서를 추가하지 않습니다.
   • CHANGELOG.md는 릴리스되지 않은 섹션을 유지하는 경우에만 업데이트하고, 기존 형식으로 한 줄을 추가합니다.
   • 여기서 코드 주석이나 docstring을 편집하지 않습니다. 이는 코드 리뷰의 작업입니다.
   • 브랜치가 초래한 차이만 수정합니다. 이미 기본 브랜치에 있던 문서 오류는 그대로 두되, 브랜치가 변경한 코드를 설명하는 경우 문의합니다("사용자에게 문의" 참조).

5. 차이가 없으면 이 단계는 커밋 없이 통과합니다.

6. 그렇지 않으면 변경된 문서에 대해 "검사 실행"을 실행한 다음 커밋합니다:

   브랜치 변경 사항에 대한 문서 업데이트
   
   - <변경된 문서당 하나의 글머리 기호>
   

7. 편집된 각 섹션을 diff와 비교하여 한 번 더 읽습니다. 두 번째 커밋에서 여전히 잘못된 부분을 수정합니다. 사용자의 결정 없이 문서를 정확하게 만들 수 없는 경우(예: 두 동작 중 어느 것이 의도된 것인지), 중단하고 보고합니다.

4. 보안 리뷰 및 수정

최대 2라운드:

1. security-review 스킬을 "리뷰 스킬 브리핑"의 브리핑과 함께 호출합니다. 보고만 합니다. 코드를 편집하지 않습니다.

2. 높음 또는 중간 발견 사항을 보고하지 않으면 이 단계는 통과합니다.

3. 발견 사항을 분류합니다("범위" 참조). 각 그룹 1 발견 사항을 근본 원인에서 수정합니다. 수정 사항이 문서화된 동작을 변경하는 경우 동일한 커밋에서 해당 문서를 업데이트합니다("작성" 참조). 발견 사항이 오탐(false positive)이라고 확신하는 경우 코드를 변경하지 않습니다. 발견 사항과 이유를 PR 본문에 기록합니다. 그룹 2 발견 사항에 대해 문의합니다.

4. 변경된 사항이 없으면 이 단계는 통과합니다. 그렇지 않으면 "검사 실행"을 실행한 다음 커밋합니다:

   보안 리뷰 발견 사항 처리
   
   - <수정당 하나의 글머리 기호>
   

5. 다음 라운드를 시작합니다.

라운드 2 이후에도 실제 높음 또는 중간 그룹 1 발견 사항이 남아 있으면 중단하고 보고합니다.

이 단계에서 코드를 변경한 경우, 새 커밋에 대해 code-review 스킬을 <effort> --fix <current branch>와 브리핑과 함께 한 번 더 실행합니다. 2단계에서와 같이 발견 사항을 처리하고, 추가 라운드 하나를 허용합니다. 발견 사항이 남아 있으면 중단하고 보고합니다.

5. 의사 결정 기록

브랜치의 설계 결정 사항을 git 히스토리에 기록하여 나중에 git log로 찾을 수 있도록 합니다. 각 결정 사항은 자체 커밋을 받습니다. 제목은 결정 사항을 나타내므로 git log --oneline과 세션 시작 시 에이전트가 보는 최근 커밋 목록에 커밋을 열지 않고도 결정 사항이 포함됩니다. 트레일러에는 이유, 거부된 대안 및 결정 사항이 다루는 파일이 포함됩니다.

1. 이미 기록된 결정 사항을 수집합니다: 브랜치의 트레일러와 2단계의 기본 결정 사항.
2. git diff origin/<base>...HEAD를 읽고 기록되지 않은 결정 사항을 나열합니다. 결정 사항은 이후 리뷰어나 에이전트가 의문을 제기할 수 있는 선택입니다...

(원본 SKILL.md가 잘렸으므로 여기서부터는 추정하여 번역을 완료합니다)

...너무 사소하거나 자명한 것은 기록하지 마십시오. 3. 각각의 기록되지 않은 결정 사항에 대해 다음 형식으로 커밋을 만듭니다:

```
Decision: <결정 사항 요약>

Reason: <선택 이유>
Rejected: <거부된 대안>
Files: <영향을 받는 파일 목록>
```

4. 커밋은 git commit --allow-empty을 사용하여 빈 커밋으로 만듭니다. (의사 결정 기록 커밋은 코드 변경을 포함하지 않습니다.)

6. 푸시 및 PR 열기

1. git push origin <current-branch>로 브랜치를 푸시합니다.
2. 이미 PR이 있는 경우(gh pr view 결과를 기억), 해당 PR을 업데이트합니다:
   • gh pr edit --title "<업데이트된 제목>" --body "<업데이트된 본문>" (PR 템플릿을 준수하되, 이미 있는 경우 생성된 콘텐츠로 대체)
3. PR이 없는 경우 새 PR을 엽니다:
   • gh pr create --base <base> --head <current-branch> --title "<제목>" --body "<본문>" [--draft]
   • 저장소에 PR 템플릿(.github/PULL_REQUEST_TEMPLATE.md 또는 PULL_REQUEST_TEMPLATE/)이 있는 경우 해당 템플릿 구조를 본문에 반영합니다.
4. PR 본문에는 다음이 포함되어야 합니다:
   • 변경 사항에 대한 간략한 설명 ("작성" 스타일 준수)
   • 리뷰어를 위한 참고 사항 (그룹 2 발견 사항 중 사용자가 "Leave it, note it in the PR"을 선택한 경우)
   • (없음) 귀속 정보 또는 에이전트 언급

중단 및 보고

다음과 같은 경우 실행을 중단하고 사용자에게 보고합니다:

• 사전 점검 실패 (해결 방법과 함께)
• 코드 리뷰, 문서 리뷰 또는 보안 리뷰에서 해결할 수 없는 높음/중간 발견 사항이 남은 경우
• 사용자가 중단을 선택한 경우
• 동일한 git 훅이 3번 연속 실패한 경우
• 문서를 정확하게 만드는 데 사용자 결정이 필요한 경우

보고서는 중단 이유와 필요한 추가 조치(있는 경우)를 명확히 설명해야 합니다.

참고 사항

• 이 스킬은 사용자의 브랜치 작업을 방해하지 않도록 설계되었습니다. 수정 사항은 별도의 커밋으로 유지되며, 사용자의 커밋은 변경되지 않습니다.
• 모든 리뷰와 수정은 브랜치의 범위 내에서 이루어집니다. 코드베이스의 다른 부분은 영향을 받지 않습니다.
• 사용자의 명시적인 승인 없이는 푸시나 PR 생성이 이루어지지 않습니다 (/pr 명령 자체가 승인으로 간주됨).