지연 실행을 지키며 대규모 Python 데이터 시스템 수정하기

## 요청된 동작을 담당하는 계층까지 추적하기 대규모 Python 데이터 또는 병렬 계산 코드베이스를 변경하기 전에 저장소 전체를 무분별하게 읽지 말고 작업에 필요한 구조도를 만든다. 관련 계층을 식별한다. 1. 공개 컬렉션 또는 사용자용 인터페이스 2. 계획과 최적화에 사용하는 기호식 또는 상위 수준 그래프 3. 구체화된 하위 수준 작업과 의존성 연결 4. 스케줄러 또는 실행 백엔드 5. 구성, 디스패치, 직렬화, 유틸리티 계층 요청된 동작을 공개 진입점부터 그 동작을 담당하는 가장 작은 구현 계층까지 추적한다. 편집 전에 인접한 테스트와 구성을 읽는다. 작업 유형에 따라 탐색한다. - 스케줄링 동작: 공개 계산 API, 그래프 유틸리티, 작업 표현, 스케줄러 어댑터 순으로 살핀다. - 그래프 최적화: 상위 수준 그래프 프로토콜, 블록 단위 또는 표현식 계층, 구체화 순으로 살핀다. - 배열 또는 데이터프레임 기능: 컬렉션 API, 작업 구현, 디스패치, 범위를 좁힌 테스트 순으로 살핀다. - 구성 변경: 실행 시 접근 함수, 기본 구성, 스키마, 문서 순으로 살핀다. - 백엔드 지원: 백엔드 인터페이스, 진입점 등록, 디스패치, 호환성 테스트 순으로 살핀다. 저장소 메모에 적힌 모듈 이름, 줄 수, 의존성 버전은 영구적인 사실이 아니라 탐색을 위한 힌트로 취급한다. 현재 소스와 매니페스트를 로컬에서 확인한다. 하위 시스템의 경계를 명확히 유지한다. 공개 컬렉션을 변경하면 관련 메타데이터, 그래프, 스케줄러, 테스트, 문서도 함께 갱신해야 할 수 있지만 관련 없는 계층은 편집하지 않는다. ## 저장소의 환경을 쓰고 가장 작은 테스트 범위 고르기 저장소가 지정한 환경 관리자와 명령을 사용한다. 전역 Python 설치가 지원되는 의존성 조합과 일치한다고 가정하지 않는다. 구현 전에 다음을 수행한다. 1. 프로젝트 매니페스트와 사용 가능한 환경을 확인한다. 2. 영향을 받는 기능을 대표하는 가장 작은 환경을 선택한다. 3. 가장 가까운 기존 테스트, 픽스처, 표시자, 검증 보조 함수를 찾는다. 4. 관련 선택적 의존성, 기능 플래그, 경고 정책을 기록한다. 다음 작업에는 저장소가 제공하는 명령 실행 도구를 우선 사용한다. - 실패하는 단일 테스트 - 영향을 받는 모듈의 테스트 파일 - 린트 및 정적 검사 - 공개 예시의 문서 테스트 - 최소 의존성 또는 선택 기능 환경 - 변경 범위상 필요할 때만 수행하는 더 넓은 CI 동등 검사 경고를 오류로 처리하는 정책, 엄격한 예상 실패, 시간 제한, 환경별 표시자와 같은 엄격한 테스트 동작을 준수한다. 메타데이터, 형식, 파티션, 수치 허용 오차를 함께 확인하는 지연 컬렉션용 공용 동등성 보조 함수가 있다면 이를 사용한다. 선택적 의존성에는 임시 조건문 대신 프로젝트의 가져오기 및 건너뛰기 보조 함수를 사용한다. 새 API를 사용할 때는 지원되는 최소 버전과 최신 버전을 모두 고려한다. 작업에서 허용하지 않았다면 패키지를 설치하거나 환경을 변경하거나 네트워크 의존 테스트를 활성화하지 않는다. 의존성이 없을 때는 시스템을 몰래 변경하지 말고 환경상의 제약으로 보고한다. ## 그래프를 만드는 동안 `compute()`를 호출하지 않고 지연 실행 지키기 지연 그래프 시스템의 핵심 불변 조건을 지킨다. 그래프 구성 코드는 계산을 실행하지 않고 계산 내용을 설명해야 한다. 컬렉션 작업, 그래프 계층, 기호식을 정의하는 동안 `compute()` 또는 `persist()` 같은 즉시 구체화 메서드를 절대로 호출하지 않는다. 구체화는 사용자가 명시했거나 실행이 이루어지는 경계에서만 수행한다. 그래프 구성 중에는 다음을 따른다. - 가능하면 메타데이터로 결과를 추론한다. - 작업 의존성을 명시적이고 결정적으로 유지한다. - 안정적인 키와 토큰화 동작을 보존한다. - 숨겨진 입출력이나 스케줄러 선택을 피한다. - 기호 최적화와 하위 수준 실행을 분리한다. 저장소 규칙을 따른다. - 새 코드에 완전한 형식 힌트를 추가한다. - 호환성용 가져오기와 지연 주석의 일관성을 유지한다. - 순환 의존성을 피하도록 형식 검사 전용 가져오기를 보호된 형태로 사용한다. - 표준 라이브러리, 외부 라이브러리, 로컬 가져오기를 예측 가능한 순서로 정리한다. - 공개 API에는 문서화된 설명문 형식과 실행 가능한 예시를 사용한다. - 비공개 보조 함수, 테스트, 디스패치 함수에 확립된 명명 규칙을 따른다. 백엔드, 표현식, 계층, 구성 옵션을 추가할 때는 필요한 모든 등록 지점을 갱신하고, 디스패치 또는 계획 단계가 새 구현에 도달함을 입증하는 범위가 좁은 테스트를 추가한다. 가져오기 시점의 등록이나 쿼리 계획에 영향을 주는 기능 플래그는 관련 모듈을 처음 가져오기 전에 설정해야 한다. 활성화와 비활성화 상태를 모두 계속 지원한다면 두 동작을 모두 테스트한다. 범위가 좁은 결함을 고치면서 광범위한 구조 변경을 하지 않는다. 관련 없는 동작을 보존하고 새 테스트 결과를 설명하는 가장 작은 변경만 수행한다. ## 테스트를 단계적으로 넓히고 허락 없이 배포하지 않기 범위를 점차 넓히며 검증한다. 1. 범위를 좁힌 테스트로 이전 실패를 재현한다. 2. 가장 가까운 테스트 파일 또는 하위 시스템 테스트 모음을 실행한다. 3. 편집의 직접적인 영향을 받는 린트, 형식, 문서 테스트 검사를 실행한다. 4. 관련 선택 기능, 최소 의존성, 기능 플래그 변형을 실행한다. 5. 변경이 넓은 아키텍처 경계를 가로지를 때만 전체 테스트 모음을 사용한다. 흔한 실패 유형을 확인한다. - 순환 가져오기와 등록 순서 - 첫 가져오기 후 변경된 기능 플래그 - 계산 결과와 일치하지 않는 메타데이터 - 일부 인터프리터에서 사용할 수 없는 선택 패키지 - 관련 패키지 사이에서 달라진 의존성 고정 버전 - 스키마에 빠진 기본 구성 - 더 이상 실행되지 않는 문서 테스트 예시 - 하나의 스케줄러나 백엔드에서만 통과하는 테스트 완료를 보고하기 전에 차이를 검토하고 실제로 실행한 검사, 통과한 검사, 실행하지 않은 검사를 밝힌다. 코드 검사만으로 성공을 추론하지 않는다. 배포 작업은 별도의 권한 경계다. 명시적으로 허가받지 않았다면 릴리스를 만들거나, 패키지를 배포하거나, 태그를 원격 저장소로 보내거나, 결과물을 업로드하거나, 외부 배포 시스템을 변경해서는 안 된다. 배포 준비가 허가된 경우에도 외부 상태를 변경하기 전에 변경 기록 항목, 버전과 패키지 간 고정 버전, 패키징 결과, 저장소에 문서화된 절차를 확인한다. 다른 사람과 소통하라는 요청을 받으면 사용자를 사칭하거나 사용자의 결정을 지어내지 말고 근거와 선택지를 제시한다.