GitHub Extract は何をしますか？
このスキルが解決する問題
ユーザーがGitHubリンクを投げてきたとき、多くの場合、その目的はファイル内容の羅列を欲しいのではなく、次の3点を理解することです：
- このプロジェクトは一体何をするものか？
- 今回の変更で何を解決しようとしているのか？
- なぜこのアプローチを選んだのか？ ファイル、差分、メタデータはあくまで証拠です。証拠を結論として提示するのは、抽出したことになりません。読者は表の羅列を受け取っても、そのリポジトリが存在する理由を説明できません。 完了基準（一言で）：このリポジトリを聞いたことがない人が、最初の300文字を読めば、「このプロジェクトが何を解決するのか、今回何が変わったのか、なぜその変更をしたのか」を自分の言葉で言えること。これができなければ、抽出は完了していません。
ステップ0：まず「プロジェクト」を読み、次に「ページ」を読む
PRやIssueを取得する前に、まずそのコンテナとなるプロジェクト自体を理解します。このステップを飛ばすと、どれだけ詳細に書いても根拠のないものになります。
| 答えるべき質問 | どこから読むか |
|---|---|
| これは何のプロジェクトか | リポジトリの description、topics、README冒頭 |
| 何のギャップを埋めるのか / 何を代替するのか | README内の各パッケージの「Why」の列 |
| 誰がどんなシナリオで使うのか | READMEのInstall / Usage / Developのセクション |
| 今回の変更はプロジェクト内でどの位置づけか | PRのベースブランチ、変更されたパッケージの役割 |
| monorepo / プラグイン集合作成時は特にスキップ不可：最初に「パッケージ名 → 一言での責務」の対照表を作成しなければ、読者は今回の変更を位置づけられません。READMEが業界用語（例："lifecycle hooks"、"ctx.web seam"）を多用している場合は、まず平易な言葉で翻訳してから本題に入ります。 |
ステップ1：URLタイプを識別する
| URLの形状 | タイプ | 主なデータソース |
|---|---|---|
github.com/{o}/{r} | リポジトリ | /readme + git/trees?recursive=1 |
…/issues/{n} | Issue | 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 はフラグメントであり、パスではありません。IssueとPRは同じ番号空間を共有しています：/issues/1 が /pull/1 に302リダイレクトされる場合、それはPRであり、その旨を明示する必要があります。 |
ステップ2：APIから全文を取得する、HTMLにこだわらない
- ページのHTMLはナビゲーションバーと本文の一部のみを提供するため、本文は必ず
api.github.com経由で取得します。 - パッチは
patch-diff.githubusercontent.com/raw/{o}/{r}/pull/{n}.diffから取得します（github.com/.../pull/n.diffはクロスオリジンリダイレクトを引き起こすため、最終的なURLに直接アクセスする必要があります）。 raw.githubusercontent.comはしばしば利用できないため、代わりにcontentsAPIから取得したbase64データをローカルでデコードします。- ローカルの
git/curlでTLSエラーSEC_E_NO_CREDENTIALSが発生した場合、シェル環境を修正しようとせず、代わりにハーネスのweb_fetchを使用します。「cloneの失敗」をタスクの障害と見なさないでください。
ステップ3：クロスチェック
additions/deletions/changed_files ←→ filesリスト ←→ .diffのハンク；PRのhead SHA ←→ パッチのref；merged は state=closed だけを見て判断しません。不整合があれば調査を続けます（多くの場合、ページネーションか古いパッチが原因です）。矛盾した成果物を作成しないでください。
ステップ4：「読める」成果物に構成する
順序は厳格です：説明が先、証拠は後。読者は200行の表を読み進めてから、これが何なのかを理解すべきではありません。
- それが何か（150～300文字、平易な言葉） — プロジェクトが存在する理由、それが埋めるギャップ。専門用語が初出の場合は、必ず一文で説明すること：
hookkit = 「プラグインを書かないとライフサイクルフックを実装できない」を「YAMLを1つ書くだけ」に変えるもの。 - 今回の変更で解決したいこと — 「以前はどうだったか → 現在はどうか」の比較で書く。ファイルリストで代用しない。
- なぜこのアプローチを選んだか — PRの説明 / コミットメッセージから、トレードオフと因果関係を抽出する（なぜpushトリガーを選ばなかったのか、なぜレジストリを状態として扱ったのか）。
- 変更リスト — 表：ファイル / ステータス / 追加削除数 / 一言での役割。
- 原文 — PRの説明、コミットメッセージを一字一句引用し、書き換えない。
- 完全な内容 — 各ファイルの全文。「…残りは省略」と書かない。
- 応用可能な手法 — 読者が次回実際に使えるものだけを残す。
- 検証とカバレッジ — 最後に付録として配置：
git apply --checkの結果、blob SHAの比較、取得できなかったもの。 文章作成ルール
- 結論を先に：各段落の最初の文が結論であり、その後に根拠を続ける。
- 表は説明責任を負わない。 「これは何か」「なぜか」はすべて完全な文章で書く。
- ファイル名で機能説明を代用しない：
- 「publish.ymlを変更した」❌
- 「手動公開ワークフローを追加。ボタンを押した時のみ公開し、デフォルトではドライランする」✅
- 数字は出典を特定できるようにするが、検証ログを冒頭に配置しない。
- ユーザーが使用している言語で記述する。
- アンチパターン：大きな表の羅列、ファイル単位の差分を本文とする、冒頭がメタデータ、用語の未説明。
ステップ5：自己チェック
- 最初の300文字（タイトルと表を除く）だけで、「何をするのか / 何が変わったのか / なぜその変更をしたのか」に答えられるか？ 答えられなければ書き直す。
- まだ説明していない用語はないか？
- 「ファイルA、B、Cに変更があった」ことを変更説明として使っていないか？
- パッチは
git apply --checkに合格したか？ 実行していなければ「未検証」と明記する。
失敗パターン
| 症状 | 原因 | 対処 |
|---|---|---|
| 本文の途中で途切れる | HTMLを取得した | APIを使用する |
| raw.githubusercontent で404 | ネットワークの許可リスト | contents APIの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、グローバルパッケージ、プロファイルの変更、PRの作成、push、ファイルの削除）：常に最初に確認する。 - 認証情報が必要な場合（プライベートリポジトリ、トークン、SSHキー）：一度確認する；取得できれば使用し、取得できなければ公開で検証可能な部分のみを出力し、何が不足しているかを明記する。 自律的に範囲を拡大できるケース
- ユーザー自身のリポジトリであり、かつ「自由に変更して / 直接インストールして / 確認不要」と明確に指示されている場合。
- または、一時ディレクトリ内で完結し、元のリポジトリやグローバル状態に影響を与えない場合（この場合、拡大されるのは「書き込み」であり、「信頼できないコードの実行」ではない）。 範囲を拡大した場合は、成果物の末尾に「ご依頼に基づきXを実行しました」と一文追加し、越権が可視化され、取り消し可能になるようにします。