Document the route-change contract with shipwithai.io in CLAUDE.md

[kamikaze011001]

Context

This repo owns course.shipwithai.io. shipwithai.io hardcodes course URLs — in vercel.json redirect destinations and in outbound links across pages, nav, and blog posts.

There is no CI on either side that catches a route change here breaking a link there.

It has already happened once. This repo restructured everything under /{locale}/claude-code/ and added internal redirects. Nothing reminded anyone that shipwithai.io pointed at the old paths, so its redirects became 2-hop chains ending in 404 — live for weeks, discovered only via Google Search Console. Root-caused and fixed in shipwithai.io PR #232.

The consumer side is now documented: shipwithai.io CLAUDE.md hard rule 4a records what it hardcodes, where, and what CI does and does not guard. This issue covers the producer side — the half that actually gets to prevent the breakage.

What's coupled today

Measured against shipwithai.io at develop:

Where	Count
vercel.json redirect destinations → course	16 entries (8 distinct URLs)
src/ code + config	9 files
src/content/ (docs + blog posts)	16 files

The 8 distinct destinations:

https://course.shipwithai.io/{en,vi}/claude-code/
https://course.shipwithai.io/{en,vi}/claude-code/cheat-sheet/
https://course.shipwithai.io/{en,vi}/claude-code/tips-tricks/
https://course.shipwithai.io/{en,vi}/claude-code/phase-:phase/:path+/

Ask — add a hard rule to this repo's CLAUDE.md

Suggested wording:

Route changes are a cross-repo contract. shipwithai.io hardcodes course.shipwithai.io URLs in its vercel.json redirect destinations and in outbound links. Any route change here — rename, restructure, delete, or a new internal redirect — must update those consumers in the same change, not as a follow-up.

Before merging a route change, check the consumer:

grep -rn 'course\.shipwithai\.io' vercel.json src/   # run in shipwithai.io

Adding an internal redirect here is not sufficient. It turns the consumer's existing redirect into a 2-hop chain, which leaks link equity and breaks outright if the internal redirect is ever removed. Point the consumer at the final URL.

Why CLAUDE.md rather than a wiki page

Both repos are developed primarily through Claude Code sessions. CLAUDE.md is the one file both humans and agents reliably read before a route refactor — which is exactly the moment this needs to be seen.

Related

• shipwithai.io issue #245 — the tracking issue for this contract
• shipwithai.io PR #232 — the 404 chain this is meant to prevent recurring
• shipwithai.io issue #239 — scheduled live link-health check; until it lands, a route change here fails silently there