Community라이팅 & 에디팅github.com

tzwkb/repo-maintainer

에이전트 스킬 — GitHub 저장소 정리, 통합 및 유지보수.

repo-maintainer란 무엇인가요?

이 에이전트 스킬은 개발자의 GitHub 프로필을 체계적으로 정리하여 깔끔하고 유지보수 가능한 전문 저장소로 변환하는 워크플로우를 제공합니다. 6단계(스캔 및 진단, 기본 파일 표준화, 오래된 저장소 처리, 관련 저장소 병합, 저장소 이름 변경, 코드 수준 리팩토링)로 구성되어 있으며, 각 단계는 사용자 확인 하에 진행됩니다. 모든 공개 저장소에는 LICENSE, README.md, .gitignore 및 GitHub 설명이 필수적으로 포함되어야 하며, 이 중 하나라도 누락되면 다른 작업보다 우선하여 수정합니다. 특히 push 전에는 secret 스캔을 의무적으로 수행하여 API 키나 비밀번호가 유출되는 것을 방지하며, 대규모 리팩토링 시에는 git rename 감지가 깨지지 않도록 단계별 커밋 전략을 제시합니다. 이 스킬은 GitHub API, Git 명령어, Python 스크립트를 활용하며, Windows 환경에서의 인코딩 문제와 같은 기술적 함정도 함께 다룹니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

저장소 유지보수 도구

조각난 GitHub 프로필을 깔끔하고 유지보수 가능한 전문 저장소로 변환하기 위한 체계적인 워크플로우입니다.

개요

6단계로 정리 작업을 수행합니다. 해당되지 않는 단계는 건너뛰세요. 파괴적인 작업(삭제, 이름 변경, 병합)에는 항상 사용자 확인을 받으세요.

핵심 원칙 (협상 불가)

모든 저장소(신규, 기존, 활동 중, 보관됨)에는 다음 네 가지 기본 문서가 반드시 있어야 합니다. 네 가지가 모두 확인될 때까지 정리가 완료된 것으로 간주하지 마세요.

문서규칙이유
LICENSE모든 공개 저장소에는 LICENSE가 있어야 합니다. 사용자가 다른 라이선스를 지정하지 않는 한 MIT를 기본값으로 합니다.라이선스가 없으면 코드는 기본적으로 "모든 권리 보유" 상태입니다. 아무도 합법적으로 사용할 수 없습니다.
README.md프로젝트 이름, 한 문장 설명, 해당하는 경우 사용법/설치 지침이 최소한 포함되어야 합니다.모든 방문자가 가장 먼저 보는 것입니다. README가 비어 있거나 없으면 버려진 프로젝트로 간주됩니다.
.gitignore기본 언어(Python/PHP/Node 등)와 일치해야 합니다. 빌드 아티팩트, 캐시, 환경 파일 또는 IDE 구성을 커밋하지 마세요.실수로 인한 비밀 유출을 방지하고 diff를 읽기 쉽게 유지합니다.
GitHub 설명description 필드는 절대 비어 있으면 안 됩니다. 한 문장으로, 일반 영어(또는 저장소 언어와 일치)로 작성합니다.검색 결과, 프로필 고정 항목 및 소셜 카드에 표시됩니다.

저장소에 네 가지 중 하나라도 누락된 경우, 병합, 이름 변경 또는 리팩토링보다 수정이 우선됩니다.

1단계: 스캔 및 진단

GitHub API를 통해 전체 저장소 목록을 가져옵니다:

curl -sH "Authorization: Bearer TOKEN" \
  "https://api.github.com/user/repos?per_page=100&affiliation=owner"

각 저장소에 대해 다음을 확인합니다:

  • LICENSE, .gitignore, README.md 누락
  • 비어 있는 description 필드
  • 이름 불일치(대소문자 혼용, 지나치게 긴 이름)
  • 명백한 중복 또는 시리즈 (예: project, project-v2, project-mineru)
  • outdated, deprecated, old, test가 포함된 이름

2단계: 기본 파일 표준화

모든 활성 저장소에 대해 최소 파일 세트가 있는지 확인합니다:

파일규칙
LICENSE사용자가 다른 라이선스를 지정하지 않는 한 MIT를 기본값으로 합니다
.gitignore기본 언어(Python/PHP/Node)와 일치
README.md반드시 존재해야 함; 플레이스홀더만 있는 경우 다시 작성
GitHub 설명API를 통한 한 문장 요약

GitHub Contents API(PUT /repos/{owner}/{repo}/contents/{path})를 통해 대량 업데이트합니다.

중요: PowerShell here-string은 Markdown의 삼중 백틱 코드 블록을 손상시킵니다. ` → ``` 이스케이프 실패를 방지하려면 Python 스크립트를 사용하여 대량 README를 생성하세요.

