패키지가 많은 대규모 모노레포에서 코드를 고치고 테스트하기

## 편집 전에 패키지와 진입점 위치 찾기 - 작업 공간 레이아웃, 게시된 패키지, 네이티브 구성 요소, 테스트 스위트, 예제, 문서, 유지 관리 스크립트를 식별한다. - 기본 패키지의 소스 트리, 컴파일된 결과물, 명령줄 진입점, 서버 진입점, 빌드 진입점의 위치를 찾는다. - 동작을 변경하기 전에 관련 진입점을 추적하고, 파일 이름만 보고 소유 범위를 추론하지 않는다. - 중첩된 파일을 편집하기 전에 저장소 루트부터 대상 디렉터리까지 적용되는 모든 `README.md`를 읽는다. - 생성된 결과물과 종속성 디렉터리는 검색 전용 증거로 취급한다. 생성 파일을 직접 편집하지 말고 그 소스나 생성기를 변경한다. ## 빌드 결과물을 최신으로 두고 부분 빌드와 전체 빌드 중 고르기 - 브랜치를 전환하거나 상태가 불확실한 작업 공간을 부트스트랩한 뒤에는 전체 부트스트랩 빌드를 실행하여 종속 패키지 결과물을 최신 상태로 만든다. - 소스 또는 통합 테스트를 반복적으로 작업할 때는 패키지의 감시 빌드가 이미 실행 중인 경우를 제외하고 편집 전에 시작한다. - 문서만 변경하거나, 읽기 전용으로 조사하거나, CI만 분석하는 경우에는 감시 모드를 생략할 수 있지만 그 이유를 기록한다. - 변경이 하나의 패키지 안에 머물면 해당 패키지에 집중한 빌드를 사용한다. 작업이 여러 패키지에 걸치거나 네이티브 코드를 변경하면 전체 빌드를 사용한다. - 타입 오류의 경우 전용 타입 검사가 동등한 증거를 제공한다면 전체 빌드보다 이를 우선한다. - 작업 완료 후 자신이 시작한 모든 감시 프로세스를 중지한다. ## 개발 모드와 프로덕션 모드에 맞는 테스트 고르기 - 개발 또는 프로덕션 동작과 의도한 번들러 또는 런타임 구현에 정확히 일치하는 테스트 명령을 선택한다. - 통합 테스트를 실행하기 전에 영향을 받는 소스를 다시 빌드한다. 오래된 컴파일 결과물은 결과를 무효로 만든다. - 먼저 가장 좁은 범위의 관련 테스트 파일 또는 이름 패턴을 실행한 뒤, 실패 내용이나 변경 영향 범위가 요구할 때만 확대한다. - 동일한 명령, 모드, 기능 플래그, 환경 변수 이름으로 CI를 재현한다. 작은 모드 차이도 해석 결과와 스냅샷을 바꿀 수 있다. - 주장에 패키지 해석, 번들링, 시작 또는 브라우저 동작이 포함된다면 편리한 단위 테스트로 통합 테스트를 대신하지 않는다. - 기능 플래그가 동작을 암묵적으로 활성화하는 경우, 기존 전용 스위트에만 의존하지 말고 해당 플래그를 사용해 일반 스위트를 테스트한다. ## 고정 대기 대신 조건을 기다리는 테스트 작성하기 - 픽스처와 하네스 구성이 로컬 규칙을 따르도록 비대화형 인수를 포함하여 저장소의 테스트 생성기를 사용한다. - 고정된 대기보다 어설션을 포함한 조건 기반 재시도 헬퍼를 우선한다. 고정 지연은 느리고 여전히 경쟁 조건에 취약하다. - 사용 중단된 폴링 헬퍼를 지원되는 재시도 및 어설션 패턴으로 교체한다. - 테스트가 실제 프로젝트와 비슷하고 유지 관리하기 쉽도록 대규모 인라인 파일 맵보다 실제 픽스처 디렉터리를 우선한다. - 모드별 테스트에서는 하네스가 지연 시작을 요구할 경우 서버를 수동으로 시작하기 전에 모드 가드를 실행한다. - 테스트의 동기화 경계 안에서 프리페치와 탐색 상태를 제어하고, 캐시된 상태를 복원하여 통제되지 않는 작업을 유발하는 기록 작업은 피한다. ## 테스트와 빌드 결과를 저장하고 같은 실행을 반복하지 않기 - 테스트 또는 빌드의 전체 결과를 한 번만 캡처한 뒤, 다른 필터로 같은 스위트를 다시 실행하지 말고 저장한 결과를 검색하고 요약한다. - 약 500줄보다 큰 파일은 먼저 관련 기호를 검색하고 그 주변 범위만 읽는다. - 생성 디렉터리는 생성된 동작을 확인하는 데 필요한 경우에만 검색하고, 기본 소스로 탐색하지 않는다. - 다음 빌드를 실행하기 전에 관련 편집을 일괄 처리하고, 현재 가설을 입증하는 가장 빠른 검사를 사용한다. - 한 번의 조사 중에는 원격 상태 응답을 캐시하고, 반복해서 가져오지 말고 저장한 응답을 여러 관점에서 분석한다. - 정확한 실패 결과, 명령, 모드, 환경을 다음 진단 단계의 증거로 보존한다. ## CI 실패를 같은 조건으로 재현하고 검토 댓글보다 먼저 고치기 - 저장소에 상태 분석 도구가 있으면 이를 사용하고, 현재 브랜치와 명시적인 변경 요청 중 무엇을 조사하는지 식별한다. - 증거가 다른 순서를 요구하지 않는 한 빌드, 포맷팅 또는 lint, 타입, 테스트 순으로 차단 실패를 처리한다. - 반증될 때까지 실패를 실제 문제로 취급한다. 알려진 불안정 동작은 조사 맥락일 뿐, 실패를 무시해도 된다는 허가는 아니다. - 특히 서로 다른 번들러나 런타임 경로를 사용할 수 있다면 동일한 CI 모드와 환경 플래그로 재현한다. - 모듈 해석 또는 빌드 그래프 실패에서는 실제 패키지 그래프가 실행되도록 일반적인 모드별 통합 명령을 실행한다. - CI 실패와 검토 의견을 분리하고, 실행을 차단하는 증거를 먼저 해결하며, 재현한 내용을 간결하게 기록해 둔다. ## 기능 플래그를 빌드와 런타임 양쪽에 연결하기 - 사용자가 번들링하는 코드에서 새 기능 플래그를 사용하는 경우 그 공개 타입, 검증 스키마, 빌드 시 주입 지점에 플래그를 추가한다. - 미리 컴파일된 런타임 코드가 플래그를 사용하는 경우 관련된 각 서버 또는 워커 경로에도 런타임 값을 연결한다. - 사용자 코드용 빌드 시 주입이 미리 컴파일된 런타임 내부까지 제어한다고 가정하지 않는다. - 조건부 모듈 로드를 컴파일 시점의 `if` / `else` 분기 안에 두어 데드 코드 제거가 도달할 수 없는 종속성을 제거할 수 있게 한다. - 제한된 런타임에서는 지원되지 않는 플랫폼 가져오기를 보호하는 플래그를 `false`로 강제한다. - 런타임별 가져오기는 지정된 진입 모듈에 두고 필요한 동작은 해당 모듈의 공개 파사드를 통해 제공한다. - 전용 런타임 신호를 사용하여 실행 중인 개발 서버와 디버그 빌드를 구분한다. 일반적인 환경 레이블은 둘 다 나타낼 수 있다. - 진입 계층에서 제거하거나 인증하는 경우를 제외하고, 새로 추가하는 비표준 수신 요청 헤더는 모두 보안 검토 대상으로 표시한다. ## 시크릿을 로그에 남기지 않고 인증이 실패하면 멈추기 - 문서화된 테스트 모드 플래그가 아닌 한 환경 변수 값은 민감한 정보로 취급한다. - 토큰, 키, 쿠키, 시크릿 값을 공유 로그, 검토 문서 또는 예제에 절대 출력하거나 붙여 넣거나 커밋하거나 배치하지 않는다. - 값을 인라인으로 넣지 말고 CI 변수 이름과 모드를 그대로 맞춘다. 필요한 시크릿이 없다면 중지하고 승인된 경로를 통해 요청한다. - 설정을 문서화할 때는 자리표시자를 사용하고 로컬 시크릿 파일은 절대 커밋하지 않는다. - 서명 에이전트, 키 공급자 또는 하드웨어 기반 자격 증명을 사용할 수 없어 소스 제어 인증에 실패하면 중지하고 사용자에게 잠금 해제를 요청한다. - 명시적인 승인 없이는 원격 프로토콜이나 주소를 변경하거나, 실패한 작업을 반복하거나, 다른 인증 우회 방법을 시도하지 않는다. ## 변경 요청이나 댓글을 올리기 전에 권한 확인하기 - 원격 변경 요청, 이슈, 토론 또는 댓글을 만들거나 편집하기 전에 기여가 내부 브랜치에서 왔는지 외부 포크에서 왔는지 확인한다. - 사용자를 대신해 작성하기 전에 저장소의 기여 정책과 사용자 권한을 확인한다. - 권한이 충분하지 않다면 유지 관리자를 사칭하거나 원격에 전체 내용을 게시하지 않는다. 기술적 사실을 제공하고, 사용자가 작성한 글을 검토하며, 사용자가 통제하는 제출 경로를 안내한다. - 문서화된 예외는 조건을 확인한 후 좁은 범위에서만 적용한다. - 사용자가 검토할 준비가 되었다고 명시적으로 결정하지 않는 한 새로 만든 변경 요청을 초안 상태로 유지한다. - 원격 쓰기에는 명시적인 범위가 필요하며, 로컬 분석과 재현이 게시 권한을 뜻하지는 않는다. ## 작업을 작게 나누고 단계마다 확인하기 - 큰 작업을 결과를 독립적으로 확인할 수 있는 작은 단계로 나눈다. - 다음 단계로 넘어가기 전에 위험에 맞는 방법, 즉 검사, 포맷팅, lint, 타입, 단위 테스트, 통합 테스트, 빌드 또는 런타임 관찰로 각 단계를 검증한다. - 올바른 검증 방법이 명확하지 않다면 단계가 완료되었다고 주장하기 전에 묻는다. - 커밋 전에 변경한 파일에 저장소의 커밋 훅과 동일한 포매터 및 린터 구성을 실행한다. - 최종 diff를 검토하여 관련 없는 편집, 생성 잡음, 시크릿 자료, 누락된 테스트 또는 문서가 있는지 확인한다. - 변경된 동작을 뒷받침하는 증거를 명시하지 않고 완료를 보고하지 않는다. ## 오래된 네이티브 바이너리와 맞지 않는 스냅샷 찾기 - 소스 맵 조회에는 명시적인 런타임 플래그가 필요할 수 있고 컴파일러마다 소스 경로가 다를 수 있으므로 알려진 경로 형식을 테스트한다. - 테스트와 프로덕션의 스택 추적을 비교할 때 현재 작업 디렉터리를 고려한다. - 브랜치 변경 후 동작이 소스와 모순되면 오래된 네이티브 바이너리를 의심하고, 승인된 부트스트랩 경로를 통해 종속성이 관리하는 산출물을 갱신한다. - 내부 컴파일러 오류에서는 영향을 받은 증분 컴파일 캐시만 제거하고 상위 단계로 올리기 전에 한 번만 다시 시도한다. - 네이티브 언어 코드에는 공식 포매터를 사용하고, 엄격히 범위가 한정된 인라인 테스트 모듈 안을 제외하면 저장소 루트를 기준으로 한 가져오기를 우선한다. - 스냅샷 결과는 플래그와 런타임 구현에 따라 달라질 수 있으므로 대상 CI 작업에서 사용한 정확한 환경에서만 스냅샷을 갱신한다. - 문서 코드 블록에서는 편집 후 표시된 줄 수를 다시 세고 모든 강조 표시가 의도한 명령문을 가리키는지 확인한다.