대규모 플랫폼 모노레포를 고치면서 영향받는 클라이언트를 모두 맞춘다

## 루트 규칙을 읽은 뒤 각 폴더의 지침을 더한다 저장소 루트를 조율 지점으로 사용하고 가장 가까운 로컬 지침 파일을 작업별 기준으로 사용하세요. 한 모듈의 규칙이 전체 변경을 지배한다고 가정하지 말고, 먼저 루트 규칙을 적용한 다음 영향을 받는 각 디렉터리가 소유한 규칙을 추가하세요. 로컬 지침 파일이 없는 영역은 가장 가까운 유지 관리 대상 개발 가이드, 모듈 README, 지속적 통합 워크플로를 다음 기준 소스로 사용하세요. 여러 영역에 걸친 변경을 편집하기 전에 적용 가능한 모든 가이드를 읽으세요. ## 편집 전에 어느 모듈이 어떤 부분을 맡는지 확인한다 제어 평면, 런타임 구성요소, 공개 사양, 클라이언트 라이브러리, 배포 리소스, 명령줄 인터페이스, 엔드투엔드 테스트, 문서, 예시, 아키텍처 제안을 어떤 모듈이 소유하는지 식별하세요. 수명 주기와 구성 동작은 제어 평면 소유자에게, 런타임 프로세스 동작은 가장 가까운 구성요소 가이드에, 공개 스키마 변경은 사양 소유자에게, 클라이언트 생성은 라이브러리 소유자에게, 배포 동작은 운영 또는 패키징 소유자에게, 명령 동작은 CLI 소유자에게 배분하세요. 계약, 구현, 클라이언트에 걸친 변경은 공개 사양에서 시작한 다음 영향을 받는 모든 소비자 가이드를 불러오세요. 구성요소 API, 테스트 가정, 배포 통합을 동일한 계약에 맞게 유지하세요. ## 목표를 확인하고 필요한 줄만 바꾼다 가정을 밝히고 모호성을 드러내며 요청을 서로 상충하는 방식으로 해석할 수 있을 때는 방향을 물으세요. 단순하지 않은 작업은 구현 전에 관찰 가능한 성공 기준으로 전환하고, 결정이 필요하면 중단하세요. 요청을 충족하는 가장 작은 해결책을 선택하세요. 추측에 따른 기능, 일회성 추상화, 불필요한 구성 가능성, 관련 없는 리팩터링, 기존 작업의 삭제를 피하세요. 작업에 필요한 파일과 줄만 건드리고, 로컬 스타일을 따르며, 동작이 변경되면 집중 테스트를 추가하거나 업데이트하고, 검사가 통과하거나 남은 방해 요소가 명확해질 때까지 반복하세요. ## 공개 사양이 바뀌면 클라이언트와 문서도 맞춘다 공개 사양을 기준 계약 소스로 취급하세요. 사용자에게 보이는 동작이 변경될 때는 사양, 구현, 클라이언트 라이브러리, 문서, 예시, 구성, 명령 동작, 릴리스 산출물을 동기화된 상태로 유지하세요. 배포 API나 오케스트레이터 리소스가 변경될 때는 생성된 매니페스트, 배포 패키지, 컨트롤러 동작, 서버 통합, 운영 문서도 업데이트하거나 검증하세요. 명시적인 승인 없이 계약이 구현에서 의도적으로 벗어나게 두지 마세요. 문서화된 동작이 기준 공개 약속으로 유지되도록 사용자 대상 문서와 운영 대상 문서를 구현 전이나 구현과 함께 업데이트하세요. ## 생성 파일은 직접 고치지 않고 소스에서 다시 만든다 생성 산출물만 편집하여 문제를 해결하지 마세요. 기준 스키마, 템플릿, 구성 또는 생성기 입력을 찾아 변경한 다음, 지원되는 워크플로를 통해 영향을 받는 모든 클라이언트, 매니페스트, 참조, 예시, 패키징된 산출물을 다시 생성하세요. 생성된 차이에서 예기치 않은 변경을 검토하고 다시 생성한 계약을 기준으로 다운스트림 소비자를 검증하세요. 수동 작성 어댑터를 생성 코드와 분리하고 그 사이에 설정된 저장소의 소유권 경계를 보존하세요. 재생성이 막힌 경우 누락된 도구나 환경을 보고하고, 소스와 파생 산출물을 동기화된 것으로 제시하지 말고 명확히 식별된 미완료 상태로 두세요. ## 호환성을 깨는 공개 변경은 먼저 묻는다 공개 API, 클라이언트 인터페이스, 구성, 프로토콜, 명령 동작, 배포 리소스, 주석, 레이블, 패키지 값에는 추가 방식의 하위 호환 변경을 우선하세요. 호환성을 깨는 공개 변경을 적용하거나, 의도적인 계약 편차를 도입하거나, 명확한 마이그레이션 경로 없이 가시적 동작을 변경하기 전에 물으세요. 승인을 요청하기 전에 영향을 받는 소비자, 호환성 영향, 마이그레이션 요구사항, 릴리스 결과를 설명하세요. 호환성을 깨는 변경을 생성된 차이 뒤에 숨기거나 관련 없는 구성요소 작업을 같은 변경에 섞지 마세요. 승인된 호환성 결정을 구현, 문서, 테스트, 릴리스 노트에 명시적으로 유지하세요. ## 가장 작은 범위부터 검사하고 점차 넓힌다 더 넓게 검증하기 전에 파일 또는 패키지 범위의 포매터, 린터, 단위 테스트, 계약 검사, 명령 출력 어설션을 실행하세요. 변경이 해당 경계를 넘는 경우 통합, 언어 간, 배포 또는 문서 빌드로 범위를 확장하세요. 명령 도움말과 출력을 CLI 테스트와 함께, 계약 예시를 스키마 검사와 함께, 지원되는 언어 전반의 클라이언트 동작과 영향을 받는 플랫폼의 배포 출력을 검증하세요. 동작이 변경되거나 버그가 수정될 때마다 집중 테스트를 업데이트하세요. 실행하지 못했거나 차단된 모든 검사를 최종 인계에 명시하세요. 필수 검사가 실패하거나 영향을 받는 소비자가 명시적 제한 없이 미검증 상태인 동안에는 완료를 주장하지 마세요. ## 문서는 한곳에 두고 복사 대신 링크한다 사용자와 운영자를 위한 장문의 안내는 지정된 문서 트리에 유지하세요. 루트 README는 저장소 진입점에만 사용하고, 게시 가능한 패키지의 README는 설치, 빠른 시작, 패키지 진입점에 사용하세요. 유지 관리되는 문서 페이지가 있으면 내부 구성요소 README는 최소한으로 유지하세요. 실행 가능한 예시는 예시 트리에, 그 설명 페이지는 문서 트리에 저장하세요. 저장소 규칙이 그런 경우 제안 문서를 기준으로 사용하고 커뮤니티 페이지는 색인으로만 사용하세요. 커뮤니티 및 개발 정책을 중복하지 말고 링크하세요. 문서가 체크아웃한 브랜치나 태그를 따르도록 저장소 파일에서는 버전 상대 링크를 우선하고, 버전 관리 코드에서 공개 웹사이트를 유일한 소스로 사용하지 마세요. ## 문서 사이트의 페이지 규칙을 지키고 오류 없이 빌드한다 문서화되지 않은 빌드 시점 생성을 도입하지 말고 설정된 문서 엔진과 정적 사이트 구성을 사용하세요. 이미지는 지정된 공개 자산 디렉터리에 두고 사이트에서 승인한 경로 규칙을 사용해 참조하세요. 게시되는 모든 페이지에 필수 메타데이터를 설정하고, 구성된 내부 링크 스타일을 사용하며, 문서 트리 외부로 연결할 때는 전체 소스 링크를 사용하세요. 승인된 콜아웃, 코드 그룹, 탐색 규칙을 일관되게 적용하세요. 기여자 전용 지침은 게시 사이트에서 제외하세요. 현지화 정책이 허용하는 경우에만 현지화 사본을 추가하고, 게시 준비 변경을 완료로 간주하기 전에 문서 빌드를 오류 0건으로 실행하세요. ## 호환성을 깨는 변경을 집중 검토하고 남은 위험을 보고한다 공개 사양, 클라이언트 인터페이스, 구성, 명령 동작, 배포 리소스, 프로토콜에서 호환성을 깨는 변경을 우선 검토하세요. 불필요하거나, 내부적으로 일관되지 않거나, 소비자가 구현하기 어렵거나, 신뢰할 수 있는 마이그레이션 경로가 없는 변경을 표시하세요. 기준 소스 경계의 훼손, 계층 구조 위반, 오래된 생성 산출물, 누락된 테스트, 문서화되지 않은 동작, 호환성 회귀를 확인하세요. 확인된 결함과 검증되지 않은 위험을 구분하고 영향을 받는 계약이나 소비자를 인용하세요. 변경된 영역, 동기화된 소비자, 실행한 검사, 차단된 검증, 호환성 결정, 남은 위험을 다루는 근거 기반 보고서로 마무리하세요.