앱과 명령줄로 쓰는 제품의 코드 저장소를 정리된 상태로 유지하기

## 전체 규칙 문서를 먼저 읽고, 폴더별 규칙도 따르기 루트 지침 파일을 저장소 전체의 교차 경계, 작업 흐름, 명령에 대한 단일 진실 공급원으로 취급한다. 모듈 세부 정보를 중복하지 않으면서 새로운 기여자가 방향을 잡을 수 있을 만큼 간결하게 유지한다. - 제품, 아키텍처, 기여, 검토, 현재 계획 문서로 연결되는 짧은 색인을 제공한다. - 보관된 사양을 명확히 표시하고 과거의 결정을 현재 동작으로 절대 취급하지 않는다. - 각 주요 디렉터리에서 해당 영역의 소유권과 제약 조건을 다루는 전용 지침 파일을 안내한다. - 규칙으로 관리되는 디렉터리에서 작업하기 전에 루트 규칙과 함께 해당 영역의 지침도 읽는다. - 두 문서가 충돌하면 내용을 섞지 말고 지정된 단일 진실 공급원을 따른 뒤 충돌을 보고한다. 모듈 수준 규칙을 루트 문서에 다시 복사해서는 안 된다. 규칙을 완전히 소유하는 가장 좁은 계층에서 업데이트하고, 찾기 쉽도록 필요한 경우에만 상위 문서에서 연결한다. ## 변경 전에 새 코드와 테스트를 둘 곳 정하기 각 최상위 영역이 소유하는 항목과 경계를 넘을 수 있는 의존성을 설명하는 저장소 지도를 유지한다. 새 코드, 테스트, 템플릿, 문서, 런타임 데이터를 어디에 둘지는 이 지도를 기준으로 결정한다. - 사용자 애플리케이션, 공유 계약, 플랫폼 기본 요소, 오케스트레이션 도구, 종단 간 테스트, 콘텐츠 확장을 분리한다. - 애플리케이션 비즈니스 로직이 프로세스 제어와 패키징 내부 구조를 알지 못하게 한다. - 한 애플리케이션이 다른 애플리케이션의 비공개 소스나 테스트를 가져오지 못하게 한다. - 런타임 간 DTO, 이벤트, 오류, 작업 형식을 순수한 공유 계약 계층으로 승격한다. - 테스트는 검증 대상 계층이 소유한 디렉터리에 두고, 애플리케이션 간 일관성 테스트는 종단 간 계층에 둔다. - 제거되었거나 비활성인 디렉터리를 기록하여 기여자가 오래된 아키텍처를 실수로 다시 만들지 않게 한다. 재사용 가능한 관심사의 소유자가 명확하지 않다면 중단하고, 다른 공유 위치를 만들기 전에 소유권 결정을 받는다. ## 데이터 저장 위치를 한곳에서 정하고 그대로 넘기기 각 런타임 루트, 이름공간, 식별 정보는 소유 경계에서 한 번만 결정한 후 그 값을 하위 구성 요소에 전달한다. 구성 요소는 포트, 작업 디렉터리, 애플리케이션 이름, 환경 대체값에서 이를 다시 구성하지 말고 전달받은 값을 사용해야 한다. - 런타임이 소유하는 모든 데이터 경로를 결정된 데이터 루트 또는 여기에서 파생된 상수로부터 도출한다. - 범위가 좁은 재정의 값과 마이그레이션 원본을 대체 루트가 아닌 명시적인 예외로 취급한다. - 일시적인 전송 세부 정보와 영구적인 런타임 식별 정보를 분리한다. - 하위 프로세스를 시작하기 전에 패키징 상태와 개발 상태에 이름공간을 할당한다. - 결정된 상태를 하위 프로세스에 전달하고, 하위 프로세스가 저장 위치를 추측하게 해서는 안 된다. - 알려진 이전 방식의 이탈 경로를 제거 후보로 문서화하고 절대 예시로 사용하지 않는다. 명확한 수정 방법이 있다면 정규 루트 또는 명시적인 인수를 통해 경로를 전달한다. 올바른 소유권이 불확실하다면 새로운 규칙을 만들지 말고 유지관리자의 결정을 요청한다. ## 새 기능을 앱과 명령줄 양쪽에 넣기 하나의 서비스 계약을 중심으로 사용자 기능을 설계하고 지원하는 모든 상호작용 인터페이스에서 제공한다. 인터페이스 간 동등성은 기능 완성의 일부이며 나중에 추가할 개선 사항이 아니다. 새 기능마다 다음을 수행한다. 1. 공유 요청, 응답, 오류, 이벤트 계약을 정의하거나 업데이트한다. 2. 서비스 엔드포인트를 동작의 단일 공급원으로 구현한다. 3. 해당 엔드포인트를 호출하는 그래픽 인터페이스를 추가한다. 4. 동일한 엔드포인트를 호출하는 명령줄 인터페이스를 추가한다. 5. 해당하는 경우 기계 판독 가능한 명령 결과와 긴 프롬프트를 위한 파일 입력을 제공한다. 6. 변경 점검표를 업데이트하여 영향을 받는 모든 인터페이스를 명시한다. 클라이언트마다 서로 다른 동작을 구현해서는 안 된다. 특정 인터페이스가 실제로 적용되지 않는다면 조용히 생략하지 말고 변경 기록에 이유를 설명한다. ## 화면 부품을 다시 쓸 수 있고 누구나 쓰기 쉽게 만들기 의도적인 전역 계약을 보존하면서 시각적 소유권을 가장 작고 안정적인 구성 요소에 할당한다. 새로운 지역 변형을 만들기 전에 공유 기본 요소를 재사용한다. - 전역 스타일시트를 의도적인 가져오기 경계와 디자인 변수 경계로 유지한다. - 구성 요소가 소유한 스타일은 해당 구성 요소 옆에 두고 기본적으로 범위가 지정된 모듈을 사용한다. - 전역 선택자는 초기화, 디자인 변수, 애플리케이션 셸, 공유 콘텐츠 계약, 외부 서비스 통합 지점에만 사용한다. - 스타일시트를 분할할 때 계단식 적용 순서를 유지하고 명시도가 의도치 않게 바뀌지 않았는지 검증한다. - 버튼, 숨김 레이블, 공통 양식 동작에 의미론적 컨트롤과 공유 접근성 기본 요소를 사용한다. - 실제로 재사용할 수 있을 때만 공유 기본 요소를 추가하고, 제품별 배치는 제품 계층에 둔다. - 종료 애니메이션이 중요하면 조건부 요소를 계속 마운트해 두고 클래스로 상태를 전환한다. - 빠른 감속 동작, 진입보다 짧은 종료 시간, 영이 아닌 시작 배율을 우선한다. 인접한 전역 스타일을 작고 테스트 가능한 변경으로 안전하게 이전할 수 있다면 구성 요소와 함께 옮긴다. 광범위한 기계적 이전과 관련 없는 동작 변경을 함께 수행해서는 안 된다. ## 문제를 찾을 수 있는 가장 가벼운 테스트로 변경 확인하기 요구 사항을 관찰할 수 있는 가장 가벼운 검증 계층을 선택하고, 위험이 경계를 넘을 때만 더 넓은 검사를 추가한다. 검증은 변경의 소유권 범위와 사용자 영향에 맞아야 한다. - 결함은 반증 가능한 회귀 테스트부터 시작하고 수정 전에 실패하는지 확인한다. - 테스트 범위를 보고된 동작으로 제한하고, 인접 결함은 별도의 후속 작업으로 기록한다. - 저장소 보호 검사와 정적 검사를 실행하고 변경된 패키지에 맞춘 테스트 또는 빌드도 수행한다. - 파서나 에이전트 이벤트 스트림 변경은 실제 제공자 호출을 사용하기 전에 기록된 세션을 재생한다. - 단위 테스트로 입증할 수 없는 표시상 상호작용, 애니메이션, 경쟁 동작은 브라우저 검사를 사용한다. - 작업 공간이나 의존성을 변경하면 저장소가 요구하는 생성 링크와 패키징 해시를 갱신한다. - 인접 테스트 모음에 알려진 실패가 있으면 기준 상태와 비교한다. 구현에는 과거의 예외가 아니라 지속적인 불변 조건을 표현한다. 승인 기준에 사람이 직접 보는 비교가 필요하다면 자동 검사가 통과했다는 이유만으로 준비가 끝났다고 주장해서는 안 된다. ## 테스트 버전과 정식 버전을 나누고, 내보내기 전에 각 버전 확인하기 각 배포 채널의 릴리스 식별 정보, 패키징 동작, 검토 증거를 명확히 한다. 편리한 지름길이 채널 분리를 없애거나 신뢰할 수 있는 검증을 우회하도록 허용해서는 안 된다. - 개발, 내부 검증, 미리 보기, 안정 채널에 서로 다른 목적과 공개 식별 정보를 부여한다. - 승격 의존성을 명확히 정의하고, 안정 채널이 관련 없는 미리 보기 단계에 의존하게 해서는 안 된다. - 패키징된 런타임 경로를 이름공간별로 분리하고 임시 포트와 독립적으로 유지한다. - 호출 측에서 프로세스 인수나 검색 규칙을 다시 구성하지 말고 소유 패키지의 기본 요소를 통해 오케스트레이션한다. - 변경 설명에 동기가 된 사용 사례, 사용자가 보는 효과, 영향을 받는 인터페이스, 검증 증거를 반드시 포함한다. - 표시상 인터페이스 변경에는 격리된 구성 요소 이미지만이 아니라 진입점을 보여 주는 스크린샷을 첨부한다. - 결함 수정을 해당 회귀 테스트와 문제 기록에 연결한다. - 정확성, 보안, 데이터 무결성, 계약 호환성을 막지 않는 한 관련 없는 발견을 현재 변경에 포함하지 않는다. 릴리스 전에 사용자가 실행할 경로와 동일한 경로로 산출물을 검증한다. 저장소 경계를 위반하거나, 필수 검증을 누락하거나, 비밀을 노출하거나, 영구 데이터를 손상할 위험이 있는 변경을 승인해서는 안 된다.