큰 TypeScript 모노레포에 테스트를 거친 작은 변경 적용하기

## 편집 전에 저장소 구조와 사용하는 도구 파악하기 저장소의 표준 에이전트 가이드를 유일한 지침 출처로 취급하세요. 대체 에이전트 진입점은 간결한 참조로 유지하고, 아키텍처, 도구, 버전, 작업 절차 또는 기여자 규칙이 바뀌면 표준 가이드를 갱신하세요. 다음을 파악하세요. - 실제 저장소 루트, 주요 소스 영역, 빌드 스크립트 영역, 문서, 테스트 애플리케이션, 생성된 작업 공간 - 필수 기반 브랜치, 런타임 버전, 패키지 관리자, 작업 오케스트레이터, 린터, 포매터, CI 운영체제 - 공개 내보내기와 명시적으로 내부용인 내보내기의 구분 - 패키지별 타입 검사기와 저장소 검사, 편집기 도구, 하위 API 소비자 사이에 존재할 수 있는 컴파일러 버전 분리 공유 구성은 지원되는 모든 컴파일러 경로에서 유효하게 유지하세요. 최신 검사기가 허용한다는 이유만으로 옵션이나 구문을 채택하지 마세요. 모듈식 UI 도구에서는 런타임 렌더러, 번들링 엔진, 그리고 이 둘을 프레임워크 구성과 결합하는 프레임워크 통합을 구분하세요. 런타임 로드 전에 정적 인덱싱을 수행하는 방식처럼 빠른 시작을 위한 아키텍처를 유지하세요. 잘못된 사용자 모듈 하나 때문에 전체 탐색 또는 관리 인터페이스가 중단되어서는 안 됩니다. ## 변경에 필요한 빌드와 검사만 실행하기 문서화된 작업 디렉터리에서 명령을 실행하고, 작업 그래프를 지정할 때는 게시된 패키지 이름이 아니라 작업 공간의 프로젝트 이름을 사용하세요. 캐시를 활용하고 종속성을 고려하며 프로덕션용이 아닌 작업부터 시작하세요. 1. 영향을 받는 프로젝트 또는 패키지 집합을 컴파일합니다. 2. 범위를 한정한 타입 검사를 실행합니다. 3. 변경된 파일을 포맷하고 린트합니다. 4. 가장 직접적으로 관련된 테스트를 실행합니다. 5. 내부 개발 UI에서 동작을 검증합니다. 변경이 템플릿 통합, 프로덕션 작업 연결 또는 패키지 간 동작에 의존할 때만 프로덕션 구성, 생성된 샌드박스 또는 CI와 동등한 흐름으로 확대하세요. 검증된 후반 단계부터 의도적으로 재개하는 경우가 아니라면 작업 종속성을 준수하세요. 장시간 실행되는 개발 서버를 기본 동작으로 시작하지 마세요. 템플릿, 대상 또는 환경이 필요한 명령에는 해당 값을 명시적으로 제공해야 합니다. 생성된 샌드박스가 실패하면 빌드 아키텍처를 변경하기 전에 문서화된 내부 UI를 진단용 대안으로 사용하세요. ## 코드 종류에 맞는 테스트를 고르고 테스트끼리 영향 주지 않게 하기 동작에 맞는 테스트 형식을 선택하세요. - 렌더링된 컴포넌트는 접근성과 사용자 동작을 포함하여 같은 위치에 배치된 스토리와 상호작용 함수로 테스트합니다. - 순수 유틸리티, 훅, 렌더링하지 않는 모듈에는 단위 테스트를 사용합니다. - 외형에는 시각적 도구를 사용합니다. - 통합 계약에는 엔드투엔드, 스모크 또는 테스트 실행기 모음을 사용합니다. 비공개 구현 세부사항이 아니라 내보낸 동작과 관찰 가능한 부수 효과를 테스트하세요. 타입, 린트 규칙, 스토리 상호작용 또는 상위 수준 브라우저 테스트에서 이미 보장하는 내용을 중복해서 검사하지 마세요. 파일 시스템 코드에는 실제 임시 디렉터리나 모듈 전체 교체보다 메모리 내 파일 시스템을 우선하세요. 각 테스트 전에 가상 상태를 초기화하고, 필요한 파일 시스템 메서드만 리디렉션하며, 유용한 경우 가상 디스크 상태를 검증하세요. 테스트에서 암묵적 전역값을 직접 할당하지 마세요. 테스트 프레임워크가 추적하는 전역 스텁을 사용하고, 이전에 존재하지 않았던 키를 포함해 각 테스트 후에 복원하세요. 직접 할당하면 파일 간에 실행 순서에 따라 달라지는 누수가 발생합니다. 런타임 경로 유틸리티로 예상 경로를 정규화하여 Unix와 Windows 모두에서 파일 시스템 검사가 통과하도록 하세요. ## 가정을 먼저 확인하고 불필요한 추상화 더하지 않기 아키텍처의 근거로 삼기 전에 작은 일회성 검증으로 환경에 대한 가정을 확인하세요. 번들러, 메타데이터, 로더 또는 생성된 출력에 관한 검증되지 않은 믿음을 영구적인 주석이나 추상화로 만들지 마세요. 지속적으로 유효해야 하는 가정은 먼저 타입과 기존 린트 규칙으로 명시하세요. 정적 강제가 실용적이지 않다면 경계에 비용이 적은 런타임 어설션을 추가하여 위반이 발생 지점 가까이에서 실패하도록 하세요. 추측에 기반한 유연성보다 제거와 직접성을 우선하세요. 존재하지 않는 소비자를 위한 추상화, 대체 경로 또는 확장 지점을 추가하지 마세요. 주석은 유지보수 문서이지 조사 기록이 아닙니다. 지속되는 이유를 한두 문장으로 설명하고, 티켓 코드, 검증 이력, 바이트 비교 과정, 변경에 취약한 줄 번호 참조는 생략하세요. 보안에 민감한 경로와 레거시 마이그레이션에는 광범위한 극단 사례 검사를 적용하세요. 지원이 끝나면 제거할 수 있도록 호환성 코드의 범위를 명시적인 버전 구간으로 제한하세요. ## 생성된 파일은 함부로 바꾸지 않고 정해진 포맷·로깅 도구 사용하기 편집 후 저장소 포매터를 실행한 다음 변경된 파일을 린트하고 관련 테스트를 실행하세요. 구성된 도구를 사용하고, 폐기된 린터로 대체하거나 포매터가 담당하는 코드를 수동으로 포맷하지 마세요. 새 TypeScript 스크립트는 저장소의 현재 기본 실행 경로를 통해 실행하고, 그렇게 구성된 경우 TypeScript 가져오기에 명시적인 확장자를 사용하세요. 레거시 로더는 작업한 범위 안에서만 마이그레이션하세요. 일반적인 서버 및 클라이언트 코드에서는 프로젝트의 로깅 추상화를 사용하세요. 로거를 가져오는 것이 합리적이지 않은 독립 스크립트에서만 원시 콘솔 호출을 사용하세요. 생성된 파일의 우발적인 변경을 절대 커밋하지 마세요. 생성된 산출물은 같은 작업에서 의도적으로 변경한 소스의 결정론적 결과일 때만 변경할 수 있습니다. 그 외에는 그대로 두고 반복되는 생성기 드리프트를 보고하세요. 경로, 하위 프로세스, 테스트에서 Unix와 Windows를 모두 고려하세요. CI 플랫폼 범위를 선택적 정리가 아니라 호환성 요구사항으로 취급하세요. ## 컴파일 통과만으로 끝내지 않고 동작을 확인한 뒤 변경 마무리하기 일반적인 변경의 경우 다음 순서를 따르세요. 1. 필요한 경우에만 종속성을 설치합니다. 2. 관련 종속성 그래프를 컴파일합니다. 3. 일관성을 유지하는 가장 작은 편집을 수행합니다. 4. 영향을 받는 패키지를 다시 컴파일합니다. 5. 범위를 한정한 타입 검사, 포맷, 린트, 계약에 맞는 테스트를 실행합니다. 6. 내부 UI에서 검증합니다. 7. 직접적인 관련이 있을 때만 샌드박스 또는 프로덕션 동등성 검사를 추가합니다. 렌더러, 프레임워크, 빌더 또는 플러그인을 통합할 때는 이를 소유한 패키지를 편집하고, 먼저 프로덕션 모드 없이 컴파일한 다음, 이에 맞는 생성 애플리케이션과 관련 테스트 실행기 또는 엔드투엔드 흐름을 통해 테스트하세요. 빌드가 실패하면 메모리를 늘리거나 아키텍처를 변경하기 전에 종속성을 갱신하고 범위가 한정된 컴파일을 다시 시도하세요. 샌드박스 동작이 내부 UI와 다를 때는 생성된 출력과 캐시를 검사하세요. 컴파일만으로 준비 완료를 주장하지 마세요. 필요한 증거는 변경된 패키지 경계, 지원되는 컴파일러 경로, 관찰 가능한 동작, 플랫폼 간 가정, 직접 영향을 받는 통합 흐름을 포괄하는 최소 집합입니다.