Claude Code SEO: Complete Website Optimization Workflow

What an agent can and cannot do for SEO

SEO splits cleanly into two halves, and Claude Code is excellent at one of them and dangerous at the other.

Technical SEO is verifiable. Does this URL return 200? Is there a canonical tag and does it point at itself? Is this title unique across the site? Does the sitemap contain the URLs it should? Is this structured data valid? Every one of these has a right answer that can be established by fetching a URL and reading the response. This is exactly the sort of tedious, checkable, high-volume work an agent does well and a person does badly.

Everything involving external data is not. Search volume, keyword difficulty, competitor rankings, traffic estimates, backlink counts — none of these are derivable from your codebase, and a language model asked for them will produce numbers. The numbers will be plausible, specific, confidently stated, and made up. This is the single biggest risk in using AI for SEO work and it is easy to avoid: never ask for a number that would require data the model does not have, and put an explicit prohibition in every audit prompt.

Do not invent search volumes, keyword difficulty scores, traffic
estimates, ranking positions, or competitor data. You do not have
access to that data.

If a finding would require external data, say what data is needed
and where to get it. "Not measured" is a correct answer. A
fabricated number is not.

Include that in every SEO prompt. It costs four lines and it removes the failure mode entirely.

There is a third category worth naming: judgement about content. Whether a page genuinely serves the person who lands on it, whether it demonstrates real experience, whether it says anything a dozen other pages do not. An agent can help you assess this and can flag obvious thinness, but it cannot supply the experience — and content produced primarily to rank rather than to help is the thing Google's guidance is most directly aimed at.

The shape of the workflow

The order below is not arbitrary. It runs from the checks that can make an entire site invisible down to the ones that adjust how well individual pages perform. Do them in this order, because there is no point optimising a title tag on a page that is blocked from crawling.

1. Can it be crawled and indexed? Everything else is moot until yes.
2. Do URLs behave correctly? Status codes, redirects, duplicates.
3. Is the canonical story clear?
4. Is discovery working? Sitemaps, internal links.
5. Is each page described accurately? Titles, descriptions, headings.
6. Is the machine-readable layer correct? Structured data.
7. Is the experience good? Speed, mobile, accessibility.
8. Is the content worth ranking?

And one rule that applies throughout: audit before changing anything. Establish what is true now, in writing, with evidence. Then change. Then re-verify. A session that audits and fixes in the same pass gives you no way to tell what it actually improved.

1. Crawlability and indexing

The catastrophic failures live here. A noindex left over from staging, a robots.txt that blocks a directory it should not, a redirect loop on a canonical URL — any of these can remove a site from search results entirely, and none of them are visible to a person browsing the site.

Audit indexability. Do not change anything.

Check:
- robots.txt: fetch it, report its contents, and identify anything
  blocked that should be crawlable. Confirm CSS and JS are not
  blocked — Google needs them to render the page.
- Any noindex directive, whether in a meta robots tag or an
  X-Robots-Tag response header. Report every URL carrying one.
- Any nofollow on internal links.
- Whether any important page is reachable only via JavaScript.
- Whether any page is orphaned — no internal link points to it.

For each finding: the URL, the exact directive, and where it comes
from — a file and line, or the response header.

Two subtleties worth knowing, because they cause the same confusion repeatedly.

Blocking in robots.txt is not the same as noindex. A disallowed URL is not crawled, but it can still be indexed — typically as a bare URL with no description, discovered through links elsewhere. If you want a page out of the index, use noindex and let it be crawled.

Which leads to the trap: a page that is both blocked in robots.txt and carries noindex will not be deindexed, because the crawler is not permitted to fetch the page and therefore never sees the noindex. The two directives cancel each other. Check for this combination explicitly.

2. Status codes and redirects

Every URL you have ever published should still do something sensible. The check is mechanical: extract every URL you know about — sitemap, internal links, historical URLs — and fetch each one.

Fetch every internal URL and report the actual status code.

Flag: any 4xx or 5xx; any redirect chain longer than one hop; any
redirect loop; any 302 that should be a 301; any soft 404 — a page
returning 200 whose content says nothing was found.

Also check: does the site canonically prefer www or the apex domain,
and does the other redirect to it in one hop? Does HTTP redirect to
HTTPS? Are trailing slashes handled consistently?

Report a table of URL, status, and destination. Show me what you
found, not a summary of it.

The www-versus-apex and trailing-slash checks matter more than they look. If both /about and /about/ return 200 with the same content, you have duplicated every page on the site.

Soft 404s deserve their own attention because nothing surfaces them automatically — a 200 response containing "sorry, that product no longer exists" is a page the crawler will treat as real content.

