여러 구현이 있는 모노레포를 구현끼리 동작을 맞춘 채로 고치기

## 고치기 전에 모노레포 구조와 해당 위치의 규칙 읽기 - 제품, 언어, 기능 영역, 공유 유틸리티 영역, 테스트 모음, 릴리스 도구, 설정을 기준으로 저장소를 매핑한다. - 각 구현에 속한 디렉터리와 저장소 전체에 적용되는 최상위 규칙을 식별한다. - 중첩된 영역을 편집하기 전에 해당 영역의 에이전트 가이드, 기여 가이드, 설정을 읽는다. 지역 규칙은 기준을 구체화할 수 있지만 약화해서는 안 된다. - 언어별 빌드, 스타일, 테스트 규칙은 해당 언어로 작성된 코드에만 적용한다. - 명령이나 의존성을 선택하기 전에 작업 공간 정의, 루트 스크립트, 제품별 지침을 찾는다. ## 사용자에게 보이는 변경을 모든 구현에 똑같이 넣기 - 동일한 사용자 대상 제품의 병렬 구현을 동등한 단일 진실 공급원으로 취급한다. - 가능하다면 사용자가 볼 수 있는 모든 변경을 동일한 변경 요청 안에서 모든 구현에 반영한다. - 사용자에게 보이는 동작에는 플래그, 기본값, 환경 처리, 오류 코드와 메시지, 도구가 사용하는 로그, 파일 및 상태 형식, 저장소 배치, 훅 의미가 포함된다. - 내부 리팩터링, 특정 구현만의 성능 작업, 구현별 테스트 정리는 억지로 다른 구현에 반영할 필요가 없다. - 동등한 작업을 즉시 완료할 수 없다면 남은 동등성 차이, 그 이유, 변경을 병합하기 전에 완료해야 할 작업을 정확히 밝힌다. - 한 구현이 다른 구현의 문서화되지 않은 하위 이식판이 되게 해서는 안 된다. ## 오래된 코드를 테스트하지 않도록 테스트가 실행하는 산출물 다시 빌드 - 테스트 결과를 신뢰하기 전에 저장소에 문서화된 초기 설정 경로를 통해 의존성을 설치하고 컴파일한다. - 선택한 테스트가 사용하는 것과 동일한 산출물을 생성하는 경우에는 빠른 반복 중에 영향을 받는 패키지만 컴파일한다. - 종단 간 테스트가 소스 산출물, 패키지 산출물, 번들된 실행 파일 중 무엇을 실행하는지 확인한다. - 종단 간 테스트가 번들을 사용한다면 구성 패키지가 변경될 때마다 번들을 다시 빌드한다. 그렇지 않으면 테스트가 오래된 코드를 실행할 수 있다. - 변경된 각 구현에 적합한 언어별 빌드를 실행한다. - 오래된 생성 결과를 대상으로 통과한 테스트는 유효한 증거로 취급하지 않는다. ## 영향받는 부분만 테스트하고 모든 실패 조사 - 기본적으로 대규모 저장소의 전체 테스트 모음을 실행하지 않는다. 영향을 받는 프로젝트, 파일 또는 이름이 지정된 테스트 사례부터 시작한다. - 의존성, 공유 계약 또는 관찰된 실패가 필요성을 뒷받침할 때만 테스트 범위를 확장한다. - 검증하려는 주장에 맞춰 런타임, 빌드 산출물, 테스트 대상 구현을 선택한다. - 증거 없이 무관하거나 기존에 있던 문제라고 표시하지 말고 모든 실패를 조사한다. - 변경 전부터 실패했다면 원인을 식별하고 허가된 범위에서 수정하거나 구체적인 장애를 보고한다. 조용히 건너뛰어서는 안 된다. - 정확한 명령, 영향을 받는 대상, 결과를 기록하여 다른 기여자가 증거를 재현할 수 있게 한다. ## 변경된 코드를 보안 먼저, 그다음 성능 순으로 검토 - 저장소의 검토 가이드를 따르고 발견 사항을 변경의 영향을 받은 코드와 직접적인 결과로 제한한다. - 더 엄격한 프로젝트 규칙이 없다면 보안을 먼저, 성능을 다음으로 검토한다. - 보안 발견 사항에는 도달 가능한 입력, 신뢰 경계, 악용 경로, 영향을 설명한다. - 성능 발견 사항에는 부하가 높은 경로, 빈도, 할당 또는 I/O 비용, 예상 사용자 영향을 밝힌다. - 승인 과정의 일부로 테스트, 릴리스 의도, 구현 간 동등성을 검증한다. - 변경된 동작과 연결할 수 없는 추측성 발견 사항을 만들지 않는다. ## 코드나 의존성을 추가하기 전에 기존 것 찾기 - 사소하지 않은 로직을 구현하기 전에 공유 패키지, 파일 시스템 도우미, 암호화 유틸리티, 텍스트 유틸리티, 인접 영역 모듈을 검색한다. - 기존에 공개된 유틸리티가 이미 해당 동작을 소유한다면 재사용한다. - 유사한 로직이 특정 패키지에 갇혀 있다면 복사하지 말고 공통 계약을 가장 좁고 적절한 공유 위치로 추출한다. - 일반 기능에는 적합하고 충분히 가벼우며 저장소 정책에서 허용하는 경우 유지관리되는 기존 의존성을 우선한다. - 새 의존성은 이를 필요로 하는 가장 구체적인 패키지에 추가하고, 여러 패키지가 실제로 공유할 때만 상위로 옮긴다. - 계약을 추가하지 않고 기존 작업의 이름만 바꾸거나 전달하는 래퍼를 추가해서는 안 된다. ## 커밋 메시지 규칙을 지키고 커밋 훅을 우회하지 않기 - 저장소가 요구하는 커밋 메시지 규칙을 사용하고 사용자 영향을 반영하는 변경 유형을 선택한다. - 커밋하기 전에 저장소 훅이 설치되어 활성화되었는지 확인한다. 새 작업 복사본에는 아직 등록되지 않았을 수 있다. - 실패한 커밋 보호 검사를 우회하거나, 훅을 비활성화하거나, 억제 파일을 추가해서는 안 된다. 근본적인 메시지 또는 변경을 수정한다. - 호스팅 플랫폼이 잘못된 저장소로 연결할 수 있으므로 숫자만 있는 문제 참조를 피한다. 저장소가 포함된 참조나 절대 URL을 사용한다. - 사용자 이름처럼 보이는 코드 식별자는 인라인 코드로 감싸거나 불필요한 언급을 제거하여 커밋이 관련 없는 사람에게 알림을 보내지 않게 한다. - 항목을 열거할 때는 참조 표시가 없는 목록 번호를 사용한다. ## 공개된 패키지를 바꾸면 릴리스 항목 추가 - 변경이 공개된 패키지에 영향을 줄 때마다 릴리스 의도 항목을 추가한다. - 영향을 받는 모든 패키지를 명시하고 버전 영향을 결함 수정, 하위 호환 기능, 호환성을 깨는 변경 중에서 선택한다. - 항목은 사용자를 위해 간결하게 작성하고 구현 근거는 커밋 메시지에 둔다. - 저장소 정책이 요구하면 주요 구현 변경에 기본 명령줄 패키지도 포함한다. - 구현별 변경에서는 실제로 변경된 제품만 명시한다. 동등성 변경은 영향을 받는 모든 구현의 패키지를 명시해야 한다. - 안정 및 사전 릴리스 경로, 고정 버전 그룹, 저장소의 정식 승격 절차를 준수한다. ## 코드만으로 알 수 없는 이유만 주석으로 쓰기 - 코드가 스스로 설명할 수 있도록 이름, 타입, 도우미 경계, 제어 흐름을 우선한다. - 작업을 다시 설명하거나, 호출 대상 문서를 중복하거나, 명백한 구문을 서술하는 주석을 추가해서는 안 된다. - 공유 이유는 각 호출 위치에서 반복하지 말고 공통 소유자에게 한 번만 문서화한다. - 사전 조건, 사후 조건, 경계 사례, 명확하지 않은 보장에는 문서 주석을 사용한다. - 리팩터링 이력과 제거된 설계 설명은 현재 소스 주석이 아니라 버전 관리 이력과 변경 메시지에 보관한다. - 설명을 추가하기 전에 이름 변경, 구조 변경, 추출이 개념을 더 확실하게 전달할 수 있는지 검토한다. ## 저장소의 서식과 오류 처리 규칙 따르기 - 저장소 포매터와 언어별 스타일 가이드를 사용하고 기존 가져오기 분류와 순서를 유지한다. - 코드베이스의 관례가 그렇다면 상태를 가진 클래스보다 함수를 우선하고, 긴 매개변수 목록은 타입이 지정된 옵션 객체로 바꾼다. - 사용자가 도달할 수 있는 실패에는 안정적인 영역 오류 타입을 사용하고, 오류 코드를 보존하고, 관련 맥락을 포함하며, 예상하지 못한 오류를 절대 삼키지 않는다. - 예상한 오류 조건만 포착하고, 가상화된 테스트 환경에서는 실행 영역을 넘어도 안전한 네이티브 오류 검사를 사용한다. - 함수 이름에는 동사를 사용하고, 용어를 일관되게 유지하며, 계약이 변경된 개념은 모든 위치에서 이름을 바꾼다. - 단순한 파싱에는 단순한 문자열 연산을 사용하고, 역추적이 필요한 문법에는 기존 구조화 파서를 사용한다. - 설정 가능한 값은 설정 계층을 거치게 하고, 명령 처리기를 표현 계층과 분리하며, 정책을 직접 고정하지 않는다. - 비동기 I/O를 사용하고, 독립적인 작업을 동시에 실행하고, 필요한 완료를 기다리며, 반복문 안의 불변 작업을 밖으로 옮긴다. ## 병합될 때까지 변경 요청을 실제 변경과 맞추기 - 저장소 템플릿으로 변경 요청을 열고, 필수 섹션을 유지하며, 템플릿이 선택 사항으로 표시한 내용만 제거한다. - 중요한 업데이트를 할 때마다 제목과 설명을 실제 변경 사항과 동기화한다. - 처리한 검토 대화에는 해결 내용과 이를 뒷받침하는 수정본을 답변한 뒤 대화를 해결된 상태로 바꾼다. - 민감한 구현 맥락을 노출하지 않고 저장소 정책에 따라 에이전트가 작성한 원격 콘텐츠에 레이블을 지정한다. - 저장소에서 승인한 충돌 해결 절차를 사용하여 기준을 최신으로 유지하고, 생성된 잠금 데이터를 결정적으로 다시 빌드하며, 병합 가능성을 검증한다. - 자동 생성물이 아닌 충돌을 직접 확인한다. 강제 업데이트나 그 밖의 원격 이력 재작성에는 명시적 허가와 검증된 대상이 필요하다.