md-review

md-review skill 개요

md-review가 하는 일

md-review는 markdown으로 작성한 PR 리뷰 내용을 단일 파일의 2열 HTML 리뷰로 바꿔 주는 Code Review 프레젠테이션 skill입니다. 입력은 unified diff fenced block과 > [!BLOCKER], > [!MAJOR], > [!MINOR], > [!NIT]처럼 심각도 태그가 붙은 코멘트를 포함한 리뷰 markdown을 전제로 합니다. 결과물은 왼쪽에 렌더링된 diff, 오른쪽에 주석 카드, 상단에 findings jump-nav, 하단에 필수 reviewer 이름이 들어간 footer를 배치합니다.

가장 잘 맞는 사용자와 워크플로

md-review skill은 이미 구조화된 코드 리뷰 노트를 markdown으로 작성하고 있으며, 이를 PR 플랫폼 밖에서도 공유하거나 보관하거나 인수인계할 수 있는 휴대성 높은 HTML 산출물로 만들고 싶은 팀에 가장 잘 맞습니다. 엔지니어링 리드, 리뷰어, 문서 관리자, PR 분석을 다듬어진 리뷰 페이지로 변환하는 에이전트 워크플로에 적합합니다. 단순한 markdown 요약보다 리뷰 심각도, 라인 기준 연결, 접근성이 더 중요한 경우 특히 유용합니다.

md-review의 차별점

일반적인 “이 리뷰를 보기 좋게 만들어 줘” 프롬프트와 달리, md-review에는 명확한 파이프라인이 있습니다. diff_parser.py가 unified diff hunk를 추출하고, annotation_extractor.py가 심각도 callout을 가장 가까운 앞쪽 diff block에 연결하며, review_html_renderer.py가 최종 HTML을 생성합니다. 또한 저장소에는 references/diff_rendering_canon.md, references/pr_annotation_ux.md, references/severity_coding.md에 렌더링 기준이 문서화되어 있어, 임의의 LLM 포맷팅보다 결과를 더 예측하기 쉽습니다.

도입 전 확인해야 할 제약

가장 큰 제약은 입력 형식입니다. md-review는 diff hunk가 없는 일반 markdown 페이지, 릴리스 노트, 서술형 보고서용이 아닙니다. 명시적인 reviewer 이름이 없으면 렌더링을 거부하며, 심각도를 색상만으로 표현하지 않도록 설계되어 있습니다. badge에는 WCAG 1.4.1을 고려해 아이콘과 aria-label 텍스트가 포함됩니다. 원본에 실제 unified diff가 없다면 이 작업은 문서 렌더링용 skill로 보내는 편이 맞습니다.

md-review skill 사용 방법

md-review 설치와 확인해야 할 저장소 파일

Claude 호환 skill manager에서는 GitHub 저장소 경로에서 설치할 수 있습니다. 예를 들면 다음과 같습니다.

npx skills add alirezarezvani/claude-skills --skill md-review

설치 후에는 먼저 SKILL.md를 읽어 호출 규칙을 이해하고, 프로덕션에서 사용하기 전에 다음 파일을 확인하세요.

• scripts/diff_parser.py: 허용되는 diff fence 형식과 --infer-diff
• scripts/annotation_extractor.py: callout 파싱과 연결 방식
• scripts/review_html_renderer.py: --reviewer 같은 필수 renderer flag
• assets/md_review_template.html: 최종 페이지 구조
• references/severity_coding.md: 기본 및 custom severity tier

md-review가 파싱할 수 있는 입력 준비하기

