Community코딩 & 개발github.com

머지 리퀘스트 주석 작성

AI가 작성한 변경 사항에 대해 리뷰어가 이해할 수 있도록 의도, 변경 전후 동작, 검증된 진입점 그래프를 포함한 주석을 머지 리퀘스트/풀 리퀘스트에 자동으로 추가합니다. 개요, 파일별, 인라인 주석의 세 가지 레이어로 구성되며, 푸시 후에도 동기화됩니다.

머지 리퀘스트 주석 작성란 무엇인가요?

이 스킬은 AI가 생성한 코드 변경 사항을 리뷰어가 쉽게 이해할 수 있도록 머지 리퀘스트(MR) 또는 풀 리퀘스트(PR)에 자동으로 주석을 추가합니다. 리뷰어가 코드를 분석하는 데 드는 시간을 줄이고, Q&A 없이 MR을 검토 가능하게 만드는 것이 목적입니다. GitLab, GitHub, Bitbucket 등 주요 플랫폼을 지원하며, 주석은 세 가지 레이어로 구성됩니다. MR 수준의 개요 주석(전체 변경 사항의 지도), 변경된 각 파일에 대한 파일 수준 주석(해당 파일 변경의 의미 설명), 그리고 정말 명확하지 않은 부분에만 추가되는 인라인 주석(특정 코드의 이유 설명)입니다. 이 스킬은 먼저 변경 사항 목록을 작성하고, 각 레이어에 맞는 주석을 생성한 후, 사용자 승인 후 게시합니다. 모든 주석에는 식별 마커가 포함되어 있어 이후 푸시 시 '동기화(sync)' 모드로 기존 주석을 새 diff와 비교하여 업데이트, 제거 또는 추가할 수 있습니다. 또한 진입점 그래프는 실제 코드 검색을 통해 검증하도록 하여 잘못된 정보를 제공하지 않도록 설계되었습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

리뷰어를 위한 머지 리퀘스트 주석 작성

AI가 작성한 diff를 읽는 리뷰어는 대부분의 시간을 작성자가 이미 알고 있던 세 가지를 재구성하는 데 사용합니다. 왜 이 변경이 존재하는지, 어떤 동작이 변경되었는지, 이 코드를 누가 호출하는지입니다. 이 스킬은 이 세 가지 정보를 소스 코드 주석이 아닌, 머지 리퀘스트 수준에서 평이한 언어로 작성합니다.

주석은 세 가지 레이어로 구성되며, 각각 다른 규칙을 따릅니다.

레이어범위내용
개요 - MR 수준 주석 1개항상전체 변경 사항의 지도
파일 - 변경된 파일당 1개 주석항상, 자동 생성 파일 제외이 파일 변경의 의미
인라인 - diff 라인에 고정정말 명확하지 않은 부분만, 예산 제한이 특정 코드가 이렇게 작성된 이유

파일 커버리지는 조건부가 아닙니다. 리뷰어가 diff에서 어떤 파일을 열든 해당 파일에 대한 설명이 있어야 합니다. 명확하지 않은 부분과 명확한 부분을 판단하는 것은 파일 내에서 메서드와 개별 청크에 적용되며, 파일 자체가 주석을 받을지 여부에는 적용되지 않습니다.

작동 모드

모드시점동작
annotateMR 첫 실행 시전체 주석 세트를 구축하고 미리 본 후 승인 시 게시
syncMR 브랜치에 푸시할 때마다기존 주석을 새 diff와 비교하고 변경된 내용만 업데이트, 제거 또는 추가

이 스킬의 주석이 이미 MR에 존재하는 경우(마커로 감지, §7 참조), annotate를 다시 실행하지 말고 sync를 실행하세요. annotate를 다시 실행하면 주석이 중복됩니다.

1. 사전 점검

