gitpodium — 대화형 기여 감사은(는) 무엇을 하나요?
귀하(에이전트)는 이 전체 과정을 처음부터 끝까지 실행합니다. 사용자는 명령어를 직접 입력할 필요가 없습니다.
설정은 간단한 인터뷰 형식으로 진행하고, 계획을 확인받은 후 파이프라인을 실행하고, 보고서를 전달하며, 항상 주의사항을 언급해야 합니다.
질문은 소규모로 묶어서 하십시오(Claude Code에서는 AskUserQuestion 사용). 한 줄씩 인터뷰하지 마십시오.
GP 아래는 이 스킬의 디렉터리 경로입니다. 모든 단계는 사용자가 선택한 출력 디렉터리(GITPODIUM_OUT, 기본값은 현재 디렉터리)에 결과물을 기록합니다.
0단계 — 사전 요구사항 (다른 것을 묻기 전에 먼저 확인)
gh auth status— 인증되지 않은 경우, 사용자에게gh auth login을 실행하라고 안내합니다(Claude Code에서는! gh auth login을 입력하면 됩니다). 필요한 토큰 범위:repo(비공개 저장소) 및read:org(조직 저장소 목록). 계속하기 전에 다시 확인하세요.git,python3,bash,awk가 존재하는지 확인합니다(macOS/Linux의 표준). 누락된 경우 중단하고 보고합니다.
gh auth status가 성공적으로 완료된 후에만 진행합니다.
1단계 — 범위 (감사할 대상)
사용자에게 물어보세요:
- 어떤 GitHub 소유자? 하나 이상의 조직 및/또는 사용자(예:
acme-inc acme-labs). 사용자 자신의 저장소도 가능합니다.gh org list/gh repo list <owner> --limit 5를 실행하여 올바른 이름을 확인할 수 있도록 제안하세요. - 전체 소유자 또는 일부? 특정 저장소만 원하는 경우
owner/repo목록을 수집하여 전체 조직 대신 저장소 파일(-f repos.txt)을 사용하세요. - 참고: 비공개 저장소는
gh토큰이 접근할 수 있는 경우에만 포함됩니다.
매핑 → clone-all.sh 인수 또는 -f repos.txt 파일
2단계 — 순위 측정 기준
질문: 어떤 기준으로 순위를 매길까요? (HTML 보고서는 항상 뷰어가 실시간으로 전환할 수 있습니다. 이 설정은 기본 보기와 보고할 헤드라인을 결정합니다):
| 선택 | 의미 |
|---|---|
churn (기본값) | 추가 + 삭제된 라인 — "얼마나 많은 코드가 움직였는가"를 나타내는 가장 일반적인 지표 |
commits | 커밋 수 — 활동/빈도, 대규모 리팩터링에 덜 영향받음 |
added / deleted | 성장 vs. 정리 |
net | 추가 − 삭제 |
repos | 폭(얼마나 많은 저장소를 건드렸는지) |
매핑 → GITPODIUM_METRIC=<선택> (보고서 빌드에 전달). 이는 git 변동 보기의 순위를 결정합니다. 보고서에는 자체 GitHub 지표가 있는 협업 탭(다음 문단)도 포함되므로, 둘 중 하나를 선택할 필요 없이 둘 다 빌드됩니다.
추가 수집: GitHub 협업 (PR, 리뷰, 이슈)
git 히스토리 외에도 gitpodium은 GitHub API(gitpodium github)에서 풀 리퀘스트, 코드 리뷰, 리뷰 코멘트, 이슈를 가져와 GitHub 로그인별로 협업 탭에 표시합니다. 이는 변동(churn)이 포착하지 못하는 작업(코드를 거의 작성하지 않지만 리뷰를 많이 하는 사람)을 보여줍니다. 보고서를 소개할 때 이 내용을 언급하세요. 전달할 주의사항:
ghAPI가 필요하며 GitHub에 호스팅된 저장소만 토큰이 볼 수 있는 범위 내에서 처리합니다. GraphQL 속도 제한이 적용됩니다. 이를 건너뛰려면GITPODIUM_SKIP_GITHUB=1을 설정합니다(GitHub 외 저장소 또는 속도 제한 절약을 위해).- 이슈는 팀이 Jira/Linear를 사용하는 경우 거의 비어 있을 수 있습니다. 이는 정상적인 현상이며 버그가 아닙니다.
- 봇(GraphQL
Bot유형 행위자,*[bot],extra_bots)은 리뷰어에서 제외됩니다.
3단계 — 시간 범위
질문: 전체 기간, 아니면 날짜 범위? 그리고 콘솔 요약에서는 월/분기/연도로 버킷팅할까요? HTML 보고서는 항상 모든 히스토리와 실시간 시간 필터를 포함하며, 시간 범위는 주로 사용자에게 설명할 콘솔 리더보드를 결정합니다.
매핑 → report.sh FROM TO [month|quarter|year]
4단계 — 노이즈 필터
기본값을 설명하고 사용자가 조정하도록 하세요:
- 봇(
dependabot, CI, AI 에이전트) — 기본적으로 제외됨(DROP_BOTS=1). - 대량/벤더 덤프(프레임워크 임포트, 생성된 코드) —
MAXCHURN=10000라인 또는MAXFILES=400파일을 초과하는 단일 커밋은 가짜 승자를 만들지 않도록 제거됩니다. 원한다면 "필터링 없음, raw"(MAXCHURN=0 MAXFILES=0 DROP_BOTS=0)도 제공합니다.
매핑 → 환경 변수 DROP_BOTS, MAXCHURN, MAXFILES
5단계 — 출력
질문: 보고서를 어디에 저장할까요? 기본값: 현재 디렉터리 → ./report.html(하나의 독립형 파일, 서버 불필요, 이메일/Slack에 첨부 가능). GITPODIUM_OUT을 설정합니다.
6단계 — 계획 확인 후 실행
한 문단으로 계획을 요약해 보여주세요: 소유자, 측정 기준, 시간 범위, 필터, 출력. 승인을 받으면 선택한 환경 변수를 내보내고 실행합니다. 저장소가 많은 경우 클론을 백그라운드에서 실행합니다:
export GITPODIUM_OUT="<출력-디렉터리>" GITPODIUM_METRIC="<측정-기준>" \
MAXCHURN=<n> MAXFILES=<n> DROP_BOTS=<0|1>
"$GP/bin/clone-all.sh" <소유자...> # 또는: -f repos.txt (멱등성, 재실행 시 업데이트)
"$GP/bin/build-mailmap.py" "$GITPODIUM_OUT/clones"
"$GP/bin/collect.sh" "$GITPODIUM_OUT/clones"
"$GP/bin/rollup.sh"
"$GP/bin/collect-github.py" <소유자...> # PRs/리뷰/이슈 -> github.json (gh API, GITPODIUM_SKIP_GITHUB=1로 건너뛰기)
"$GP/bin/build-report.py" # -> $GITPODIUM_OUT/report.html (두 데이터셋 모두 포함)
(동등한 한 줄 명령: 환경 변수를 내보낸 후 "$GP/gitpodium" run <소유자...> — run은 GitHub 단계를 최선 방식으로 포함하므로 API가 실패해도 git 보고서는 생성됩니다.)
7단계 — 신원 검토 (강요하지 말고 제안)
build-mailmap.py가 실행된 후, 병합된 신원 수를 출력하고 mailmap-review.md를 작성합니다 — 낮은 신뢰도의 추측(한 이름이 다른 이름의 접두사인 경우)은 병합되지 않은 상태로 남깁니다. 이를 보여주겠다고 제안합니다. 사용자가 병합을 확인하면 gitpodium.identity.json 파일에 내용을 기록하고(force_merge / canonical_override / extra_bots — examples/gitpodium.identity.json 참조), GITPODIUM_IDENTITY를 설정한 후 build-mailmap.py → collect.sh → rollup.sh → build-report.py를 다시 실행합니다.
8단계 — 전달
- 사용자에게
report.html을 알려줍니다(브라우저에서 바로 열 수 있습니다). "$GP/bin/report.sh"를 사용하여 상위 기여자 몇 명을 설명합니다(같은 시간 범위/필터 env를 따름). 투명성 라인은 벌크/봇으로 얼마나 많은 커밋/변동이 제거되었는지를 보여줍니다 — 아무것도 숨겨진 것처럼 보이지 않도록 언급합니다.- 협업 탭(
github.json이 빌드된 경우)을 가리킵니다: 상위 리뷰어와 "변동에 가려진 리뷰어" 수 — git 리더보드에서 완전히 누락된, 리뷰는 많이 하지만 PR은 거의 열지 않는 사람들입니다. 이것이 git 변동(churn)을 넘어 봐야 할 핵심 이유입니다. - 항상 주의사항을 언급하며 마무리합니다(필수):
코드 변동(churn) ≠ 기여(contribution). 코드 리뷰, 멘토링, 설계, 디버깅은 git에 보이지 않습니다. 스쿼시 병합/삭제된 브랜치는 복구할 수 없습니다. 협업 탭은 그중 일부(리뷰, PR, 이슈)를 복구하지만 전부는 아닙니다. 이는 성과 순위나 평가 지표가 아니라 대화를 시작하는 도구입니다.
빠른 참조 (질문 ↔ 설정)
| 인터뷰 응답 | 설정 방법 |
|---|---|
| 소유자 / 저장소 | clone-all.sh <소유자...> 또는 -f repos.txt |
| 측정 기준 (git 변동 보기) | GITPODIUM_METRIC=churn|commits|added|deleted|net|repos |
| 협업 (PR/리뷰/이슈) | collect-github.py <소유자...> → github.json · 건너뛰기: GITPODIUM_SKIP_GITHUB=1 |
| 시간 범위 / 버킷 | report.sh FROM TO [month|quarter|year] |
| 봇 / 벌크 필터 | DROP_BOTS MAXCHURN MAXFILES |
| 신원 병합 | GITPODIUM_IDENTITY=gitpodium.identity.json |
| 출력 디렉터리 | GITPODIUM_OUT (클론 디렉터리: GITPODIUM_CLONES) |