3단계: 오래된 저장소 처리

의사 결정 트리:

조건조치
이름에 outdated / deprecated / old 포함보관 또는 삭제
최신 저장소로 대체됨보관 + README에 후속 저장소 링크 추가
공개 저장소 기록에 유출된 비밀(API 키) 포함삭제 (보관은 기록을 그대로 유지함)
비공개 저장소에 키, 비밀번호, 개인 설정, 또는 개인 데이터 포함사용자가 유출 규칙을 무시할 수 있음; 사용자가 정리하거나 공개로 전환할 것을 요청하지 않는 한 허용 가능한 비공개 상태로 간주
참고용으로 유용하지만 유지보수되지 않음보관

보관된 저장소는 읽기 전용입니다. 보관된 저장소를 수정하려면(이름 변경, README 업데이트) 먼저 보관을 해제하고(PATCH {"archived": false}), 변경한 다음 다시 보관합니다.

4단계: 관련 저장소 병합

2개 이상의 저장소가 동일한 시스템의 변형(다른 백엔드, 엔진, 어댑터)인 경우:

옵션 A — 모노레포 (권장) 새로운 깔끔한 저장소(기록 없음)를 만듭니다. 각 변형을 engines/{name}/ 하위 디렉터리에 배치합니다.

project-suite/
├── main.py              # 기본 엔진
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

각 엔진의 진입점과 구성을 유지합니다. 루트 README를 업데이트하여 전환 방법을 설명합니다.

옵션 B — Git 서브모듈 저장소를 독립적으로 유지합니다. 상위에 서브모듈을 추가합니다. 기록 보존이 단순성보다 더 중요할 때 사용합니다.

옵션 C — 독립 유지 + 링크 병합하지 않습니다. README에 상호 링크를 추가합니다. 변형이 크게 분기된 경우 사용합니다.

기록에 비밀이 포함된 경우: 항상 새로운 깔끔한 저장소를 만들고 현재 스냅샷을 복사합니다(zip 다운로드 + 다시 커밋). git merge 또는 git submodule을 사용하지 마세요. 기록 유출이 지속됩니다.

5단계: 저장소 이름 변경

API 패치: PATCH /repos/{owner}/{repo} with {"name": "new-name"}.

지침:

  • 모두 소문자, 하이픈만 사용
  • 최대 3-4단어
  • 중복 단어 제거 (based-on, design-and-development)
  • 보관된 저장소에 아직 없는 경우 outdated 접미사 추가

GitHub는 일정 기간 동안 이전 URL을 자동으로 리디렉션하지만, 북마크와 스크립트가 중단될 수 있습니다. 스타/포크된 저장소의 이름을 변경하기 전에 사용자에게 확인하세요.

6단계: 코드 수준 리팩토링

원격 구조가 깔끔해진 후, 저장소 내부의 코드를 리팩토링합니다:

  1. 통일된 용어 — 하드코딩된 브랜드 이름을 일반 용어로 바꿉니다(GPTProcessor → LLMProcessor), 실제 API 모델 ID(gpt-4, gpt-5)는 유지합니다.
  2. 파일 이름 변경 — GitHub Contents API에는 이름 변경 기능이 없습니다. 업데이트된 콘텐츠로 새 파일을 만들고 이전 파일을 삭제합니다.
  3. 디렉터리 재구성 — 다중 변형 프로젝트의 경우 engines/, variants/, 또는 core/ + adapters/ 패턴을 사용합니다.

대규모 로컬 리팩토링을 원격으로 푸시

사용자가 로컬에서 코드를 다운로드하여 대규모 변경(파일 이름 변경, 변수 이름 변경, 구조적 재작성)을 수행한 후 원격 저장소로 다시 푸시해야 하는 경우.

푸시 전 비밀 스캔 (필수)

推送前必须先扫描 secret 泄露,有任何发现立即报告,禁止继续 push。

비공개 저장소 예외: 대상 저장소가 비공개로 확인된 경우, 키, 비밀번호, 비공개 설정, 개인 정보 및 기타 민감 정보 유출 규칙을 무시할 수 있습니다. 스캔은 알림 역할을 할 수 있지만, 적발 시 푸시를 차단하거나, 저장소 삭제 및 재생성을 요구하거나, 환경 변수로 대체하도록 요구하지 않습니다. 단, 사용자가 명시적으로 정리를 요청하거나 공개로 전환할 계획인 경우는 예외입니다.

스캔 모드(두 가지 모두 실행해야 함 — 토큰 정규식만 실행하면 일반 텍스트 비밀번호를 놓칠 수 있음):

① 고엔트로피 토큰 / API 키:

grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
  --include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
  --include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
  --exclude-dir=".git" .