무엇이든 작성하기 전에 다음을 확인합니다.

  1. 플랫폼 및 MR 식별. git remote -v → gitlab.com/자체 호스팅 GitLab, github.com 또는 Bitbucket. 그런 다음 현재 브랜치의 오픈 MR을 찾습니다(glab mr view, gh pr view). MR이 없으면 중단하고 그 사실을 알립니다. 이 스킬은 기존 MR에 주석을 달며, MR을 생성하지는 않습니다.
  2. Diff 범위. 항상 git merge-base HEAD origin/<대상-브랜치> → <base>..HEAD를 사용합니다. 대상 브랜치의 최신 커밋과 직접 비교하지 마세요. 대상에 병합된 관련 없는 커밋이 이 MR의 변경 사항으로 표시될 수 있습니다.
  3. 언어. 프로젝트의 MR이 이미 사용하는 언어로 주석을 작성합니다(기존 MR/PR 설명 및 주석 확인). 기본값은 사용자가 말하는 언어입니다.
  4. 게시 권한. MR에 게시하는 것은 팀 전체에 공개되며 리뷰어에게 알림이 전송됩니다. 기본적으로 대화에서 드라이런 미리보기를 제공하고 사용자가 승인한 후에만 게시합니다. 사용자가 미리 묻지 않고 게시하라고 말한 경우에만 미리보기를 건너뜁니다.

정확한 명령어는 references/platform-gitlab.md, references/platform-github.md, 또는 references/platform-bitbucket.md를 참조하세요. 주석 API는 중요한 부분(파일 수준 고정, 해결 가능성, 업데이트 의미)에서 다릅니다.

2. 변경 인벤토리 구축

두 개의 스크립트는 이 파일 옆에 있는 scripts/ 디렉토리에 있습니다. 절대 경로로 호출하세요. 이 경로는 이 스킬의 자체 디렉토리에서 빌드됩니다. 스킬 실행 중 작업 디렉토리는 사용자의 저장소이지 스킬 디렉토리가 아니므로 단순 scripts/... 경로는 실패합니다. 아래에서 $SKILL은 이 SKILL.md가 포함된 디렉토리를 나타냅니다(예: 사용자 수준 설치의 경우 ~/.claude/skills/annotate-merge-request, 플러그인에서 로드된 경우 플러그인의 skills/annotate-merge-request).

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

변경된 각 파일에 대해 변경 종류(추가/수정/삭제/이름 변경), requires_file_comment(자동 생성/벤더 파일에서만 false), file_fingerprint, 그리고 새 쪽 라인 번호(인라인 주석이 고정되어야 하는 위치), 가장 가까운 포함 심볼, 사소함 신호가 포함된 파일의 청크를 제공합니다. spec 및 테스트 파일의 경우 test_cases도 제공합니다. 이는 diff에서 직접 읽는 것이 아니라 두 리비전 간의 케이스 본문을 비교하여 계산된 각 케이스의 상태(unchanged / adapted / added / removed)입니다. 이는 읽기를 위한 휴리스틱 맵이며, 설명하려는 내용의 실제 diff를 읽어야 합니다.

각 청크의 anchor는 제안(첫 번째 추가된 라인)이며, added_lines는 대신 고정할 수 있는 해당 청크의 모든 라인을 나열합니다. 설명이 실제로 관련된 라인을 선택하세요.

하드 제약: 인라인 주석은 diff에 나타나는 라인에만 고정할 수 있습니다. GitLab과 GitHub 모두 청크에서 멀리 떨어진 수정되지 않은 코드에는 주석을 달 수 없습니다. MR이 수정하지 않은 코드에 대해 말하고 싶은 내용은 파일 또는 개요 주석에 포함해야 하며, 인라인으로 포함해서는 안 됩니다.

3. 레이어 1 - 모든 변경된 파일 다루기

인벤토리가 requires_file_comment: true로 표시한 모든 파일은 정확히 하나의 파일 수준 주석을 받습니다. 예외, 예산, "흥미로운지"에 대한 판단은 없습니다.

유일한 예외는 자동 생성 및 벤더 출력입니다. lockfiles, dist/, 스냅샷, 코드 생성, 축소된 번들, vendor/입니다. 인벤토리가 이러한 파일을 표시합니다. 프로젝트에서 생성하는 파일을 놓친 경우에도 제외하고 사용자에게 추가할 패턴을 알려주세요.

