add CLAUDE.md with repo philosophy: batteries-loaded macOS rice

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-25 12:42:32 +08:00
parent ed52bf7b93
commit 11cc64bd4c
1 changed files with 69 additions and 0 deletions
@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+A batteries-loaded macOS rice — cross-platform Nix configuration (nix-darwin + NixOS + home-manager) for user `df`. The active system is `m2n1` — an Apple Silicon Mac running nix-darwin.
+
+## Philosophy
+
+This repo strives for the **best possible macOS setup** with seamless UX:
+
+- **Better defaults everywhere** — keyboard, trackpad, Dock, Finder, screenshots, window management, etc. If macOS has a bad default, override it.
+- **Batteries included** — tools, shell plugins, keybindings, and integrations should work out of the box. No manual post-install steps.
+- **Rice it** — the setup should look and feel polished. Consistent theming, clean status bars, good typography.
+- **Research before implementing** — when adding or changing something, check the internet for the best current practices, latest options, and what power users recommend. Don't guess.
+- **Test it works** — after making changes, run `darwin-rebuild switch` and verify the setting actually took effect (e.g. `defaults read` for macOS prefs). The UX should be seamless.
+- **Stay current** — nix-darwin, home-manager, and macOS evolve. When touching a module, check if there are newer/better options available.
+
+## Build Commands
+
+```bash
+# Primary build+switch for macOS (requires sudo)
+sudo darwin-rebuild build --flake ~/bankrupt/#m2n1
+sudo darwin-rebuild switch --flake ~/bankrupt/#m2n1
+
+# Or via Makefile (auto-detects hostname)
+make darwin-switch
+
+# Update flake inputs
+make update
+
+# Format nix files
+nix fmt
+
+# Validate flake
+nix flake check
+```
+
+## Architecture
+
+```
+flake.nix                    # Entry point: inputs, overlays, system configs
+├── common.nix               # Shared nix settings (caches, overlays, GC)
+├── darwin/configuration.nix  # m2n1 system config (imports yabai.nix, skhd.nix)
+├── nixos/configuration.nix   # Template NixOS config
+├── overlays/default.nix      # Package overlays (emacs, unstable, custom)
+└── home-manager/
+    ├── home.nix             # Imports all modules below
+    ├── common.nix           # Base home-manager settings
+    ├── platform/            # darwin.nix / linux.nix (conditional via stdenv.isDarwin)
+    └── modules/             # Feature modules: git, shells, fish, tmux, kitty, neovim, doom-emacs
+        └── inbox/           # packages.nix (large package list), inbox.nix (dev tools)
+```
+
+## Key Patterns
+
+- **Platform conditionals**: `lib.mkIf pkgs.stdenv.isDarwin` / `lib.mkIf pkgs.stdenv.isLinux`
+- **Flake inputs**: nixpkgs 25.05, home-manager release-25.05, nix-darwin darwin-25.05
+- **Determinate Nix**: `nix.enable = false` in darwin config (conflicts with nix-darwin's daemon)
+- **Overlays** in `overlays/default.nix` feed into `common.nix` and are applied system-wide
+
+## Workflow Notes
+
+- To add a new package: edit `home-manager/modules/inbox/packages.nix` (user-level) or `darwin/configuration.nix` (system-level)
+- To add a new tool module: create `home-manager/modules/<tool>.nix` and import it in `home-manager/home.nix`
+- When build fails, read the error output carefully — common issues are hash mismatches (run `nix flake update`) or missing inputs
+- **After changing `system.defaults`**: run `darwin-rebuild switch`, then verify with `defaults read <domain> <key>`. Some settings need a logout/restart to take effect.
+- **When adding a new default or tool**: search the web for current best practices before implementing. Check nix-darwin options, popular dotfile repos, and macOS power-user guides.