The agent adds a “Settings” link. It points at /settings. The app has used /account/preferences for three years. The TypeScript build is green. The first click in staging 404s.
I’ve started treating a guessed path string in an agent PR as incomplete work. If the repo has a route manifest — React Router config, Next.js app/ tree, a routes.ts, a generated Route type — that file is the source of truth. The model should read it, not reconstruct the sitemap from the page title.
Why the guess is usually wrong
Human URL schemes are messy. Marketing pages sit at /pricing. The signed-in equivalent is /app/billing. A rename left /settings as a redirect. Localized routes add a prefix. The agent has seen a thousand tutorials where settings live at /settings, so that is what it writes.
String literals also skip type-safe helpers. If the app already has routes.settings() or a href={Routes.AccountPreferences}, a raw "/settings" is a second routing API. The next PR will not update both.
A simple routing policy
-
Read the manifest first —
routes.ts,app/**/page.tsxtree,router.getRoutes(), whatever the repo already has - Use the typed helper if one exists; do not add a new pathname literal next to it
- No invented nested paths — if you need a new screen, add the route in the same PR and say so
- Redirects are data — do not “fix” a stale path by adding a second link; follow the canonical one
If the project has file-based routing, paste a directory listing of the relevant tree, not a prose summary of “there’s a settings area.”
What to put in the prompt
Here is routes.ts (or the app/ directory listing).
Use only paths or helpers declared there.
If this change needs a new route, add it to the manifest in this PR and link to it from the nav with the same helper.
Do not invent /settings, /user, or /app/... because they sound conventional.
Attach the failing 404, the manifest, and the nav file. Do not attach only the button component.
In review, grep the diff for quoted pathnames. Every new '/' string should correspond to a manifest entry or a documented external URL.
This also applies to redirects, sitemap entries, and email or push deep links the agent might add in the same ticket. A marketing path (/pricing) and an app path (/app/billing) are easy to swap if you only remember the noun. If the manifest has both, the prompt should say which audience the link is for.
When the typed helper needs a param — :orgId, a locale prefix, a feature flag — make the agent use the helper’s arguments. Do not concatenate a string next to a function that already knows the shape. That is how /en/en/settings and missing org ids land in staging.
Reject / send back
Reject
- A nav item, redirect, or
router.pushto a path that is not in the manifest - A second routing helper invented for one link
- “I assumed settings would be at /settings”
- Changing copy on a 404 page instead of fixing the href
Accept
- A link or navigation call that uses the existing helper or a manifest path
- A new route added in the same PR, wired through the same pattern
- A deliberate external URL, obviously marked as such
Top comments (0)