diff --git a/AGENTS.md b/AGENTS.md
index 2a5e4af..8cefd2d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,4 +125,6 @@ These features are product requirements, not “nice to have” ideas.
 
 - Keep `golangci-lint` passing.
 - Keep `go test ./...` passing.
+- When running tests or other automated validation that may touch persisted UI state, set `KEEPASSGO_STATE_DIR` to an isolated temporary directory so recent-vault history and other local state do not pollute the user’s real config.
+- Prefer commands shaped like `KEEPASSGO_STATE_DIR=\"$(mktemp -d)\" go test ./...` for ad hoc local validation unless a test already manages its own isolated state directory.
 - Do not commit generated binaries.