분산 작업 플랫폼의 모노레포를 실제 서비스로 테스트하며 수정하기

## 루트에서 명령을 실행하고, 패키지 종류에 맞는 검사를 골라라 고정된 패키지 관리자 래퍼를 통해 저장소 루트에서 워크스페이스 명령을 실행하라. 애플리케이션이나 명령줄 도구를 시작하기 전에 필요한 종속성을 빌드하고, 워크스페이스 필터를 사용하여 작업을 영향을 받는 패키지 그래프로 제한하라. 저장소의 종속성 설치 정책을 정확히 따르라. 설치 전에 패키지 선언을 편집해야 한다면, 검토 가능한 버전 선택을 우회하는 추가 명령을 호출하지 말고 선언을 편집하라. 패키지 역할에 따라 검증을 선택하라: - 애플리케이션과 비공개 패키지는 빌드만으로 정확성이 입증되지 않을 때 정적 타입 검사를 사용한다. - 게시 패키지는 실제 패키지 빌드를 사용하여 내보내기와 생성 산출물이 실행되게 한다. - 주요 변경, 새 파일, 스키마 작업, 광범위한 리팩터링에는 로컬 타입 또는 빌드 검증을 적용한다. - 프로젝트가 명시적으로 허용한다면 사소한 편집은 집중 검사와 지속적 통합에 의존해도 된다. 익숙하다는 이유만으로 광범위한 빌드를 실행하지 마라. 변경된 계층에서 실제로 실패를 감지할 수 있는 검사를 사용하라. ## 큐와 데이터베이스는 모의 객체 대신 실제 서비스 컨테이너로 테스트하라 테스트를 소스와 같은 위치에 두고 저장소가 지원하는 단일 테스트 실행기를 사용하라. 영향을 받는 패키지나 하나의 테스트 파일부터 시작하고, 워크스페이스에서 요구할 때만 먼저 해당 종속성을 빌드하라. 프로젝트가 일회용 서비스 컨테이너를 제공한다면 데이터베이스, 큐, 캐시를 모의 객체로 대체하지 마라. 다음을 위해 실제 연결 옵션과 깨끗한 상태를 제공하는 격리된 테스트 도우미를 사용하라: - 큐 및 캐시 동작. - 관계형 트랜잭션 및 마이그레이션. - 스토리지 경계를 넘나드는 결합 워크플로. 순수 함수에는 가벼운 단위 테스트 경계를 남겨라. 인프라 동작에는 직렬화, 타이밍, 재시도, 트랜잭션 의미론이 드러나도록 통제된 실제 서비스를 우선하라. 최종 읽기 전용 린트 검사 전에 포맷팅과 자동 린트 수정을 실행하라. 정적 가져오기를 우선하고, 피할 수 없는 순환, 측정된 코드 분할 이점, 실제 런타임 조건이 있을 때만 동적 로딩을 사용하라. ## 공개 패키지 변경을 기록하고, 공유 의존성은 한 버전으로 맞춰라 게시 패키지나 통합이 변경될 때마다 버전이 지정된 변경 기록을 추가하라. 수정과 작고 호환되는 변경에는 기본적으로 패치 릴리스를 적용하고, 마이너 릴리스는 유지관리자와 확인하며, 명시적 승인 없이 메이저 릴리스를 선택하지 마라. 게시 패키지 변경 없이 서버 동작만 변경된다면 패키지 버전 기록 대신 서버 변경 노트 메커니즘을 사용하라. 사용자를 위해 릴리스 설명을 작성하라: - 변경된 동작을 먼저 제시한다. - 가능하면 평이한 한 문장을 사용한다. - 내부 도구, 큐, 스토리지, 배포 이름을 생략한다. - 구현 방식을 이점으로 설명하지 않는다. 런타임 타입 동일성이 종속될 때는 의도적으로 공유되는 종속성을 워크스페이스 전체에서 하나의 정확한 버전으로 유지하라. 그러한 종속성을 추가하기 전에 기존 고정 버전을 찾아 정확히 일치시켜라. 버전 범위나 병렬 버전은 한 패키지의 스키마를 다른 패키지의 소비자와 호환되지 않게 만들 수 있다. ## 계층 간에 작업을 옮기기 전에 요청이 지나는 경로를 먼저 따라가라 편집하기 전에 요청 경로를 이해하라: 1. 외부 요청이 API와 대시보드 애플리케이션으로 들어온다. 2. 서비스가 의도를 검증하고 실행 수명 주기 엔진을 호출한다. 3. 엔진이 상태를 영속화하고 작업을 큐에 넣는다. 4. 감독자가 작업을 확보하고 격리된 실행을 관리한다. 5. 결과가 수명 주기 엔진을 통해 반환된다. 6. 트랜잭션 상태와 분석 이벤트가 각각 별도의 저장소로 흐른다. 공개 SDK, 명령줄 도구, 공유 타입, 빌드 확장, 클라이언트 훅, 큐 워커, 데이터베이스, 분석, 스케줄링, 실행 엔진을 선언된 패키지에 유지하라. 내보내기 계약에서 요구한다면 광범위한 패키지 루트가 아니라 지원되는 하위 경로를 통해 공개 공유 타입을 가져오라. 편의를 위해 이러한 계층 사이로 책임을 옮기지 마라. 스케줄링, 큐잉, 실행, 영속성 변경은 전체 상태 전이와 실패 경로를 고려해야 한다. ## 폐기한 실행 엔진을 되살리지 말고, 오래된 클라이언트는 오류로 깔끔하게 거절하라 이전 엔진이 제거되었다면 과거의 디렉터리 이름이나 호환성 열거형이 남아 있어도 여전히 실행된다는 증거가 아니다. 현재 아키텍처 문서와 활성 패키지 그래프를 권위 있는 기준으로 취급하라. 오래된 브랜치나 요청을 충족하기 위해 폐기된 경로를 다시 도입하지 마라. 호환성 처리는 구식 버전을 인식하더라도 클라이언트 오류로 거부하거나 정상적으로 마무리하는 데만 사용해야 한다. 존재하지 않는 실행 코드로 작업을 라우팅하거나 예상된 거부를 서버 실패로 바꾸어서는 안 된다. 호환성 동작을 변경하기 전에: - 활성 엔진 선택을 추적한다. - 구식 클라이언트를 식별하는 방법을 확인한다. - 명확한 오류 의미론을 보존한다. - 현재 경로와 폐기 버전 거부 양쪽에 대한 테스트를 추가한다. 버전별 SDK 지침과 생성된 에이전트 규칙은 전용 유지관리 작업으로 처리하라. 작업에 명시적으로 포함되지 않았다면 배포된 지침 번들을 업데이트하지 마라. ## 현재 공개 SDK로 작업을 작성하고, SDK가 바뀌면 문서도 고쳐라 현재 공개 SDK 진입점을 통해 내구성 있는 작업을 정의하라. 구식 버전 하위 경로를 가져오거나 더 이상 권장되지 않는 작업 정의 API를 되살리지 마라. 작업 정의에는 다음이 있어야 한다: - 안정적인 식별자. - 타입이 지정된 입력 계약. - 하나의 비동기 실행 함수. - 유효하지 않은 입력에 대한 명시적 오류. - 부작용에 대한 멱등 동작 또는 문서화된 재시도 경계. 명령줄 패키지에서 유래하더라도 고객 실행 이미지에 번들되는 코드는 공개 런타임 코드로 취급하라. 패키지 내보내기, 번들 종속성, 컨테이너 동작을 함께 검증하라. SDK 계약이 변경되면 공개 문서와 예제를 업데이트하라. 제품 문서는 지정된 사이트에 유지하고 해당 사이트의 로컬 포맷팅 및 탐색 규칙을 따르라. ## 로컬 빌드에서 실제 작업을 처음부터 끝까지 실행해 확인하라 유지관리되는 참조 프로젝트를 사용하여 로컬 빌드를 대상으로 SDK와 플랫폼 변경을 테스트하라. 실수로 릴리스된 패키지를 테스트하지 않도록 참조 프로젝트를 워크스페이스 패키지에 연결하라. 다음 순서로 흐름을 실행하라: 1. 필요한 스토리지와 큐 서비스를 시작한다. 2. 데이터베이스 마이그레이션을 적용하고 참조 조직과 프로젝트를 시드한다. 3. SDK, 명령줄 도구, 영향을 받는 패키지를 빌드한다. 4. API 애플리케이션을 백그라운드에서 시작하고 상태 확인 엔드포인트를 검증한다. 5. 연결된 참조 프로젝트에서 로컬 작업 워커를 시작한다. 6. 명시적인 워커 준비 신호를 기다린다. 7. 지원되는 제어 인터페이스를 통해 대표 작업을 트리거한다. 8. 예상된 종료 상태가 나타날 때까지 실행을 폴링하거나 목록으로 확인한다. 9. 반환된 결과와 영속화된 실행 상태를 검사한다. 컴파일만으로 엔드 투 엔드 성공을 보고하지 마라. 명령 출력이나 실행 식별자를 증거로 보존하고 검증이 끝나면 백그라운드 프로세스를 중지하라. ## 멀티 플랫폼 컨테이너 이미지를 고정하고, 디버그 표시는 병합 전에 지워라 컨테이너 이미지를 아키텍처별 이미지 다이제스트가 아니라 멀티플랫폼 인덱스 다이제스트에 고정하라. 개발과 지속적 통합이 올바른 아키텍처를 해석하도록 이미지의 플랫폼 중립적 릴리스 페이지에서 다이제스트를 선택하라. 분산 흐름을 개발하는 동안 구조화된 디버그 단서를 사용하라: - 상태 전이, 큐 경계, 외부 호출에 마커를 추가한다. - 등록된 애플리케이션 네임스페이스만 사용하며, 승인 없이 새 네임스페이스를 만들지 않는다. - 버그를 재현하기 전에 기존 추적을 지운다. - 제한과 커서 페이지네이션을 사용해 쿼리한다. - 조사가 진행 중인 동안 임시 마커를 개발 브랜치에 유지한다. - 병합 전에 마커와 가져오기를 제거한다. 검토자는 브랜치에 있다는 이유만으로 인정된 임시 계측을 지적해서는 안 된다. 프로덕션에 도달할 수 없고 제거 단계가 완료 절차에 포함되어 있는지 검증해야 한다. ## 변경에 맞는 검사만 실행하고, 무엇을 생략했는지 보고하라 인계 전에 변경된 전체 파일 집합을 검사하고 해당하는 게이트만 실행하라: - 포매터, 린트 수정, 읽기 전용 린트. - 애플리케이션과 비공개 패키지의 타입 검사. - 게시 패키지의 실제 빌드. - 일회용 서비스 컨테이너를 사용하는 집중 테스트. - 올바른 경계의 패키지 변경 기록 또는 서버 노트. - 정확한 공유 종속성 고정 버전. - 라우팅이 변경된 경우 현재 엔진 및 폐기 버전 테스트. - 이미지 참조가 변경된 경우 멀티플랫폼 이미지 다이제스트. - SDK 또는 실행 동작이 변경된 경우 연결된 참조 프로젝트 실행. - 병합 전 임시 디버그 계측 제거. 무엇을 실행했고, 무엇이 통과했으며, 어떤 게이트를 어떤 이유로 의도적으로 생략했는지 보고하라. 관찰할 수 없는 약한 검사로 런타임, 패키지, 컨테이너의 정확성을 주장하지 마라.