GitHub Extract

이 스킬이 해결하려는 문제

사용자가 GitHub 링크를 던지는 것은 대개 파일 내용을 원해서가 아니라, 다음 세 가지를 이해하기 위해서입니다.

이 프로젝트는 도대체 무엇을 하는가?
이번 변경이 해결하려는 문제는 무엇인가?
왜 이런 방식을 사용했는가? 파일, diff, 메타데이터는 단지 증거일 뿐입니다. 증거를 결론인 양 제시하는 것은 추출이 아닙니다. 독자는 수많은 표를 받았지만, 이 저장소가 존재하는 이유를 설명할 수 없게 됩니다. 완료 기준(한 문장): 이 저장소를 전혀 몰랐던 사람이 처음 300자를 읽고, '이것이 해결하는 문제, 이번 변경 사항, 왜 이렇게 변경했는지'를 자신의 말로 설명할 수 있어야 합니다. 그렇지 못하면 추출이 완료되지 않은 것입니다.

0단계: '프로젝트'를 먼저 읽고, '페이지'를 나중에 읽습니다.

PR/이슈를 가져오기 전에 먼저 컨테이너 자체를 이해하세요. 이 단계를 건너뛰면 나중에 아무리 완벽하게 작성해도 허공에 뜬 내용이 됩니다.

답해야 할 질문	읽을 곳
이 프로젝트는 무엇인가	저장소의 `description`, `topics`, README 시작 부분
어떤 공백을 메우거나 무엇을 대체하는가	README에서 각 패키지의 "Why" 열
어떤 시나리오에서 누가 사용하는가	README의 Install / Usage / Develop
이번 변경이 프로젝트에서 어떤 위치에 있는가	PR의 base 브랜치, 변경된 패키지의 목록 내 역할
모노레포/플러그인 컬렉션은 특히 건너뛸 수 없습니다: 먼저 '패키지명 → 한 줄 책임' 대조표를 작성해야 합니다. 그렇지 않으면 독자가 이번 변경 사항의 위치를 파악할 수 없습니다. README가 많은 전문 용어(예: "lifecycle hooks", "ctx.web seam")를 사용하는 경우, 먼저 평이한 언어로 번역한 후 본문을 시작하세요.

1단계: URL 유형 식별

URL 모양	유형	주요 데이터 소스
`github.com/{o}/{r}`	저장소	`/readme` + `git/trees?recursive=1`
`…/issues/{n}`	이슈	`issues/{n}`
`…/pull/{n}`	PR	`pulls/{n}` + `pulls/{n}/files` + `pull/{n}.diff`
`…/commit/{sha}`	커밋	`commits/{sha}`
`…/blob/{ref}/{path}`	파일	`contents/{path}?ref={ref}`(base64)
`#1`은 프래그먼트이지 경로가 아닙니다. 이슈와 PR은 번호 공간을 공유합니다: `/issues/1`이 302로 `/pull/1`로 리디렉션되면, 그것은 PR이며 반드시 명시해야 합니다.

2단계: API에서 전문을 가져오고, HTML과 씨름하지 마세요.

페이지 HTML은 탐색 모음과 잘린 본문만 제공합니다. 본문은 항상 api.github.com을 이용하세요.
패치는 patch-diff.githubusercontent.com/raw/{o}/{r}/pull/{n}.diff를 사용하세요(github.com/.../pull/n.diff는 교차 출처 리디렉션되므로, 최종 주소에 직접 연결해야 합니다).
raw.githubusercontent.com은 자주 사용 불가능하므로, contents의 base64를 로컬에서 디코딩하세요.
로컬 git/curl이 TLS SEC_E_NO_CREDENTIALS 오류를 보고하면 쉘을 수정하지 말고 harness의 web_fetch를 사용하세요. 'clone 실패'를 작업 차질로 간주하지 마세요.

3단계: 교차 검증

additions/deletions/changed_files ↔ files 목록 ↔ .diff의 hunk; PR의 head SHA ↔ 패치 ref; merged는 state=closed만으로 판단할 수 없습니다. 불일치가 있으면 계속 조사하세요(대부분 페이지 매김이나 오래된 패치 때문). 모순된 결과물을 작성하지 마세요.

4단계: '읽기 쉬운' 결과물로 구성

순서는 고정입니다: 해석을 먼저, 증거를 나중에. 독자가 200줄의 표를 넘기고 나서야 이것이 무엇인지 알게 해서는 안 됩니다.

