Shangshui0302/some-NixOS-skills

Nix 패키지 개발

철칙: 대상 Nixpkgs 인터페이스와 업스트림 소스/릴리스 증거를 기록하기 전까지 패키지 표현식을 변경하지 마십시오. 증거 없이 빌드하는 것은 재현 가능한 패키징 결과가 아닙니다.

다음과 같은 적신호가 나타나면 증거 단계로 돌아가십시오:

• 단일 마커 파일이나 메모리만으로 빌더를 선택했습니다.
• 유동 채널, 레지스트리 결과 또는 "최신" URL이 유일한 소스 증거입니다.
• 해시, 래퍼, 데스크탑 항목 또는 런타임 종속성을 추측했습니다.
• nix develop는 성공했지만, 파생물, 출력 레이아웃 또는 실행 파일이 빌드되지 않았습니다.
• 성공적인 dry-build가 배포 또는 라이브 런타임 테스트로 보고되었습니다.

범위 경계

이 스킬은 패키지 표현식, 빌드 입력, 출력 계약 및 패키지 관련 플레이크 또는 오버레이 통합을 담당합니다. NixOS/Home Manager 모듈은 소비자로 취급하십시오: 해당 패키지 인터페이스를 검사하고 범위 내에 있을 때 dry-build를 수행하되, 시스템 구성 및 활성화는 nixos-ecosystem에 맡기십시오.

요청이 업스트림 NixOS/nixpkgs 유지보수 프로세스(예: 업데이트 또는 손상 분류, 패키지 채택, 영향받는 종속성 확인, 또는 nixpkgs PR 준비)를 대상으로 할 경우 nixpkgs-maintainer를 사용하십시오. 둘 다 관련된 경우, 이 스킬은 파생물 증거를 제공하고 유지보수 스킬이 업스트림 워크플로우를 담당합니다.

진행 상황 체크리스트

작업 노트에 이 체크리스트를 복사하고 작업이 진행됨에 따라 표시하십시오:

• 단계 0: 저장소 정책 로드 및 범위 정의 ⚠️ 필수
  • AGENTS.md, 기여 규칙, 더티 파일, 패키지 소비자 및 요청된 관찰 가능한 동작을 찾으십시오.
  • 작업을 추가, 업그레이드, 수리 또는 리뷰로 분류하십시오.
  • 표현식이 패키지 저장소, 독립 파일, 플레이크, 오버레이 또는 nixpkgs 트리에 있는지 식별하십시오.
• 단계 1: 신선도 게이트 통과 ⛔ 차단
  • flake.lock, 고정된 패키지 저장소 입력 또는 nixpkgs 체크아웃에서 대상의 nixpkgs 리비전을 기록하십시오. 없는 경우 대체 방법을 명시하십시오.
  • 고정된 빌더/헬퍼 인터페이스를 검사하고 현재 공식 문서와 비교하십시오.
  • 드리프트 및 마이그레이션 영향을 보고하십시오. 더 오래된 잠금에 최신 API를 조용히 적용하지 마십시오.
• 단계 2: 소스 및 패키지 증거 수집 ⚠️ 필수
  • 대상 트리, 관련 nixpkgs 입력, 오버레이 및 기존 헬퍼에서 기존 패키지 또는 구현을 검색하십시오.
  • 업스트림 태그/커밋, 빌드 명령어, CI, 라이선스, 플랫폼, 아티팩트, 실행 파일 이름 및 설치 레이아웃을 확인하십시오.
  • 가장 좁은 경로를 선택하십시오: 소스, 사전 빌드된 ELF, AppImage, Electron/ASAR, 데이터, 폰트/테마 또는 플러그인.
• 단계 3: 최소 계획 제시 ⚠️ 중요하지 않은 편집에는 필수
  • 파일, 종속성, 위험, 확인 명령어 및 검증되지 않은 항목을 명시하십시오.
  • 파괴적 편집, 설치, 시스템 활성화, 커밋, 푸시 또는 PR 생성 전에 허가를 구하십시오.
• 단계 4: 가장 작은 파생물 구현
  • pname, version, 소스/리비전 및 SRI 해시를 고정하십시오. URL 및 파일 이름에서 pname/version을 일관되게 사용하십시오.
  • 가장 좁은 nixpkgs 빌더와 기본 단계를 사용하십시오. 사용자 정의 단계는 해당하는 훅을 실행해야 합니다.
  • 빌드 도구, 링크/런타임 라이브러리, 테스트 도구 및 래퍼 제공 명령어를 분리하십시오.
  • GUI 통합을 하나의 단위로 완료하십시오: 래퍼, 데스크탑 항목, 아이콘, Exec 및 런타임 플래그.
  • 대상의 기존 패키지 표면(플레이크 출력, 오버레이 또는 패키지 속성)을 범위 내에 있을 때만 보존하거나 노출하십시오.
• 단계 5: 계층별 확인 ⚠️ 필수
  • 구문 분석, 평가/확인, 빌드, 저장소 출력 검사 및 하나의 안전한 스모크 테스트를 수행하십시오.
  • 패키지가 NixOS/Home Manager에 통합된 경우에만 시스템 dry-build를 실행하십시오.
  • 빌드, 스모크, dry-build 및 활성화 후/라이브 상태를 별도로 유지하십시오.
• 단계 6: 보고 및 유지보수
  • 증거, 변경된 파일, 해시, 검사, 차단 요소 및 정확한 수동 다음 단계를 보고하십시오.
  • 업그레이드의 경우 변경 로그, 잠금 파일, 라이선스, 아티팩트 레이아웃 및 모든 해시를 다시 확인하십시오.
  • 업데이트 경로가 안정적이고 결정론적임이 입증된 후에만 업데이트 스크립트를 추가하십시오.

