Claude Code broke this site last week. Not by hallucinating. By being right about the wrong thing. That distinction is the most useful thing I’ve learned about AI-assisted work in months, and it changed how I set up every session since.

What happened

I was doing an SEO pass. Claude noticed my TIL posts rendered at two URLs: /blog/some-post/ and /til/some-post/. Duplicate content is a real SEO problem with a well-known fix, so it filtered TIL posts out of the blog route. Clean diff, build passed, validation green. I approved it.

Except /til/some-post/ was never a duplicate page. It was a 301 redirect stub I’d built on purpose, pointing old TIL URLs at their canonical /blog/ home after I merged the two collections. Claude’s fix deleted the redirect targets. Every TIL post on the site started returning 404, from the homepage, the tag pages, and the TIL index all at once.

The part I keep turning over

Here’s the detail that stuck with me: the reasoning behind that URL structure was documented. I’d written up the collection merge, the category field, and the redirect decision in a TIL post on the very site being edited. Claude never read it, because nothing told it that a blog post was load-bearing architecture documentation.

The model pattern-matched “two URLs, same content” to “duplicate content bug” and acted. A human contractor would have made the same call with the same information in front of them. The failure wasn’t intelligence. It was that my decision record lived somewhere the tooling never looks.

What actually caught it

A goal-scoped session with a link check. When I later pointed a session at “fix 404 errors,” the first thing it did was crawl every href in the built output against the files on disk. Three broken URLs surfaced in seconds, and tracing them backward found the earlier “fix” in a couple of minutes.

Here’s the lesson stack, in the order that actually matters:

1. Decisions need to live where the AI reads. My redirect rationale now sits in the project’s memory files and in CLAUDE.md, in plain terms: “do NOT filter TIL out of the blog route; /til/ is a redirect by design.” The blog post was written for humans. The memory file is written for the tooling. Those are two different audiences and I’d been pretending they were one.
2. Verification beats review. I reviewed that diff and approved it. It looked correct because it was correct, for a premise that happened to be wrong. The link crawler checks reality instead of intent, so it caught what my eyeballs couldn’t.
3. Reversible beats clever. The fix was a one-line revert, because the original change was one clean line. Small diffs make wrong premises cheap to undo.

What I do differently now

Every architectural decision that isn’t obvious from the code gets a line in the repo’s memory. Not because Claude is careless, but because Claude is thorough with exactly what it can see and blind to everything else. The gap between “documented somewhere” and “documented where the agent looks” turned out to be exactly the width of a production incident.

The site’s fine now. Zero broken links, enforced on every build. The redirect stubs are still there doing their job, except now they carry a note that says why, so the next well-meaning fix leaves them alone.