Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
이 도구는 Codex를 위한 증거 기반의 읽기 전용 리포지토리 건강 감사 Skill입니다. 프로젝트 의존성 설치 없이 다양한 저장소 신호(Git 상태, CI/테스트, 보안 등)를 수집하여 기술 부채와 변경 사항을 감지합니다. 수집된 정보는 우선순위가 부여된 실행 가능한 목록과 마크다운 보고서로 제공되어 개발자가 코드베이스의 건전성을 감사할 수 있도록 돕습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CI
Release
Latest release
License: MIT
증거 기반의 읽기 전용(read-only) 리포지토리 건강 감사 Skill로, Codex를 위한 것이며 재현 가능한 인벤토리 및 스냅샷 비교를 위한 독립형 Python 도구를 제공합니다.
중국어 소개:
이것은 실용적인 Codex Skill로, 코드 저장소의 테스트, CI(지속적 통합), 의존성, 문서, 보안 신호 및 기술 부채에 대한 읽기 전용 감사를 수행하고 그 결과를 증거와 우선순위가 부여된 실행 가능한 목록으로 정리합니다. 중국어 빠른 시작를 참조하십시오.
컬렉터는 자동 발견 사항이 아닌 인벤토리 신호를 생성합니다. 이 Skill은 Codex에게 영향도나 우선순위를 할당하기 전에 컨텍스트와 증거를 검증하도록 지시합니다.
Codex에서 가장 쉬운 방법은 내장된 설치 도구를 사용하여 이 저장소를 설치하도록 요청하는 것입니다:
Use $skill-installer to install https://github.com/1838904818/audit-repo.
오프라인 또는 버전 고정 설치의 경우, 최신 릴리스에서 .zip 파일과 일치하는 .sha256 파일을 다운로드하십시오. 체크섬을 확인한 후, 아카이브의 최상위 audit-repo 디렉토리를 $HOME/.agents/skills에 추출합니다. 릴리스 에셋은 Linux, Windows, macOS에서 Python 3.10 및 3.14를 사용하여 전체 테스트 매트릭스가 통과된 후에만 빌드됩니다. 리포지토리 코드가 실행되기 전에, 게시(publishing)는 원격 태그가 기본 브랜치에 있는 워크플로우 이벤트 커밋을 해결하는지 확인합니다. 그런 다음 게시된 릴리스가 불변(immutable)해야 하며, 그 정확한 두 가지 에셋 세트가 현재의 결정론적 빌드와 일치하는지 확인하고, 온라인 에셋이 일치한 후 태그/기본 브랜치의 출처(provenance)를 재확인합니다. 기존에 게시된 릴리스를 발견하는 실행은 이를 변경하지 않고 검증하며; 기존 드래프트는 편집되거나 삭제되지 않은 채로 실패 처리됩니다. 불변성은 리포지토리 설정이 활성화되기 이전에 생성된 과거 릴리스가 아닌, v1.10.7 이후의 릴리스에 적용됩니다.
수동 사용자 전체 설치를 위해서는 레포지토리를 공식 로컬 스킬 디렉터리에 클론하십시오. 현재 위치 및 호출 방법은 OpenAI Build skills 문서를 참조하십시오.
macOS 또는 Linux:
mkdir -p "$HOME/.agents/skills"
git clone https://github.com/1838904818/audit-repo.git "$HOME/.agents/skills/audit-repo"
Windows PowerShell:
$skillRoot = Join-Path $HOME ".agents asks"
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
git clone https://github.com/1838904818/audit-repo.git (Join-Path $skillRoot "audit-repo")
Codex는 설치된 스킬 변경 사항을 자동으로 감지합니다. 스킬이 나타나지 않으면 Codex를 다시 시작하십시오.
Codex CLI 또는 IDE 확장 프로그램에서 /skills 또는 $audit-repo로 명시적으로 호출합니다:
Use $audit-repo to audit this repository and prioritize the most important fixes.
ChatGPT 데스크톱 앱에서 @를 입력하고 스킬 피커(skill picker)에서 Audit Repo를 선택하세요.
Codex는 또한 리포지토리 상태, 릴리스 준비도, 유지보수성, 보안 태세(security posture), 기술 부채(technical debt), 그리고 감사 비교 요청을 위해 이를 자동으로 호출할 수 있습니다.
Python 3.10 이상이 필요합니다. Python 3.10부터 3.14까지 지속적으로 테스트되며, 스크립트는 파이썬 표준 라이브러리만을 사용합니다.
리포지토리 감사하기:
python scripts/collect_repo_signals.py /path/to/repo --format markdown
재사용 가능한 JSON 스냅샷 저장하기:
python scripts/collect_repo_signals.py /path/to/repo --format json --output before.json
filesystem을 사용할 때는 재사용 가능한 스냅샷을 대상 리포지토리 외부에 보관하여 이전 출력이 다음 스캔의 입력으로 사용되지 않도록 하세요.
의도한 워크플로우에 맞는 스캔 모드를 선택하세요:
# 기본값: 무시되거나 추적되지 않은 파일을 포함한 도달 가능한 파일 시스템 파일
python scripts/collect_repo_signals.py /path/to/repo --scan-mode filesystem
...
반복 가능하고 대소문자를 구분하는, 루트 상대 POSIX globs로 모노레포(monorepo) 범위 지정하기:
python scripts/collect_repo_signals.py /path/to/repo \
--scan-mode tracked \
--include-path "packages/api/*" \
...
모든 모드는 컬렉터의 내장 디렉토리 제외 규칙을 유지하고 심볼릭 링크(symlinks)는 건너뜁니다. 경로 globs는 전체 상대 경로에 대해 Python fnmatchcase 시맨틱을 사용하며, *는 /를 일치시킬 수 있고, 제외 규칙이 포함 규칙보다 우선합니다. tracked는 무시되거나 추적되지 않은 모든 파일을 생략하지만, 나중에 무시 규칙과 일치하는 추적된 파일은 여전히 포함합니다. 우연히 생성된 민감한 파일을 발견하는 것이 우선순위일 때는 filesystem을 사용하세요.
git-visible은 체크아웃의 유효한 Git ignore 설정을 따르며, 여기에는 리포지토리 로컬 및 글로벌 제외 항목이 포함됩니다. 반복 비교 시 동일한 무시(ignore) 구성을 사용합니다. 작업 트리 상태와 같은 Git 메타데이터는 Git 체크아웃을 설명하며, 경로-글롭 범위보다 더 광범위할 수 있습니다. 만약 Git이 작업 트리에 없는 추적 파일(예: 희소 체크아웃에서)을 열거한다면, 스냅샷은 불완전한 스캔을 기록하고 비교기는 이를 직접 비교 가능하다고 취급하지 않습니다.
Scope ID는 기본적으로 설정되지 않으며 어떤 파일을 스캔하는지 변경하지 않습니다. 이는 단지 서로 다른 해결된 루트의 스냅샷이 동일한 논리적 범위를 나타낸다는 명시적인 주장일 뿐입니다. 두 스냅샷 모두에 프로젝트 한정형 값을 사용하고, 리포지토리나 패키지 전반에 걸쳐 절대 재사용하지 않으며, 이를 채택할 때는 검토된 기준선(baseline)을 재생성해야 합니다. 레거시 암묵적 값인 repository는 더 이상 크로스-루트 동등성을 증명하지 않습니다.
v1.9.0은 스캔 의미론(scan semantics)을 버전 2로 발전시킵니다. 따라서 v1.8.x가 생성한 스냅샷은 동일한 루트에서도 의도적인 비교 제한을 초래하므로, 새로운 분류 규칙을 검토하고 비교 가능성 게이트를 복원하기 전에 승인된 기준선을 재생성해야 합니다.
v1.9.1은 윈도우 접합점(junction) 및 재파스-포인트(reparse-point) 순회에 대해 심볼릭 링크와 일관되게 제외함에 따라 스캔 의미론을 버전 3으로 발전시킵니다. 따라서 v1.9.0 기준선은 의도적인 제한을 초래하므로, 경계 변경 사항을 검토하고 --require-comparable을 복원하기 전에 승인된 기준선을 재생성해야 합니다.
Manifest 및 lockfile 인벤토리는 표준화되고 대소문자를 구분하는 파일명을 사용합니다. 따라서 스냅샷이 특정 생태계 도구가 대소문자가 잘못된 파일을 소비할 것이라고 주장하지 않습니다. 이 인벤토리에는 SwiftPM 버전별 매니페스트와 NuGet 프로젝트별 lockfile이 포함됩니다. GitHub Action 참조는 어휘적 워크플로우 신호입니다. 스크립트 및 설명 블록 내용은 제외되며, uses에 첨부된 모호하지 않은 단일 라인 블록 값만 인식합니다. 고정 정책(pinning policy)은 YAML 앵커(anchors), 별칭(aliases), 태그(tags), 그리고 파싱된 종속성 키가 단순한 텍스트 검색과 다르게 만들 수 있는 명시적 매핑-키 구문에서 실패 시 안전하게 작동해야 합니다.
두 스냅샷 비교:
python scripts/compare_repo_signals.py before.json after.json --format markdown
단일 명령으로 전체 워크플로우를 실행합니다. 이 명령어는 항상 snapshot.json과 report.md를 작성하며, 기준선(baseline)이 제공되면 comparison.json과 comparison.sarif도 작성합니다:
python scripts/check_repo.py /path/to/repo --output-dir audit-results
python scripts/check_repo.py /path/to/repo \
--baseline previous-snapshot.json
...
--baseline-sha256은 정확히 64개의 16진수 문자(대문자 또는 소문자)를 허용하며, 파싱하기 전에 기준선(baseline)의 원시 바이트를 확인합니다. 접두사, 공백, 체크섬 파일 라인은 거부됩니다. JSON 형식 지정, 바이트 순서 표시(byte-order mark), 후행 개행 문자, LF/CRLF 변환 등은 모두 다이제스트를 변경시킵니다. 외부 스냅샷 및 기준선은 64 MiB를 초과하지 않는 일반 파일로 해석되어야 합니다. 파이프, 장치, 디렉터리, 더 큰 파일은 거부됩니다. 심볼릭 링크는 열린 대상이 해당 한도 내의 일반 파일인 경우 계속 허용됩니다. 스냅샷 JSON 역시 모든 중첩 수준에서 고유한 객체 키를 가져야 하며, 중복된 키는 JSON 소비자가 첫 번째 값 대 마지막 값 해석에 대해 의견이 다르기 때문에 거부됩니다. 예상 다이제스트는 유지 관리자 제어 구성 또는 별도로 검증된 아티팩트로부터 독립적으로 얻어야 합니다. 이 확인 직전에 동일한 신뢰할 수 없는 기준선으로부터 계산해서는 안 됩니다.
각 실행 전에, 러너(runner)는 재사용된 디렉터리가 오래된 보고서를 노출하는 것을 방지하기 위해 관리되는 출력 경로 네 개만 제거합니다. 이는 네 개의 모든 경로를 사전 점검하고, 다른 모든 항목은 보존하며, 관리되는 경로가 디렉터리인 경우 어떠한 형제 아티팩트도 삭제하지 않고 종료 코드 2로 실패합니다. --baseline 없이 비교 게이트 중 어느 것을 활성화하는 것도 유효하지 않습니다. 잘못된 다이제스트, 기준선 없는 다이제스트, 다이제스트 불일치, 읽을 수 없음, 너무 큼, 비(非)정규 파일, 또는 유효하지 않은 기준선은 출력 디렉터리가 생성되거나 관리되는 아티팩트 또는 GitHub Action 출력이 변경되기 전에 실패합니다. 제공되면, 기준선은 한 번 열리고, 경계가 있는 일반 파일로 검증되며, 한 번 읽히고, 선택적으로 다이제스트 확인을 거치며, 엄격한 UTF-8 JSON으로 파싱되어 비교를 위해 메모리에 유지됩니다. 다이제스트는 여전히 선택 사항입니다. 유효하고 변경되지 않은 기준선은 생략되더라도 동일한 비교 의미론 및 결과를 유지하지만, 러너는 수집 전에 여전히 기준선을 읽고 고정합니다.
스냅샷(Snapshot), 스캔 루트(scan-root), 그리고 관리 출력 경로 컨텍스트는 오류 발생 시 ASCII 이스케이프되고 길이 제한이 적용되어 악의적인 파일 이름으로 CI 로그 라인이나 워크플로우 명령을 추가하는 것을 막습니다.
러너(runner)는 또한 관리 출력을 생성하거나 지우기 전, 액션 임시 디렉터리를 할당하기 전, 또는 액션 출력을 추가하기 전에 --max-files, --large-file-mib, 포함/제외 경로 글롭(path globs), 제외된 디렉터리 이름, --scope-id, 스캔 루트 가용성, 그리고 Git 모드 워크트리 적격성을 검증합니다. 제외된 디렉터리는 비어있지 않은 단일 이름이어야 합니다: 경로 구분자, ./.., 공백만 있는 값, 제어 문자는 거부되지만, -로 시작하는 이름은 유효합니다. 일치 여부는 이전 릴리스와 마찬가지로 대소문자를 구분하지 않습니다. 컬렉터(collector)와 러너는 이러한 사전 검사 규칙을 공유하므로, 잘못 구성된 설정, 누락된 루트, 또는 호환되지 않는 Git 스캔 모드는 이전 보고서를 희생시키지 않고 2를 반환합니다. 출력이 지연된 관리 파일이 정리된 후에도 성공적인 수집은 발생하며, 출력 디렉터리가 스캔된 루트 내부에 있을 경우 확립된 스캔 결과를 보존합니다.
러너는 또한 출력 디렉터리가 스캔된 저장소 또는 그 포함 Git 워크트리 내부 어디에서든 심볼릭 링크(symbolic link)나 Windows 리파스 포인트(reparse point)(NTFS 접합점 포함)를 통과하는 것을 거부합니다. 여기에는 하위 디렉터리만 스캔할 때의 모노레포(monorepo) 형제 저장소도 포함되며, 이는 신뢰할 수 없는 체크아웃이 관리 쓰기를 자신의 트리 외부로 리디렉션하는 것을 방지합니다. 액션 모드에서 GitHub 출력 파일은 기준선(baseline) 또는 모든 관리 아티팩트와 같거나 별칭을 가질 수 없습니다.
Git-aware collection은 Git을 전체 포함하는 Git 작업 트리 외부의 절대적인 PATH 디렉터리에서 발견된 절대 실행 파일로 해결합니다. 이는 모노레포(monorepo) 하위 디렉터리만 스캔할 때도 마찬가지입니다. 어휘적 스캔 항목과 그 해결된 대상 모두 신뢰할 수 없는 경계를 정의하며, 포함 여부는 파일 시스템 식별자뿐만 아니라 경로 철자를 통해서도 검증됩니다. 따라서 리포지토리 내에 포함된 심볼릭 링크(symlinks)나 대소문자 변형은 대소문자를 구분하지 않는 볼륨(case-insensitive volumes)에서 체크아웃 로컬 실행 파일을 숨길 수 없습니다. 컬렉터는 현재 디렉터리 실행 파일 검색에 의존하지 않으므로, 체크아웃 로컬 git.exe가 정적 Windows 감사(audit)를 코드 실행으로 전환할 수 없습니다. 작업 트리 청결도(Worktree cleanliness)는 인벤토리(inventory)가 더 광범위한 리포지토리 인식 상태 기계 장치(repository-aware status machinery)를 호출하지 않도록 의도적으로 unknown으로 보고됩니다.