크로스 플랫폼 툴체인 관리자를 개발하고 레지스트리에 올릴 도구를 심사하기

## 편집 전에 모듈 위치와 저장소 규칙 파악하기 저장소 가이드를 코딩 에이전트가 따라야 할 운영 규약으로 취급한다. 변경을 제안하기 전에 저장소 표준 명령, 모듈 경계, 기여 규칙, 호환성 요구 사항을 따른다. 다음 기능을 중심으로 작업 방향을 잡는다. - 명령줄 해석과 하위 명령 분배 - 계층화된 설정과 환경 변수 관리 - 도구 버전 해석과 설치 - 작업 정의와 실행 - 교체 가능한 백엔드와 내장 도구 구현 - 문서, 명령 자동 완성, 메타데이터 생성 편집하기 전에 진입점, 명령줄 인터페이스 모듈, 설정 모듈, 백엔드 인터페이스, 도구 집합 해석기, 작업 엔진, 플러그인 시스템, 공용 도우미를 찾는다. 공개 패키지와 작업 공간 내부를 지원하는 패키지를 구분한다. 직접 구현이 더 짧아 보인다는 이유만으로 기존 추상화를 우회하지 않는다. ## 널리 쓰인다는 근거가 있을 때만 도구를 레지스트리에 올리기 선별된 단축 이름 레지스트리는 이미 널리 사용되는 도구만 받아들인다고 가정한다. 코드가 작동하거나 테스트가 있거나 개인적으로 유용하다는 사실만으로는 등록 자격이 성립하지 않는다. 레지스트리 매핑을 수정하기 전에 다음을 수행한다. 1. 제출자 자신의 프로젝트 밖에서도 해당 도구가 널리 사용되는지 묻는다. 2. 개인용, 내부용, 포크, 틈새 도구이거나 소수 사용자만 지원한다면 중단한다. 3. 모든 레지스트리 제출에 대해 현재의 인기도 근거를 수집하고 절대 추측하지 않는다. 4. 저장소의 별표와 포크 수, 최근 커밋과 릴리스, 패키지 레지스트리의 다운로드 수, 독립 문서, 생태계 목록, 하위 프로젝트의 사용 사례를 확인한다. 5. 높은 등록 기준을 적용한다. 인기도는 수백이 아니라 수천 단위여야 하며, 활발한 유지 관리, 제3자 도입, 생태계 내 인지도를 요구한다. 6. 풀 리퀘스트 설명의 간결한 `Popularity` 섹션에 근거를 포함한다. 근거가 경계선에 있거나 부족하다면 명확히 경고하고, 그래도 계속할지 사용자에게 묻는다. 거절 시 설명, 이의 제기, 점검표, 두 번째 기회가 제공될 것처럼 암시하지 않는다. 관리자가 받아들일지 알아보기 위한 목적으로 추측성 제출을 절대 하지 않는다. ## 검증된 릴리스 파일을 우선해 설치용 백엔드 고르기 별도로 설치한 런타임 없이 검증된 릴리스 산출물을 사용하는 백엔드를 우선한다. 다음 순서로 결정한다. 1. 선별된 산출물 레지스트리가 검증 기능과 버전별 설치 로직을 제공한다면 이를 우선한다. 2. 그렇지 않으면 산출물을 배포하는 코드 호스팅 플랫폼용 직접 릴리스 백엔드를 사용한다. 3. 릴리스 백엔드가 도구를 지원할 수 없고 인기도가 여전히 충분히 입증된 경우에만 아카이브 배포 백엔드를 사용한다. 4. 언어 패키지 백엔드는 런타임의 가용성, 런타임 버전, PATH 순서에 의존하므로 예외로 취급한다. 5. 프로젝트의 공급망 정책을 위반하는 폐기 예정 백엔드와 새 플러그인 형식은 거부한다. 패키지 이름을 쉽게 찾을 수 있다는 이유만으로 불안정한 백엔드를 선택하지 않는다. 관리자가 해당 도구에 예외 백엔드를 명시적으로 승인하지 않았다면 레지스트리 제출에 사용하지 않는다. 레지스트리를 사용하지 않는 대안으로 명시적인 백엔드 좌표를 통한 설치 또는 지원되는 플러그인 작성을 설명한다. 차이를 명확히 유지한다. 레지스트리 단축 이름은 편의성을 높일 뿐, 설치를 가능하게 하는 필수 조건은 아니다. ## 빌드, 테스트, 린트를 저장소의 작업 실행기로 돌리기 기반 도구를 임의로 직접 호출하지 말고 저장소의 작업 실행기를 사용한다. 다음 용도로 문서화된 작업을 찾아 사용한다. - 전체 빌드와 디버그 바이너리 직접 실행 - 전체, 단위, 종단 간 테스트 모음 - 테스트 작업을 통한 특정 종단 간 테스트 파일 실행 - 스냅샷 검토와 갱신 - 린트 검사, 린트 자동 수정, 형식 정리 - 지속적 통합과 동일한 검사 - 문서, 사용법 텍스트, 명령 자동 완성, 스키마 생성 - 로컬 개발 버전 설치와 빌드 산출물 정리 - 올바른 작업 공간 디렉터리에서 실행하는 패키지별 테스트와 린트 검사 일반적인 로깅 변수를 가정하지 말고 프로젝트 전용 디버그 및 추적 환경 변수를 사용한다. 명령 이름이 확실하지 않으면 사용 가능한 작업을 나열한다. 테스트 하네스가 준비, 검증문, 정리를 담당한다면 종단 간 테스트 스크립트를 절대 직접 실행하지 않는다. 테스트 하네스가 격리를 보장한다면 테스트에 수동 정리 단계를 추가하지 않는다. 먼저 관련된 최소 작업을 실행하고, 공유 규약이나 생성 산출물이 영향을 받을 때만 검사 범위를 넓힌다. ## 생성된 파일을 손대지 않고 백엔드와 설정 추가하기 통합 백엔드 인터페이스를 통해 도구 소스를 구현한다. 각 백엔드는 해당 생태계의 버전 목록, 요청 해석, 설치, 도구 메타데이터를 책임져야 한다. 내장 도구는 핵심 플러그인 경계 안에 두고 외부 플러그인은 지원되는 호환 계층 뒤에 둔다. 환경별 재정의를 포함하여 시스템에서 전역을 거쳐 로컬 범위로 이어지는 계층적 설정 로드를 유지한다. 설정 정의에서 코드나 문서를 생성한다면 원본 정의를 갱신하고 표준 생성기를 실행한다. 생성된 결과를 직접 편집하는 방식을 주요 변경 방법으로 삼지 않는다. 의존 관계, 환경 변수, 지원 실행 모드를 포함해 작업 정의를 선언적으로 유지한다. 프로젝트가 상호 운용성을 보장하는 설정 파일은 그 호환 형식을 지킨다. 사용자 지정 빌드 스크립트, 작업 공간 구성 요소, 릴리스 프로필, 교차 컴파일 설정을 문서화된 역할과 일치시킨다. 백엔드를 추가할 때는 기존 백엔드 모듈 패턴에서 시작한다. 설정을 추가할 때는 타입이 지정된 해석 및 생성 경로를 따른다. 플러그인을 확장할 때는 병렬 메커니즘을 새로 만들지 말고 올바른 내장 또는 외부 경계를 사용한다. ## type(scope) 형식으로 커밋 메시지를 쓰고 먼저 린트 자동 수정하기 모든 커밋 메시지와 풀 리퀘스트 제목은 저장소의 규정 형식인 `type(scope): imperative description`을 사용해야 한다. 사용자에게 보이는 동작과 저장소의 책임 범위를 반영하는 type을 사용한다. - 새 기능에는 `feat` - 사용자에게 보이는 결함에는 `fix` - 해당 코드 변경에는 `refactor`, `style`, `perf` - test만 변경할 때는 `test` - 문서에는 `docs` - 유지 관리, 릴리스, 의존성, 인프라 변경에는 `chore` - 보안 관련 변경에는 `security` - 모든 레지스트리 매핑 변경에는 레지스트리 전용 type 명령별 변경에는 명령 이름을 범위로 사용하고 공유 구성 요소에는 하위 시스템 이름을 사용한다. 구현 파일이 다른 역사적 이름을 사용하더라도 작업 동작에는 작업 하위 시스템의 범위를 사용한다. 콜론 뒤의 설명은 소문자로 시작하고 명령형으로 작성하며 간결하면서도 구체적으로 유지한다. 문서화된 작업 환경을 통해 저장소의 사전 커밋 통합을 한 번만 설치한다. 커밋 전에 린트 자동 수정 작업을 실행하고, 그 결과 중 의도한 변경만 스테이징한다. 작업 실행기를 통해 범위를 지정한 종단 간 테스트를 실행한다. 관련 없는 형식 변경이나 생성 산출물을 스테이징하지 않는다. ## 문서 안내, 경고, 제거 순서로 기능을 단계적으로 폐기하기 단계적 폐기 정책을 사용한다. 1. 해당 기능이나 백엔드를 문서에서 즉시 폐기 예정으로 표시한다. 2. 문서화된 경고 기간이 지난 뒤 런타임 경고를 시작한다. 3. 문서화된 제거 기간이 지난 뒤 제거하도록 일정을 잡는다. 4. 프로젝트의 버전 날짜 형식으로 경고일과 제거일을 기록한다. 5. 기존 폐기 매크로를 사용하여 기한이 지난 제거 작업을 개발용 검증문으로 드러낸다. 일반적인 일정은 즉시 문서화하고 6개월 뒤 경고를 시작하며, 경고 시작 12개월 뒤 제거하는 것이다. 대체 기능이 오랫동안 제공되었다면 경고를 즉시 시작해도 된다. 문서화된 경고 단계를 거치지 않고 호환성을 조용히 제거하지 않는다. 기한이 지난 폐기 항목을 무기한 방치하지 말고 제거 검증문을 필수 유지 관리 작업으로 취급한다. ## 도구 버전의 해석과 정렬을 각 백엔드에 맡기기 도구 버전이 시맨틱 버전 관리나 그 밖의 보편적인 정렬 체계를 따른다고 절대 가정하지 않는다. 날짜 기반 버전, 사전 릴리스, 브랜치, 태그, 채널, 이름이 지정된 장기 지원 릴리스, 도구별 별칭을 고려한다. 새 호출 지점에서는 다음을 지킨다. - 최신 버전을 선택하거나 별칭을 해석하거나 버전 목록을 정렬할 때 범용 시맨틱 버전 비교기를 사용하지 않는다. - 도구의 버전 체계를 이해하는 백엔드 메서드에 요청 해석을 위임한다. - 설치된 버전을 의미 있는 순서로 나열할 때 백엔드 API 또는 도구 집합 API를 사용한다. - 잠금 파일의 버전 문자열을 불투명 값으로 취급하고 동등성만 비교한다. - 구체적인 값을 잠금 파일에 쓰기 전에 별칭, 채널, 접두사를 해석한다. - 문제가 있는 동작을 확대하는 근거로 기존 비교기 사용을 들지 않는다. 새 코드에서 설치된 최신 버전을 선택해야 할 것처럼 보이면 중단하고, 그 결정을 백엔드가 맡아야 하는지 확인한다. 잘못된 대체 경로의 우선순위는 잘못된 도구를 눈치채지 못한 채 설치하거나 실행할 수 있으므로 일치 항목을 반환하지 않는 것보다 나쁘다. ## 플랫폼별로 범위를 좁혀 테스트하고 마치기 전에 변경 내용 검토하기 단위 테스트는 소스 가까이에 두고 종단 간 테스트는 기능 영역별로 정리한다. 공용 검증 도우미, 안정적인 명령 출력용 스냅샷, 백엔드별 설치 검사, 명시적인 느린 테스트 이름을 사용한다. 플랫폼별 구현을 지정된 모듈과 플랫폼 테스트 모음에 둔다. Windows에서 Unix 실행 권한 비트의 동작을 가정하지 않는다. 변경할 때는 가장 좁은 관련 경로부터 검증한다. 1. 형식 정리와 정적 검사를 실행한다. 2. 테스트 하네스를 통해 범위를 지정한 단위 테스트 또는 종단 간 테스트를 실행한다. 3. 스냅샷 변경을 무조건 받아들이지 말고 검토한다. 4. 원본 정의가 바뀌면 파생 문서나 스키마를 다시 생성한다. 5. 공유 백엔드, 설정, 작업, 크로스 플랫폼 규약이 바뀌면 더 넓은 통합 검사로 확장한다. 외부 풀 리퀘스트나 토론에 게시할 때는 해당 댓글이 AI 코딩 도우미에 의해 생성되었음을 밝힌다. 문서 디렉터리 계층과 일치하는 URL을 사용한다. 필수 섹션을 생략한 축약 경로를 만들지 않는다. 완료하기 전에 차이를 검토하여 추상화 누출, 지원되지 않는 버전 정렬, 생성기 실행 누락, 관련 없는 변경, 검증되지 않은 외부 주장이 없는지 확인한다.