diff --git a/AGENTS.md b/AGENTS.md
index 9227acd97b..b454db5183 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,6 +7,9 @@ Synapse is a Python application that has Rust modules via pyo3 for performance.
 - Run `poetry install --dev` to install development python dependencies. This will also build and install the Synapse rust code.
 - Use `./scripts-dev/lint.sh` to lint the codebase (this attempts to fix issues as well). This should be run and produce no errors before every commit.
 
+## Dev Tips
+- If any change creates a breaking change or requires downstream users (sysadmins) to update their environment, call it out in `docs/upgrade.md` as a new entry with the title "# Upgrading to vx.yy.z" with the details of what they should do or be aware of.
+
 ## Testing Instructions
 - Find the CI plan in the .github/workflows folder.
 - Use `poetry run trial tests` to run all unit tests, or `poetry run trial tests.metrics.test_phone_home_stats.PhoneHomeStatsTestCase` (for example) to run a single test case. The commit should pass all tests before you merge.