② 일반 텍스트 비밀번호 / 자격 증명 도우미(토큰 정규식으로는 찾을 수 없음; 실제로 askpass.sh에 echo "<sudo密码>" 한 줄이 포함되어 init 커밋과 함께 GitHub에 푸시된 사례가 있었음):

git ls-files -z | xargs -0 grep -nIE "password|passwd|密码|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# 그리고 독립적인 askpass.sh / *_secret* / .pgpass / .npmrc 유형의 파일을 수동으로 확인하십시오. 이러한 파일 자체가 자격 증명입니다.

공개 저장소의 경우, 두 가지 중 하나라도 적발되면 아래 강제 절차를 따릅니다. 비공개 저장소의 경우 사용자에게 알림만 제공하고 차단 조건으로 간주하지 않습니다. 스캔 대상은 git ls-files(추적된 파일 세트)이며, .gitignore에 의해 제외된 것은 유출로 간주되지 않지만, 이미 커밋된 파일은 현재 gitignore에 있더라도 기록에 남아 있습니다.

보고 형식:

[LEAK] scripts/eval.py:15 — sk-xxxx (하드코딩된 fallback)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (하드코딩된 기본값)

유출 발견 후 강제 절차:

  1. 즉시 사용자에게 어떤 파일의 몇 번째 줄인지 알립니다.
  2. 환경 변수로 대체합니다(os.getenv("API_KEY") 기본값 없음).
  3. 이미 원격에 푸시된 경우: 사용자에게 알리고, 명시적 확인 후 저장소를 삭제하고 재생성합니다(git 히스토리는 force push로 완전히 제거할 수 없음).
  4. 사용자가 해당 서비스 제공자의 키를 취소합니다.

푸시 전 체크리스트

푸시 전에 반드시 실행:

git status

다음 상황이 없는지 확인:

  • Untracked files — 추적되지 않은 새 파일(일반적인 누락: docs/, scripts/, config 템플릿)
  • Changes not staged — 수정되었으나 add되지 않음
  • Changes to be committed에 업로드해서는 안 되는 파일 포함(키, 개인 데이터, 임시 스크립트)

확인 전까지 직접 푸시를 금지합니다.

의사 결정 트리

상황권장 조치
로컬 저장소에 .git이 없음 (zip 다운로드 / 복사된 파일)아래 시나리오 A 참조
로컬이 git clone이고 기록이 있으며, 원격이 변경되지 않음일반 git add → commit → push
로컬이 git clone이고, 원격에 새로운 커밋이 있음git pull --rebase 또는 병합, 충돌 해결 후 푸시
로컬이 git clone이고, 변경 사항이 대규모 이름 변경 + 재작성인 경우아래 시나리오 B 참조
원격 기록은 유지하되 모든 코드를 교체하려는 경우아래 시나리오 C 참조

시나리오 A: 로컬에 Git 기록이 없음

사용자가 zip을 다운로드하고 광범위하게 편집한 후 다시 동기화하려는 경우 가장 일반적입니다.

옵션 A1 — 강제 푸시 (개인 / 단독 프로젝트)

# 로컬 프로젝트 폴더에서
git init
git add .
git commit -m "refactor: 대규모 재작성"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force

⚠️ 원격 기록을 삭제합니다. 사용자가 원격 기록을 폐기 가능하다고 확인한 경우에만 사용하세요.

옵션 A2 — 원격 기록 유지 (중요 저장소에 권장)

git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./your-local-project/
cd your-local-project
git add .
git commit -m "refactor: 대규모 재작성"
git push

이렇게 하면 모든 이전 커밋이 유지되고 리팩토링이 하나의 새로운 커밋으로 추가됩니다.

옵션 A3 — 새 깔끔한 저장소 재작성이 너무 근본적이어서 본질적으로 새 프로젝트인 경우:

  1. GitHub에 새 저장소를 만듭니다(생성 본문에 description을 포함하거나 즉시 PATCH로 설정).
  2. 로컬 코드를 해당 저장소로 푸시합니다.
  3. 이전 저장소를 보관하고 README에 후속 저장소 링크를 추가합니다.

시나리오 B: 클론된 저장소에서 대규모 이름 변경 + 재작성

중요 규칙: 파일 이름 변경과 내용 변경을 동일한 커밋에 혼합하지 마십시오. Git은 이를 "이전 파일 삭제 + 새 파일 생성"으로 처리하고 기록 연결을 잃게 됩니다.

단계별 커밋 전략:

# 1단계: 이름 변경만
git mv old_module.py new_module.py
git mv old_utils/ new_utils/
git commit -m "refactor: 모듈 이름 변경"

# 2단계: 변수/클래스 이름 변경
git add .
git commit -m "refactor: 변수 및 클래스 이름 변경"