3. Canonicalisation

Canonical tags tell search engines which URL is the real one when several serve similar content. Getting them wrong is quietly expensive.

Audit canonical tags across the site.

For each page, report the URL and its canonical. Flag:
- Missing canonical tags
- Canonicals pointing to a different page (only correct if
  deliberate — tell me which ones look accidental)
- Canonicals pointing to a URL that redirects, 404s, or is
  noindexed
- Relative canonicals
- Protocol or hostname mismatches with the page's own URL
- More than one canonical tag on a page
- Pages with URL parameters that lack a canonical to the clean URL

Report the actual tag content from each page.

Two things to keep in proportion. A canonical is a hint, not a directive — search engines may choose a different URL if the signals disagree, so canonicals that contradict your internal linking and sitemap will often lose. And a canonical pointing at a noindexed page is a genuinely bad combination: you have told search engines the real version of this content is one they must not index.

4. Sitemaps

A sitemap helps discovery, particularly for large sites, new sites, and pages with few internal links. It is not a ranking factor and inclusion does not guarantee indexing — Google is explicit that sitemaps are a hint.

Practical facts worth knowing: a single sitemap file is limited to 50,000 URLs and 50MB uncompressed, with a sitemap index for anything larger. Google ignores the <priority> and <changefreq> elements entirely — do not spend effort on them. It does use <lastmod>, but only when it is accurate; a sitemap that stamps today's date on every URL every day teaches search engines to disregard the field.

Validate the sitemap.

Confirm it returns 200 with an XML content type and is well-formed.
If it is an index, fetch every child sitemap too.

Then sample at least fifteen URLs from it and fetch each one. For
each, report the actual status code, whether it is canonical, and
whether it carries noindex.

Flag: any URL that is not 200; any that redirects; any noindexed;
any non-canonical; any that does not belong. Also tell me which
important pages are missing from the sitemap entirely.

Report the URLs you sampled and what each returned.

The sampling requirement is the point. A sitemap can be perfectly valid XML and full of URLs that 404. Only fetching them tells you.

If your platform generates the sitemap — Shopify, most CMSs — do not replace it with a static file. A hand-written sitemap is accurate on the day it is written and drifts from that moment. Validate the generated one instead.

5. Titles and meta descriptions

Title tags are a real ranking signal and are what most people see first in results. Meta descriptions are not a ranking factor, but they affect click-through, and search engines frequently rewrite them when the page offers better text for the query — a good description is worth writing and not worth agonising over.

Audit page titles and meta descriptions across the site.

Report a table: URL, title, title length in characters, meta
description, description length.

Flag: any missing; any duplicated across pages; titles that are
generic or that lead with the site name rather than the page
subject; descriptions that do not describe the specific page;
anything obviously truncated; and any page where the title is a
fallback value rather than real content.

Do not rewrite anything yet. Show me the audit first.

That last flag catches a real and embarrassing failure: a template that builds the title from a setting nobody filled in, producing a homepage titled with a raw domain name. It looks fine in a browser tab and terrible in search results.

Then rewrite with the constraint that matters:

Rewrite the titles and descriptions flagged in the audit.

Each title: describes that specific page, front-loads the
distinctive part, reads like something a person wrote, and is
unique across the site.

Each description: accurately describes what is on the page and gives
someone a reason to click. Never promise something the page does
not contain.

No keyword stuffing. No repeating the same phrase in both. If a page
genuinely duplicates another, the fix is the duplication, not the
title.

Show me the before and after side by side.

The "reads like something a person wrote" instruction is doing real work. Left unconstrained, generated titles converge on a mechanical Keyword | Keyword | Brand pattern that helps nothing.

6. Heading structure

Headings serve two audiences at once: they give assistive technology a navigable document outline, and they give search engines a structural summary of the page. The same fix serves both, which makes this unusually good value.

Audit heading structure on every page.

For each: list the headings in document order with their levels.

Flag: pages with no h1; pages with more than one h1; skipped levels
(h2 to h4); headings used for visual size rather than structure;
non-heading elements styled to look like headings; empty headings;
and headings whose text does not describe the section below them.

Report the actual outline for each page so I can see the shape.

The last flag is the substantive one. Structurally valid headings that say "Overview", "Details", "More" describe nothing. The outline of a good page reads like a summary of it.

7. Structured data

Structured data makes a page's meaning explicit and can qualify it for rich results. It does not guarantee them, and it is not a general ranking boost — the honest framing is that it makes eligibility possible, not certain.

Audit structured data across the site.

For each page: what types are present, and is the JSON-LD valid?