변하는 것은 형태와 길이이지, 존재 여부가 아닙니다.

  • 실제 로직 변경이 있는 파일은 전체 템플릿(references/annotation-format.md)을 사용합니다: 역할, 변경 이유, 이전 → 이후, 어디서 호출되는지.
  • spec 또는 테스트 파일은 대신 테스트 케이스 목록을 받습니다. 현재 포함된 모든 케이스와 각각의 상태(unchanged / adapted / added / removed), 변경된 케이스에 대한 간단한 설명입니다. 표준 템플릿은 spec에 적합하지 않습니다. spec을 호출하는 곳은 없으므로 진입점 섹션은 본질적으로 비어 있습니다. 인벤토리가 상태를 계산합니다(파일당 test_cases). adapted 케이스는 리뷰어가 가장 필요로 하는 것이므로 먼저 나오며 호출 형태 또는 기대값이 변경되었는지 말해야 합니다. 전체 규칙은 references/annotation-format.md에 있습니다.
  • 기계적인 파일은 리뷰어가 확신을 가지고 건너뛸 수 있는 한 줄을 받습니다: 가져오기 경로만 변경됨 - PricingService 이름 변경에 따른 것; 동작 변경 없음.
  • 삭제된 파일은 왜 삭제되었고 무엇으로 대체되었는지에 대한 한 줄을 받습니다. 종종 MR에서 가장 유용한 주석입니다.

이를 파일 수준 주석(GitHub에서는 subject_type=file, GitLab에서는 position_type=file)으로 고정하고, 라인에 고정하지 마세요. 파일 헤더에 첨부되므로 코드와 섞이지 않으며 리뷰어가 각 파일을 열 때 만나게 됩니다. 인스턴스가 파일 수준 고정을 지원하지 않는 경우 파일의 첫 번째 변경된 라인으로 폴백합니다. 플랫폼 참조에 정확한 폴백 방법이 나와 있습니다.

한 줄을 잘 작성하는 것이 이 스킬의 핵심입니다. 볼륨은 파일 수에 비례하므로 세 단락으로 설명된 기계적 파일은 결함이지 철저함이 아닙니다.

4. 레이어 2 - 개요 주석

MR 수준의 주석 하나로, 전체 리뷰의 진입점이며 references/annotation-format.md에 지정된 대로 정확히 구성됩니다.

  • 의도 - 이 MR이 해결하는 문제, 두세 문장, 평이한 언어. diff를 다시 말하지 않음.
  • 변경 전 → 변경 후 동작 - 실행 중인 시스템의 관찰자가 알아차릴 수 있는 점. 새 구성 요소의 경우 "이전"을 지어내지 말고 "새로움"이라고 말함.
  • 진입점 그래프 - 독자가 실제 진입점(HTTP 경로, CLI 명령, 이벤트 핸들러, 크론, 내보낸 API)에서 변경된 코드에 도달하는 방법. 최대 3레벨로 제한됨. 파일당이 아닌 변경된 영역당 한 줄.
  • 읽기 순서 - 어떤 파일을 먼저 열어야 하는지, 어떤 파일이 기계적인 후속 작업인지.
  • 인라인 주석 색인 - 각 인라인 주석에 대한 링크.

개요에는 자체 볼륨 제한이 있습니다(최대 7개의 읽기 순서 항목, 최대 5개의 동작 행, 파일별 열거 없음 - 파일 주석이 그 역할을 함). 이는 references/annotation-format.md에 있습니다. 이를 준수하지 않으면 개요가 파일 주석이 방지하려고 했던 장문의 텍스트 덩어리가 됩니다.

진입점 그래프 검증

