Rust 라이브러리·CLI 워크스페이스를 참조 도구와 비교하며 고친다

## 변경은 맡은 crate에 두고 저수준 API는 가볍게 유지한다 저장소를 라이브러리 사용자와 명령줄 사용자 모두에게 제공되는 다중 크레이트 워크스페이스로 다루세요. 편집하기 전에 워크스페이스 매니페스트를 읽고 지원되는 최소 Rust 버전, 기능 그래프, 크레이트별 책임, 공개 진입점을 파악하세요. 저수준 내부 요소와 고수준 편의 요소를 분리하세요. - 저수준 내부 API는 참조를 우선하고, 변경 가능한 작업 상태를 명시적으로 노출하며, 편의를 위한 복제를 피해야 합니다. - 고수준 편의 API는 사용하기 쉬워지는 대가로 어느 정도의 할당이나 소유권 이전을 허용할 수 있습니다. - 가벼운 플랫폼 객체는 일반적으로 저장소를 빌려야 합니다. - 수명 때문에 API가 지나치게 복잡해지는 경우, 비용이 큰 캐시는 저장소 상태를 소유하거나 복제할 수 있습니다. 기본값을 둘 수 있는 분기 동작에는 `Options`를 사용하세요. 작업 수행에 필수적이어서 안전한 기본값을 둘 수 없는 데이터에는 `Context`를 사용하세요. 관련 데이터 구조나 작업을 소유하는 크레이트에 변경 사항을 배치하세요. 공유 명령줄 동작은 각 바이너리에 중복하지 말고 공통 CLI 계층에 유지하세요. 공개 인터페이스를 변경하기 전에 라이브러리 직접 호출자와 명령줄 동작을 모두 고려하세요. ## 실패하는 테스트로 시작하고 참조 도구와 비교한다 동작 변경은 의도한 이유로 실패하는 회귀 테스트부터 시작하세요. 테스트는 관찰 가능한 동작에 집중하고, 일반적인 형식 및 소유권 오류는 Rust 컴파일러가 확인하도록 맡기세요. 확립된 프로토콜이나 파일 형식을 구현할 때는 가능하면 지배적인 참조 구현을 판정 기준으로 사용하세요. 두 구현에서 동일한 사례를 실행하고, 호환된다고 가정하지 말고 의미상의 차이를 조사하세요. 기존 실패가 변경 사항 때문인 것으로 잘못 판단되지 않도록 편집 전에 기존 테스트를 실행하세요. 다음을 사용하세요. - 로컬 알고리즘과 데이터 변환에는 단위 테스트 - 크레이트 경계에는 통합 테스트 - 명령줄의 처음부터 끝까지 이어지는 동작에는 여정 테스트 - 호환성에 민감한 경로에는 실제 저장소 또는 현실적인 데이터 세트 각 어설션 메시지는 단순히 어설션이 실패했다고 알리는 것이 아니라 검사 중인 불변 조건을 설명해야 합니다. 테스트 대상 동작과 필수 세부 사항을 설명하는 명확한 픽스처 문서를 추가하세요. 픽스처 시스템이 지원하는 경우 문서 문자열을 우선하세요. ## unwrap() 대신 무엇이 어디서 실패했는지 알려 주는 오류를 쓴다 프로덕션 코드에서 `unwrap()`을 절대 사용하지 마세요. 테스트에서도 피하고 `?`를 우선하세요. `expect()`는 조건이 반드시 충족되어야 하는 이유를 간결하게 설명할 때만 사용하세요. 사용자가 무엇이 어디에서 실패했는지 이해할 수 있도록 전체 오류 체인을 보존하세요. 명령줄 바이너리는 유연한 최상위 오류 형식을 사용할 수 있지만, 저수준 크레이트는 워크스페이스의 구조화된 오류 규칙을 따라야 합니다. 오류를 추가하기 전에 크레이트 매니페스트와 주변 코드를 확인하세요. - 크레이트가 이미 맥락을 전달하는 최신 오류 프레임워크를 사용한다면 그 패턴을 계속 따르세요. - 기존의 derive 기반 오류 열거형을 계속 사용한다면 마이그레이션이 명시적으로 범위에 포함되지 않는 한 해당 크레이트 내에서 일관성을 유지하세요. 맥락을 전달하는 패턴에서는 다음을 지키세요. - 프로젝트 도우미를 통해 정적 메시지나 형식화된 메시지를 생성하세요. - 호출한 함수의 오류를 전파할 때 맥락을 추가하세요. - 호출한 함수의 오류가 없으면 독립적인 메시지를 발생시키세요. - 콜백 경계에서 필요할 때만 형식이 지정된 오류를 소거하세요. - 프로젝트 예외 래퍼를 표준 오류로 변환하는 작업은 상호 운용성 경계에서만 수행하세요. 프로젝트 예외 래퍼가 의도적으로 표준 오류 트레이트를 구현하지 않는다면 일반 오류 API에 억지로 넣지 마세요. 제공된 경계 메서드로 변환하세요. 박싱된 표준 오류를 반환하는 테스트는 `?`를 사용하기 전에 래퍼를 매핑해야 합니다. 오류 체인을 직접 다시 만들지 말고 기존 오류 확장 트레이트와 임포트를 사용하세요. ## 불필요한 clone을 피하고 저장소 경로를 바이트로 다룬다 비용이 큰 복제를 피하려면 저수준 크레이트에서 참조를 우선하세요. 소유된 값이 명시적으로 필요하고 API가 연결된 형태를 받을 수 없는 경우가 아니라면 저장소 기반 핸들을 분리하지 마세요. 내부 가변성에는 워크스페이스의 동시성 추상화를 사용하세요. 기능 호환성과 플랫폼 동작을 확인하지 않은 채 관련 없는 동기화 기본 요소로 대체하지 마세요. 네이티브 경로 API가 다른 인코딩을 사용하는 플랫폼에서도 버전 관리 경로는 바이트 기반 데이터로 다루세요. 저장소 경로를 운영체제 경로로 변환할 때는 프로젝트의 경로 유틸리티 또는 전용 경계 형식만 사용하세요. 유효한 저장소 경로가 유효한 유니코드라고 가정하지 마세요. 구문 분석, 비교, 저장, 프로토콜 코드에서 손실 변환을 피하세요. 소유권, 캐싱, 할당을 추가하기 전에 성능이 중요한 경로를 측정하세요. 편의 기능은 고수준 계층에 속하며, 저수준 기본 요소는 제어 가능성과 예측 가능한 비용을 유지해야 합니다. ## 기본 빌드만이 아니라 모든 기능 조합을 테스트한다 종합 테스트 명령, 워크스페이스 구성 검사, 린트, 여정 테스트, 문서 빌드에는 저장소의 작업 실행기를 사용하세요. 의도적으로 단위 테스트만 실행해도 충분한 경우에만 `cargo test`를 직접 사용하세요. 기본 빌드와 경량 또는 최소 의존성 세트를 포함해 지원되는 릴리스 변형을 검증하세요. 기본 기능에서만 작동하는 변경은 완료된 것이 아닙니다. 작게, 경량, 최대, 순수 변형이 존재한다면 이를 포함해 워크스페이스에 문서화된 기능 조합을 실행하세요. 영향을 받는 각 조합에서 선택적 의존성과 플랫폼 추상화가 컴파일되는지 확인하세요. 생성되는 픽스처 내용이 플랫폼마다 달라지는 경우 저장소의 아카이브 안정화 메커니즘을 사용하세요. 바이트 단위의 안정성이 중요하다면 플랫폼별 로컬 생성보다 패키지된 픽스처 아카이브를 우선하세요. 저장소가 macOS 또는 Windows의 아카이브 테스트를 위한 플랫폼별 환경 플래그를 정의한다면 문서에 나온 그대로 적용하세요. 다른 플랫폼에서 영향을 받는 테스트를 조용히 건너뛰지 마세요. 사용자에게 보이는 CLI 변경에는 명령의 엔드투엔드 테스트를 실행하고, 실용적인 경우 참조 구현과 비교하세요. ## changelog에 쓰일 커밋을 쓰고 호환성을 깨는 변경에 표시한다 목적이 분명한 관례적 커밋을 사용하세요. - 변경 사항이 변경 로그에 포함될 때만 관례적 접두사를 추가하세요. - 사용자에게 보이는 기능과 수정에는 `feat:`와 `fix:`를 사용하세요. - 내부 리팩터링과 잡무에는 접두사를 생략하세요. - 모든 호환성 파괴 변경에는 `!` 접미사를 표시하세요. 커밋 제목에는 사용자에게 보이는 목적을 명시하고 프로젝트가 요구하는 경우 이슈 또는 검토 참조를 포함하세요. 호환성 파괴 변경이 여러 크레이트에 영향을 미치고 하나의 커밋 메시지로 모든 영향을 정확히 설명할 수 없다면 크레이트별로 나누세요. 호환성을 깨는 API 변경을 첫 번째 커밋에 넣고, 그에 따른 후속 조정은 다음 커밋에 넣으세요. 릴리스 자동화가 커밋 메시지에서 버전 또는 변경 로그를 산출한다면 커밋 메시지를 릴리스 입력으로 취급하세요. 코드 변경이 직접 영향을 주는 경우 고수준 가이드, 기여 지침, 개발 노트, 크레이트 상태 기록, 안정성 문서를 업데이트하세요. 프로젝트가 더 엄격한 목표를 정의하지 않는 한 기본 CI 환경에서 사용할 수 있는 참조 도구 버전을 호환성 기준으로 사용하세요. ## 끝내기 전에 crate 계층부터 커밋 메시지까지 점검 목록으로 확인한다 완료하기 전에 다음을 확인하세요. 1. 변경이 저수준 내부 요소와 고수준 편의 요소 중 어디에 속하는지 식별합니다. 2. 유사한 크레이트에서 확립된 패턴을 확인합니다. 3. 오류 처리가 해당 크레이트의 현재 프레임워크와 일치하는지 확인합니다. 4. 프로덕션 코드에 `unwrap()`이 새로 도입되지 않았는지 검증합니다. 5. 영향을 받는 모든 기능 조합과 릴리스 변형을 검사합니다. 6. 라이브러리 호출자와 명령줄 사용자를 별도로 고려합니다. 7. 해당하는 집중 테스트, 워크스페이스 테스트, 여정 테스트, 호환성 테스트를 실행합니다. 8. 바이트 기반 경로가 플랫폼 간에 손실 없이 유지되는지 확인합니다. 9. 새 복제, 분리, 캐싱, 동기화에 측정 가능한 필요성이 있는지 검토합니다. 10. 직접 관련된 문서를 업데이트합니다. 11. 커밋 메시지가 변경 로그와 호환성 파괴 변경의 영향을 올바르게 설명하는지 확인합니다. 테스트하지 않은 기능 세트, 플랫폼, 참조 비교 또는 릴리스 변형이 있다면 누락된 정확한 전제 조건과 함께 보고하세요. 기본 기능 단위 테스트 실행만으로 워크스페이스 전체의 호환성을 주장하지 마세요.