nixos-best-practices

Flakes を使用した NixOS システムの設定

Flakes を使用して NixOS システムを設定し、オーバーレイを適切に管理し、保守しやすい構成に整理します。

⚠️ 重要：変更する前にお読みください

NixOS の設定を変更する前に、必ず次のことを行ってください。

1. クイックリファレンスにある関連ルールファイルを確認する
2. よくある間違いを避けるため、common-mistakes.md を確認する
3. 体系的なデバッグ方法を把握するため、troubleshooting.md を確認する
4. コードベースにある既存のパターンに従う

該当するドキュメントを読むまでは、コーディングを始めないでください。

設定エラーのほとんどは、最初にルールを読まないことが原因で起こります。読むのにかかる5分で、何時間ものデバッグを省けます。

危険信号 — コーディングを始める前に中断してください

• 「このオプションを試せばいいだけ」 → nixpkgs または Home Manager に存在するか確認してください
• 「いろいろな方法を試してみよう」 → 推測せず、ドキュメントを読んでください
• 「これなら動くはず」 → nixpkgs で構文と利用可否を確認してください
• 何度もビルドを試みる → 体系的なデバッグができていません
• 「これは動くと覚えている」 → ドキュメントは更新されます。現在の方法を確認してください

基本原則

NixOS システム設定と Home Manager のオーバーレイの相互作用を理解してください。

useGlobalPkgs = true の場合、オーバーレイは Home Manager の設定ファイルではなく、NixOS の設定レベルで定義する必要があります。

使用する場面

• Flakes と Home Manager を使用して NixOS を設定する
• 適用されないように見えるオーバーレイを追加する
• カスタムオーバーレイと useGlobalPkgs = true を使用する
• 複数のホストにわたる NixOS 設定を整理する
• 再ビルド後もパッケージの変更が反映されない
• オーバーレイの定義場所がわからない

次の用途には使用しないでください。

• 新しいソフトウェアをパッケージ化する（nix-packaging-best-practices を使用してください）
• オーバーレイを使用せずにパッケージを簡単にインストールする
• NixOS モジュールを開発する（NixOS モジュールのドキュメントを参照してください）

クイックリファレンス

トピック	ルールファイル
オーバーレイのスコープと useGlobalPkgs	overlay-scope
Flakes の設定構造	flakes-structure
ホスト設定の整理	host-organization
パッケージインストールのベストプラクティス	package-installation
よくある設定ミス	common-mistakes
設定の問題のデバッグ	troubleshooting

基本パターン：useGlobalPkgs を使ったオーバーレイ

# ❌ WRONG: Overlay in home.nix (doesn't apply)
# home-manager/home.nix
{
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];  # Ignored!
  home.packages = with pkgs; [ claude-code ];  # Not found!
}

# ✅ CORRECT: Overlay in NixOS home-manager block
# hosts/home/default.nix
{
  home-manager.useGlobalPkgs = true;
  home-manager.useUserPackages = true;
  home-manager.users.chumeng = import ./home.nix;
  home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };
  # Overlay must be HERE when useGlobalPkgs = true
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];
}

よくあるタスク

タスク	解決方法
Flake の入力を追加する	flake.nix の inputs に追加します
システムパッケージ用のオーバーレイを追加する	システム設定の nixpkgs.overlays で定義します
Home Manager 用のオーバーレイを追加する（useGlobalPkgs=true）	ホスト設定の home-manager.nixpkgs.overlays で定義します
Home Manager 用のオーバーレイを追加する（useGlobalPkgs=false）	nixpkgs.overlays を使って home.nix で定義します
入力をモジュールに渡す	nixosSystem または home-manager で specialArgs を使用します
複数のホスト設定を管理する	hosts/ にホストごとのファイルを作成します
共通設定モジュールを管理する	modules/ にモジュールを作成し、各ホストでインポートします
オーバーレイ適用後もパッケージが見つからない	オーバーレイのスコープと useGlobalPkgs の設定を確認します

オーバーレイのスコープ選択表

useGlobalPkgs	オーバーレイの定義場所	影響範囲
true	home-manager.nixpkgs.overlays	システム + Home Manager のパッケージ
true	nixpkgs.overlays を使った home.nix	なし（無視されます！）
false	nixpkgs.overlays を使った home.nix	Home Manager のパッケージのみ
false	home-manager.nixpkgs.overlays	Home Manager のパッケージのみ
任意	システムの nixpkgs.overlays	システムパッケージのみ

設定レイヤー（下から上へ）

1. システム設定（/etc/nixos/configuration.nix またはホストファイル）

   • システム全体のサービス
   • システムパッケージ
   • システムオーバーレイはこのレイヤーにのみ影響します

2. Home Manager（useGlobalPkgs=true）

   • システムの pkgs を使用します（システムオーバーレイを含みます）
   • Home Manager のオーバーレイは、システムパッケージとユーザーパッケージの両方に影響します
   • 単一ユーザーのシステムで最も効率的です

3. Home Manager（useGlobalPkgs=false）

   • 個別の pkgs インスタンスを作成します
   • Home Manager のオーバーレイはユーザーパッケージにのみ影響します
   • ニーズが異なる複数ユーザーのシステムに適しています

要注意事項 — 作業を中断してください

• 「home.nix のオーバーレイが機能しない」→ useGlobalPkgs=true か確認し、ホスト設定に移動してください
• 「オーバーレイをあちこちに追加すればよい」→ 適切なスコープで一度だけ定義してください
• 「nix repl ではパッケージが機能するのに、インストールされない」→ オーバーレイのスコープを確認してください
• 「再ビルド後も変更が反映されない」→ オーバーレイの場所が正しいか確認してください
• 「理由もなく useGlobalPkgs=false にしている」→ パッケージセットを分ける必要がない限り、true を使用してください

使い方

詳しい説明とコード例については、各ルールファイルをお読みください。

rules/overlay-scope.md       # The core overlay scope issue
rules/flakes-structure.md    # How to organize flake.nix
rules/host-organization.md   # How to structure host configs
rules/common-mistakes.md     # Pitfalls and how to avoid them

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 補足情報と参考資料

完全版ドキュメント

すべてのルールを展開した完全なガイドは、AGENTS.md をご覧ください。