절대 호출 그래프를 추측하지 마세요. 조작된 호출자 목록은 주석이 없는 것보다 더 나쁩니다. 확신에 차서 잘못된 정보를 제공하며 리뷰어가 이를 신뢰할 것입니다. 주장된 각 엣지에 대해 실제 검색(rg -n 'symbolName' 저장소 전체, 테스트 및 설정 포함)으로 호출자를 찾고, 진입점 또는 3레벨 중 먼저 도달하는 곳까지 위로 추적하세요. 심볼의 호출자를 확인할 수 없는 경우(동적 디스패치, DI 컨테이너, 리플렉션, 문자열 키 기반 레지스트리), 그럴듯한 체인을 작성하는 대신 진입점 확인 불가 (<이유>)라고 작성하세요.

5. 레이어 3 - 코드가 명확하지 않은 경우에만 인라인 주석

판단이 필요한 유일한 레이어입니다. 모든 메서드와 청크에 대해 references/significance-test.md의 유의성 테스트를 실행하세요.

다음과 같은 경우 주석을 답니다. 독자가 합리적으로 "왜 이렇게 되었지?"라고 질문할 수 있는 경우 - 명확하지 않은 의도, diff에서 보이지 않는 동작 변경, 지역적이지 않은 결과, 의도적인 트레이드오프, 일반적이지 않은 알고리즘, 해결 방법, 파일 외부의 제약 조건, 또는 이 동일한 MR의 다른 변경과의 상호 작용.

다음과 같은 경우 건너뜁니다. 코드가 이 코드베이스에 능숙한 독자에게 설명이 되는 경우: 문자열을 제목 형식으로 바꾸는 5-10줄의 헬퍼, DEBOUNCE_MS = 300 상수, 명백한 null 검사, 기계적인 테스트 업데이트. 파일 주석이 이미 파일을 다루고 있습니다. 여기에 인라인 주석을 추가하면 더 낮은 가치로 반복됩니다.

코드의 크기는 테스트 대상이 아닙니다. 추론 거리가 중요합니다. 사용자 정의 인코딩 체계 내부의 6줄 헬퍼는 주석이 필요합니다. 200줄의 생성된 스냅샷 파일은 그렇지 않습니다.

예산 (기본값, 사용자가 명시적으로 늘릴 수 있음):

  • 파일당 최대 3개의 인라인 주석, MR당 최대 12개.
  • 이는 상한선이며 할당량이 아닙니다. 파일 주석으로 이야기가 완전히 전달되는 파일은 0개의 인라인 주석을 받으며, 이것이 정상적인 경우입니다.
  • 예산 초과는 신호이지 허가가 아닙니다. 하나의 MR에서 12개 이상의 부분이 정말 명확하지 않다면 MR이 너무 크거나, 설명이 하나의 이야기로 전달될 수 있는 개요에 속합니다. 사용자에게 그렇게 말하세요.

각 인라인 주석은 파일 주석과 동일한 섹션을 사용하지만 해당 청크로 범위가 지정되며 짧게 유지합니다. 3~6줄, 좁은 diff 보기 내에서 읽습니다.

6. MR 내 상호 참조

변경 사항이 동일한 MR의 다른 변경과 함께 있을 때만 의미가 있는 경우 서로 연결하세요. 상호 참조는 일반적으로 진입점 그래프에 속하지만 의도("<다른 파일>이 이제 X를 전달하기 때문에 필요함") 및 변경 전/후("이전 경로는 여전히 존재합니다. <다른 주석> 참조")에도 나타납니다. 파일 주석이 가장 자연스러운 위치입니다: 이 파일의 새 계약은 [[ref:order-controller]]에서 사용됩니다.

주석 URL은 주석이 게시될 때까지 존재하지 않습니다. 따라서 상호 연결에는 두 단계가 필요합니다.

  1. 다른 주석에 대한 링크가 있어야 하는 위치에 플레이스홀더 토큰([[ref:<슬러그>]])을 포함하여 모든 주석을 게시합니다.
  2. 생성된 주석의 ID/URL을 수집한 다음 각 본문을 편집하여 토큰을 실제 링크로 바꿉니다.

게시하기 전에 슬러그를 계획하세요. 모든 [[ref:...]] 토큰은 2단계에서 확인되어야 하며, 게시된 주석에 남은 토큰은 눈에 띄는 결함입니다. 2단계는 선택 사항이 아닙니다.

