diff --git a/CLAUDE.md b/CLAUDE.md
index 785e93e..e26d6f9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -80,6 +80,13 @@ utils/pkgs/<package-name>/
 └── (other files like patches, lock files)
 ```
 
+**IMPORTANT: When modifying a custom package** (patches, version updates, etc.), always test by building the package directly, not just running `test-configuration`. The configuration test only checks that the Nix expression evaluates, but doesn't verify the package actually builds:
+
+```bash
+# Build a custom package directly to verify it works
+nix-build -E 'with import <nixpkgs> { overlays = [ (import ./utils/overlays/packages.nix) ]; config.allowUnfree = true; }; <package-name>'
+```
+
 ## Workflow
 
 **IMPORTANT: Always run `./scripts/test-configuration <hostname>` after making any changes** to verify the NixOS configuration builds successfully. This is required before committing.