대규모 타입 모노레포를 수정하되 다른 패키지는 망가뜨리지 않기

## 수정 전에 변경을 맡은 패키지 찾기 저장소 루트에서 시작하여 요청된 동작을 담당하는 패키지를 식별하세요. - 핵심 라이브러리, 프레임워크 통합, 배포 가능한 애플리케이션, 예제, 내부 도구를 구분하세요. - 루트 가이드와 가장 가까운 패키지 수준 가이드를 읽으세요. 더 구체적인 가이드가 패키지 동작을 규정합니다. - 개발 명령을 실행하기 전에 고정된 런타임, 패키지 관리자, 작업 공간 구조, 선행 빌드를 확인하세요. - 루트 개발 서버가 있다고 가정하지 마세요. 담당 패키지를 시작하거나 그 패키지의 상위 종속성을 포함하는 작업 공간 필터를 사용하세요. - 소비자를 변경하기 전에 공유 타입, 유틸리티, 스타일, 생성된 자산을 각각의 표준 패키지까지 추적하세요. - 공개 계약이 실제로 여러 패키지에 걸치는 경우가 아니라면 변경을 가장 작은 담당 패키지 안에 유지하세요. ## 패키지마다 빌드와 종속성 규칙 지키기 작업 공간 전체에 하나의 도구를 강제하지 말고 패키지에 맞는 빌드 경로를 선택하세요. - 순수 타입 라이브러리에는 컴파일러 중심 빌드를 사용하고, UI 패키지에는 컴포넌트 번들러를 사용하세요. - 라이브러리 출력에서는 종속성을 외부화하세요. 결과물에 런타임 종속성을 묶어야 하는 경우에만 명시적인 독립 실행형 빌드를 사용하세요. - 내부 종속성에는 작업 공간 프로토콜을 유지하고, 공유하는 타사 버전은 중앙 버전 카탈로그에서 가져오세요. - 공유 타입은 광범위한 패키지 루트가 아니라 문서화된 진입점에서 가져오세요. - 패키지가 여러 형식을 게시하면 선언된 각 출력과 해당 타입 선언을 검증하세요. - 빌드 구성, 잠금 파일, 공유 컴파일러 설정, 작업 공간 카탈로그는 더 넓은 검증이 필요한 광범위 영향 파일로 취급하세요. ## 새 코드를 쓰기 전에 공유 유틸리티 재사용하기 새 유틸리티를 작성하기 전에 공유 헬퍼 패키지를 검색하세요. 기존 배열, 객체, 문자열, URL, HTTP, JSON, Markdown, 오류, 파일, 큐, 포맷, 정규식, 테스트 헬퍼를 확인하세요. 적합한 헬퍼는 그대로 재사용하세요. 기존 동작 중 일치하는 것이 없고 여러 소비자가 새 추상화를 사용할 수 있을 때만 공유 패키지에 새 헬퍼를 추가하세요. 기능 패키지에 거의 같은 구현을 만들지 마세요. 기존 동작이 비슷하지만 정확히 일치하지 않는다면, 이를 확장할지 아니면 로컬 도메인 전용 함수를 유지할지 결정하기 전에 계약, 경계 사례, 번들 영향, 호출 위치를 비교하세요. ## `any` 대신 함수와 컴포넌트 props에 타입 지정하기 타입 추론의 유용성을 유지하면서 공개 계약을 명시하는 코드를 작성하세요. - 코드베이스 표준이 그렇게 정한 경우 인터페이스와 열거형보다 타입 별칭과 문자열 리터럴 유니온을 우선하세요. - 함수에 명시적인 반환 타입을 지정하고, `any` 대신 `unknown`을 사용하며, 타입 전용 가져오기를 표시하고, 기본적으로 불변 바인딩을 사용하세요. - 직접 가져오기를 유지하세요. 의도적으로 만든 패키지 진입점을 제외하고 barrel 파일을 피하며, 와일드카드 재내보내기도 피하세요. - 타입 오류를 포괄적으로 숨기지 마세요. 오류가 의도적임을 입증하는 이유가 있을 때만 예상 오류 지시문을 사용하세요. - 모든 Promise를 처리하고, 어떤 작업을 기다리지 않는 함수는 비동기로 표시하지 마세요. - 컴포넌트 파일에서는 속성과 이벤트에 타입을 지정하고, 구조 분해로 기본값을 설정하며, 복잡한 템플릿 로직을 계산값으로 옮기고, 정해진 설정 순서를 따르세요. - 주석과 API 문서는 코드를 되풀이하지 말고 제약이 존재하는 이유를 설명하도록 작성하세요. ## 저장소 전체가 아니라 영향받는 패키지부터 테스트하기 변경을 입증하는 가장 작은 테스트 범위를 실행하세요. 1. 단위 테스트를 소스 옆에 배치하고 최상위 테스트 모음의 이름을 파일에 맞춥니다. 2. 동작 단언과 순수 함수를 우선하세요. 모의 객체 사용을 최소화하고, 사용자 동작이 계약일 때는 마크업 구조나 스타일 세부사항을 테스트하지 마세요. 3. 명시적인 경로 필터를 사용하여 영향받는 패키지를 한 번 실행하세요. 감시 모드는 개발을 진행 중일 때만 사용하세요. 4. 변경된 어댑터에는 통합 테스트를, 영향받는 사용자 여정에는 엔드투엔드 테스트를 실행하세요. 5. 필요한 로컬 테스트 서비스를 시작하고 서비스 의존 테스트 전에 준비 완료를 기다리세요. 단위 테스트는 실제 네트워크를 사용해서는 안 됩니다. 6. 전체 모노레포 테스트 모음은 의도적인 최종 통합 검사 또는 광범위한 공유 계약 변경에만 실행하세요. 관련 없는 기존 실패는 별도로 처리하세요. 변경 범위 밖에서 재현하고 그 사실대로 보고하며, 환경 성공이나 변경으로 인한 실패라고 잘못 표시하지 마세요. ## 변경한 파일은 lint, 영향받는 패키지는 타입 검사하기 변경된 파일 집합을 도출하고 각 도구를 담당 구문에만 적용하세요. - 변경된 타입 언어 파일에 해당 언어의 린터와 포매터를 실행하세요. - 변경된 컴포넌트, 문서, 데이터, 스타일, 구성 파일에 컴포넌트 린터와 범용 포매터를 실행하세요. - 각 작업 공간 스크립트를 통해 영향받는 모든 패키지를 타입 검사하세요. - 검토를 열거나 갱신하기 전에 사용하지 않는 내보내기, 파일, 종속성을 검색하세요. - 관련된 모든 린트, 포맷, 타입, 테스트, 미사용 코드 검사가 오류 없이 통과하도록 요구하세요. 패키지 필터가 관련 없는 잡음을 줄이면서 더 강한 신호를 제공한다면 저장소 전체 명령을 사용하지 마세요. 기반 구성이 변경되거나 종속성 분석에서 여러 하위 소비자가 확인되면 검증 범위를 넓히세요. ## 리뷰 제목을 type(scope) 형식으로 쓰고 changeset 추가하기 전용 브랜치를 사용하고 관련 패키지 범위를 포함하여 관례에 맞는 현재형 변경 설명을 작성하세요. - 허용된 변경 유형을 사용하여 검토 제목을 시맨틱 형식 `type(scope): subject`로 작성하세요. - 올바른 종료 또는 비종료 키워드와 함께 티켓 및 이슈 참조를 검토 설명에 넣으세요. 필수 추적 식별자를 주석 속에 묻어 두지 마세요. - 추적 링크가 제공되면 전용 티켓 섹션을 추가하세요. - 게시 가능한 패키지, 통합 또는 애플리케이션 변경은 릴리스 노트 상태를 확인하고 버전을 올려야 할 때 patch 또는 minor 변경 세트를 추가하세요. 일반 작업 절차로 major 버전 상승을 도입하지 마세요. - 임시 우회 방법은 TODO로 드러나게 유지하고 제거 조건을 설명하세요. - 알려진 린트, 타입, 테스트 또는 미사용 내보내기 실패가 있는 변경을 절대 커밋하지 마세요. ## 변경이 보이는 시험 환경과 스크린샷으로 UI 변경 확인하기 상위 패키지를 빌드한 다음, 변경된 동작을 가장 직접적으로 드러내는 시험 환경을 선택하세요. - 기본 컨트롤에는 컴포넌트 카탈로그를, 렌더링과 탐색에는 문서 화면을, 편집, 인증, 요청, 응답에는 클라이언트 화면을 사용하세요. - 공유 컴포넌트, 테마, 구문 렌더링 또는 아이콘이 여러 제품에 반영될 때는 보조 화면도 확인하세요. - 수정된 UI에는 변경 전후 스크린샷을, 새 동작에는 맥락이 포함된 스크린샷을, 상호작용에는 짧은 녹화를 남기세요. - 결과물에 내용을 설명하는 이름을 붙이고 검토 설명의 전용 시각 자료 섹션에 증거를 삽입하세요. - 변경이 여러 화면이나 레이아웃에 영향을 미치면 스크린샷 한 장을 보편적인 증거로 간주하지 말고 실질적으로 다른 결과를 각각 기록하세요. 시각적 결과물은 자동화 테스트를 보완할 뿐, 동작 단언, 접근성 검사, 타입 검증을 대체하지 않습니다. ## 프로젝트 용어를 정확히 쓰고 실제로 실행한 검사만 보고하기 코드, 문서, 테스트, 검토 문구에서 프로젝트 용어집을 일관되게 사용하세요. 프로토콜 형식과 API 설명, 데이터 스키마와 문서, 역참조와 해석을 각각 구분하고, 번들링도 마지막 두 작업과 구분하세요. 완료 전에 다음을 수행하세요. - 최종 차이를 검토하고 변경된 모든 파일이 의도한 범위에 속하는지 확인하세요. - 해당되는 빌드, 테스트, 린트, 포맷, 타입, 미사용 코드 검색, 시각적 증거를 검증하세요. - 패키지 진입점, 종속성 카탈로그, 변경 세트가 구현과 일치하는지 확인하세요. - 실행할 수 없었던 검사를 나열하고 정확한 실패 증거를 보존하세요. - 패키지 범위 검사만 실행했다면 전체 모노레포 결과라고 주장하지 마세요. 영향받는 패키지, 실행한 명령, 직접적인 결과, 남은 위험, 의도적으로 연기한 작업을 보고하세요.