@@ -1,15 +1,14 @@
# AGENTS.md
NixOS + Home Manager flake。v2 リセット中 — flake-parts 導入済み、outputs はまだスケルトンのみ 。
NixOS + Home Manager flake (v2)。flake-parts ベース 。
## Commands
``` sh
# flake の更新
nix flake update
# フォーマット
nix fmt
nix flake update # flake の更新
nix fmt # フォーマット
sudo nixos-rebuild build --flake .#<host> # ビルド確認
sudo nixos-rebuild switch --flake .#<host> # 適用
```
## Conventions
@@ -17,67 +16,170 @@ nix fmt
- User: `moons` , locale: `ja_JP.UTF-8` , timezone: `Asia/Tokyo`
- Commits: conventional commits (`feat:` , `chore:` , `fix:` , etc.)
- リモート: `[email protected] :moons-14/dotfiles.git`
- `modules/system/` や `modules/applications/` に新しいファイルを追加した際は、必ず同ディレクトリの `default.nix` の `imports` に 追加する
- `environment.systemPackages` にパッケージを追加する際は、パッケージ名の横に簡単な説明をコメントで追加 する
- `environment.systemPackages` にパッケージを追加する際はパッケージ名の横に簡単な説明をコメントで 追加する
- 警告を抑制する設定は書かない。根本原因を調査して修正 する
- home-manager の `sharedModules` 内で `lib.hm.*` を使う場合は、そのモジュール関数の引数で `lib` を受け取る必要がある（NixOSモジュールの `lib` とは別スコープ）
- `useGlobalPkgs = true` なので、home-manager 内で `nixpkgs.config` を設定しない（NixOSレベルで一括設定）
- `allowUnfree` は `hosts/default.nix` でグローバルに設定済み。各モジュールで個別設定しない
## Module Stru cture
## Archite cture
### `modules/system/ `
`` `
flake.nix
└── hosts/default.nix # mkSystem でホスト構成を生成
├── modules/ # 全モジュール（常にインポートされる）
│ ├── applications/ # アプリケーション設定
│ ├── system/ # システム設定
│ ├── drivers/ # ドライバ設定
│ ├── features/ # 機能バンドル（application/systemを束ねる）
│ └── integrations/ # home-manager 統合
└── profiles/ # ホストごとに有効化するfeaturesの組み合わせ
├── interfaces/ # 操作インターフェース (CLI/GUI)
├── platforms/ # ハードウェア (desktop/laptop/vm)
└── workloads/ # 用途 (dev/personal/srv)
```
システムレベル（NixOS）の設定。OS 全体に影響する設定を配置する。
### 評価の流れ
- 例: boot, hardware, network, user, locale, fonts, power, secure-boot, caches, gc, version
```
profile (featuresの有効化)
→ features (application/systemの有効化 + パッケージ追加)
→ applications (system.nix + home.nix)
→ system (NixOS設定)
```
### `modules/applications/`
## Layer Design
アプリケーション固有の設定。ユーザーが個別に有効/無効を切り替えたいアプリケーションを配置する。
### `modules/system/` — NixOS システム設定
- 例: niri, noctalia, greetd, fcitx5, kde, wayland
OS全体に影響する設定。`config.my.system.*` namespace。
### Module Patter n
- boot, hardware, network, user, locale, fonts, power, secure-boot, gc, versio
- 常にインポートされるが、`enable` オプションで実効性を制御
- home-manager の設定は含めない
`modules/system/` と `modules/applications/` のモジュールは、デフォルトで `config.my.*` namespace で有効/無効を切り替えられる仕組みにする。
### `modules/applications/` — アプリケーション設定
#### Simple Module (NixOS のみ)
個別に有効/無効を切り替えたいアプリケーション。`config.my.applications.*` namespace。
h ome-m anager の設定を含まないモジュール:
- NixOS設定のみ、または NixOS + H M anager の両方
- Complex Module は system.nix と home.nix に分離
### `modules/features/` — 機能バンドル
application や system より抽象度の高い「機能」単位で、複数の application/system を束ねて有効化する層。`config.my.features.*` namespace。
**features がやること: **
1. 複数の `my.applications.*.enable` / `my.system.*.enable` をまとめて有効化
2. application/system に属さないパッケージや設定を直接記述（`environment.systemPackages` 、`home.activation` 等）
3. 追加オプションの受け渡し（例: tailscale の `acceptDns` を feature から application に passthrough）
**features がやらないこと: **
- 個別アプリケーションの詳細設定（それは applications 層の責務）
### `profiles/` — ホスト構成
features の `enable` を指定するだけの薄い層。ロジックは書かない。
| カテゴリ | 役割 | 例 |
| ------------- | -------------------- | --------------------------------- |
| `interfaces/` | 操作インターフェース | cli-minimal, cli-interactive, gui |
| `platforms/` | ハードウェア固有設定 | desktop, laptop, thinkpad, vm |
| `workloads/` | 用途・ワークロード | dev, personal, srv |
profiles は継承可能:
``` nix
# cli-interactive.nix
{
lib ,
config ,
. . .
}:
imports = [ ./cli-minimal.nix ] ;
my . features . cli . interactive . enable = true ;
}
```
### `hosts/` — ホスト定義
`mkSystem` でホストを定義。profiles のリストを指定:
``` nix
nix-example = mkSystem {
host = " n i x - e x a m p l e " ;
system = " x 8 6 _ 6 4 - l i n u x " ;
profiles = [
" i n t e r f a c e s / c l i - i n t e r a c t i v e "
" p l a t f o r m s / v m "
" w o r k l o a d s / d e v "
] ;
} ;
```
`specialArgs` で `inputs` , `username` , `unstable` , `host` が全モジュールに渡される。
## Module Patterns
### Simple Module（
home-manager の設定を含まない。1ファイルで完結:
``` nix
# modules/system/audio.nix
{ lib , config , . . . }:
let
cfg = config . my . <category> . <name> ;
cfg = config . my . system . audio ;
in
{
options . my . <category> . <name> = {
enable = lib . mkEnableOption " < d e s c r i p t i o n > " ;
options . my . system . audio = {
enable = lib . mkEnableOption " A u d i o s u p p o r t ( P i p e W i r e ) " ;
} ;
config = lib . mkIf cfg . enable {
# configuration here
# NixOS設定をここに書く
} ;
}
```
- `my.system.*` — system モジュール用
- `my.applications.*` — applications モジュール用
### Simple Module（
#### Complex Module (NixOS + H ome M anager)
NixOS設定を含まず、h ome-m anager のみ:
home-manager の設定も含むモジュールは3つのフラグを設定する:
``` nix
# modules/applications/zoom.nix
{ pkgs , lib , config , . . . }:
let
cfg = config . my . applications . zoom ;
in
{
options . my . applications . zoom = {
enable = lib . mkEnableOption " Z o o m v i d e o c o n f e r e n c i n g " ;
} ;
config = lib . mkIf cfg . enable {
home-manager . sharedModules = [
{
home . packages = with pkgs ; [
zoom-us # Video conferencing application
] ;
}
] ;
} ;
}
```
### Complex Module（ ）
ディレクトリ構造で system と home を分離:
```
modules/applications/<app>/
├── default.nix # my.applications.<app>.enable (マスター)
├── system.nix # my.applications.<app>.system.enable
├── home.nix # my.applications.<app>.h omeManager.enable
├── default.nix # マスター enable + imports
├── system.nix # NixOS 設定
├── home.nix # H ome Manager 設定
└── (other files) # 設定ファイル等
```
` default.nix`
** default.nix** — `enable` のみ宣言。 `system.enable` / `homeManager.enable` は sub-file に任せる :
``` nix
{
@@ -89,17 +191,15 @@ let
cfg = config . my . applications . <name> ;
in
{
imports = [
./home.nix
./system.nix
] ;
options . my . applications . <name> = {
enable = lib . mkEnableOption " < d e s c r i p t i o n > " ;
system . enable = lib . mkEnableOption " < d e s c r i p t i o n > s y s t e m c o n f i g u r a t i o n " ;
homeManager . enable = lib . mkEnableOption " < d e s c r i p t i o n > h o m e - m a n a g e r c o n f i g u r a t i o n " ;
} ;
imports = [
./system.nix
./home.nix
] ;
config = lib . mkIf cfg . enable {
my . applications . <name> . system . enable = lib . mkDefault true ;
my . applications . <name> . homeManager . enable = lib . mkDefault true ;
@@ -107,4 +207,194 @@ in
}
```
マスターの `enable` を有効にすると、`lib.mkDefault` で system と homeManager の両方が有効化される。個別に無効化も可能。
**system.nix: **
``` nix
{
pkgs ,
lib ,
config ,
. . .
}:
let
cfg = config . my . applications . <name> . system ;
in
{
options . my . applications . <name> . system = {
enable = lib . mkEnableOption " < n a m e > s y s t e m c o n f i g u r a t i o n " ;
} ;
config = lib . mkIf cfg . enable {
environment . systemPackages = with pkgs ; [
<package> # Description
] ;
} ;
}
```
**home.nix ** — `home-manager.sharedModules` を使用:
``` nix
{
lib ,
config ,
. . .
}:
let
cfg = config . my . applications . <name> ;
hmCfg = config . my . applications . <name> . homeManager ;
in
{
options . my . applications . <name> . homeManager = {
enable = lib . mkEnableOption " < n a m e > h o m e - m a n a g e r c o n f i g u r a t i o n " ;
} ;
config . home-manager . sharedModules = [
{
config = lib . mkIf hmCfg . enable {
# home-manager 設定をここに書く
} ;
}
] ;
}
```
**注意点: **
- `default.nix` では `enable` のみ宣言。`system.enable` /`homeManager.enable` は `system.nix` /`home.nix` で宣言する（重複宣言エラー回避）
- home.nix で親の `cfg` を参照する場合は `cfg` と `hmCfg` の両方を let で定義
- Complex Module の home-manager 設定は `home-manager.sharedModules` で記述（`home-manager.users.<user>` は使わない）
### Feature Module
**application/system を束ねる場合: **
``` nix
# modules/features/services/container.nix
{ lib , config , . . . }:
let
cfg = config . my . features . services . container ;
in
{
options . my . features . services . container = {
enable = lib . mkEnableOption " C o n t a i n e r r u n t i m e ( D o c k e r ) " ;
} ;
config = lib . mkIf cfg . enable {
my . applications . docker . enable = true ;
} ;
}
```
**パッケージを直接追加する場合（application/system に属さない）: **
``` nix
# modules/features/gui/capture.nix
{ pkgs , lib , config , . . . }:
let
cfg = config . my . features . gui . capture ;
in
{
options . my . features . gui . capture = {
enable = lib . mkEnableOption " S c r e e n c a p t u r e t o o l s " ;
} ;
config = lib . mkIf cfg . enable {
environment . systemPackages = with pkgs ; [
slurp # Tool for selecting a region of the screen
grim # Screenshot tool for Wayland
] ;
} ;
}
```
**オプションを passthrough する場合: **
``` nix
# modules/features/network/tailscale.nix
{
options . my . features . network . tailscale = {
enable = lib . mkEnableOption " T a i l s c a l e V P N " ;
acceptDns = lib . mkOption { type = lib . types . bool ; default = false ; } ;
} ;
config = lib . mkIf cfg . enable {
my . applications . tailscale = {
enable = true ;
inherit ( cfg ) acceptDns ;
} ;
} ;
}
```
**home.activation を使う場合（identity 等）: **
``` nix
# modules/features/identity/ssh-default-key.nix
config . home-manager . sharedModules = [
(
{ lib , . . . }:
{
config = lib . mkIf cfg . enable {
home . activation . generateSshKey = lib . hm . dag . entryAfter [ " w r i t e B o u n d a r y " ] ''
# s h e l l s c r i p t h e r e
'' ;
} ;
}
)
] ;
```
### Profile
features の有効化のみを記述:
``` nix
# profiles/platforms/laptop.nix
{
my . features = {
boot . power . enable = true ;
connect = {
wifi . enable = true ;
bluetooth . enable = true ;
} ;
gui . camera . enable = true ;
identity . fingerprint . enable = true ;
network . tailscale . enable = true ;
} ;
}
```
## Adding New Features — Checklist
### 新しいアプリケーションを追加する場合
1. `modules/applications/` にモジュール作成（Simple or Complex）
2. `modules/applications/default.nix` の `imports` に追加
3. `modules/features/` の適切なカテゴリに feature を作成（既存の feature に追記でも可）
4. `modules/features/<category>/default.nix` の `imports` に追加
5. `profiles/` の適切な profile で feature を有効化
### 新しいシステム設定を追加する場合
1. `modules/system/` にモジュール作成（Simple Module）
2. `modules/system/default.nix` の `imports` に追加
3. `modules/features/` の適切なカテゴリに feature を作成
4. `modules/features/<category>/default.nix` の `imports` に追加
5. `profiles/` の適切な profile で feature を有効化
### 新しいホストを追加する場合
1. `hosts/<hostname>/default.nix` を作成（`hardware-configuration.nix` を import）
2. `hosts/default.nix` の `flake.nixosConfigurations` に `mkSystem` で追加
3. profiles のリストを指定
## Key Technical Notes
- **nixpkgs channel**: `nixos-26.05` (stable) + `nixpkgs-unstable`
- **unstable パッケージ**: `specialArgs.unstable` 経由で参照（`unstable.<pkg>` ）
- **llm-agents**: `inputs.llm-agents.packages.${pkgs.stdenv.hostPlatform.system}.<name>` で参照
- **nixvim**: `nixpkgs.source = pkgs.path` と `nixpkgs.config.allowUnfree = true` を vim/home/default.nix で設定
- **home-manager**: `useGlobalPkgs = true` , `useUserPackages = true`
- **hostname**: `specialArgs.host` から `modules/system/network/default.nix` で `networking.hostName` に設定
- **stateVersion**: `config.my.stateVersions.nixos` / `config.my.stateVersions.homeManager` で管理（`modules/system/version.nix` ）