Check that every value matches what is actually on the page — a
price in structured data that differs from the displayed price is a
serious error.

Check for: required properties missing; markup for content not
visible on the page; and any review, rating, or aggregateRating
markup.

Flag every instance of review or rating markup. If we do not have
genuine reviews, that markup must be removed — it is a spam policy
violation and can result in a manual action.

Report what is present, what is invalid, and what is inaccurate.

Three rules keep structured data safe over time. Mark up what is on the page, not what you wish were. Generate values from the same source as the visible content, so they cannot diverge — hard-coded structured data is correct exactly once. Never mark up reviews you do not have, which is the most commonly penalised abuse in this area and an entirely plausible thing for a helpful agent to generate as placeholder content.

Validate against Google's Rich Results Test rather than trusting an assessment. Valid JSON-LD and eligible structured data are different bars.

8. Internal linking

Internal links are the part of SEO you have complete control over and the part most often ignored. They distribute authority, they establish which pages are important, and they are how crawlers find things.

Audit internal linking.

Report: which pages have the most inbound internal links and which
have the fewest; any page with zero inbound internal links; how many
clicks each page is from the home page; any broken internal link;
any internal link that redirects rather than pointing at the final
URL; and any generic anchor text — "click here", "read more", "this
page".

Then tell me: which important pages are under-linked, and where in
the existing content would a link to them be genuinely useful to a
reader?

Do not suggest links that would not help someone reading that
sentence.

That final constraint is the difference between internal linking and link spam. A link is worth adding when a reader at that point in the text would plausibly want it. Ask an agent for internal linking opportunities without the constraint and you will get a list of every possible keyword match, most of which would make the content worse.

Two mechanical fixes worth doing while you are here: point internal links at final URLs rather than through redirects, and replace generic anchor text with text that describes the destination — which is both an SEO improvement and an accessibility one, since screen reader users routinely navigate by pulling up a list of links out of context.

9. Duplicate content and URL parameters

Duplicate content is rarely deliberate. It accumulates: a page reachable at two paths, a filter that appends a parameter, a print view, a paginated series where every page carries the same title. None of it is penalised as such — search engines simply pick one URL and consolidate — but you lose control over which one they pick, and you spend crawl budget on copies.

Find duplicate and near-duplicate content.

Check: pages reachable at more than one URL; URL parameters that
return the same content as the clean URL — sorting, filtering,
tracking, session; trailing-slash and case variants both returning
200; print or AMP-style alternate views; and paginated series where
every page shares a title and description.

For each: which URL should be canonical, and what the fix is —
canonical tag, redirect, noindex, or a parameter that should not be
generating a crawlable URL at all.

Report the duplicate sets, not a count.

Two mistakes to avoid here. Do not canonicalise paginated pages to page one — each page has different content, and doing so hides everything after the first page. And do not noindex something merely because it duplicates: if the duplicate is the version people link to, a canonical preserves that value while noindex discards it.

10. Images

Audit images across the site.

For each: the file size, the intrinsic dimensions, the rendered
dimensions, the format, whether width and height are set, whether
loading and decoding attributes are appropriate, and the alt text.

Flag: images served substantially larger than they render; formats
that should be modern equivalents; missing dimensions, which cause
layout shift; missing alt attributes; alt text that is a filename or
a keyword list; decorative images with descriptive alt instead of
alt=""; and any image above the fold set to lazy load.

Report the actual numbers.

On alt text specifically: describe the image's purpose in context, not its appearance. A product photo's alt text should say what the product is. A decorative flourish takes alt="" so it is skipped, which is correct and not a failure. Keyword-stuffed alt text is worse than none — it degrades the experience for screen reader users, which is who the attribute is for.

11. Core Web Vitals

Google's page experience signals centre on three metrics: Largest Contentful Paint (loading — good is 2.5 seconds or less), Interaction to Next Paint (responsiveness — 200 milliseconds or less; this replaced First Input Delay in 2024), and Cumulative Layout Shift (visual stability — 0.1 or less). Thresholds are assessed at the 75th percentile of real user visits.

Keep the weight of this in proportion. Page experience is a real signal and a genuinely better site is worth building, but it does not outrank relevance. A fast page about the wrong thing still loses.

Measure this site's performance and establish a baseline. Do not
optimise anything yet.

Build for production and report actual numbers: JS and CSS bundle
sizes by chunk, total image weight with the largest named, font
payload, third-party bytes by origin, and request count.

Then for each key template: identify the LCP element, list every
render-blocking resource, and identify anything that could cause
layout shift — images without dimensions, injected content, fonts
without a size-adjusted fallback.