# 3단계: 로직 변경
git add .
git commit -m "feat: 핵심 로직 업데이트"

사용자가 이미 작업 트리에서 모든 것을 혼합한 경우:

# 현재 변경 사항을 스태시에 저장하고 단계별로 재생
git stash push -m "혼합 리팩토링"

# 이름 변경만 복원 (git mv 또는 수동 mv + git add 사용)
git mv old_file new_file
git commit -m "refactor: 파일 이름 변경"

# 내용 변경 복원
git stash pop
# 충돌이 있으면 해결한 다음 커밋

시나리오 C: 모든 코드를 교체하지만 기록은 유지

사용자가 새 코드로 시작하지만 스타, 이슈, URL을 유지하려는 경우 유용합니다.

git checkout --orphan fresh-start
git rm -rf .
# 여기에 새 로컬 코드를 복사
git add .
git commit -m "init: 새로 작성"
git branch -D main
git branch -m main
git push -u origin main --force

이름 변경 감지 확인

푸시 후 Git이 이름 변경을 올바르게 추적했는지 확인합니다:

git log --follow -- new_file.py

기록이 끊어진 경우(파일이 완전히 새 파일로 표시됨), 이름 변경과 내용 변경이 함께 커밋된 것입니다.

보안 및 규정 준수

  • GitHub 토큰: PAT가 필요한 경우 에이전트 메모리에서 찾습니다(구체적인 경로/계정/값은 여기에 기록하지 않음). 토큰 값을 푸시되는 파일(스킬, README, 구성 포함)에 절대 기록하지 마십시오 — 토큰이 포함된 콘텐츠가 푸시되면 GitHub secret-scanning에 의해 즉시 해지됩니다.
  • 토큰 위생: 대량 작업 후 https://github.com/settings/tokens에서 즉시 PAT를 해지하도록 사용자에게 지시합니다.
  • 비공개 저장소 예외: 저장소가 비공개인 경우, 에이전트는 키 유출, 비밀번호, 비공개 설정, 개인 데이터 및 기타 민감 정보 유출 규칙을 무시할 수 있습니다. 사용자가 요청하거나 저장소가 공개될 가능성이 없는 한, 비공개 기록에 비밀이 포함되었다는 이유만으로 푸시를 차단하거나, 강제로 삭제를 권장하거나, 정리된 히스토리로 재생성하지 마십시오.
  • 공개 비밀 기록: 공개 저장소가 API 키를 커밋한 적이 있는 경우, 기록을 GitHub에서 완전히 제거하려면 저장소를 삭제하는 것이 유일한 방법입니다. 정리된 기록을 강제 푸시한다고 해서 GitHub의 백업 시스템에서 제거된다는 보장은 없습니다.
  • 비밀이 포함된 보관된 공개 저장소: 삭제가 불가능한 경우, 최소한 저장소를 공개 상태에서 제거(비공개로 전환)하거나 삭제하고 깔끔한 코드로 빈 상태로 재생성합니다.

기술 참조

인코딩 함정 (Windows)

PowerShell은 stdout에 대해 기본적으로 CP1252를 사용하여 중국어 문자와 Markdown 코드 블록을 손상시킵니다. 항상 재구성합니다:

import sys
sys.stdout.reconfigure(encoding='utf-8')

PowerShell에서 JSON 본문에 백틱 또는 삼중 백틱이 포함된 Invoke-RestMethod를 사용할 때는 JSON 직렬화가 ```를 `로 망가뜨리는 것을 방지하기 위해 콘텐츠 생성에 Python 스크립트를 선호합니다.

GitHub API 패턴

저장소 생성(description을 절대 생략하지 마십시오):

api_call("POST", "/user/repos", {
    "name": "repo-name",
    "private": True,
    "description": "한 문장 요약."
})

파일 생성/업데이트:

import base64, json, urllib.request

payload = {
    "message": "커밋 메시지",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": existing_sha  # 업데이트에 필요
}
req = urllib.request.Request(
    f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
    method="PUT",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {token}", ...}
)

보관/보관 해제:

api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})

저장소 이름 변경:

api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "new-name"})

저장소 삭제:

api_call("DELETE", f"/repos/{owner}/{repo}")

클론 없이 대량 다운로드

불안정한 네트워크에서 느린 git clone을 피하기 위해 저장소 스냅샷을 zip으로 다운로드합니다:

curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip

번들 리소스

  • scripts/repo_analyzer.py — 사용자의 GitHub 저장소를 스캔하고 정리 권장 사항 생성
  • scripts/bulk_file_updater.py — GitHub API를 통해 LICENSE, .gitignore, README를 일괄 생성/업데이트

관련 스킬