Agent-Skills.md

Agent Skills: Nix 공통 이슈

|

UncategorizedID: shren207/nixos-config/understanding-nix

Repository

shren207/nixos-config
greenheadHQ
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/greenheadHQ/nixos-config/tree/HEAD/.claude/skills/understanding-nix

Skill Files

Browse the full folder contents for understanding-nix.

Download Skill

Loading file tree…

.claude/skills/understanding-nix/SKILL.md

Skill Metadata

Name
understanding-nix
Description
|

Nix 공통 이슈

NixOS와 nix-darwin 모두에 해당하는 Nix 공통 개념 및 이슈입니다.

목적과 범위

flake 평가, derivation 해석, substituter/빌드 성능, 공통 오류 복구 절차를 다룬다.

빠른 참조

주요 설정 파일

| 파일 | 용도 | |------|------| | flake.nix | 입력과 출력 정의 (nixpkgs → nixos-unstable) | | flake.lock | 입력 버전 고정 | | modules/shared/configuration.nix | 공통 Nix 설정 (experimental-features, GC, substituter) | | modules/shared/programs/direnv/default.nix | direnv + nix-direnv 설정 | | lefthook.yml | Pre-commit hooks 정의 | | ~/.config/nix/nix.conf | 사용자별 Nix 설정 |

Flake 명령어

nfu                                       # fzf로 input 선택 → update → FOD fix → nrs (권장)
nfu -a                                    # 모든 input 일괄 업데이트
nix flake update <input-name>             # 수동: 특정 input만 업데이트
nix flake check --no-build --all-systems  # flake 평가 오류 검사

Experimental Features

experimental-features = nix-command flakes가 modules/shared/configuration.nix에서 시스템 전역 설정됨. 부트스트랩 전에는 --extra-experimental-features "nix-command flakes" 플래그 필요.

빌드 속도 최적화

| 방법 | 명령어/설정 | 효과 | |------|------------|------| | 오프라인 빌드 | nrs --offline | 네트워크 요청 없음 (~10초, 18배 빠름) | | 병렬 다운로드 | max-substitution-jobs = 128 | 동시 128개 다운로드 (기본 16) | | HTTP 연결 | http-connections = 50 | 동시 50 연결 (기본 25) | | 다운로드 버퍼 | download-buffer-size = 256 * 1024 * 1024 | 기본 64 MiB → 256 MiB | | GitHub 토큰 | access-tokens = github.com=... | rate limit 해제 |

에러 디버깅

nix build --show-trace                                   # 상세 빌드 로그
nix derivation show .#darwinConfigurations.<host>.system  # derivation 확인

핵심 절차

Flake 변경 반영

  1. git add . — Nix flakes는 git-tracked 파일만 인식한다.
  2. nix flake update <input-name> — 외부 input 갱신이 필요한 경우.
  3. nrs 또는 nrs --offline으로 빌드.

빌드 실패 진단

  1. --show-trace로 에러 원인 모듈을 좁힌다.
  2. nix derivation show로 derivation 구조를 확인한다.
  3. 수정 후 nrs로 재검증한다.

direnv + nix-direnv

프로젝트 디렉토리 진입 시 devShell 환경을 자동 활성화한다.

echo "use flake" > .envrc    # .envrc 생성 (nixos-config은 이미 커밋됨)
direnv allow                 # 최초 1회 허용
cd ~/Workspace/nixos-config  # 자동 활성화 (이후 이탈 시 자동 해제)
  • nix-direnv가 .direnv/에 결과를 캐싱 (첫 로드 ~수 초, 이후 ~100ms)
  • devShell 내 도구(gitleaks, lefthook 등)는 direnv 환경에서만 사용 가능

Pre-commit Hooks (lefthook)

| Hook | 도구 | 기능 | |------|------|------| | gitleaks | gitleaks protect --staged | 민감 정보 커밋 차단 | | nixfmt | nixfmt --check | Nix 포맷 검사 | | shellcheck | shellcheck -S warning | Shell 스크립트 린팅 | | eval-tests | tests/run-eval-tests.sh | NixOS 보안 검증 (~1.2s) | | flake-check (pre-push) | nix flake check | Flake 평가 오류 검사 |

direnv 환경이 비활성 상태에서 커밋하면 hook이 실패한다. direnv allow 실행으로 해결.

자주 발생하는 문제

  1. flake 인식 안 됨: git add 필요 (untracked 파일은 무시됨)
  2. experimental features 비활성화: nix-command flakes 활성화 필요
  3. 빌드 느림: nrs --offline 사용 또는 substituter 설정 확인
  4. gitleaks/lefthook not found: direnv 환경 미활성 — direnv allow 실행
  5. builtins.toJSON 한 줄 출력: pkgs.formats.json 사용으로 pretty-print

레퍼런스