The agent adds a “Back to settings” control as <a href="/settings">. The app already has a Link (or RouterLink, or Next.js Link) that prefetches, keeps the client transition, and applies the active class from the design system. The raw anchor does a full reload, loses draft state on the page, and looks unstyled for a frame.
I’ve started treating a raw <a> to an internal path as a merge question, not as a finished navigation change. External URLs, mailto:, and file downloads can stay anchors. In-app paths should go through the shared component.
Why the raw anchor sneaks in
The model has seen millions of HTML examples. href="/settings" looks correct, and it will work in the preview. What it will not do is honor the app’s scroll restoration, locale prefix, base path, or analytics hook that lives on Link. A new tab target also disappears: the shared component may already set it, or may explicitly forbid it for internal routes.
A full reload on an internal click is easy to miss in a happy-path click-through and expensive in a form or a wizard.
A simple navigation policy
- Internal paths use the shared
Link - External URLs use
<a>(or the sharedExternalLinkif you have one), withrelset the way the app already sets it - Do not invent a second wrapper to “add prefetch”
- Hash links and in-page anchors follow the existing pattern, not a new one-off
onClick
If the repo has a lint rule for this (@next/next/no-html-link-for-pages, a custom ESLint check), paste the rule into the prompt. If it does not, a one-line review grep for <a href="/ is enough.
What to put in the prompt
Internal routes must use the existing Link component (see src/components/Link or next/link). Do not add a raw <a> for an in-app path. External URLs, mailto, and file downloads may use <a>, with the existing rel/target helpers. Do not invent a new NavLink or PrefetchLink. In review, search the diff for <a. Each hit should be external, a download, or justified. If the href is a path the router owns, send it back.
Reject / send back
Reject
-
<a href="/dashboard">in a page that already importsLink - A new
SmartLinkhelper whenLinkalready exists - An in-app anchor that forces
target="_blank" - A click handler that
window.location.href =to an internal path
Accept
-
Link(or the repo’s named wrapper) for in-app paths - A raw anchor for an external docs URL, with the existing
rel - A genuine download link that the shared
Linkdoes not support

