파일 형식과 API를 깨지 않고 다중 언어 데이터 라이브러리 수정하기

## 네이티브 코어와 다른 언어용 얇은 바인딩 이해하기 저장소를 하나의 네이티브 코어와 다른 언어를 위한 얇은 바인딩으로 구성된 것으로 취급하세요. 코어는 데이터 형식의 동작, 인코딩, 압축, 파일, 인덱스, I/O, 객체 스토리지, 선형 대수, 테이블 연산, 선택적 도메인, 테스트 인프라, 개발자 도구를 담당합니다. 바인딩은 검증이나 비즈니스 로직을 중복하지 않고 이 동작을 노출합니다. 비동기 I/O, 네이티브 열 지향 메모리, 매니페스트 추적을 수반하는 버전별 쓰기, 워크로드 지향 인코딩, 로컬 및 원격 객체 저장소에 공통으로 적용되는 단일 스토리지 추상화라는 아키텍처의 주요 특성을 보존하세요. 명령이나 코드 변경을 계획하기 전에 저장소 안내서와 영향을 받는 모든 언어 또는 디렉터리의 안내서를 읽으세요. 디렉터리별 규칙은 저장소 계약을 대체하는 것이 아니라 구체화합니다. ## 안정 형식은 호환성을 지키고 불안정 형식은 자유롭게 바꾸기 안정적이라고 선언된 모든 형식을 지속적인 호환성 계약으로 취급하세요. 안정적인 데이터를 변경할 때는 하위 호환성과 상위 호환성을 모두 보존해야 합니다. 불안정하다고 선언된 모든 형식을 폐기 가능한 것으로 취급하세요. 이러한 형식은 자유롭게 변경할 수 있으며, 이전의 불안정한 개정판에서 생성된 파일을 위해 호환성 코드, 마이그레이션, 대체 경로 또는 테스트를 추가하지 마세요. 모든 안정적 계약을 계속 준수하면서, 새 호환성 작업은 최근에 출시된 최신 안정 버전을 기준으로 평가하세요. 현재 개발 브랜치에만 존재하는 상태는 호환성 제약 조건이 아닙니다. 출시되지 않은 중간 상태를 보존한다는 이유만으로 더 깔끔하거나 완전한 설계를 약화하지 마세요. ## 다른 툴체인으로 바꾸지 말고 문서화된 명령과 빌드 프로필 사용하기 명령을 실행하기 전에 영향을 받는 언어에 대해 문서화된 확인, 테스트, 린트, 포맷, 커버리지, 벤치마크, 통합 명령을 파악하세요. 별도의 병렬 워크플로를 만들어 내지 말고 저장소에서 제공하는 패키지 및 테스트 선택자를 사용하세요. 명령이 없거나 느리거나 사용할 수 없는 것처럼 보인다는 이유로 다른 환경 관리자나 도구 체인으로 대체하지 마세요. 언어별 명령이 문서화된 워크플로 밖에서 실패하면 먼저 환경 사용 방식을 바로잡고 지정된 명령을 다시 실행하세요. 그런 다음에만 의존성이나 도구를 사용할 수 없다고 결론 내리세요. 임의의 최적화 재정의 대신 저장소에서 정의한 컴파일 프로필을 사용하세요. 디버그 기호를 유지하는 최적화 빌드로 벤치마크와 프로파일링을 수행하세요. 측정 대상 병목 지점에 영향을 줄 수 없는 로컬 디버깅, I/O 병목 벤치마크 또는 컴파일 시간 조사에 한해서만 링크 타임 최적화를 비활성화하세요. 통합 테스트에서는 필요한 픽스처 서비스만 시작하고, 문서화된 환경 값을 설정한 다음, 지정된 통합 대상을 실행하세요. ## 데이터를 메모리에 쌓지 않고 스트리밍하는 집중된 코드 작성하기 코드, 예제, 주석에는 영어를 사용하세요. 코드는 실행 성능뿐 아니라 가독성도 최적화해야 합니다. 명확하지 않은 이유를 설명할 때만 주석을 추가하고, 검토 전에 직접적인 디버그 출력을 제거하여 확립된 추적 또는 로깅 시스템으로 대체하세요. 두 곳 이상에서 반복되는 로직은 공유 헬퍼로 추출하세요. 한 번만 사용되는 로직은 호출 위치에 유지하세요. 인지 부하를 실질적으로 낮추거나 상당한 중복을 제거할 때만 헬퍼를 도입하고, 호출 이름만 바꾸거나 그대로 전달하는 얇은 래퍼는 추가하지 마세요. 변경 범위를 집중적으로 유지하세요. 부수적인 리팩터링, 재포맷, 외관상 수정은 피하세요. 배치를 메모리에 모으지 말고 스트리밍 동작을 유지하며, 밀집된 정수의 포함 여부를 표현할 때는 범용 해시 집합보다 컴팩트한 비트맵 구조를 선호하세요. ## 바인딩은 얇게 유지하고 옛 공개 API는 깨지 말고 사용 중단 표시하기 검증과 로직을 네이티브 코어에 집중하고 모든 언어 바인딩을 얇은 래퍼로 유지하세요. 모든 바인딩에서 같은 매개변수 이름을 사용하고, 이름을 바꾸려면 전부 바꾸거나 어느 것도 바꾸지 마세요. 기존 공개 시그니처를 그 자리에서 절대 깨뜨리지 마세요. 해당 언어가 지원하는 애너테이션으로 기존 메서드를 사용 중단 처리하고 새 메서드를 추가하세요. 상호 배타적인 불리언 플래그 묶음은 하나의 열거형 또는 모드 매개변수로 교체하세요. 코어 동작이 변경되면 적용 대상인 각 바인딩, 생성된 인터페이스, 예제, 호환성 테스트를 함께 업데이트하세요. 바인딩은 코어가 거부하는 값을 조용히 재해석해서는 안 됩니다. ## 값에는 그 내용대로 이름을 붙이고 잘못된 입력은 명확한 오류로 거부하기 변수에는 우연히 사용되는 방식이 아니라 그 값 자체를 나타내는 이름을 붙이세요. 변수를 포함하는 타입이나 모듈이 이미 도메인을 나타내면 중복 접두사를 제거하세요. API와 문서에서는 승인된 하나의 복수형을 일관되게 사용하고, 공급자별 용어보다 스토리지에 종속되지 않는 이름을 선호하세요. 타입, 구조체 또는 열거형의 이름을 바꿀 때는 메서드, 필드, 변수, 테스트, 문서를 함께 업데이트하세요. API 경계에서 입력을 검증하고 잘못된 값은 설명이 명확한 오류와 함께 거부하세요. 값을 조용히 범위 안으로 잘라내거나 조정하지 마세요. 상호 배타적인 빌더 또는 구성 옵션이 둘 다 있으면 거부하세요. 오류 메시지에 관련 변수의 이름, 값, 크기, 타입을 포함하세요. ## 의존성은 적게 추가하고 잠금 파일은 동기화하기 외부 패키지를 추가하기 전에 표준 라이브러리나 기존 워크스페이스 의존성을 우선 사용하세요. 잠금 파일은 의도한 경우에만 변경하고, 관련 없는 업그레이드는 되돌리며, 문제가 있는 의존성은 업스트림 이슈로 연결되는 주석을 남기는 경우에만 버전을 고정하세요. 워크스페이스 의존성이 변경되면 문서화된 매니페스트별 검사를 통해 루트 잠금 파일과 제외된 모든 바인딩의 잠금 파일을 갱신한 다음, 관련 업데이트를 모두 커밋하세요. 오프라인 잠금 파일 동기화 훅을 활성 상태로 유지하세요. 선택적이거나 도메인별인 의존성은 기능 플래그 뒤에 배치하세요. 상당한 도메인 기능은 별도 패키지로 분리하여 기본 빌드와 소비자가 불필요한 코드를 물려받지 않도록 하세요. ## 모든 버그 수정과 새 기능에 테스트 붙이기 모든 결함 수정과 기능에는 그에 대응하는 테스트가 필요합니다. 테스트 없는 코드를 받아들이지 마세요. 사례가 입력만 다를 때는 해당 언어의 매개변수화 테스트 기능을 사용하고, 각 사례에 읽기 쉬운 이름을 붙이세요. 출력만으로는 회귀를 감지할 수 없으므로 테스트의 출력문을 어설션으로 교체하세요. 기존 테스트가 이미 해당 동작을 담당한다면 겹치는 테스트 파일을 추가하지 말고 그 테스트를 확장하세요. 정해진 테스트 위치에 내용을 추가하세요. 건너뛴 테스트에는 추적 이슈 링크가 있어야 하며, 지속적인 근거 없이 단독 건너뛰기 애너테이션을 추가하지 마세요. ## null 값·빈 데이터와 이전 안정 버전 파일로 테스트하기 읽기, 인덱스, 스캔에 다중 프래그먼트 시나리오를 포함하세요. 인덱스 테스트에서는 null 요소, 모두 null인 컬렉션, 빈 컬렉션, null 열을 다루세요. 벡터 인덱스 테스트는 인덱스 생성에 성공했는지만 확인하지 말고 재현율 지표가 0.5 이상임을 어설션해야 합니다. 하위 호환성을 검증할 때는 이전 안정 버전에서 생성되어 저장소에 커밋된 데이터셋을 사용하세요. 생성자 버전을 확인하는 데이터 생성 스크립트를 유지하고, 읽기 전에 이 픽스처를 임시 스토리지로 복사하세요. 컴파일을 피하려고 문서 테스트를 비활성화하지 마세요. 함수 형태의 컨텍스트 안에서 컴파일되는 예제를 작성하세요. 프로덕션 커버리지 임곗값을 낮추지 말고, 프로젝트가 승인한 커버리지 애너테이션으로 테스트 전용 유틸리티를 커버리지에서 제외하세요. ## 모든 공개 API에 컴파일되는 예제를 붙여 문서화하기 모든 공개 API를 문서화하고 예제를 포함하세요. 관련 형식과 메서드에 링크하고, 코드가 리팩터링될 때마다 예제를 실제 시그니처와 동기화하세요. 인코딩 계층, 파일 형식, 스토리지 배치 같은 계층 구조에는 ASCII 트리 다이어그램을 사용하세요. 안내 상자 지시문 아래에서 공백 네 칸을 들여쓰는 규칙을 포함해 문서 시스템의 들여쓰기 계약을 따르세요. 검토 전에 주석과 문서를 교정하세요. 더 이상 컴파일되지 않거나 사용 중단된 API를 언급하는 문서는 외관상 문제가 아니라 호환성 결함입니다. ## 이슈에 라벨을 붙이고 변경 요청 전에 린트 검사 통과하기 명령줄 도구나 API로 이슈를 생성할 때는 템플릿 자동화를 우회할 수 있으므로 결함, 기능 또는 성능 작업을 나타내는 라벨을 명시적으로 전달하세요. 콘텐츠 기반 자동화가 신뢰할 수 있는 대체 신호를 얻도록 제목에 해당 분류를 접두사로 붙이세요. 저장소의 관례적인 변경 제목 접두사를 사용하고, 유용한 경우 범위를 추가하세요. 변경 요청을 생성하거나 업데이트하기 전에 비용이 많이 들더라도 영향을 받은 모든 언어 영역에 필요한 린트 검사를 실행하세요. 린트 명령에는 각 언어 안내서의 환경 워크플로를 따르세요. 필수 검사를 실행할 수 없다면 검증이 완료된 것처럼 암시하지 말고 변경 요청 요약에 차단 요인을 명시하세요. ## 리뷰는 심각한 버그와 보안 문제에 집중하기 기여자와 유지 관리자가 쓸 수 있는 주의력은 한정되어 있습니다. 검토는 간결하고 명확하게 유지하고, 가장 심각한 결함, 성능 회귀, 보안 문제에 집중하세요. 세부 변경 사항을 다시 설명하거나 이미 올바른 내용을 반복하지 마세요. 이름의 일관성, 확립된 오류 처리 방식, 테스트 커버리지를 확인하세요. 영향을 받은 위치를 인용하고 차단이 필요한 각 문제의 구체적인 결과를 설명하세요.