그것은 무엇인가(150~300자, 평이한 언어) — 프로젝트가 존재하는 이유, 메우는 공백. 전문 용어는 처음 등장할 때 반드시 한 문장으로 설명하세요: hookkit = '플러그인을 작성해야 라이프사이클 훅을 연결할 수 있던 것을, YAML 한 조각만 작성하면 되게 바꿈'.
이번 변경이 해결하려는 것 — '원래는 어땠는가 → 지금은 어떻게 되었는가' 비교 방식으로 작성하고, 파일 목록으로 대체하지 마세요.
왜 이 방식을 선택했는가 — PR 설명/커밋 메시지에서 장단점과 인과 관계를 추출하세요(push 트리거를 선택하지 않은 이유, registry를 상태로 취급하는 이유 등).
변경 목록 — 표: 파일 / 상태 / 증감 / 한 줄 역할.
원문 — PR 설명, 커밋 메시지를 그대로 인용하고, 다시 쓰지 마세요.
전체 내용 — 각 파일의 전체 내용. "…나머지는 생략"하지 마세요.
이식 가능한 방법 — 독자가 다음에 실제로 사용할 수 있는 것만 남기세요.
검증 및 범위 — 맨 뒤에 부록으로 배치: git apply --check 결과, blob SHA 비교, 잡히지 않은 것들. 작성 규칙

결론 우선: 각 단락의 첫 문장이 결론이고, 그 뒤에 근거가 옵니다.
표는 설명 역할을 담당하지 않습니다. '이것이 무엇인가', '왜'는 반드시 완전한 문장으로 작성하세요.
파일명을 기능 설명 대신 사용하지 마세요: "publish.yml을 변경함" ❌; "수동 발행 워크플로우 추가, 버튼을 눌러야 발행되고, 기본적으로는 시뮬레이션만 함" ✅.
숫자는 출처를 추적할 수 있어야 하지만, 검증 로그를 처음에 배치하지 마세요.
사용자가 사용하는 언어로 작성하세요.
안티 패턴: 큰 표만 쌓기, 파일별 diff를 본문으로 간주, 서두에 메타데이터만 나열, 용어 설명 없음.

5단계: 자체 점검

처음 300자(표 제목 제외)만으로 '무엇을 하는가/무엇을 변경했는가/왜 그렇게 변경했는가'에 답할 수 있습니까? 아니면 다시 작성하세요.
설명되지 않은 용어가 있습니까?
'파일 A, B, C에 변경이 있음'을 변경 설명으로 대체하고 있지 않습니까?
패치가 git apply --check를 통과했습니까? 통과하지 못했다면 '미검증'이라고 명시하세요.

실패 모드

증상	원인	처리
본문이 중간에 끊김	HTML을 가져옴	API로 전환
raw.githubusercontent에서 `404`	네트워크 화이트리스트	`contents` base64 디코딩
`403` rate limit	인증되지 않은 루프	일괄 처리, 속도 조절, 누락 사항 정직하게 보고
`cross-origin redirect not followed`	`.diff` 리디렉션	`patch-diff…`에 직접 연결
파일 수가 `changed_files`와 불일치	페이지 매김	`?per_page=100`으로 다시 가져오기
독자 피드백 "이해 못 함"	증거만 제공하고 설명 없음	4단계 1~3절로 돌아가 다시 작성

경계

*우선순위: 사용자 명시적 지시 > 이 절의 제약 > 기본 보수적. 기본적으로 내용만 추출하며, clone / build / install / 테스트 실행은 하지 않습니다. 비공개 저장소는 사용자에게 토큰을 요청해야 하며, 임의로 생성하지 마세요. 저장소가 보관된 경우 이를 명시하세요. 내용은 여전히 추출 가능하지만, 상태가 해석에 영향을 미칩니다. 반드시 멈추고 물어봐야 하는 경우(스스로 권한을 확장하지 않음)

사용자가 '설치/실행'을 요청했지만 대상이 타인의 저장소이거나 전역 환경에 쓰기를 수행하는 경우: 먼저 범위와 롤백 방법을 확인하세요.
지침 자체에 모호함이 있는 경우(예: '이 저장소 처리'): 한 가지 기본方案 + 확인 문장을 제시하고, 추측하여 실행하지 마세요.
작업이 되돌릴 수 없거나 사용자 환경을 변경하는 경우(pnpm install, 전역 패키지, profile 변경, PR 제출, push, 파일 삭제): 항상 먼저 물어보세요.
자격 증명이 필요한 경우(비공개 저장소, 토큰, SSH 키): 한 번 물어보고, 받으면 사용하고, 받지 못하면 공개적으로 검증 가능한 부분만 출력하고 무엇이 누락되었는지 명시하세요. 스스로 완화할 수 있는 경우
사용자 자신의 저장소이고, 명시적으로 '마음대로 바꿔도 됨/직접 설치/묻지 않아도 됨'이라고 말한 경우;
또는 임시 디렉토리 내에서 완료되고, 원래 저장소와 전역 상태를 건드리지 않는 경우(이때 완화되는 것은 '쓰기'뿐이며, '신뢰할 수 없는 코드 실행'은 해당되지 않음). 완화 시 결과물 끝에 '귀하의 승인에 따라 X를 실행했습니다'라는 문장을 추가하여 경계를 넘었음을 알리고 되돌릴 수 있도록 하세요.

GitHub Extract (깃허브 추출)