diff --git a/CLAUDE.md b/CLAUDE.md
index 1dbf28e..e776ebc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -94,6 +94,15 @@ Update the `const version` in `main.go`. The Nix build extracts the version from
 
 **When to bump**: If any Go code has changed, bump the version before committing. Do this automatically when asked to commit. On feature branches, only bump once per branch (check if version has already been bumped compared to master).
 
+## Documentation
+
+When adding new features, always update `README.md` to include:
+
+- New CLI flags (add to the CLI Flags table)
+- New NixOS module options (add to the NixOS Module Options example)
+- New metrics (add to the appropriate Metrics table)
+- Major features that need explanation (add a dedicated section)
+
 ## Key Design Decisions
 
 - Go chosen for mature Prometheus client library and static binary output