diff --git a/CLAUDE.md b/CLAUDE.md
index 105ec4a..d6b6aa0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,6 +46,15 @@ bosun.secrets.npmrc = { ... };       # Secret definitions
 
 Profile definitions are in `modules/generic/profiles.nix`, implementations in `modules/nixos/profiles/`.
 
+## Adding packages
+
+Before writing a custom `packages/` derivation, always check if the package already exists in nixpkgs:
+- Stable: https://search.nixos.org/packages?channel=25.11&query=<name>
+- Unstable: https://search.nixos.org/packages?channel=unstable&query=<name>
+- Master (bleeding edge): check open PRs at https://github.com/NixOS/nixpkgs/pulls
+
+If it exists in `unstable` or `master` but not stable, pull it via `overlays/unstable.nix` using `channels.unstable` or `channels.master`. Only write a custom `packages/` derivation as a last resort.
+
 ## Architecture patterns
 
 - **import-tree** auto-discovers and imports `.nix` files in `modules/flake/`. Files prefixed with `_` are excluded from auto-import.