신선도 게이트

빌더를 선택하거나 새 해시를 작성하기 전에 references/freshness-and-evidence.md를 로드하십시오. GitHub 조사에는 gh를 사용하십시오. API 사실에는 고정된 nixpkgs 소스를 선호하고, 프로세스 변경을 감지하려면 현재 공식 Nixpkgs/nix.dev 문서를 사용하십시오. 이들이 불일치할 경우, 변경 사항이 잠금 호환 가능한지, 잠금 업데이트가 필요한지, 또는 문서화된 예외로 남아야 하는지 설명하고 일시 중지하십시오.

빌더 및 구현 라우팅

증거 단계 후 references/builder-routing.md의 관련 섹션만 로드하십시오. 알 수 없는 단계 실패를 숨기기 위해 광범위한 종속성 세트를 추가하지 마십시오. 유지 관리 가능한 경우 소스 빌드를 선호하고, 업스트림 소스 경로를 사용할 수 없거나 실질적으로 덜 신뢰할 수 있는 경우에만 릴리스 바이너리 또는 AppImage를 사용하십시오.

사용자 정의 buildPhase, checkPhase 또는 installPhase의 경우 해당하는 runHook preX 및 runHook postX를 보존하십시오. 사전 빌드된 네이티브 코드의 경우, 출처를 기록하고 아키텍처, 인터프리터, NEEDED 라이브러리 및 번들 구성 요소 라이선스를 검사하십시오.

검증

패키지 유형 매트릭스 및 출력 검사에 대해서는 references/validation.md를 로드하십시오. 대상의 패키지 표면에 맞게 다음 검사를 조정하십시오:

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # 대상이 플레이크를 노출하는 경우
nix build path:.#pname -L --no-link --print-out-paths  # 대상 출력 이름 사용
git diff --check

패키지가 NixOS/Home Manager 구성에 연결된 경우 다음도 실행하십시오:

nixos-rebuild dry-build --flake path:.

scripts/validate-skill.py를 사용하여 이 스킬 저장소 자체를 확인하십시오. 이는 결정론적 린트이며 대상 패키지 빌드를 대체하지 않습니다.

사용자가 소비자 이름 없이 "검증 실행"을 요청할 경우, 기본적으로 패키지 평가, 빌드, 출력 검사 및 안전한 스모크 테스트를 수행하십시오. 해당 소비자가 범위 내에 있을 때만 NixOS/Home Manager 또는 다른 소비자 dry-build를 추가하십시오.

업그레이드 및 신선도 유지보수

반복 업데이트에 대해서는 references/update-policy.md를 로드하십시오. 소스 및 문서 입력을 고정하고, 업데이트 검사를 명시적으로 만들며, 자동 작업을 기본적으로 읽기 전용으로 유지하십시오. 자동화된 작업은 검사 통과 후 검토 가능한 업데이트 변경 사항을 열 수 있지만, 스킬을 조용히 다시 쓰거나, 시스템을 전환하거나, 커밋하거나, 푸시해서는 안 됩니다.

네 가지 구체적인 요청 형태

요청이 모호할 경우 references/examples.md를 로드하십시오. 지원되는 형태는 다음과 같습니다: 패키지 저장소, 독립 표현식, 플레이크 또는 오버레이에 패키지 추가; 기존 파생물 업그레이드 및 소스/종속성 해시 새로 고침; 사전 빌드/AppImage, Electron, 폰트/테마 또는 플러그인 패키지 수리; 기존 플레이크 또는 오버레이를 통해 소비자용 패키지 통합.

안티 패턴

• nix develop 성공을 nix build가 작동한다는 증거로 사용하지 마십시오.
• Cargo.toml, package.json 또는 추측된 하나의 종속성만으로 빌더를 선택하지 마십시오.
• 샌드박스 빌드 중에 온라인에서 종속성을 가져오지 마십시오(cargo fetch, npm install, pip install 등).
• 유동 소스 URL, 가변 브랜치, 구식 해시 또는 표현식 전체에 중복된 버전 리터럴을 사용하지 마십시오.
• autoPatchelfIgnoreMissingDeps, 기본 FHS 래퍼 또는 과도한 buildInputs 목록으로 누락된 라이브러리를 숨기지 마십시오.
• 파생물만 빌드되었을 때 데스크탑, IPC, 재생, Wayland 또는 컴포지터 동작이 테스트되었다고 주장하지 마십시오.
• 패키지 표현식 검사를 nixpkgs 통합 또는 PR 리뷰로 취급하지 마십시오. 해당 업스트림 워크플로우에는 nixpkgs-maintainer를 사용하십시오.
• 명시적 승인 없이 nixos-rebuild switch, 커밋, 푸시, 파일 삭제 또는 PR 생성을 실행하지 마십시오.

전달 형식

간결한 증거 보고서를 반환하십시오:

1. 범위 및 경로 — 대상 저장소/공개 표면, 작업 유형, 패키지 유형 및 이 빌더를 선택한 이유.
2. 증거 — 고정된 nixpkgs 리비전/API, 업스트림 리비전/아티팩트/라이선스 및 관련 해시.
3. 변경 사항 — 패키지 표현식, 플레이크 또는 오버레이 표면, 소비자 및 문서.
4. 검증 — 구문 분석, 플레이크 확인, 빌드, 출력/스모크, dry-build 및 라이브 상태를 별도로.
5. 다음 조치 — 여전히 필요한 정확한 수동 명령어 또는 사용자 결정.

필수 검사가 누락된 상태에서 패키지를 "완료"라고 부르지 마십시오. 대신 차단 요소와 가장 작은 다음 실험을 표시하십시오.