State how you measured. Do not present an estimate as a measurement.

Then fix in the order that matters: layout shift first, because it is usually a handful of missing dimension attributes and is the cheapest of the three to fix outright; then the LCP element, which is usually an oversized hero image or a render-blocking stylesheet; then interaction responsiveness, which is usually long JavaScript tasks and is the hardest.

Re-measure after each change. Lab measurements are not field data — the assessment that counts comes from real users, which means improvements take time to show up. Do not conclude a change failed because a number did not move the same day.

12. Mobile

Google indexes the mobile version of your site. Whatever is missing from your mobile rendering is, for practical purposes, missing.

Audit this site as a mobile crawler would see it.

Render every key page at 375px wide and compare the content to the
desktop rendering. Report anything present on desktop and absent on
mobile — text, links, structured data, headings, metadata.

Also check at 320px: horizontal overflow, text under 16px, tap
targets smaller than 24x24 CSS px or too close together, and
anything that requires hover.

Report measured values.

The content-parity check is the one with SEO consequences. A responsive site that hides a block of text on small screens has removed that text from indexing.

13. Rendering without JavaScript

Google renders JavaScript, but rendering is queued and deferred rather than immediate, and other crawlers are far less capable. Content that requires JavaScript is content whose indexing is delayed and less reliable.

Fetch each key page's raw HTML without executing JavaScript, and
compare it to the fully rendered DOM.

Report what is missing from the raw HTML: main content, headings,
internal links, title, meta description, canonical, structured data.

Tell me which of these would be a problem if a crawler never
executed the JavaScript, and what it would take to render each
server-side.

You do not need everything in the initial HTML. You do need the main content, the metadata, the canonical, the internal links, and the structured data.

Triage: what to fix first

An audit of a site that has never had one will produce a long list, and treating every item as equally urgent is how the list never gets finished. Rank by what the finding actually costs.

Ask for this ranking explicitly, because an unranked audit tends to present a missing <meta> description with the same gravity as a site-wide noindex:

Rank every finding by actual impact: critical if it removes pages
from search, high if it loses or misdirects existing value, medium
if it is incremental, low if it is polish.

Do not inflate severity. A missing meta description is not critical.
If nothing is critical, say so.

The last line matters. An audit that always finds something critical is one you will learn to discount.

What this actually turned up on this site

Running the above on this store — a small, new, carefully built site — found more than expected. Worth listing, because the pattern is instructive: almost none of it was visible to someone looking at the site.

The homepage title was the raw .myshopify.com domain. The layout built the title from a theme setting that had never been filled in, and fell back to the store's internal domain. The page looked completely normal. Only fetching the URL and reading the <title> surfaced it. There was no meta description either.

An og:image tag was emitting a Liquid error into the page head. The setting held a value but the theme's schema had no matching picker, so the object resolved to an error string that rendered inside the meta tag. Invisible in a browser; plainly wrong in the response body.

Every call-to-action on non-home pages was dead. They linked to #buy, a fragment that exists only on the home page. On every other page the click did nothing at all — no error, no navigation. This was found by crawling and resolving every anchor target rather than by clicking around, because clicking around on the page you built is exactly where it works.

Policy pages were rendering in the wrong layout entirely. Attempts to give them a template failed in two different ways — one with an explicit error, one silently — so they fell back to the vendor theme's default chrome while every other page used ours.

Storefront copy overstated the product. Specific numeric claims about the bundle had drifted from what the bundle actually contained as the product changed. Caught by a script that extracted every number from the page and compared it to the real artefact, which is not something you would think to check manually.

The common thread: every one of these was found by fetching a URL and reading what came back, and none of them by looking at the site. That is the argument for making the audit mechanical. A person reviewing these pages would have said they looked fine, and they did.

Content quality, honestly

Everything above is necessary and none of it is sufficient. A technically flawless page about nothing ranks for nothing.

Google's guidance here has been consistent for years and is worth reading in the original rather than in summary. The framing that has held up best is its self-assessment questions, which come down to three:

• Who created this content, and is that clear to a reader?
• How was it produced — including, explicitly, whether automation was involved and why?
• Why does it exist? To help someone, or to rank?

That third question is the whole thing. Google's spam policies name scaled content abuse — producing many pages primarily to manipulate rankings rather than to help people — and the policy is about the purpose and the result, not the tool. AI-assisted content that genuinely helps someone is fine. AI-generated content produced at volume to occupy keywords is the thing the policy exists to catch, and using an agent makes that easy to do accidentally.

