PR 정리 (PR tidy)
브랜치를 Pull Request로 만들기 전에 일관성 점검을 수행합니다. diff가 변경한 내용을 살펴본 후, diff가 함께 변경해야 할 모든 것을 찾습니다.
브랜치 자체의 변경 사항에 대해서만 작업합니다. diff가 해당 부분을 틀리게 만들지 않는 한, 저장소의 다른 곳에 있는 수정하지 않은 부채는 건드리지 않습니다.
0. 범위
-
저장소의 지침을 먼저 읽습니다:
AGENTS.md,CLAUDE.md,CONTRIBUTING*,README*, 그리고 이들이 가리키는 모든 문서. -
기준(base)과 diff를 찾습니다:
base=$(git merge-base origin/main HEAD) # 또는 저장소의 기본 브랜치 git log --oneline "$base"..HEAD git diff --stat "$base"...HEAD git diff --name-only "$base"...HEAD -
작업 트리(
git status)를 확인합니다. 커밋되지 않은 변경 사항은 유지합니다. 만들려는 편집이 이와 겹치면 중단하고 질문합니다. -
비교할 대상이 없는 기본 브랜치에 있다면 중단하고 그렇게 말합니다.
1. diff 분류
변경 사항을 다음으로 분류합니다:
- 새 항목: 파일, 명령어, 함수, 옵션, 플래그, 구성 키, 환경 변수, 스크립트, 스킬.
- 변경됨: 동작, 기본값, API, 시그니처, 규칙, 디자인: 가이드나 명세가 이제 다른 내용을 말하는 경우.
- 제거 또는 이름 변경: 삭제, 이름 변경, 이동, 또는 대체된 모든 것.
- 인프라: 빌드, CI, 테스트, 도구.
이를 바탕으로 표면(surface) 을 나열합니다: 독자나 다른 파일이 참조할 수 있는 모든 이름, 경로, 플래그, 옵션, 용어, 규칙. 디자인 변경의 경우, 이름뿐만 아니라 이전 아이디어의 핵심 문구도 나열합니다(제거된 "레벨별 검사"가 여전히 "각 레벨 아래의 검사"로 설명될 수 있음).
2. 낡은 참조(Stale references)
제거, 이름 변경, 또는 재설계된 모든 항목에 대해, 변경된 파일뿐만 아니라 전체 저장소를 검색합니다:
git grep -n -w "old_name" # 이름, 경로, 플래그
git grep -n -i "구 디자인의 문구"
코드, 주석, 테스트, 문서, README, 예제, 노트북, 템플릿, 스킬 파일, 다이어그램(Mermaid 및 ASCII), 구성 등에서 찾습니다. 모든 결과는 업데이트되거나 이유와 함께 플래그가 지정됩니다.
그런 다음 각 새 항목 또는 변경된 항목에 대한 커버리지 맵(coverage map) 을 구축합니다: 어디에 문서화되어 있습니까?
커버리지 맵:
항목 참조 방법 예제 설명
--new-flag README - - -
check_levels.py scripts/ - - -
커버리지가 없는 항목은 간격(gap)입니다. 보고하세요. 요청 없이 새로운 문서 페이지 전체를 작성하지 마십시오.
3. 새 동작에 대한 테스트와 문서
새롭거나 변경된 각 동작에 대해:
- 테스트가 동작을 실행하며, 해당 동작을 소유한 계층에서 실행하고, 변경된 실패 경로도 테스트합니다. 저장소의 기존 테스트 패턴과 회귀를 잡을 수 있는 가장 좁은 테스트를 선호합니다.
- 문서는 이전 동작이 설명되었던 모든 곳(참조, 예제, 이전 방식을 가르친 가이드)에서 새 동작을 설명합니다.
- 테스트 누락은 잡을 구체적인 실패를 명명할 수 있을 때만 보고하십시오. 추측과 건드리지 않은 커버리지 부채는 건너뜁니다.
4. 체커가 확실히 실패하도록
새롭거나 변경된 각 체커, 린터, 검증기, 또는 검사 스크립트에 대해:
- 연결됨. 저장소가 사용하는 모든 진입점을 찾습니다:
.pre-commit-config.yaml,.github/workflows/*,Makefile,justfile,noxfile.py,tox.ini,pyproject.toml또는package.json스크립트, 다른 검사를 호출하는 검증기. 체커가 최소한 하나에서 호출되는지 확인합니다. 그렇지 않으면 동일한 방식으로 연결하거나 플래그를 지정합니다. - 잘못된 입력에서 실패. 의도적으로 깨진 입력에서 실행합니다; 0이 아닌 종료 코드로 종료되어야 합니다.
- 빈 입력에서 실패. 빈 입력이나 누락된 입력(파일 없음, 일치 없음, 파싱된 것 없음)에서 실행합니다; 0이 아닌 종료 코드로 종료되거나 아무것도 확인하지 않았음을 명확히 말해야 하며, 조용히 통과해서는 안 됩니다.
- 2와 3을 다루는 테스트가 있습니다.
나중에 이를 유지하기 위해, references/test_checkers_wired.py와 같은 연결 테스트를 추가합니다.
5. 숫자, 버전, 예제
diff가 건드린 파일이나 이를 설명하는 문서에 있는 모든 숫자, 버전, 날짜, URL, 인용, 명령어, 코드 예제를 나열합니다. 각각에 대해:
- 소스 이름 지정: 숫자를 생성하는 코드나 명령어, 구성 값, 데이터셋, 또는 정확한 버전(arXiv
v3, DOI)이 있는 논문. - 다시 확인: 명령어를 다시 실행하거나 소스를 다시 읽습니다. 수정하거나, 확인할 수 없으면 플래그를 지정합니다.
- 조건 유지: 숫자가 유효한 데이터셋, 설정, 기계, 시간("N 포인트"가 아니라 "기계 M에서 T 시간 동안 N 포인트").
- 외부 소스를 버전에 고정.
- 계속 변경될 숫자는 수동으로 입력하는 것보다 코드에서 생성하는 것이 좋습니다(예:
cog사용,cog --check로 확인). 제안하세요.
6. 개인정보와 자격 증명
브랜치가 추가하는 모든 것과, 추가되려는 모든 추적되지 않은 파일을 기계를 떠나기 전에 확인합니다. 이것은 차단(blocking) 단계입니다: 아래의 어떤 것도 넘어가서 "수정"될 수 없습니다.
git diff "$base"...HEAD # 브랜치에 커밋됨
git diff; git diff --cached # 아직 커밋되지 않음
git status --short # 추가될 수 있는 추적되지 않은 파일
찾을 내용:
- 자격 증명: API 키, 토큰, 비밀번호, 비밀번호가 포함된 연결 문자열, 개인 키(
-----BEGIN … PRIVATE KEY-----), 클라우드 및 CI 비밀, 세션 쿠키. - 이를 포함하는 파일:
.env*,*.pem,*.key,id_rsa*,credentials*,secrets*,*.p12, 서비스 계정 JSON, 토큰이 있는.npmrc또는.pypirc, 로컬 설정 파일. - 개인정보: 이메일 주소, 전화번호, 집 또는 우편 주소, 예제나 테스트 데이터의 실제 이름, 계정 또는 ID 번호, 다른 사람을 식별하는 데이터.
- 기계 세부정보: 절대 홈 경로(
/Users/<name>,/home/<name>,C:\Users\<name>), 내부 호스트 이름, 개인 IP 주소, 로그나 노트북 출력의 사용자 이름. - 숨겨진 장소: 노트북 출력 및 메타데이터, 로그, 스크린샷, 픽스처, 생성된 보고서, 커밋 메시지, 브랜치의 전체 기록(최종 상태뿐만 아니라).
저장소에 스캐너가 있으면 실행하고(gitleaks, detect-secrets, pre-commit run --all-files), diff를 직접 읽으십시오; 스캐너는 개인 데이터를 놓칠 수 있습니다.
무언가를 찾았을 때:
- 절대 값을 보고서나 커밋 메시지에 반복하지 마십시오. 파일, 줄, 항목 종류(
AWS key,email address)를 명명하십시오. - 아직 커밋되지 않음: 제거하고, 무시된 파일이나 환경 변수로 이동하며, 파일 패턴인 경우
.gitignore에 추가하십시오. - 이미 브랜치에 커밋됨: 중단하고 사용자에게 알리십시오. 한 번 커밋된 자격 증명은 기록을 다시 쓴 후에도 취소되고 교체되어야 합니다. 이미 복사되었을 수 있기 때문입니다. 사용자 없이 공유 기록을 다시 쓰지 마십시오.
- 사용자가 의도적으로 넣은 개인정보(예: 라이선스에 자신의 공개 이름): 질문하고, 제거하지 마십시오.
7. 수정 또는 플래그 지정
파일의 고유한 어조, 구조, 용어를 사용하여 최소한으로 편집하십시오. 편집하기 전에 파일을 완전히 읽으십시오.
질문 없이 수정:
- diff에서 직접 따르는 사실적 수정;
- 낡은 이름, 경로, 개수, 버전, 상호 참조;
- 기존 표나 목록에 새 항목 추가;
- 형제 항목이 패턴을 보여주는 곳에 체커 연결.
플래그 지정 또는 변경 전에 질문:
- 서사, 디자인, 정책 텍스트, 그리고 브랜치의 명백한 의도와 모순되는 모든 것;
- 제거 및 대규모 재작성;
- 보안에 민감한 변경;
CHANGELOG항목 및 버전 범프;- 다른 사람이나 팀이 소유한 파일;
- 설계 결정이 필요한 새 테스트.
절대: 기존 체인지로그 항목을 다시 쓰거나 재생성하지 말고, 조용히 버전을 올리지 말며, 생성된 파일을 직접 편집하지 말고(생성기를 사용), 비밀이나 실제 자격 증명을 붙여넣지 마십시오.
8. 증거로 검증
마지막 관련 편집 이후, 이 세션의 새로운 증거 없이는 주장하지 마십시오:
- 주장을 증명하는 명령어를 명명합니다.
- 전체를 실행합니다.
- 전체 출력과 종료 코드를 읽습니다.
- 그 증거와 함께 결과를 진술하거나, 실제 상태를 진술합니다.
저장소가 이미 가지고 있는 것(테스트, 린터, pre-commit run --all-files, 문서 빌드, 링크 검사)을 실행합니다. 설치되지 않은 도구나 다운된 서비스는 검증 간격(verification gap) 이며, 그렇게 보고되어야 하고 절대 통과로 간주되지 않습니다. "통과해야 함"과 에이전트의 "완료"는 증거가 아닙니다.
9. 보고서
범위: <base>..HEAD, N개 파일, M개 커밋
차단 (Blocking)
- path:line — 자격 증명 또는 개인정보 종류 (값 미표시), 필요한 조치
변경됨 (Changed)
- path:line — 무엇이 변경되었고, 왜 diff가 이를 요구했는지
플래그 지정됨 (Flagged, 수정되지 않음)
- path:line — 문제, 수정되지 않은 이유, 제안된 수정
커버리지 간격 (Coverage gaps)
- 항목 — 문서화되거나 테스트되어야 할 위치
검증됨 (Verified)
- `command` → 결과 (종료 코드)
검증되지 않음 (Not verified)
- 무엇, 그리고 이유 (도구 누락, 외부 서비스, 결정 필요)
기계적인 계층 (The mechanical layer)
섹션 2-6의 대부분은 판단이 필요하지만, 일부는 모든 커밋에서 실행될 수 있습니다. 이를 위한 저장소가 없다면 references/pre-commit-config.yaml의 스타터 구성을 제공하십시오: 파일 위생, ruff, codespell, 개인 키 및 비밀 탐지(gitleaks), 그리고 push 시 diff-cover와 함께 pytest. lychee 링크 검사와 경로 게이트 CI는 커밋 훅보다 워크플로에 더 적합합니다.
크레딧
변경을 가하여 MIT 라이선스 스킬에서 가져옴: Jakub Merta(jMerta/codex-skills)의 docs-sync 및 review-test-coverage; Garry Tan(garrytan/gstack)의 document-release에서 diff 분류, 커버리지 맵, 수정-또는-플래그 규칙; Jesse Vincent(obra/superpowers)의 verification-before-completion에서 증거 규칙. 아이디어(텍스트 아님)는 Anthropic의 pr-review-toolkit 에이전트(anthropics/claude-plugins-official)에서 가져옴. 라이선스: THIRD_PARTY_NOTICES.md.