pydantic/pydantic-ai

사전 푸시 리뷰 (Pre-push Review)

푸시 또는 PR을 열기 전에 자동화된 CI 리뷰 작업을 로컬에서 시뮬레이션합니다.

작동 방식

리뷰 기준은 CI 워크플로우에 정의되어 있으며 여기에 중복 기재하지 않습니다. 리뷰 프롬프트를 진실 공급원(source of truth)에서 직접 읽으십시오:

• .github/workflows/bots.yml — review 작업의 prompt: 필드 (Review this pull request로 시작하는 YAML 블록)를 찾으십시오. 여기에는 CI가 사용하는 전체 리뷰 기준, 우선순위 및 지침이 포함되어 있습니다.

해당 기준을 아래 설명된 대로 로컬(PR 이전) 리뷰에 맞게 조정하십시오.

단계

1. CI 리뷰 프롬프트 읽기

.github/workflows/bots.yml 파일을 읽고 review 작업 내 anthropics/claude-code-action 단계에서 리뷰 프롬프트를 추출하십시오. 이것이 무엇을 찾고 어떻게 우선순위를 정해야 하는지에 대한 기본 참조입니다.

2. 로컬 컨텍스트 수집

아직 PR이 없으므로 로컬에서 동등한 컨텍스트를 수집합니다:

# 기준 브랜치 결정 (기본값: main)
git merge-base main HEAD

# 변경된 파일
git diff main...HEAD --stat

# 함수 컨텍스트 diff (CI 스크립트에서 사용하는 -W 플래그와 동일)
git diff main...HEAD -W

diff의 경우, 한 번에 모두 로드하려고 하지 말고 관리 가능한 청크로 읽으십시오. 테스트 및 생성된 파일(uv.lock 및 캐셋 등)보다 "핵심 구현" 파일에 우선순위를 두십시오.

3. 관련 AGENTS.md 파일 읽기

루트 CLAUDE.md(이미 시스템 프롬프트에 있음)와 함께 변경된 파일이 포함된 디렉토리의 디렉토리별 AGENTS.md 파일을 읽으십시오. CI 스크립트는 다음 경로를 확인합니다:

• docs/AGENTS.md
• pydantic_ai_slim/pydantic_ai/models/AGENTS.md
• tests/AGENTS.md

변경된 디렉토리와 관련된 파일만 읽으십시오.

4. 리뷰 수행

CI 프롬프트의 리뷰 기준을 다음 로컬 적응 사항과 함께 적용하십시오:

• PR 관련 확인 건너뛰기: PR 설명, 연결된 이슈, 중복 PR 확인 또는 이전 리뷰 코멘트는 고려하지 않습니다.
• "이 PR이 존재해야 하는가" 확인 건너뛰기: 사용자가 이러한 변경을 의도했다고 가정합니다.
• 인라인 코멘트 대신 텍스트로 결과 출력.

집중 영역 (CI 프롬프트 기준 우선순위 순):

1. 공개 API (Public API) — 추상화, 클래스 계층 구조, 메서드 시그니처, 타입 안전성, 하위 호환성
2. 개념 및 동작 (Concepts & behavior) — 설계 결정, 논의가 필요한 트레이드오프
3. 문서화 (Documentation) — 어조, 패턴, 완전성
4. 테스트 (Tests) — 커버리지, 스타일, 통합 대 단위
5. 코드 스타일 (Code style) — AGENTS.md 규칙 준수, 관용적인 Python

상당한 재작업이 필요한 상위 수준의 문제가 있다면, 해당 문제에 집중하고 하위 수준의 사소한 문제는 보류하십시오.

5. 결과 제시

우선순위 계층별로 결과를 정리하십시오. 각 결과에 대해:

• 특정 파일 및 라인 참조 (file:line)
• 문제를 간결하게 설명
• 적절하다면 수정 제안

결과가 없으면 그렇게 말하십시오.

코멘트 품질

모든 발견 사항은 그 자리를 정당화해야 합니다. 리뷰는 절대 잡음을 추가해서는 안 됩니다:

• 실행 가능한 것만: 각 발견 사항은 특정 변경을 요청하거나, 논의가 필요한 우려 사항을 지적하거나, 구체적인 개선을 제안해야 합니다. 긍정적인 측면("훌륭한 설계", "좋은 선택")에 대해 코멘트하지 마십시오 — 그것들은 잡음입니다.
• 간결하게: 각 발견 사항당 1-3문장이면 거의 항상 충분합니다. 불필요한 목록, 부제목 또는 이모지는 사용하지 마십시오.
• 반복 금지: 동일한 문제가 의미 있게 다른 맥락에서 나타나지 않는 한 여러 번 지적하지 마십시오.
• 불필요한 내용 없음: 조치가 필요하지 않은 관찰로 리뷰를 늘리지 마십시오. 선택이 올바르다면 언급하지 마십시오. 코드가 프로젝트 패턴을 따른다면 칭찬하지 마십시오. 변경되거나 논의되어야 할 사항에만 집중하십시오.
• 친근하지만 아첨하지 않게: 도움이 되는 프로젝트 관리자의 어조를 사용하십시오. 칭찬, "훌륭한 작업" 없이 명확하고 직접적인 피드백만 제공하십시오.

상당한 재작업이 필요한 상위 수준의 문제가 있다면, 해당 문제에 집중하고 하위 수준의 사소한 문제는 완전히 건너뛰십시오 — 어차피 다시 검토해야 할 것입니다.