explain-diff-html: PR과 코드 diff를 한 페이지 HTML 설명으로 바꾸는 Claude Code Skill

적합한 사용자

• Claude Code에서 코드 변경 사항을 빠르게 이해하고 싶은 분께 적합합니다. 예를 들어 낯선 저장소를 인수인계받거나, 다른 사람의 PR을 검토하거나, "이번 변경이 무엇을, 왜 바꿨는지"에 대한 공유 가능한 설명 문서를 동료에게 남기고 싶을 때 유용합니다.
• 코드 변경 사항을 하나의 자기완결형(self-contained) HTML 학습 페이지로 바꾸어, 저장소 밖에 출력하며 여러분의 코드에는 손대지 않습니다.
• 적합하지 않은 경우: Claude Code 환경에서 작업하지 않는 경우, PowerShell 또는 cmd.exe가 필요한 경우(공식적으로 지원되지 않으며, POSIX shell에서만 실행 가능), 코드를 직접 수정하거나 롤백하려는 경우(이 도구는 설명 페이지만 생성합니다). 매 실행마다 git이 필요하며, PR을 설명하려면 인증된 gh가 필요합니다(gh auth status로 확인). Mermaid 다이어그램이 포함된 페이지는 CDN에서 라이브러리를 로드하므로 네트워크 연결이 필요합니다. 그 외 공식 문서에 명시되지 않은 의존성이나 제약에 대해서는 본문에서 추측하지 않습니다.

3분 만에 첫 사용 완료하기

사전 요구 사항: Claude Code가 설치되어 있고, 환경이 Linux, macOS 또는 Windows의 WSL / Git Bash이며, 로컬에 git이 있어야 합니다.

설치: 저장소를 Claude Code의 전역 skills 디렉터리(공식 기본 경로)로 클론합니다:

git clone https://github.com/malav2110/explain-diff-html.git \
  ~/.claude/skills/explain-diff-html

특정 프로젝트에서만 사용하려면, 공식 안내에 따라 <your-repo>/.claude/skills/explain-diff-html로 클론하면 됩니다.

첫 작업으로는 저위험의 읽기 전용 시도를 권장합니다: Claude Code에서 자연어 한 문장으로 시작하세요. 예: "explain PR 1234"(병합 권한이 없는, 읽기만 하는 공개 저장소의 PR을 대상으로). 이 작업은 gh 외 추가 조치가 필요 없지만, 먼저 gh auth status가 통과했는지 확인해야 합니다.

성공 신호: skill은 설명 페이지를 홈 디렉터리의 code-explanations 폴더에 YYYY-MM-DD-<KEY>-explanation.html 형식의 파일명으로 작성하고, 그 경로를 알려줍니다. 해당 경로와 생성된 HTML 파일을 확인하면 완료입니다. 주의: 순수 코드 설명 페이지는 오프라인에서 열 수 있지만, 페이지에 Mermaid 상태 다이어그램, 시퀀스 다이어그램 등이 포함된 경우 그래프를 렌더링하려면 네트워크가 필요합니다.

공식 문서는 명령이 POSIX shell이라고만 밝히고 있으며, 다른 파일을 읽고 쓰는지, 어떤 내부 명령을 실행하는지, 어떤 네트워크 엔드포인트에 접근하는지는 설명하지 않으므로 이러한 동작은 알 수 없습니다.

사용 사례

사례 1: PR 이해하기. 상황: 익숙하지 않은 오픈소스 저장소의 변경 사항을 파악해야 합니다. Claude Code에서 "explain PR 1234"라고 말하세요. skill은 PR 설명 흐름을 진행하여 이번 변경의 논리 흐름을 설명하는 한 페이지 HTML을 생성합니다. 기대할 수 있는 결과는 $HOME/code-explanations 아래에 날짜 기반으로 이름 지정된 페이지입니다. 전제 조건은 gh가 인증되어 있어야 한다는 점입니다. 페이지에 Mermaid 다이어그램이 포함되는지는 해당 변경 사항 자체에 따라 다르며, 다이어그램이 있으면 페이지를 열 때 네트워크가 필요합니다.

사례 2: 로컬 diff 이해하기. 상황: 저장소에서 방금 커밋을 완료하거나 pull했고, 팀에 무엇이 바뀌었는지 설명하고 싶습니다. Claude Code에서 자연어로 이 변경 사항을 설명해 달라고 하세요. 확인 가능한 것은 동일한 유형의 자기완결형 HTML 학습 페이지가 생성되어 같은 code-explanations 디렉터리에 출력되고 경로가 보고된다는 점입니다. 공식 문서에 로컬 diff에 대한 구체적인 명령 문구가 명시되어 있지 않으므로, "변경 사항을 한 문장의 자연어로 설명한다"까지만 확정할 수 있으며, 구체적인 트리거 문구는 저장소의 README를 따릅니다.

사용 경계

• 파일과 네트워크: 생성된 HTML을 $HOME/code-explanations(의도적으로 저장소 밖에 위치)에 작성하며, 여러분의 저장소에는 쓰지 않습니다. 페이지에 Mermaid 다이어그램이 있으면 CDN에서 라이브러리를 로드하므로 네트워크가 필요합니다. 이 외에 다른 파일을 읽고 쓰는지, 어떤 명령을 실행하는지는 공식 문서에 명시되지 않았습니다.
• 확인 사항: PR을 설명하기 전에 gh auth status를 실행해 인증을 확인하세요. 생성 작업 자체가 새 HTML 파일을 만들므로, 파일 생성이 부담스러운 사용자는 시작 전에 이 점을 인지해야 합니다.
• 실행 환경: Linux와 macOS는 바로 사용 가능하며, Windows는 WSL 또는 Git Bash가 필요합니다. PowerShell과 cmd.exe는 명시적으로 지원되지 않습니다. 매 실행마다 git이 필요하고, PR 시나리오에는 인증된 gh가 필요하며, Mermaid 다이어그램 검증에는 npx를 통한 node가 필요합니다.
• 공식 제약: 출력은 항상 홈 디렉터리의 code-explanations 폴더에 작성됩니다. 페이지는 Mermaid CDN을 제외하고 자기완결형이며 오프라인에서 열 수 있습니다.
• 미확인 정보: 공식 문서는 어떤 텍스트 언어를 지원하는지, Claude Code 외 다른 agent에서도 작동하는지 설명하지 않습니다. 이에 대해서는 저장소의 최신 문서를 기준으로 하고, 클라이언트 목록으로 추측하지 마세요.