GitHub 캐시 관리
목표: gitcrawl과 gh shim의 캐시된 데이터로 일반적인 GitHub 읽기 질문에 먼저 응답하고, 신선도나 쓰기가 필요한 경우에만 실시간 GitHub API 호출을 사용합니다.
기본 경로
gh를 정상적으로 사용합니다. Peter의 머신에서는 gitcrawl 기반 shim이 예상되므로, 지원되는 읽기 작업은 명령어 변경 없이 로컬 또는 캐시에서 처리할 수 있습니다.
로컬/캐시된 읽기 작업을 선호하세요:
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 폴링 루프를 피하세요. 푸시 또는 워크플로우 디스패치 후 하나의 정확한 실행을 식별하고, 백오프(backoff)를 사용하여 폴링하세요. 실패한 작업이나 사용자가 명시적으로 로그를 요청한 경우에만 전체 로그를 가져옵니다. 완료된 스타일의 gh run view --log, --log-failed 및 일반적인 Actions REST 로그 엔드포인트는 gitcrawl에 의해 더 오래 캐시되는 반면, 실행 상태는 수명이 짧습니다.
신선도
로컬 응답은 발견, 중복 검색, 이전 스레드 검토, 작성자/레이블 분류, "이미 이슈/PR이 있을 가능성이 있는가?" 확인에 좋습니다.
다음과 같은 경우 실시간 호출을 사용하세요:
- 쓰기, 댓글, 닫기, 병합, 재실행, 편집 시
- 유지 관리자 작업 전 최종 현재 상태 확인 시
- 푸시 후 CI 상태 확인 시
- 로컬 결과가 누락되었거나 명백히 오래된 경우
- 사용자가 최신/실시간 상태를 요청한 경우
PR 검토의 경우, 파일, 커밋, 검사 또는 실행 요약을 반복적으로 검사할 것임을 알 때 gitcrawl sync owner/repo --numbers <n> --with pr-details로 정확한 PR 세부 정보를 한 번 명시적으로 보충(hydrate)하는 것이 좋습니다. gh shim은 GITHUB_TOKEN 또는 gh auth token을 사용하여 누락 시 하나의 정확한 PR을 자동으로 보충할 수 있습니다. 명시적인 보충은 의도와 비용을 더 명확하게 합니다.
쓰기 작업 후에는 광범위한 재스캔 없이 대상이 지정된 한 번의 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
에이전트 에티켓
리포지토리와 상태별로 질문을 일괄 처리하세요. 세션에서 이미 출력된 데이터를 재사용하세요. CI 폴링을 줄이세요. 실패한 실행이나 검토 중인 정확한 실행에 대해서만 로그를 검사하세요. shim 자체를 진단하지 않는 한 /opt/homebrew/opt/gh/bin/gh로 shim을 우회하지 마세요.