7. 식별 마커와 함께 게시

이 스킬이 생성하는 모든 주석은 렌더링된 마크다운에서 보이지 않는 마커 라인으로 끝납니다.

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<슬러그> anchor=<파일> ffp=<파일-지문> -->
<!-- sdmr:v1 kind=inline slug=<슬러그> anchor=<파일>@<새-라인> fp=<청크-지문> -->

ffp=에는 인벤토리의 file_fingerprint를 사용하고 fp=에는 청크 fingerprint를 사용하세요. 마커는 sync를 가능하게 하는 요소입니다. 즉, 스킬 자체의 주석, 각 주석이 첨부된 대상, 설명된 코드의 지문을 식별합니다. 마커 없이 주석을 게시하지 마세요. 사람의 주석을 편집하지 마세요.

주석을 해결되지 않은 상태로 두세요. 해결된 스레드는 축소되어 렌더링되므로 리뷰어가 모든 주석을 하나씩 펼쳐야 합니다. 이는 주석이 존재하는 이유를 정확히 숨기는 것입니다. 열린 상태로 게시하고 리뷰어가 읽을 때 각 주석을 해결하도록 하세요. 그 클릭이 리뷰어 자신의 "읽음" 마커입니다.

이 선택의 비용: 프로젝트에서 병합 전에 모든 스레드가 해결되어야 하는 경우(GitLab의 모든 스레드가 해결되어야 함, GitHub의 대화 해결 필요), 병합 버튼이 활성화되기 전에 주석을 해결해야 합니다. 파일당 파일 주석이 있으므로 이제 실제 클릭 수가 발생합니다. 따라서 이러한 설정을 감지하면 사용자에게 알리고 마지막에 일괄 해결을 제안하세요. 두 플랫폼에 대한 명령어는 플랫폼 참조 파일에 있습니다.

8. 푸시 후 동기화

새 커밋은 자동으로 주석을 무효화합니다. 주석이 설명하는 코드가 이동하거나, 의미가 변경되거나, 사라졌을 수 있으며, 새 파일은 전혀 커버리지가 없습니다. MR 브랜치에 푸시할 때마다 sync 모드에서 이 스킬을 다시 실행하세요.

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments는 반복 가능하며 플랫폼의 원시 JSON을 그대로 사용합니다. GitHub에서는 리뷰 주석과 이슈 주석이라는 두 번의 호출이 필요하므로 두 파일을 모두 전달하세요.

기존 주석을 ok(앵커와 지문 변경 없음 - 그대로 둠), moved(동일한 코드, 새 라인 - 재앵커), stale(설명된 코드 변경됨 - 다시 읽고 다시 작성), 또는 orphaned(파일 또는 청크 사라짐 - 삭제)로 분류합니다. 또한 **file coverage**를 보고합니다. 즉, 어떤 변경된 파일에 파일 수준 주석이 여전히 없는지, 어떤 파일이 면제되는지, 그리고 인라인 주석의 후보가 되는 uncovered 청크입니다.

그런 다음 플래그가 지정된 내용만 수정하고, 항상 개요 주석을 제자리에서 다시 작성하고(MR 전체를 요약하므로 모든 푸시가 이를 무효화할 수 있음), §6의 2단계를 다시 실행하여 상호 참조 링크가 여전히 활성 주석을 가리키도록 합니다. 파일 커버리지의 MISSING 행은 선택적 작업이 아닙니다. 주석이 없는 새 파일은 이 스킬이 방지하기 위해 존재하는 유일한 격차입니다. 강제 푸시 케이스, 플랫폼별 삭제된 주석 처리, 실제로 변경되지 않은 주석의 요동을 방지하는 방법은 references/sync-after-push.md를 참조하세요.

사용자에게 각 푸시 후에 이 작업을 실행해야 한다는 점과, references/sync-after-push.md에 선택적 pre-push 후크가 포함되어 있다는 점을 한 번 언급하세요.

관련 스킬