PR 개선기(PR Improver)
/code-improver:improve를 실행하여 현재 브랜치를 개선합니다. 이 명령어는 PR 리뷰어와 수정 하위 에이전트를 브랜치의 변경 사항에 대해 반복 호출하여 리뷰에서 심각/중대한 문제가 보고되지 않을 때까지 루프를 실행하는 동적 워크플로우입니다. 루프, 원장(ledger), 보호 장치는 워크플로우에 있으며, 이 스킬은 브랜치 차이(diff)에서 범위를 파생하고 결과를 전달합니다.
루프 시작하기
사용자가 제공한 내용: $ARGUMENTS (비어 있으면 대화에서 기준 브랜치와 기본 설정을 가져옵니다).
1. 브랜치 및 변경 표면 해결
- 저장소 루트:
git rev-parse --show-toplevel. 저장소 외부에서는 명시적으로 실패합니다. - 기준 브랜치: 인수가 주어지면 해당 인수, 그렇지 않으면 저장소의 기본 브랜치 (
git symbolic-ref refs/remotes/origin/HEAD→ 짧은 이름,main으로 폴백). 현재 브랜치가 기준 브랜치와 같으면 실행을 거부합니다 — 개선할 차이가 없습니다. - 변경된 파일:
git diff --name-only <base>...HEAD. 비어 있으면 알리고 중지합니다. - 범위: 변경된 파일의 디렉토리를 확장하여 결정합니다. 파일별 글로브는 너무 제한적입니다 (PR 수정은 변경된 코드 옆에 테스트를 정당하게 추가합니다). 각 변경된 파일을 저장소-상대 디렉토리 글로브
<dir>/**로 매핑합니다 (루트에 파일이 변경된 경우에만**), 중복을 제거하고 다른 글로브에 포함된 글로브는 삭제합니다.
2. 루프 스크립트 해결
루프는 이 플러그인의 동적 워크플로우 workflows/improve.js입니다. 경로로 실행합니다: scriptPath는 절대 경로를 받고, Workflow 도구의 name은 내장 및 프로젝트 워크플로우를 해결하므로 마켓플레이스에서 설치된 것은 code-improver:improve에 응답하지 않을 수 있습니다. 순서대로 시도하고, 첫 번째로 발견된 것을 사용합니다 — 홈 디렉토리가 .보다 먼저 오므로 설치된 복사본이 이 마켓플레이스의 체크아웃보다 우선합니다:
Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"(해당 변수가 대신 설정된 경우)Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null
출력된 경로를 정확히 사용하세요. 플러그인 디렉토리 — /workflows/improve.js를 제거한 경로 — 는 pluginRoot입니다. 세 가지 모두 비어 있으면 {name: "code-improver:improve"}를 한 번 시도합니다. 그마저도 사용할 수 없으면 중지하고 루프를 찾을 수 없다고 말합니다. 경로를 수동으로 조립하지 말고 루프를 즉석에서 구현하지 마십시오.
3. 워크플로우 호출
Workflow 도구를 사용하여 {scriptPath: "<2단계의 경로>", args: {...}}로 실행합니다:
{
"target": "<저장소 루트>",
"reviewer": {
"kind": "skill",
"name": "pr-review-toolkit:review-pr",
"notes": "작업 트리의 변경 사항을 <base>에 대해 풀 리퀘스트로 리뷰: 정확성, 테스트, 오류 처리, 그리고 스킬이 규정하는 리뷰 차원."
},
"scope": ["<파생된-디렉토리-글로브>/**"],
"pluginRoot": "<2단계의 플러그인 디렉토리>",
"maxRounds": 5
}
reviewer— 위의 기본값은pr-review-toolkit플러그인이 필요합니다. 사용자가 다른 PR 리뷰어(스킬 또는 에이전트)를 지정하면 그에 맞게 kind를 설정하여 사용합니다.maxRounds— 사용자가 다른 상한을 요청한 경우에만 설정합니다.pluginRoot— 실행이 메트릭 수집기를 찾을 수 있도록 합니다. 2단계가 워크플로우 이름으로 대체된 경우에만 키를 생략합니다 — 워크플로우가 자체적으로 검색합니다.finalize기본값은 PR에 적합합니다. 브랜치가 플러그인 내부에 있지 않으면 버전 범프 없음, 내레이션 스트립 및 문서 패스는 그대로 진행합니다.decision— 계속 진행하는 경우에만 사용합니다 (아래 참조).
루프의 기준 스냅샷은 루프 시작 시점의 트리입니다. 범위 보호 장치는 브랜치의 커밋되지 않은 작업을 보호합니다. PR 자체의 커밋은 리뷰어가 리뷰하는 대상입니다.
워크플로우는 백그라운드에서 실행되며 감독이 필요하지 않습니다: 리뷰, 수정, 재리뷰, 각 수정 라운드 후 범위 확인을 수행하며, 깨끗한 리뷰에서만 완료할 수 있습니다. 절대 커밋하지 않습니다. 모든 변경 사항은 작업 트리에 유지됩니다.
Workflow 도구를 사용할 수 없거나 거부된 경우 중지하고 그렇게 말합니다. 직접 편집으로 루프를 즉석에서 구현하지 마십시오 — 원장, 범위 보호 장치, 에스컬레이션 보장은 워크플로우에 있으며, 인라인 모방에는 이러한 기능이 전혀 없습니다.
결과가 halted: "reviewer-unavailable"이면 전달하고 중지합니다. 리뷰어가 이 세션에 설치되지 않았습니다. 어느 플러그인이 제공하는지 사용자에게 알리고(기본값은 pr-review-toolkit 필요) 설치 후 다시 실행하도록 합니다. 직접 브랜치를 리뷰하지 마십시오.
루프가 실행되는 동안 턴을 종료하지 마십시오. Workflow 도구는 즉시 작업 ID를 반환합니다. 결과는 나중에 옵니다. 대화형 세션에서는 완료 알림이 다시 호출하므로 기다리십시오. 비대화형 실행(스크립트, CI, 평가)에서는 나중 턴이 없습니다. 중간에 중단하면 루프가 라운드 중간에 버려지므로 실행 시작 후 반환된 작업 ID로 TaskOutput을 폴링하거나 sleep-and-recheck하여 완료될 때까지 기다린 후 결과를 전달합니다. "루프가 실행 중입니다. 나중에 보고하겠습니다."라고 응답하는 세션은 실행을 잃게 됩니다.
결과 전달
워크플로우는 구조화된 결과를 반환합니다. 차이점이 중요하므로 정직하게 보고하십시오:
converged: true— 마지막 작업이 심각/중대한 문제가 없는 리뷰였습니다. 사용된 라운드 수, 남은 사소한 문제(open_minor_count), 아티팩트 경로(ledger_path,metrics)를 보고합니다.capped: true— 수정 예산이 소진되었고 최종 리뷰에서 여전히 차단 문제가 발견되었습니다. 명확하게 말합니다: 상한 도달, 수렴되지 않음,open_blocking을 나열합니다. 이것을 성공으로 제시하지 마십시오.escalation— 루프가 수렴하지 않음을 감지했습니다(반복되는 발견, 감소하지 않는 수, 또는 문제를 재배치한 수정). 에스컬레이션 메시지와 발견 ID를 사용자에게 전달합니다: 더 많은 라운드가 아닌 설계 결정이 필요합니다.halted— 보호 장치가 작동했습니다(범위 위반, 등록되지 않은 새 파일, 중단되었거나 사용할 수 없는 리뷰어, 또는 편집이 후속 검사에 실패한 finalize 패스).violations/new_untracked_files의 경로,finalize_regressions의 위치, 노트를 전달합니다.notes— 항상 결과와 함께 제공됩니다. 이를 표면화하십시오. "git 저장소가 초기화되었습니다"와 같은 큰 경고를 포함합니다.
에스컬레이션 후 계속하기
루프는 설계상 에스컬레이션 시 중지됩니다. 사용자가 결정하면 동일한 인수에 다음을 추가하여 새 실행을 시작합니다:
{ "decision": "<사용자의 판결, 그대로>" }
새 실행은 디스크의 원장을 다시 로드하므로 모든 발견, 거부, 판정이 이어집니다. 라운드는 재시작되지만 재파생은 발생하지 않습니다.
실행 중인 루프를 중지하려면 워크플로우 작업을 중지하십시오(TaskStop). 디스크의 원장은 마지막 라운드까지 최신 상태이며 재실행은 그 지점부터 재개됩니다.
사용하지 말아야 할 경우
- 일회성 리뷰: PR-review 스킬을 직접 실행하십시오. 루프의 가치는 반복에 있습니다.
- 스킬 개선:
skill-improver항목을 사용하십시오. 올바른 리뷰어를 연결합니다. - 푸시되지 않은 탐색적 작업: 리뷰-수정 루프는 diff를 강화합니다. 형태가 유동적인 경우 수동 반복이 더 많은 제어를 제공합니다.