How to build and test a redirect map with Claude Code

To build a redirect map with Claude Code, you give it two lists, every old URL and every new URL, and ask it to match them, flag what it can't match with confidence, and write the rules in your host's format. A person then decides the hard cases. Last, Claude writes a test script that requests every old URL and confirms it lands, in one permanent hop, on the right page returning 200. The matching is the easy part. The test is the part that protects your traffic.

This guide walks through that process step by step, with example prompts, the check that proves each step worked, and what a person has to review. It assumes you are changing URLs during a redesign, a platform move or a cleanup. For the wider technical SEO picture, start with Claude Code for technical SEO.

What a redirect map is and what Google expects

A redirect map is a table with one row per old URL: where it should go, and with which status code. It becomes the rules file your server or host reads. Google's redirects documentation splits redirects into two groups. Permanent redirects (301, 308, an instant meta refresh) "Show the new redirect target in search results." Temporary ones (302, 303, 307) "Show the source page in search results." For a page that has moved for good, you want permanent, and server-side where you can.

Two more rules shape the map. Google's crawlers "follow up to 10 redirect hops," but its site-move guide advises "redirecting to the final destination directly" and, if that isn't possible, keeping chains "ideally no more than 3 and fewer than 5." And redirecting many URLs to one irrelevant page, like the home page, can be treated as a soft 404. Consolidated content is the exception: if several old pages were merged into one, they can all point to that page.

Step 1: Collect every old URL

The map is only as good as this list. A sitemap alone misses pages that were dropped from it, old campaign landing pages and files. Google's site-move guide suggests sitemaps, "server logs or analytics software," the "Links to your site feature in Search Console," and your CMS, and reminds you to "Include images and videos."

1. Export what you can: the current sitemap, a CMS export of all posts and pages, top landing pages from analytics, and the linked pages from Search Console.
2. Put the files in a folder in your project, on a branch in git.
3. Ask Claude Code to merge and clean them.

Example prompt: Merge the URL lists in /redirects/sources into one CSV of unique paths. Normalize trailing slashes and lowercase only where the old site treated URLs as case-insensitive. Keep a column listing which source each URL came from. Don't fetch anything from the live site.

The check: Claude reports the count per source and the merged total. If one source is much larger than the rest, ask why before moving on.

Step 2: Collect the new URLs

Build the new site on staging or locally and list every URL it serves, from its build output or generated sitemap. Ask Claude to add each page's title and H1 to the list. Those give the matching step something to compare beyond the slug.

The check: the new list's count matches the number of pages your build reports. Pages marked noindex during development are still in the list, since they will go live.

Step 3: Let Claude Code match old to new, in plan mode first

Start in plan mode (press Shift+Tab until the mode indicator shows plan mode, or start a prompt with /plan) so Claude proposes its matching method before it writes anything. A good method works in passes, from most to least certain:

Example prompt: Match every old path in old-urls.csv to a new path in new-urls.csv. Add columns for match method and confidence (high, medium, low). Never match to the home page unless the old URL was the home page. Put every row you can't match, or that matches more than one new page, in a separate review file. Show me the counts per method.

The check: the counts add up to the old-URL total, with nothing silently dropped. Read ten random high-confidence rows yourself. If even one is wrong, the method needs fixing before anyone trusts the rest.

Step 4: A person decides the hard cases

This is the step Claude can't do for you. Someone who knows the business goes through the review file and picks one of three outcomes for each row:

• Redirect to the closest equivalent when a page covers the same topic or product, even under a new name.
• Redirect to a consolidated page when several old pages were merged into one.
• Let it return 404 or 410 when nothing on the new site serves the same need. Google's guide says to "make sure those URLs correctly return an HTTP 404 or 410 error response code on the new site."

Prioritize rows with traffic or inbound links, which you already have from step 1. A discontinued product with years of backlinks deserves a thoughtful target. A tag page nobody visited doesn't.

Step 5: Flatten chains and loops

Most sites already have redirects. If an old rule sends A to B, and your new map sends B to C, a visitor to A takes two hops. Ask Claude to merge the existing rules into the new map and resolve them.

Example prompt: Combine the current redirect rules in old-redirects.txt with the new map. Rewrite every chain so each source points straight to its final target. List any loops and any target that is itself redirected or missing from the new site.

The check: a script follows each rule through the combined map and reports zero chains longer than one hop and zero loops.

Step 6: Write the rules in your host's format

Each platform reads redirects differently, and a few have traps worth telling Claude about in your CLAUDE.md:

The trap in Netlify's redirects documentation is easy to miss: its force option, which overrides "any existing content in the path," is "false by default." If the old page file is still in your build, the redirect won't fire. Vercel's redirects page recommends bulk redirects "For large-scale migrations." Here is a Netlify example, where the first line is a comment:

# old service pages moved under /services/
/web-design.html /services/web-design/ 301
/seo-packages/ /services/seo/ 301

When we rebuilt eseospace.com, the redirects ended up in one file: 235 rules as of September 2026. One file under git made every change reviewable as a diff.

Step 7: Test every old URL before launch

Deploy the rules to staging and have Claude write a test script that requests every old URL without following redirects automatically, so it can record each hop. Request at a gentle pace. A burst of thousands of requests can trip your host's bot protection, even on your own site.

Example prompt: Write a script that requests every source URL in redirect-map.csv on the staging host, one hop at a time, and records each status code and Location header. Flag any row where the first response isn't 301 or 308, the chain is longer than one hop, the final URL doesn't match the map's target, or the target doesn't return 200. Then run it and summarize the failures.

The check: zero failures, and the script's row count equals the map's row count. Run it twice. The second run should report exactly the same results. Google's site-move guide suggests the URL Inspection Tool "for testing individual URLs, or command line tools or scripts to test large numbers of URLs."

Step 8: Update links and launch, then test again live

Redirects are a safety net, not a link strategy. Google's guide says to "replace all URLs that pointed to your own pages" in internal links, and to make sure canonical tags on the new site use the new URLs. Ask Claude to rewrite internal links in the source files using the map, then crawl staging for any link that still points at a redirect. Our guide to finding and fixing broken links covers that crawl.

A person approves the deploy. After launch, run the same test script against the live domain, and again after a CDN cache clears if your first live run shows old behavior. Then submit the new sitemap, keep the redirects for at least a year, and watch Search Console. Google says to "Expect temporary fluctuation in site ranking during the move."

For the content side of a move, see moving content between platforms with Claude Code. Our older guide to building a 301 redirect map covers the method without the Claude Code workflow.

What a person must review

• Every low-confidence, duplicate and unmatched row, and every pattern rule, since one wrong wildcard can redirect hundreds of pages.
• Any rule that points at the home page or a category page.
• The diff of the rules file before it merges, and the test report before launch.
• The decision to let a page 404. That is a business call about whether an equivalent exists.

Claude Code is good at the volume. People own the judgment and the go-live. If the redirect map is part of a full rebuild, our guide to rebuilding a website with Claude Code shows where it fits.

Conclusion

A redirect map built with Claude Code is quick to draft and straightforward to test, as long as you treat the draft as a draft. Collect old URLs from every source, let Claude match them in passes with a confidence score, have a person settle the hard cases, flatten chains, write rules in your host's format and test every row on staging and again live. If you'd rather have a team plan and run the move, see our website migration services. More guides are in our Claude Code Guide.

Frequently asked questions