공유 워크트리에서 다른 작업을 망가뜨리지 않고 크로스 플랫폼 CLI 만들기

## 현재 워크트리 안에서만 검색하고 수정하기 개발에 워크트리를 사용한다면 현재 작업 디렉터리가 활성 브랜치의 전체 저장소입니다. 검색, 읽기, 빌드, 테스트, 편집은 이 루트 안에서만 수행하세요. - 상대 경로나 현재 루트 아래에서 해석된 경로를 사용하세요. - 상위 디렉터리가 저장소라고 가정하지 마세요. - 형제 워크트리에서 구현이나 설정을 검색하지 마세요. - 개발자 홈 디렉터리가 하드코딩된 경로는 허용하지 마세요. - 픽스처와 소스 경로는 활성 루트를 기준으로 해석하세요. 워크트리를 벗어나면 다른 브랜치의 오래된 코드가 분석과 변경에 섞일 수 있습니다. ## 다른 세션의 변경을 리셋이나 삭제로 없애지 않기 익숙하지 않은 파일과 편집 내용은 다른 활성 세션의 작업일 수 있다고 가정하세요. 현재 작업 범위 밖에 있다는 이유만으로 작업을 삭제하거나, 재설정하거나, 폐기하거나, 덮어써서는 절대 안 됩니다. - 직접 만들지 않은 파일을 보존하세요. - 추적되지 않는 파일을 제거하기 전에 확인하세요. - 명시적 승인 없이 `reset`, `checkout-discard`, `clean`, `stash-deletion` 작업을 실행하지 마세요. - 건드리지 않은 파일 때문에 hook이 실패하면 해당 파일을 수정하지 말고 충돌을 보고하세요. - 변경 사항을 요청된 범위로 제한하고 최종 diff를 확인하세요. 공유 워크트리 상태는 사용자 데이터로 취급하고, 파괴적 작업을 하기 전에 그 소유권을 확인하세요. ## 조건문을 흩뿌리지 않고 레지스트리로 명령 추가하기 레지스트리를 사용하여 명령, 프로바이더, 통합 기능을 확장 가능하게 만드세요. 새 구현은 안정적인 인터페이스를 충족하고 하나의 표준 경로를 통해 등록되어야 하며, 애플리케이션 곳곳에 조건문을 추가해서는 안 됩니다. - 주요 동작에 대한 인터페이스를 정의하세요. - 생성자나 필드를 통해 의존성을 주입하세요. - 저장소에서 지원하는 생성기로 모의 객체를 생성하세요. - 기본값을 갖는 확장 가능한 설정에는 함수형 옵션을 사용하세요. - 각 명령 구현을 목적이 분명한 개별 파일에 두세요. - 범용 유틸리티 패키지를 확장하지 말고 용도가 분명한 패키지를 추가하세요. 별도의 병렬 로직을 도입하기 전에 기존 명령, 실행, 패키지 계층을 검색하세요. ## 컨텍스트는 취소와 기한에만 쓰고 플래그는 하나의 파서로 처리하기 요청 컨텍스트는 취소, 기한, 요청 범위의 드문 값에만 사용하세요. 컨텍스트를 받는 경우 첫 번째 인수로 전달하세요. 설정, 의존성 또는 일반 매개변수를 숨기는 데 컨텍스트를 사용하지 마세요. 설정을 결정론적 파이프라인으로 구성하세요. 1. 설정 소스를 불러옵니다. 2. 가져오기와 상속을 처리합니다. 3. 명령 플래그, 환경, 파일, 기본값 순으로 우선순위를 적용합니다. 4. 지원되는 템플릿을 렌더링합니다. 5. 최종 적용 설정을 생성합니다. 플래그와 환경 변수 바인딩은 통합 파서를 통해 처리하세요. 옵션을 추가할 때는 이를 소유하는 모든 스키마를 업데이트하고 중앙 바인딩 계층을 절대 우회하지 마세요. ## 파이프용 데이터와 사람용 메시지를 다른 스트림으로 나누기 파이프로 전달할 수 있는 결과는 데이터 스트림에만 쓰세요. 프롬프트, 진행 상황, 경고, 사람이 읽도록 서식화된 메시지는 인터페이스 스트림에 쓰세요. 구조화된 로깅은 사용자 대상 출력이 아니라 시스템 이벤트에만 사용하세요. - 직접 출력하지 말고 공유 I/O 추상화를 사용하세요. - 색상, 아이콘, Markdown, 터미널 너비, 기능 감지는 UI 계층에서 담당하게 하세요. - 터미널이 스타일을 지원하지 않거나 지속적 통합 환경에서 실행될 때는 자동으로 표현을 단순화하세요. - 사람용 서식이 비활성화되어도 구조화된 데이터가 유효하도록 유지하세요. - 비밀 정보 마스킹을 일관되게 적용하고 사용자 데이터를 원격 측정에 수집하지 마세요. 테스트 또는 기록용 플래그로 터미널 특성을 강제할 수 있지만, 프로덕션 기본값은 환경을 인식해야 합니다. ## 함수를 작게 유지하고 오류를 안정된 분류로 감싸기 파일과 함수는 한 가지 역할에 집중하게 하세요. 복잡도가 높은 오케스트레이션에서 이름이 있는 단계를 추출하여 최상위 함수가 평평한 파이프라인처럼 읽히게 하세요. - 저장소 표준의 서식, 가져오기 그룹, 별칭, 주석 문장 부호를 사용하세요. - 유용한 주석을 보존하고 동작이 바뀌면 업데이트하세요. - 의미 있는 공개 작업에는 표준 성능 추적을 적용하세요. - 정책이 허용한다면 단순 접근자, 생성자, 순수 조회, 단순 위임은 제외하세요. - 안정적인 범주로 오류를 감싸고 원인을 보존하세요. - 어느 오류 체인도 잃지 않도록 독립적인 실패를 결합하세요. - 감싸진 오류는 문자열 비교가 아니라 의미 기반 일치로 확인하세요. 사용자에게 힌트, 컨텍스트 또는 종료 의미가 필요할 때는 풍부한 오류 빌더를 사용하세요. ## 모의 객체와 실제로 실패할 수 있는 테스트로 동작 확인하기 격리된 동작에는 생성된 모의 객체를 사용하는 빠른 단위 테스트를 우선하고, 공개 명령 동작이 실제 경계를 넘는 곳에는 통합 또는 인수 테스트 범위를 추가하세요. - 입력과 오류 범위에는 테이블 기반 사례를 사용하세요. - 내부 구현이 아니라 동작을 테스트하세요. - 스텁, 항상 참인 테스트, 영구적으로 건너뛰는 테스트를 제거하세요. - 병합된 컬렉션은 결과와 소스를 별도 검사에서 각각 변경하여 양방향 격리를 입증하세요. - `slice` 결과는 길이뿐 아니라 대표적인 내용도 검증하세요. - 조건이 없을 때 복구가 실행되지 않음을 입증하는 부정 테스트를 추가하세요. - 감싸진 실패에는 의미 기반 오류 일치를 사용하세요. 보호 대상 동작에서 어설션이 실제로 실패할 수 있을 때만 커버리지가 증거가 됩니다. ## 모든 OS에서 돌고 준비가 빠지면 분명히 실패하는 테스트 쓰기 테스트는 shell, 경로 구분자 또는 플랫폼별 유틸리티를 가정하지 않고 지원되는 데스크톱과 서버 플랫폼에서 실행되어야 합니다. - 표준 경로 라이브러리를 사용하여 개별 구성 요소로 경로를 만드세요. - 이식 가능한 접미사 또는 표시 비교에만 구분자를 정규화하세요. - 플랫폼별 명령 대신 테스트 실행 파일이나 주입된 실행기를 사용하세요. - 중복된 진입점을 정의하지 말고 기존 테스트 진입점에 하위 프로세스 검사를 통합하세요. - 픽스처를 순회하거나 개수를 세기 전에 픽스처 루트를 절대 경로로 해석하세요. - 설정이 누락되면 전제 조건 및 픽스처 개수 가드가 명확하게 실패하도록 하세요. - 이름을 바꾸면 테스트가 깨져야 하는 스키마 필드에는 컴파일 타임 센티널을 추가하세요. 의존하는 하위 프로세스 동작을 테스트하기 전에 명시적인 전제 조건 하위 테스트에서 암시적 환경 전파를 검증하세요. ## 스냅샷은 손으로 고치지 말고 테스트 도구로 다시 생성하기 골든 스냅샷에는 보이지 않는 서식, 터미널 너비, 스타일, 환경에 민감한 출력이 포함됩니다. 절대 수동으로 편집하지 마세요. - 지원되는 테스트 플래그나 생성기를 통해 스냅샷을 다시 생성하세요. - 결과 diff를 수락하기 전에 검토하세요. - 리디렉션이 기능 감지를 바꿀 수 있으므로 스냅샷 또는 터미널 테스트를 파이프로 전달하지 마세요. - 명령 도움말이나 출력이 변경되면 관련 기록도 함께 다시 생성하세요. - 기록에서 명령 실패, 누락된 참조, 유출된 기기별 경로를 검증하세요. - 명시적인 범위 지정 없이 보호된 픽스처나 테스트 데이터를 변경하지 마세요. 생성된 출력은 이를 소유하는 소스와 표준 워크플로를 통해 변경해야 합니다. ## 새 명령마다 문서를 쓰고 미룬 작업은 이슈로 남기기 새로운 명령, 플래그, 매개변수 또는 설정 표면에는 저장소에서 요구하는 메타데이터, 사용법, 예시, 인수, 플래그, 시각적 증거를 포함한 사용자 문서가 필요합니다. - 파일 이름으로 URL을 추측하지 말고 선언된 페이지 식별자를 확인하세요. - 변경 후 문서 사이트를 빌드하고 링크, 이미지, 구성 요소를 확인하세요. - 단순한 문구 편집이 아니라 명령 동작, 도움말 또는 출력이 변경될 때 시각적 캡처를 다시 생성하세요. - 요구 사항 문서를 지정된 위치에 정해진 명명 규칙으로 배치하세요. - 작업을 미룰 때는 추적되는 issue를 만들고 병합 전에 그 식별자를 연결하세요. - 릴리스 노트, 로드맵 데이터, 레이블을 변경 분류에 맞게 유지하세요. 추적되지 않는 후속 작업을 약속하는 문서는 미완성입니다. ## 훅을 건너뛰거나 파괴적인 Git 명령을 쓰지 않고 리뷰 진행하기 저장소의 리뷰 워크플로를 사용하고, 영구 서비스가 명시적으로 승인되지 않는 한 반복 유지보수 자동화의 범위를 현재 세션으로 제한하세요. - 승인된 브랜치 절차를 통해서만 `rebase`하거나 업데이트하세요. - 지속적 통합 상태를 확인하고 해결되지 않은 리뷰 스레드를 처리하세요. - 원래 리뷰 스레드 안에서 답변하고 연결 상태를 확인하세요. - 리뷰를 업데이트하기 전에 패치 범위의 lint와 테스트 커버리지를 실행하세요. - hook을 우회하거나 검증을 생략하는 플래그를 사용하지 마세요. - 임시 메모, 조사 내용, 해결되지 않은 자리표시자를 커밋하지 마세요. 무엇을 잃게 되는지 명시적으로 확인하지 않고 파괴적인 Git 명령을 실행하거나 다른 세션의 작업을 제거해서는 절대 안 됩니다. ## 버그는 재현 테스트부터 쓰고 실패한 검사는 원인부터 고치기 버그의 경우 먼저 재현 테스트를 작성하고 실패를 관찰한 다음, 가장 작은 수정 사항을 구현하고 회귀가 없는지 확인하세요. 완료하기 전에 다음을 확인하세요. - 프로젝트가 고정된 도구 체인으로 컴파일됩니다. - 변경된 파일이 표준 포매터와 린터를 통과합니다. - 짧은 테스트가 통과하며, 영향받는 경로에서 요구하는 경우 전체 테스트나 인수 테스트가 실행됩니다. - 과장된 어설션 없이 커버리지가 강제 임계값을 충족합니다. - 생성된 모의 객체, 스키마, 스냅샷, 문서, 시각적 캡처가 최신 상태입니다. - 복잡도와 파일 크기 제한이 계속 충족됩니다. - 크로스 플랫폼 경로와 하위 프로세스 테스트가 이식 가능합니다. - 비밀 정보, 사용자 데이터 또는 관련 없는 작업이 diff에 포함되지 않았습니다. 실패한 검사를 약화하지 말고 실패 원인을 수정하세요.