워크플로를 돌리는 큰 Python 모노레포를 망가뜨리지 않고 고치기

## 고치기 전에 담당 패키지와 그 안내를 찾기 설명문에서는 프로젝트의 표준 도메인 용어를 사용하십시오. 리터럴 식별자, 명령, 경로, 구성 키, 호환성 이름은 코드가 요구하는 그대로 유지하고, 단지 스타일을 일관되게 만들기 위해 다시 쓰지 마십시오. 편집하기 전에: - 담당 패키지, 해당 패키지의 로컬 지침, 가장 가까운 아키텍처 또는 테스트 가이드를 확인하십시오. - 호스트 도구를 직접 호출하지 말고 프로젝트가 관리하는 개발 및 테스트 래퍼를 사용하십시오. - 저장소의 문서화된 일회성 설정 절차를 통해 훅 또는 명령 어댑터를 설치하십시오. - 임시 보조 스크립트는 지정된 마운트 개발 영역에만 두고 작업이 끝나면 제거하십시오. - 실제로 변경된 파일과 패키지에 따라 검사를 선택하십시오. 생성된 종속성 잠금 파일과 유사한 산출물은 공식 생성기의 출력으로 취급하고, 수작업으로 편집할 소스로 취급하지 마십시오. ## 스케줄러가 워크플로 코드를 실행하지 않고, 워커가 데이터베이스에 직접 접근하지 않게 하기 오케스트레이션 코드를 변경하기 전에 데이터 흐름을 이해하십시오: 1. 작성자는 공개 SDK를 통해 워크플로를 정의합니다. 2. 격리된 처리기는 해당 정의를 해석하고 직렬화된 워크플로 데이터를 영구 저장합니다. 3. 스케줄러는 직렬화된 데이터를 읽으며 작성자가 제공한 워크플로 코드를 실행해서는 안 됩니다. 4. 워커는 지원되는 SDK 또는 API를 통해 작업을 실행하며 메타데이터 데이터베이스에 직접 접근해서는 안 됩니다. 5. API 서비스는 사용자 인터페이스 및 클라이언트와 영구 상태 사이의 상호작용을 중개합니다. 6. 이벤트 트리거 서비스는 스케줄러 및 워커와 분리되어 실행됩니다. 구성 요소 사이에는 수명이 짧고 범위가 엄격히 제한된 자격 증명을 사용하십시오. 데이터베이스 직접 접근을 억제하는 소프트웨어 검사는 유용한 안전장치이지만, 의도적인 악성 코드에 대한 보안 경계는 아닙니다. 수정안을 제시하기 전에 의심되는 보안 문제를 분류하십시오: - 문서화된 신뢰 모델을 악용 가능한 방식으로 위반하는 것은 취약점입니다. - 신뢰 모델의 범위 밖이라고 이미 명시된 동작은 알려진 제한 사항입니다. - 위반된 보장을 복구하지 않고 더 안전한 배포 방안만 제시하는 것은 보안 강화 지침입니다. 심각도와 개선 조치가 실제 위험에 맞도록 이 범주들을 서로 구분하십시오. ## 의존성은 그것을 가져오는 패키지에 두기 모노레포를 구분 없는 하나의 패키지가 아니라 서로 연관된 배포 단위의 집합으로 다루십시오. 핵심 오케스트레이션, 공개 SDK, 공급자 통합, 명령줄 도구, 배포 차트, 개발 도구, 스크립트는 출시 주기와 종속성 규칙이 서로 다를 수 있습니다. 공유 라이브러리의 경우: - API를 작고 독립적으로 유지하십시오. - 자체 소스 트리, 테스트, 구성, 선언된 종속성을 갖추게 하십시오. - 코드를 복제하지 말고 저장소가 지원하는 작업 공간 링크를 사용하십시오. - 라이브러리 자체와 직접 영향을 받는 모든 사용 구성 요소를 테스트하십시오. 종속성은 그것을 가져오는 배포 단위에 배치하십시오. 변경이 패키지 경계를 넘는 경우, 매니페스트를 수정하기 전에 가져오기 방향과 출시 책임을 모두 확인하십시오. 지원되는 워크플로를 사용하여 잠금 파일을 다시 생성하고, 그 결과 생긴 종속성 변경분에 관련 없는 변동이 섞였는지 검토하십시오. ## 읽기 쉬운 Python 코드를 쓰고 한 번의 변경을 작게 유지하기 변경 사항이 아직 작을 때 수정한 각 Python 파일의 형식을 맞추고 린트 검사를 수행하십시오. 프로덕션 동작을 명시적으로 유지하십시오: - 런타임 검증이나 복구 가능한 오류 처리에 어설션을 사용하지 마십시오. - 코드를 그대로 서술하지 말고 제약 조건이나 의도를 설명하는 주석을 작성하십시오. - 단조 시계를 사용해 지속 시간을 측정하십시오. - 문서화된 순환 종속성, 지연 로딩 또는 선택적 종속성의 경우를 제외하고 가져오기를 모듈 범위에 두십시오. - 타입 검사에만 필요한 비용이 큰 가져오기는 런타임 시작에 영향을 주지 않도록 보호하십시오. - 의미가 분명한 가장 좁은 예외를 발생시키고, 모든 것을 포착하는 광범위한 기본 예외를 도입하지 마십시오. - 도메인 실패는 전송 경계에서만 프로토콜별 응답으로 변환하십시오. - 함수 이름은 동작 동사를 사용하고 필수 라이선스 헤더를 유지하십시오. 기회에 편승한 리팩터링보다 작고 검토하기 쉬운 변경을 우선하십시오. 정리 작업이 요청된 동작에 필요하지 않다면 별도의 변경으로 남겨 두십시오. ## 데이터베이스에 조금씩 나눠 써서 스케줄러를 느리게 하지 않기 데이터베이스 세션을 받는 함수는 트랜잭션을 암묵적으로 커밋해서는 안 됩니다. 코드베이스에서 해당 규칙을 사용하는 경우 세션을 키워드 전용 인자로 만들고, 트랜잭션 소유자가 커밋 또는 롤백 시점을 결정하도록 하십시오. 스케줄러 또는 유지보수 루프 안에서 한도 없는 대량 쓰기를 피하십시오: 1. 인덱스가 있는 열로 필터링하십시오. 2. 크기가 제한된 배치를 처리하십시오. 3. 배치 사이에 트랜잭션을 커밋하거나 해제하십시오. 4. 대상 행이 남지 않을 때까지 계속하십시오. 이렇게 하면 잠금 지속 시간, 메모리 증가, 다른 스케줄러 작업의 자원 고갈을 제한할 수 있습니다. 기본 데이터베이스에서 동작을 확인하고, 변경된 쿼리가 백엔드별 의미 체계에 의존할 때는 대체 백엔드 대상 테스트도 실행하십시오. 파괴적인 정리 명령을 일상적인 문제 해결 수단으로 취급해서는 절대 안 됩니다. 데이터베이스, 볼륨, 캐시 또는 사용자 데이터를 삭제하기 전에 정확한 대상을 확인하고 필수 승인을 받으십시오. ## 실패하는 테스트를 먼저 쓰고, 필요할 때만 테스트 범위를 넓히기 변경할 정확한 동작을 표현하는 테스트부터 작성하고, 구현이 없으면 그 테스트가 실패하는지 확인하십시오. 그런 다음 테스트를 통과시키는 가장 작은 변경을 적용하십시오. 저장소에서 선호하는 테스트 프레임워크와 보조 도구를 사용하십시오: - 테스트 트리에서 소스 구조를 그대로 재현하십시오. - 인터페이스 변화가 명확한 실패로 드러나도록 명세 기반 모의 객체를 사용하십시오. - 지원되는 구성 재정의 및 시간 제어 도구를 사용하십시오. - 의미 있는 입력과 백엔드 변형을 매개변수화하십시오. - 데이터베이스 테스트를 정확히 표시하고 데이터베이스를 사용하지 않는 테스트는 데이터베이스 설정과 독립적으로 유지하십시오. - 불안정하게 렌더링된 로그 텍스트 대신 구조화된 이벤트 이름과 필드를 검증하십시오. 표준 라이브러리나 서드파티 종속성을 따로 떼어 테스트하지 마십시오. 이 코드가 담당하는 통합 동작을 테스트하십시오. 먼저 대상 범위를 좁힌 테스트를 실행한 다음, 영향을 받는 패키지의 테스트 모음, 정적 타입 검사, 린트 검사를 실행하십시오. 더 넓은 테스트 모음은 종속성 범위상 필요할 때만 실행하십시오. ## CI 규칙과 문서를 함께 고치고, 릴리스 노트는 보이는 변경에만 붙이기 지속적 통합의 선택적 동작이 변경되면 선택 로직, 해당 테스트, 문서를 함께 갱신하십시오. 코드에만 있거나 설명문에만 있는 규칙은 불완전합니다. 해당 동작을 제공하는 배포 단위에서 사용자에게 보이는 변경에만 출시 메타데이터를 추가하십시오. 내부 리팩터링, 테스트 전용 작업, 개발 도구, 사용자에게 보이지 않는 유지보수에는 일반적으로 출시 노트가 필요하지 않습니다. 잠금 파일, 명령 참조, 스키마와 기타 생성 문서에는 프로젝트 생성기를 사용하십시오. 생성된 차이를 검토하되, 기준 원본의 문제를 숨기려고 생성 파일을 수정하지 마십시오. 인계하기 전에 관련 형식, 린트, 타입, 테스트, 문서, 선택적 검사 관문을 실행하십시오. 의도적으로 건너뛴 관문이 있다면 적용되지 않은 구체적인 이유와 함께 기록하십시오. ## 전체 diff를 다시 보고 포크에서 풀 리퀘스트 열기 게시하기 전에 작업 전체의 변경 내역을 검토하십시오. 아키텍처 경계, 보안 가정, 테스트, 생성된 출력, 출시 메타데이터, 로컬 지침이 모두 서로 일치하는지 확인하십시오. 대규모 패키지 간 리팩터링, 광범위한 종속성 추가, 파괴적 마이그레이션 동작 변경 또는 아직 승인되지 않은 외부 게시를 수행하기 전에 물어보십시오. 비밀을 절대 노출하지 말고, 필수 훅을 우회하거나 생성 파일을 수작업으로 편집하거나 명시적 승인 없이 파괴적인 버전 관리 명령을 실행하지 마십시오. 원격 작업을 수행하기 전에: - 구성된 원격 저장소를 살펴보고 어느 것이 기준 저장소이고 어느 것이 기여자의 포크인지 확인하십시오. - 기준 원격 저장소나 보호된 기본 브랜치에 직접 푸시하지 마십시오. - 원격 저장소의 역할이 불분명하면 이름을 바꾸거나 기록을 다시 쓰기 전에 물어보십시오. - 작업이 중복되지 않도록 기존 풀 리퀘스트를 검색하십시오. - 저장소에서 허용하는 워크플로를 통해 현재 대상 브랜치에 리베이스하거나 다른 방식으로 동기화하십시오. 명령형으로 작성된 평이한 문장의 제목을 사용하고 사용자 영향을 드러내십시오. 본문에서 변경이 필요한 이유를 설명하고, 요구되는 경우 AI 지원을 공개하며, 관련 이슈 참조를 포함하십시오. 사용자가 승인했거나 해당 인물이 이미 논의에 참여하고 있는 경우가 아니라면 자신을 공동 작성자로 추가하거나 개인을 태그하지 마십시오. 완전한 수정이 준비되었다면 중복 이슈를 여는 대신 풀 리퀘스트를 우선하십시오. 변경이 해결 방법, 완화책 또는 부분 수정에 불과하다면 추적 이슈를 만들거나 연결하고, 풀 리퀘스트와 임시 코드 근처 모두에서 이를 참조하십시오.