좋은 md-review 사용 패턴은 각 finding을 그것이 설명하는 diff 가까이에 두는 markdown에서 시작합니다.

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None
```

> [!BLOCKER]
> This can retry indefinitely if the provider never returns. Add a bounded timeout.

가능하면 diff fenced block을 사용하세요. parser는 --infer-diff를 사용할 때 일부 태그 없는 fence를 추론할 수 있지만, 명시적인 fence가 모호함을 줄입니다. 일반 코멘트를 diff 앞에 두는 것은 해당 코멘트를 unanchored comment로 렌더링하고 싶을 때만 사용하는 것이 좋습니다.

에이전트 워크플로에서 md-review 호출하기

markdown-html orchestrator가 입력을 REVIEW로 분류했을 때 skill을 트리거할 수도 있고, /cs:md-review로 직접 호출할 수도 있습니다. 완전한 프롬프트에는 원본 markdown, reviewer 이름, 심각도 규칙 변경 사항이 포함되어야 합니다.

/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

script를 직접 사용한다면 실무 흐름은 diff block을 JSON으로 파싱하고, 해당 hunk를 기준으로 annotation을 추출한 뒤, --reviewer와 함께 HTML을 렌더링하는 방식입니다. script는 Python stdlib만 사용하므로, 제한이 많은 CI나 로컬 자동화 환경에서도 실행하기가 비교적 쉽습니다.

출력 품질을 높이는 실전 팁

더 정확하게 연결하려면 각 callout을 관련 diff block 바로 뒤에 두세요. 더 나은 triage를 위해 BLOCKER는 반드시 수정해야 하는 문제에만 사용하고, 모든 우려 사항을 MAJOR로 표시하지는 마세요. 훑어보기 좋게 만들려면 각 annotation의 첫 문장을 의사결정 포인트로 작성하세요. jump-nav가 짧은 preview를 사용하기 때문입니다. 팀에서 다른 label을 사용한다면 critical,important,suggestion,nit처럼 가장 심각한 것부터 가장 덜 심각한 것 순서의 custom four-tier convention을 전달하세요.

md-review skill FAQ

md-review는 Code Review 전용인가요?

네. Code Review용 md-review는 의도적으로 범위가 좁습니다. diff hunk와 심각도 annotation이 포함된 markdown PR 리뷰를 HTML 리뷰 페이지로 변환합니다. 일반 markdown 사이트 생성기도 아니고, PR diff 생성기도 아니며, 리뷰 작성 자체를 대신하는 도구도 아닙니다.

markdown에 diff block이 없으면 어떻게 되나요?

잘 맞지 않는 입력입니다. 이 skill의 핵심 레이아웃은 unified diff hunk, line number, addition, deletion, annotation 연결에 의존합니다. diff block이 없으면 결과가 오해를 부를 수 있으므로, 의도된 동작은 거부하거나 문서 중심의 markdown-to-HTML skill로 작업을 넘기는 것입니다.

md-review가 일반 프롬프트보다 나은 점은 무엇인가요?

일반 프롬프트도 보기 좋은 HTML을 만들 수는 있지만, 레이아웃 규칙을 임의로 만들어 내거나, line-number 관례를 놓치거나, 심각도 표시를 색상에만 의존하는 경우가 많습니다. md-review는 구체적인 파싱 및 렌더링 script, 문서화된 2열 리뷰 UX, 명시적인 접근성 제약을 사용합니다. 일관성과 리뷰 의미 구조가 중요할 때 더 적합한 이유입니다.

md-review는 초보자도 쓰기 쉬운가요?

markdown code fence와 unified diff를 이미 이해하고 있다면 초보자에게도 비교적 쉽습니다. prose comment만 가진 초보자라면 먼저 실제 PR diff를 생성하거나 붙여 넣어야 할 수 있습니다. 가장 쉬운 시작 방법은 script의 sample mode를 실행해 본 뒤, sample markdown 구조를 자신의 리뷰에 맞게 조정하는 것입니다.

md-review skill 개선 방법

렌더링 전에 md-review 입력 품질 높이기

md-review 출력 품질을 가장 빠르게 높이는 방법은 원본 리뷰를 개선하는 것입니다. 표준 unified diff header에 file path를 포함하고, @@ hunk header를 유지하며, 리뷰어가 변경 내용을 이해할 수 있을 만큼 충분한 context line을 남기세요. 가능하면 callout 하나에 finding 하나만 담으세요. 서로 관련 없는 문제를 하나의 MAJOR 카드에 합치면 jump-nav의 유용성이 떨어집니다.

흔한 실패 패턴 피하기

자주 발생하는 실패에는 누락된 --reviewer, 잘못된 diff fence, 설정된 convention 밖의 severity label, 참조하는 diff와 너무 멀리 떨어진 annotation이 있습니다. 더 미묘한 문제는 severity를 우선순위가 아니라 어조처럼 사용하는 것입니다. 거칠게 표현된 스타일 선호 사항이라도 여전히 NIT이어야 하고, 차분하게 작성된 correctness issue는 BLOCKER일 수 있습니다.

첫 HTML 출력 후 반복 개선하기

첫 렌더링 후에는 세 가지를 확인하세요. 모든 finding이 상단 jump-nav에 나타나는지, annotation이 의도한 hunk에 연결되었는지, unanchored comment가 정말 일반 코멘트인지입니다. annotation이 잘못된 위치에 붙었다면 HTML을 직접 고치려 하지 말고, 해당 annotation을 관련 diff block에 더 가깝게 옮기세요.

리뷰 모델을 깨지 않는 범위에서 맞춤화하기

customization은 팀의 관례를 반영하는 데 사용해야지, 구조를 약화하는 데 사용해서는 안 됩니다. 조직에서 critical, important, suggestion, nit 같은 label을 사용한다면 custom severity list는 합리적입니다. 반면 출력을 prose report로 바꾸거나, severity icon을 숨기거나, reviewer footer를 제거하면 md-review가 보장하려는 핵심이 약해집니다. 즉, 책임 소재가 명확하고 접근 가능하며 diff 중심인 리뷰 산출물이라는 설계 목적을 해치게 됩니다.