diff --git a/agents.md b/agents.md
index 12a5e25..56c13ac 100644
--- a/agents.md
+++ b/agents.md
@@ -47,6 +47,23 @@ This repository is a browser-first photo mapping prototype.
 - Verify the result with `git diff --check` when possible.
 - Update the README only when the user-facing setup or features change.
 
+## Practical Best Practices
+
+- Prefer incremental changes over large rewrites.
+- Keep naming consistent within a feature, especially for UI state and DOM references.
+- Separate data handling, rendering, and network access where practical.
+- Treat share loading, image parsing, and metadata extraction as failure-prone paths.
+- Handle missing EXIF data, empty shares, and partial import results gracefully.
+- Keep browser work lightweight; avoid unnecessary re-renders or duplicate downloads.
+- Reuse existing helpers and structures before introducing new abstractions.
+- Prefer plain, readable TypeScript over clever patterns.
+- Add comments only where the code would otherwise be hard to follow.
+- Preserve backward compatibility for the public import flow when possible.
+- If a change affects user-visible text, keep the tone short, clear, and professional.
+- If a change affects the UI, check the result at both desktop and mobile widths.
+- If a change affects performance, prefer streaming or progressive rendering over waiting for all items.
+- If a change affects deployment, keep the container build simple and reproducible.
+
 ## Deployment Notes
 
 - The app is designed to run in a container.