TL;DR

  • Mermaidiff는 PR이나 커밋에 /mermaidiff를 입력하면 코드 변경을 시퀀스 다이어그램으로 요약해 전체 diff를 읽는 대신 약 30초 만에 파악하게 하는 도구임.
  • 변경 단계는 추가(➕)·수정(✏️)·삭제(➖)로 표시하고, 파일·줄 번호와 근거 수준, 관련 페이로드 diff를 함께 제공함.
  • Claude Code, Codex 등 스킬을 불러오는 에이전트와 GitHub PR, GitLab MR에서 동작하며, 서버나 계정이 필요하지 않음.
  • diff나 코드로 입증되는 내용만 표시하고, 저장소 밖의 시스템은 추측하지 않으며 오탐 방지를 최우선 규칙으로 둠.
  • FastAPI, gin, excalidraw의 실제 커밋 10건으로 테스트했으며, 티켓 모드와 Codex는 실험 단계이고 PR별 CI 게시와 전후 분할 보기는 계획 단계임.

Mermaidiff 소개

  • Mermaidiff는 코드 동작의 변경을 보여주는 git diff 도구로, PR이나 커밋에서 /mermaidiff를 실행하면 변경된 내용을 시퀀스 다이어그램으로 표시함.
  • 다이어그램은 새로 추가된 단계(➕), 변경된 단계(✏️), 제거된 단계(➖)를 구분함.
  • Claude Code, Codex 및 스킬을 불러오는 기타 에이전트, GitHub PR, GitLab MR에서 사용할 수 있으며 서버와 계정은 필요하지 않음.

빠른 시작

  • 저장소를 복제하고 설치 스크립트를 실행함: git clone https://github.com/osmangoninahid/mermaidiff && cd mermaidiff && ./install.sh
  • 이후 어떤 저장소에서든 에이전트 안에서 /mermaidiff를 실행하면 스테이징된 변경 사항 또는 최신 변경 사항을 확인함.
  • /mermaidiff <PR 또는 MR 링크> 형식으로 다른 사람의 변경 사항도 확인함.
  • 브리프가 브라우저에서 열리며, “RunTLS 단계를 제거해”처럼 자연어로 변경을 요청하면 열린 탭이 갱신됨.
  • Copy for MR 기능은 GitHub와 GitLab에서 그대로 렌더링되는 마크다운을 복사함.

제공 정보

  • 커밋 메시지가 아니라 diff에서 추출한 코드 변경 요약 한 줄을 제공함.
  • 변경된 단계만 담은 시퀀스 다이어그램을 diff와 같은 색상으로 표시함.
  • 각 단계에 파일:줄 위치와 근거 수준을 표시함: 🔵 코드에서 확인, 🟡 추론, 🟢 실행 중 확인.
  • 요청, 응답, 모델 또는 설정이 바뀌면 페이로드 diff를 표시함.
  • 코드가 입증하는 경우에만 문제점을 표시하고, 미해결 질문은 최대 2개까지 제시함.
  • 커밋 메시지나 PR 설명이 diff에서 확인되지 않는 내용을 주장하면 ⚠️를 표시함.

오탐 방지 원칙

  • 잘못된 경고는 누락보다 나쁘다는 원칙을 적용함.
  • diff나 코드로 입증되는 내용만 표시하며, 저장소 외부 시스템에 관해서는 추측하지 않고 확인되지 않음(Not checked)으로 나열함.

테스트

  • FastAPI, gin, excalidraw의 실제 커밋 10건을 대상으로 테스트하고, 모든 주장을 코드와 대조함.
  • 세부 내용은 eval/에서 확인할 수 있음.

전체 명령어

  • /mermaidiff: 스테이징된 변경 사항, 없으면 스테이징되지 않은 변경 사항, 그것도 없으면 마지막 커밋을 확인함.
  • /mermaidiff staged: 스테이징된 변경 사항을 확인함.
  • /mermaidiff wip: 스테이징되지 않은 변경 사항을 확인함.
  • /mermaidiff a1b2c3d: 지정한 커밋 하나를 확인함.
  • /mermaidiff main..feature: 지정한 범위의 변경 사항을 확인함.
  • /mermaidiff <PR 링크> 또는 /mermaidiff #123: GitHub PR을 확인하며 gh가 필요함.
  • /mermaidiff <MR 링크> 또는 /mermaidiff !123: GitLab MR을 확인하며 glab이 필요함.
  • /mermaidiff ABC-123: 티켓을 확인하는 실험적 모드이며 Jira MCP가 필요함.
  • /mermaidiff "move sync to a queue": 아직 코드가 없는 계획을 입력함.

설치 옵션

  • git과 python3이 필요하며, 호출자 조회를 빠르게 하려면 rg와 CodeGraph 또는 Graphify 사용을 권장함. 해당 도구가 없으면 grep으로 대체함.
  • ./install.sh: 개인용으로 설치하며 ~/.claude/skills와 ~/.agents/skills를 대상으로 함.
  • ./install.sh --project: 저장소에 설치해 팀과 공유함.
  • ./install.sh --link: Mermaidiff 자체를 개발하는 경우 심볼릭 링크로 설치함.
  • 설치 프로그램은 오프라인 사용을 위해 Mermaid를 한 번 내려받고, 전역 git ignore에 .mermaidiff/를 추가함.

상태

  • 커밋, 스테이징된 변경 사항, WIP, 범위: 테스트 완료.
  • GitHub PR, GitLab MR: 테스트 완료.
  • 브라우저 뷰어, 실시간 갱신, MR용 복사: 테스트 완료.
  • 티켓 모드, Codex: 실험 단계.
  • 모든 PR에 브리프를 게시하는 CI 작업: 계획 단계.
  • 변경 전후 분할 보기: 계획 단계.

작동 방식

  • skill/SKILL.md: 에이전트가 git, gh, glab, grep 또는 코드 그래프를 사용해 사실을 수집하는 방법을 정의함.
  • skill/format.md: 출력 형식과 오탐 방지를 포함한 규칙을 정의함.
  • skill/scripts/view.py: 브리프를 HTML로 렌더링하고 통계 행을 다시 계산한 뒤 브라우저를 엶.
  • eval/: 테스트 사례, 기대 답변, 실행 프롬프트, 점수를 포함함.
  • examples/: 공개 저장소에서 가져온 브리프를 포함함.

기여

  • 브리프에서 잘못된 주장을 발견하면 해당 브리프와 커밋 또는 PR 링크를 포함해 이슈를 제출하는 것이 가장 유용한 버그 제보임.
  • 자세한 내용은 CONTRIBUTING.md에서 확인할 수 있음.

라이선스

  • 라이선스는 MIT임.
  • Mermaid 프로젝트와 제휴 관계는 없으며, Mermaid를 사용해 다이어그램을 그림.