GitHub 저장소 에이전트 스킬
모든 AI 에이전트 호스트(Antigravity, Copilot, Claude Code, Codex, OpenCode)에서 GitHub 저장소를 감사, 개선, 릴리스, 검증하기 위한 증거 기반 운영 계약입니다.
1. 핵심 운영 원칙
- 주장 → 저장소에 대해 검증: README나 문서의 주장을 절대 신뢰하지 마십시오. 문서를 신뢰하기 전에 항상 코드, 매니페스트, 테스트, 훅, CI를 검사하십시오.
- 5-동사 수명 주기:
AUDIT= 읽기 (증거 수집, 불일치 식별, 부작용 없음).PREPARE= 제안 (정확한 통합 diff 및 API 페이로드 생성, 변경하지 않음).APPROVE= 승인 (변경 영향 범위 제시, 명시적 인간 승인 대기).EXECUTE= 변경 (승인된 항목만 엄격히 적용, 범위 외 작업 없음).VERIFY= 증명 (실제 상태와 승인된 상태 비교, 종료 코드 0이 아님).
- 범위 격리:
- 사용자 프롬프트는 오직 특별히 요청된 작업만 승인합니다.
- 감사 발견 사항은 권한이 전혀 없습니다. 범위 외 발견 사항은 별도의 승인 게이트가 필요합니다.
- 감사 중에는 절대 변경하지 않음: 감사 단계는 엄격히 읽기 전용입니다.
- 증거 기반 결과만 허용: 물리적 파일/라인/명령어 증거 없이 주장하는 경우 거부됩니다.
- 사실을 지어내지 않음: 저장소 설명, 토픽, 주장을 절대 환각하지 마십시오. 모든 메타데이터는 검증된 저장소 현실에서 파생하십시오.
- 제한된 자가 치유: 승인된 변경이 실행 중 실패할 경우, 에이전트는 승인된 파일 및 범위 내에서만 자동으로 자가 치유를 시도한 후 재검증해야 합니다. 범위 확장은 새로운 승인이 필요합니다.
2. 사용 시기
사용자가 다음을 요청하거나 의도할 때 이 스킬을 활성화하십시오:
- 전체 또는 대상 저장소 감사 (
"이 저장소 감사","저장소 위생 검토"). - 문서 검증 (
"README가 코드와 일치하는지 확인","README 지침 수정"). - Git 및 GitHub 구성 (
"토픽 표준화","git 위생 정리","CI 워크플로우 설정"). - 릴리스 준비 (
"릴리스 준비","버전 태그","릴리스 노트 생성"). - 포트폴리오 정렬 (
"이 저장소가 포트폴리오에 적합한지 평가","프로젝트 요약 준비").
3. 핵심 수명 주기 워크플로우
발견 ──► 감사 ──► 계획 ──► 준비 ──► 승인 ──► 실행 ──► 검증 ──► 보고 [──► 포트폴리오 동기화]
1단계: 발견
- GitHub 운영 ID 및 접근 (황금 경로):
local remote파싱 → SSH([email protected]:...) 및 HTTPS(https://github.com/...)에서OWNER/REPO추출.gh auth status질의 → 활성 인증된 GitHub 계정 식별.gh repo view OWNER/REPO질의 → 저장소 존재 여부, 가시성, 변경 권한 확인.- 안전 불변 조건: 인증된 계정이 소유자(예: 조직 또는 협업자)와 다른 경우 계획 전에 접근 권한을 확인하십시오. 접근 불가능한 경우 경고하고 원격 변경을 자동으로 비활성화합니다(
can_mutate_remote: false). - 오프라인/원격 없음 대체 경로: 원격이 없으면 원격 작업을 사용 불가로 표시하고 로컬 파일 수정은 정상적으로 진행합니다.
- 저장소 루트 및 현재 작업 트리 상태 감지(
git_state.py). - 제품 형태(CLI, 라이브러리, 웹 앱, 서비스, 에이전트 스킬, 모노레포) 감지.
- 분류 규칙은 references/shapes/heuristics.md 참조.
2단계: 감사 (읽기 전용)
- 8개 영역 검사 실행:
- ID: 이름, 설명, 토픽, 홈페이지, 가시성, 라이선스.
- 구조: 매니페스트, 잠금 파일, 진입점, 테스트, 죽은 파일.
- 행동: README 주장(설치, 빌드, 테스트)을 실제 구현과 비교하여 검증.
- Git: 작업 트리 정리 상태, 브랜치 상태,
.gitignore, 비밀 노출. - GitHub: 워크플로우, 이슈/PR 템플릿, 규칙 세트, 보안 구성.
- 보안: 노출된 자격 증명, 워크플로우 권한, Dependabot 알림.
- 품질: 테스트 실행 상태, 린팅, 포맷팅, CI 상태.
- 배포: 릴리스, 패키지, 태그, 데모 가용성.
- 핵심 감사 팩은 references/audit/checklist.md 참조.
- references/audit/contract.md에 따라 결과 형식화:
- 유형:
BUG,RISK,DRIFT,GAP,INCONSISTENCY,SUGGESTION. - 심각도:
P0(치명적),P1(높음),P2(중간),P3(낮음),Suggestion.
- 유형:
- 이중 형식 출력 컴파일:
- 구조화된 데이터:
audit-report.json(스키마: references/schemas/audit-report.schema.json 준수). - 경영진 마크다운 보고서 (4개 필수 섹션: 결론, 검증된 깨끗함, 발견 사항, 적용 범위 한계).
- 구조화된 데이터:
3단계: 계획
- 발견 사항을 심각도에 따라 우선순위화(
P0>P1>P2>P3). - 사용자 프롬프트로 요청된 항목과 감사로 발견된 항목을 분리.
- 포괄적인 수정 범위: 수정은 절대 애플리케이션 코드로만 제한되어서는 안 됩니다. 감사 결과에 저장소 위생 또는 GitHub 구성 격차가 포함된 경우, 수정 계획은 다음을 반드시 명시적으로 분류하고 포함해야 합니다:
- GitHub 메타데이터: 저장소 설명(
ID-002), 토픽/태그(ID-003), 홈페이지(ID-004), 메타데이터 드리프트(GH-011). - 저장소 위생 파일: 라이선스(
ID-005,ID-006), README 정확성 및 버전 일관성(DOC-001–DOC-006), CI/CD 워크플로우(GH-001–GH-004), Dependabot(SEC-003),.gitignore(GIT-002). - GitHub 설정 제안: 브랜치 보호 규칙 세트(
GH-009), 비밀 스캔 설정(SEC-006). - 애플리케이션 및 코드 수정: 일반 텍스트 자격 증명(
SEC-001), 누락된 잠금 파일(STR-002), 테스트/린트 스크립트(QAL-*). - 범위 제외: GitHub 릴리스 및 릴리스 생성(
DIST-*)은 표준 수정 중에 엄격히 건너뜁니다.
- GitHub 메타데이터: 저장소 설명(
- 제안된 변경 집합을 정의하고 위험 등급 분류:
- 로컬 되돌릴 수 있음 (문서 편집, 로컬 워크플로우, 라이선스).
- 원격 변경 (브랜치 푸시,
gh repo edit을 통한 GitHub 메타데이터/토픽 편집). - 고위험 (가시성 변경, 브랜치 삭제, 강제 푸시).
4단계: 준비
- 로컬 파일(
README.md,LICENSE,.github/workflows/ci.yml, 코드)에 대한 정확한 통합 diff 생성. - 원격 변경을 위한 정확한 GitHub CLI / API 명령 페이로드 공식화(
gh repo edit --description ... --add-topic ...). - 브랜치 보호 또는 저장소 보안 구성을 위한 설정 제안 카드 준비.
PROPOSED_STATE객체 기록.
5단계: 승인 (인간 게이트)
- 구조화된 변경 집합 카드를 사용자에게 제시:
- 대상 저장소 및 브랜치.
- 계획된 수정 사항의 정확한 목록.
- 통합 diff 미리보기 및 외부 API 페이로드.
- 영향 범위 및 롤백 요약.
- 중단하고 명시적인 사용자 확인 대기:
[승인 / 수정 / 거부]. - 승인 시
APPROVED_STATE객체 고정.
6단계: 실행 (변경)
- 로컬 파일 수정: 승인된 통합 diff 적용.
- 커밋: 특정 파일 스테이징(
git add <file>, 절대git add .사용 금지), Conventional Commit 메시지 생성. - 원격 메타데이터/설정 변경: 명시적
REMOTE_MUTATION권한 하에 승인된 명령 실행(gh repo edit, API 호출). - 실행 단계 실패 시:
stderr에서 오류 진단.- 승인된 범위 및 파일 내에서만 자가 치유 시도.
- 수정에 범위 외 변경이 필요한 경우 즉시 중단하고 수정된 승인 요청.
7단계: 검증 (증명)
- 파일 시스템, git 또는 GitHub API에서 직접
ACTUAL_STATE질의. - 정확한 어설션 수행:
ACTUAL_STATE == APPROVED_STATE. - 불일치가 있는 경우 증거와 함께
VERIFICATION_FAILED보고 및 롤백 제안. - 일치하면 상태를
VERIFIED_SUCCESS로 표시.
8단계: 보고
- 최종 경영진 요약 출력:
- 변경된 내용 (커밋, 수정된 파일, 업데이트된 메타데이터).
- 검증 증명 (실제 상태가 검증됨).
- 해결되지 않은 남은 감사 발견 사항.
- 다음 권장 단계.
9단계: 포트폴리오 동기화 (선택 사항, 이벤트 기반)
- 저장소 변경이 포트폴리오 관련 필드(상태, 설명, 기술 스택, 데모 URL)에 영향을 미치는 경우:
- references/schemas/portfolio.schema.json을 준수하는 정규화된 프로젝트 요약 생성.
- 사용자에게 프롬프트:
"포트폴리오 영향 감지됨. 동기화 제안 준비? [예 / 건너뛰기]". - 별도의 승인 없이 자동 동기화 금지.
- references/portfolio/sync.md 참조.
4. 점진적 공개 및 참조 색인
토큰 효율성을 유지하기 위해 심층 도메인 지침은 references/에 구성되며 필요 시 로드됩니다:
- 감사 및 평가:
- references/audit/contract.md — 검사 객체 스키마, 증거 수준, 발견 분류 체계.
- references/audit/checklist.md — 8개 영역 전체 핵심 감사 팩.
- references/audit/severity.md — P0, P1, P2, P3 및 제안의 정확한 정의.
- references/audit/evidence.md — 증거 계층, 직접/파생/추론 증거, 적용 범위 한계.
- 제품 형태:
- references/shapes/heuristics.md — 형태 감지 행렬 (CLI, 라이브러리, 웹 앱, 서비스, 에이전트 스킬, 모노레포).
- Git 및 GitHub 워크플로우:
- references/git/hygiene.md —
.gitignore표준, 비밀 회피, 브랜치 명명. - references/git/mutation.md — 원자적 스테이징, Conventional Commits, 강제 푸시 금지 규칙.
- references/github/metadata.md — 토픽 분류 체계, 설명 제약 조건, 홈페이지 동기화.
- references/github/security.md — Dependabot, 비밀 스캔, Actions 토큰 권한.
- references/git/hygiene.md —
- 문서 및 릴리스:
- references/documentation/readme-standards.md — 10/10 README 구조 (식별 → 평가 → 사용 → 참여).
- references/release/workflow.md — 시맨틱 버전 관리, 태그 생성, 릴리스 노트 생성기.
- 포트폴리오:
- references/portfolio/sync.md — 정규화된 프로젝트 설명자 및 이벤트 기반 동기화 파이프라인.
- 스키마:
- references/schemas/audit-report.schema.json — 전체 감사 보고서 스키마.
- references/schemas/finding.schema.json — 발견 객체 스키마.
- references/schemas/changeset.schema.json — 변경 집합 및 승인 스키마.
- references/schemas/portfolio.schema.json — 정규화된 프로젝트 스키마.
5. 결정적 스크립트 도움말 색인
결정적 작업은 scripts/에 캡슐화됩니다:
python3 scripts/audit/audit_runner.py— 정적 검사 제품군을 실행하고audit-report.json을 생성합니다.python3 scripts/audit/claim_verifier.py— 문서화된 README 명령을 패키지 매니페스트와 검증합니다.python3 scripts/audit/secret_scanner.py— 추적된 토큰, 개인 키 및.env파일에 대한 빠른 정규식 스캐너입니다.python3 scripts/git/git_state.py— 작업 트리, 브랜치 드리프트 및 추적되지 않은 아티팩트를 질의합니다.python3 scripts/verify/state_verifier.py—ACTUAL_STATE를APPROVED_STATE와 비교합니다.