diff --git a/AGENTS.md b/AGENTS.md
index 15de219e83..a45007ec9b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,7 +44,7 @@ Before any of these commands can be run, you need to run `yarn install` in the p
 
 You MUST NOT run builds or create a release by running `yarn build`, `yarn changesets version`, or `yarn release` as part of any changes. Builds and releases are made by separate workflows.
 
-All changes that affect the published version of packages in the `/packages` and `/plugins` directories must be accompanied by a changeset. Only non-private packages require changesets. See the guidelines in `/CONTRIBUTING.md#creating-changesets` for information on how to write good changesets. Changesets are stored in the `/.changeset` directory and should be created by writing changeset files directly — never use the changeset CLI. Breaking changes must be accompanied by a `minor` version bump for packages below version `1.0.0`, or a `major` version bump for packages at version `1.0.0` or higher. For non-breaking changes that introduce new APIs or features, use `minor` for packages at version `1.0.0` or higher, and `patch` for packages below `1.0.0`. Each changeset message should be relevant to the specific package it targets and written for Backstage adopters as the audience — avoid referencing internal implementation details. If a change spans multiple packages you often need to create separate changesets to make sure they are tailored to each package.
+All changes that affect the published version of packages in the `/packages` and `/plugins` directories must be accompanied by a changeset. Only non-private packages require changesets. See the guidelines in `/CONTRIBUTING.md#creating-changesets` for information on how to write good changesets. Changesets are stored in the `/.changeset` directory and should be created by writing changeset files directly — never use the changeset CLI. Breaking changes must be accompanied by a `minor` version bump for packages below version `1.0.0`, or a `major` version bump for packages at version `1.0.0` or higher. For non-breaking changes that introduce new APIs or features, use `minor` for packages at version `1.0.0` or higher, and `patch` for packages below `1.0.0`. Each changeset message should be relevant to the specific package it targets and written for Backstage adopters as the audience — describe user-facing behavior changes in plain language. Never reference internal implementation details such as internal function names, class names, variable names, or other code symbols that are not part of the public API. If a change spans multiple packages you often need to create separate changesets to make sure they are tailored to each package.
 
 When creating pull requests, use the template at `/.github/PULL_REQUEST_TEMPLATE.md`.
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d01886873..af404462c6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -248,6 +248,10 @@ Changesets are an important part of the development process. They are used to ge
 
 Here are some important do's and don'ts when writing changesets:
 
+### Changeset messages should describe user-facing behavior in plain language
+
+Changeset messages are read by Backstage adopters, not contributors. They should describe what changed from the user's perspective, not how the code was changed internally. Never reference internal implementation details such as internal function names, class names, variable names, or other code symbols that are not part of the public API. Public API names (exported functions, components, types, etc.) are fine to mention, but internal code structure should not appear in changeset messages.
+
 ### Changeset should give a clear description to what has changed
 
 #### Bad
diff --git a/REVIEWING.md b/REVIEWING.md
index 4fa203d709..803cf35682 100644
--- a/REVIEWING.md
+++ b/REVIEWING.md
@@ -135,11 +135,11 @@ Each changeset should be written in a way that describes the impact of the chang
 
 Some things that changeset should NOT contain are:
 
-- Internal architecture details - these are generally not interesting to users, focus on the impact towards users of the package instead.
+- Internal implementation details such as internal function names, class names, variable names, or other code symbols that are not part of the public API. Changeset messages should describe user-facing behavior changes in plain language. Focus on the impact towards users of the package, not on how the code is structured internally.
 - Information related to a different package.
 - A large amount of content, consider for example a separate migration guide instead, either in the package README or [./docs/](./docs/), and then link to that instead.
 - Documentation - changesets can describe new features, but it should not be relied on for documenting them. Documentation should either be placed in [TSDoc](https://tsdoc.org) comments, package README, or [./docs/](./docs/).
-- Diffs of internal code, for example mirroring what the pull request changes _inside_ a plugin rather than public surfaces. This is not of interest to the reader of a package changelog. Sometimes, however, a small and concise diff can be used in a changeset to illustrate changes that the user will have to make in _their own_ Backstage installation as part of an upgrade, specifically when breaking changes are made to a package.
+- Diffs of internal code, for example mirroring what the pull request changes _inside_ a plugin rather than public surfaces. This is not of interest to the reader of a package changelog, and internal function names, class names, or variable names should never appear in changeset messages. Sometimes, however, a small and concise diff can be used in a changeset to illustrate changes that the user will have to make in _their own_ Backstage installation as part of an upgrade, specifically when breaking changes are made to a package.
 
 ### Backstage UI Changeset Format