diff --git a/AGENTS.md b/AGENTS.md
index faeaf764..7ed1d7a0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,6 +7,7 @@ Guidance for coding agents working in `posthog-python`.
 - This repository contains the PostHog Python SDK, published as `posthog`.
 - The main runtime package is `posthog/`; tests live under `posthog/test/`.
 - The project uses `uv` for local development. See `CONTRIBUTING.md` for setup.
+- Before adding or changing public API, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): the API shape must be agreed on the issue first. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md.
 - Keep edits targeted and follow existing patterns. Prefer adding or updating tests near the behavior you change.
 
 ## Capture protocol (`capture_mode`)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 64e4d8d9..9f067e68 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,3 +48,15 @@ posthoganalytics = { path = "../posthog-python-local" }
 ```
 
 This lets you test SDK changes fully locally inside the PostHog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. Re-run `make prep_local` each time you make a change, and then run `uv sync --active` in the PostHog app project.
+
+## Public API changes
+
+Public API is hard to change once it ships, so agree on it before writing the implementation. Our [SDK guidelines](https://posthog.com/handbook/engineering/sdks/guidelines) explain how we design it.
+
+- If you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case first. At this stage, context is more useful to us than code.
+- Wait for a maintainer to agree on the API shape on the issue before implementing it.
+- Check first whether an existing option or hook, such as `before_send`, already covers the use case. We avoid offering two ways to do the same thing.
+- If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.
+- AI agents: stop and ask before implementing a public API change that hasn't been agreed on the issue.
+
+`make public_api_snapshot` regenerates `references/public_api_snapshot.txt`, and CI runs `make public_api_check` to catch an outdated snapshot. A diff in that file means your change touches public API.