The practical test: could you have written this page if you had not done the work? Specifics you could only know from experience — the error message you actually hit, the number you actually measured, the approach you tried that failed — are what separate a useful page from a fluent one. They are also, not coincidentally, what nobody else has.

An agent is genuinely useful in this half of the work, but in a different role:

Review this article critically, as an editor who is unimpressed.

What claims are unsupported? What would a knowledgeable reader push
back on? What is padding that could be cut with no loss? Where does
it say something generic that appears on every other page about
this topic?

What does it not cover that someone with this question would need?

Do not rewrite it. Tell me what is wrong with it.

That prompt is worth more than any generation prompt. Use the agent to find the weaknesses; supply the substance yourself.

Search Console and submission

Google Search Console is the only source of truth about how your site actually performs in Google. It is free, and no amount of local auditing substitutes for it — it reports what Google actually did, not what should happen.

Verify ownership, submit the sitemap once, and then use it for what it is uniquely good at: the indexing report, which tells you which pages are indexed and why the others are not; the URL Inspection tool, which shows you a specific URL as Google sees it; the performance report, which is the real query and click data no model can guess; and the Core Web Vitals report, which is field data from real users.

Bing Webmaster Tools is the equivalent for Bing, and worth ten minutes for the coverage it adds.

Two notes on submission. IndexNow is a protocol for pinging search engines when content changes; it is supported by Bing and several others, and Google has not adopted it. It is cheap to implement and worth having if you publish frequently, but it is not a Google mechanism and should not be described as one.

And a caution specific to agents: these are external systems that accept submissions on your behalf. Submitting a sitemap, requesting indexing, or configuring a property are outward-facing actions against accounts you own. Do them deliberately, with credentials you have chosen to provide, rather than letting them happen as a side effect of an audit task.

Preventing regressions

SEO breaks silently. Nobody files a bug when a canonical tag disappears; you find out from a traffic chart eight weeks later.

The defence is to make the audit repeatable and run it automatically. Everything in this article is a script — fetch URLs, parse HTML, compare against expectations — and a script can run in CI.

Write a check that runs in CI and fails the build on an SEO
regression.

Assert, for every page in the sitemap: returns 200; has exactly one
h1; has a non-empty title under 60 characters that is unique across
the site; has a meta description; has a self-referencing canonical;
is not noindexed; has no broken internal links; and every image has
an alt attribute.

Output a clear report of what failed and why. Exit non-zero on any
failure.

Test it by deliberately breaking one of these and confirming the
check catches it.

That last instruction is not optional. An automated check nobody has seen fail is not known to work — and a check with a bug in its filtering looks exactly like a clean site.

Add the standards to your CLAUDE.md as well, so future sessions maintain them by default rather than needing to be told each time:

## SEO requirements
- Every page: unique title, meta description, self-referencing
  canonical, exactly one h1
- Never add noindex without asking
- Never change a published URL without a 301
- Structured data values come from the same source as the visible
  content; never hard-coded
- No review or rating markup

What not to do

Generating pages at scale to occupy keywords

The exact thing the scaled content abuse policy describes. An agent makes it trivially easy and it is the fastest route to a manual action.

Trusting invented metrics

Search volumes, difficulty scores, competitor traffic. If it would require external data, it was made up.

Keyword density

Not a thing search engines use, and optimising for it makes writing worse. Write for the reader.

Optimising titles on pages that are blocked

Order matters. Crawlability first.

Accepting "done" without evidence

"I fixed the canonical tags" is a claim. Fetch the pages and read the tags.

Auditing the source instead of the output

What matters is what the server returns and what the browser renders, which on a templated site is frequently not what the source suggests.

Changing and auditing in one pass

You lose the ability to tell what any individual change did.

Treating structured data as a ranking lever

It makes rich results possible. It is not a boost, and adding more types does not add more benefit.

Where to go next

SEO is most effective built in rather than retrofitted — the complete website workflow shows where these checks belong during a build. The audit prompts here are applications of the patterns in the prompt library, and encoding the standards so they survive future changes is covered in creating a production CLAUDE.md. For platform specifics — what Shopify generates for you and what you must not overwrite — see the Shopify guide.

Sources and further reading

• Google: creating helpful, reliable, people-first content — the Who / How / Why self-assessment
• Google: spam policies — including scaled content abuse
• Google: build and submit a sitemap — limits, and which elements are ignored
• Google: block indexing with noindex — why it must not be combined with a robots.txt block
• Google: canonicalisation
• web.dev: Core Web Vitals — LCP, INP, and CLS thresholds
• Google: structured data search gallery
• W3C: WCAG 2.2 — the overlap between accessibility and SEO