상태를 가진 UI 라이브러리를 기존 사용자를 깨뜨리지 않고 조금씩 고치기

## 상태의 주인을 찾고 라이브러리가 허용하는 곳에서만 상태 바꾸기 먼저 요청의 영향을 받는 상태 소유자, 업데이트 경계, 공개 계약을 찾는다. 불변 상태 모델에서는 일관된 스냅샷을 통해 읽고, 라이브러리가 허용한 업데이트 컨텍스트 안에서만 변경한다. 노드나 엔터티 핸들은 버전이 있는 참조로 취급하고, 업데이트 경계를 넘어 변경 가능성에 관한 가정을 유지하지 않는다. 기능 등록, 명령, 변환, 리스너는 문서화된 수명 주기 안에 둔다. 새 작업에는 현재의 확장 또는 조합 메커니즘을 우선하되, 지원되는 기존 통합 경로도 유지한다. 모든 등록에는 명확한 정리 경로가 있어야 하며, 기존 사용자가 계속 불러올 수 있는 직렬화 형식을 보존한다. ## 문법을 이해하는 검색으로 찾고 변경을 작게 유지하기 변경이 import, 호출 위치, 타입 주석, 구조화된 코드와 관련되면 구문을 인식하는 검색과 재작성을 사용한다. 줄 단위 정규식은 여러 줄 형식을 놓치거나 관련 없는 식별자와 일치할 수 있다. 광범위한 재작성을 적용하기 전에 구문 트리에서 후보 일치를 확인한다. 변경은 대상 동작에 맞추고 국소적으로 유지한다. 도메인에 맞는 이름, 유효하지 않거나 이미 처리된 상태를 위한 가드 절, 분명한 성공 경로를 사용한다. 도우미가 책임을 명명하거나 호출부를 단순화할 때만 추출한다. 최종 패치에 기회성 리팩터링, 디버그 로그, 임시 이름, 관련 없는 서식 변경을 섞지 않는다. 부작용이 없는 팩토리를 모듈 범위에 만들 때는 프로젝트의 트리 셰이킹 주석 규칙을 유지하고, 팩토리 계열 자체가 확장되면 그 규칙을 강제하는 규정도 업데이트한다. ## 공개 API 호환성을 지키고 요소 자신의 document와 window 쓰기 외부 코드는 기존 공개 이름, 시그니처, 동작, 직렬화된 데이터에 의존한다고 가정한다. 추가형 API와 선택적 매개변수를 우선한다. 호환성을 깨는 변경이 불가피하면 이전 경로를 제거하기 전에 유지하면서 사용 중단 예정으로 표시하고, 현재 경로와 호환 경로를 모두 검증한다. API가 건드리는 모든 지원 대상 타입 시스템과 생성된 선언 표면을 유지한다. 브라우저용 코드는 주변 전역 객체에 의존하지 말고 관련 루트나 요소에서 이를 소유한 document와 window를 가져와야 한다. 실행 영역을 인식하는 선택, 포커스, 이벤트 대상, 부모 탐색 도우미를 사용해 섀도 루트와 내장 문서가 잘못된 환경에서 조용히 읽지 않도록 한다. 직렬화, 요청 처리, URL, HTML 또는 스크립트 출력, 파일 시스템 경로, 인증, 의존성 변경에서는 신뢰할 수 없는 입력과 가장 가까운 검증 가드를 식별한다. 실패 시 차단하는 동작을 우선하고, 로그와 산출물에 비밀 정보를 남기지 않으며, 모든 프로토콜의 작성 측과 읽기 측을 모두 검증한다. ## 먼저 실패하는 테스트를 쓰고 단위 테스트와 실제 브라우저 테스트 중에서 고르기 동작 변경이나 버그 수정에서는 먼저 관찰 가능한 불변 조건을 정의한다. 가장 가까운 범위의 집중 테스트를 추가하거나 업데이트하고, 가능하면 구현 전에 실행하여 예상한 이유로 실패하는지 확인한다. 그 조건을 만족하는 최소 변경을 적용하고 집중 테스트를 다시 실행한 뒤, 변경된 표면에 필요한 검증으로만 범위를 넓힌다. 실제 레이아웃이나 선택 동작에 의존하지 않는 로직에는 모의 환경 단위 테스트를 사용한다. 레이아웃, 선택, 포커스, 섀도 루트, 문서 간 동작에는 실제 브라우저 테스트를 사용한다. 엔드투엔드 테스트는 탐색, 전체 애플리케이션 통합, 실행 중인 시스템이 필요한 프로토콜에만 사용한다. 결과를 신뢰하기 전에 테스트가 사용하는 특정 산출물을 빌드한다. 이유 없이 집중 테스트를 저장소 전체의 광범위한 명령으로 대체하지 않는다. 관련 없는 테스트 모음의 통과는 변경된 경계를 증명하지 못한다. ## 끝내기 전에 변경 차이를 확인하고 릴리스 노트 추가하기 마치 새로 참여한 기여자인 것처럼 완료 전에 변경 차이를 검토한다. 이름이 도메인 의미를 드러내는지, 경계 사례에 명시적 가드가 있는지, 주요 경로를 읽기 쉬운지, 정리가 완료되었는지, 공개 계약이 의도치 않게 바뀌지 않았는지 확인한다. 영향을 받는 패키지가 요구하는 포매터, 린터, 타입 검사기, API 스냅샷 작업을 실행한다. 공개된 동작이 바뀌면 저장소에서 요구하는 릴리스 노트나 변경 기록을 추가한다. 구현 방식이 아니라 사용자가 체감하는 수정 사항이나 기능을 설명한다. 커밋과 풀 리퀘스트 문구에 비공개 세션 링크, 자격 증명, 내부 전용 참조를 넣지 말고, 변경을 뒷받침하는 집중 테스트 근거를 기록한다.