GitHub Cache Hygiene
目標:gitcrawl と gh シャムから一般的な GitHub 読み取り質問にまず回答し、新鮮さや書き込みが必要な場合にのみライブの GitHub API 呼び出しを使用する。
デフォルトパス
通常の gh を使用する。Peter のマシンでは、gitcrawl をバックエンドとするシャムが期待されているため、対応する読み取りはコマンドを変更せずにローカルまたはキャッシュから回答できる。
以下のローカル/キャッシュ読み取りを優先する:
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
gh issue list -R owner/repo --state open --author user --assignee user --label bug --json number,title,url
gh pr list -R owner/repo --state open --author user --label dependencies --json number,title,url
gh issue view 123 -R owner/repo --json number,title,state,body,comments,labels,url
gh pr view 123 -R owner/repo --json number,title,state,body,comments,labels,files,commits,statusCheckRollup,url
gh pr checks 123 -R owner/repo --json name,state,detailsUrl,workflow
gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
正確な参照(ref)と狭いフィールドを使用する。gh issue view を結果ごとに繰り返すような広範なループは避け、単一の gh search や gh issue list --json ... で最初の質問に回答できるようにする。
CI では、gh run list / gh run view のタイトなポーリングループを避ける。プッシュまたはワークフローのディスパッチ後、1 つの正確な実行を特定し、バックオフをかけてポーリングする。完全なログは、失敗したジョブまたはユーザーが明示的にログを要求した場合のみ取得する。完了済みのスタイル(gh run view --log、--log-failed、および一般的な Actions REST ログエンドポイント)は gitcrawl によってより長くキャッシュされるが、実行ステータスは短寿命のままである。
新鮮さ(Freshness)
ローカルの回答は、発見、重複検索、過去のスレッドレビュー、作成者/ラベルのトリアージ、「既に issue/PR がある可能性は?」の確認に適している。
ライブ呼び出しは次の場合に使用する:
- 書き込み、コメント、クローズ、マージ、再実行、編集
- メンテナーアクションの前に最終的な現在状態を確認する場合
- プッシュ後の CI ステータスを確認する場合
- ローカル結果が欠落しているか明らかに古い場合
- ユーザーが最新/ライブ状態を要求した場合
PR レビューでは、ファイル、コミット、チェック、実行サマリーを繰り返し確認することがわかっている場合、gitcrawl sync owner/repo --numbers <n> --with pr-details で正確な PR 詳細を一度ハイドレートすることを推奨する。gh シャムは、GITHUB_TOKEN または gh auth token を使用して、ミス時に 1 つの正確な PR を自動ハイドレートできるが、明示的なハイドレーションにより意図とコストが明確になる。
書き込み後は、広範な再スキャンではなく、1 回の対象を絞った読み戻し(readback)を行う。
XCache
レート制限が疑われる場合にキャッシュ動作を検査する:
gh xcache stats
gh xcache keys
gh xcache gc
新しいライブ GitHub ループを追加する前に、gh xcache stats --json の backend_misses_by_command と backend_misses_by_route を読む。これらのマップは、どのコマンド形状がまだキャッシュから逃れているかを示す。
gh xcache flush は、古いキャッシュフォールバック読み取りが判断を誤らせている場合にのみ使用する。
ローカルのみの証明として、一時的にバックエンドを単一のコマンドで利用不可にする:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<terms>" -R owner/repo --json number,title,url
エージェントのマナー(Agent Etiquette)
リポジトリと状態ごとに質問をまとめる。セッション中に既に出力されたデータを再利用する。CI のポーリングは控えめにし、ログは失敗した実行またはレビュー中の正確な実行についてのみ検査する。シャム自体の診断以外では、/opt/homebrew/opt/gh/bin/gh でシャムをバイパスしない。