How to Run a Technical SEO Audit with Claude Code

A technical SEO audit is not a hunt for the largest possible number of warnings. It is an investigation into whether search engines can discover, render, understand, index, and consistently retrieve the pages that matter to a business. Claude Code can accelerate that investigation because it can combine a live crawl with repository analysis, trace a symptom to a template, implement a fix, and run verification in one workspace.

That speed creates a new risk: moving from correlation to code before the diagnosis is sound. A redirect seen in a crawler might be intentional. A missing canonical on a private route may be irrelevant. A slow lab test may not reflect field performance. The workflow below keeps evidence and impact ahead of edits.

Define the audit scope and source of truth

Start with page groups, not an arbitrary URL limit. List the homepage, product or service pages, category or collection pages, editorial pages, location pages, utilities, authentication routes, and any parameterized families. For each group, state whether it should be indexable and what action it supports.

Choose the canonical hostname and protocol explicitly. Record whether trailing slashes are preferred, how uppercase paths behave, and which query parameters change primary content. This policy becomes the reference for redirect, canonical, sitemap, and internal-link tests.

Collect inputs before asking Claude Code to diagnose anything:

• A crawl that includes status, indexability, canonical, robots, title, headings, structured data, links, and content metrics.
• Server or CDN headers for representative URLs.
• The XML sitemap and robots.txt response.
• Search Console Page Indexing and performance exports.
• Analytics landing-page and conversion data.
• The source repository and deployment configuration.
• Core Web Vitals field data plus lab traces for reproduction.

Protect secrets and user data. API keys belong in environment variables, not prompts or committed files. Reduce exports to the columns needed for analysis, especially when analytics contains identifiers.

Use an evidence ladder

Technical findings become more reliable when evidence is ranked. A source-code guess is weaker than a rendered response. A single lab run is weaker than a stable field pattern. Search Console's chosen canonical is more useful for an indexation investigation than an audit tool's generic “canonical missing” warning.

Ask Claude Code to cite the evidence level for every issue. If it only has source code, the finding should say “likely” until the live output confirms it.

Step 1: test hostname and redirect consistency

Check HTTP, HTTPS, apex, and www variants. Each non-preferred variant should resolve through as few permanent redirects as practical to the same canonical destination. Test representative deep paths, not only the homepage. Confirm that redirects preserve required paths and safe query parameters.

Look for redirect chains, loops, mixed policies, temporary redirects used for permanent moves, and internal links that point to an intermediate URL. Search engines can follow redirects, but a clean internal graph communicates the destination directly and reduces wasted requests.

When a domain migration is involved, do not generate a blanket rule until legacy mappings are understood. Export high-value old URLs, backlinks, and traffic, then create a one-to-one map where a true replacement exists. Redirecting every removed URL to the homepage is not a meaningful substitute.

Step 2: audit robots controls correctly

Fetch /robots.txt as a file and confirm it returns a successful plain-text response. Review user-agent groups, allow and disallow precedence, wildcard behavior, sitemap declarations, and environment-specific rules. A staging block accidentally deployed to production can remove crawl access across the site.

Robots.txt controls crawling, not guaranteed indexing. If a URL must leave search results, use authentication, removal where appropriate, or an indexable response with a noindex directive that the crawler can actually see. Blocking the URL and expecting the crawler to read its meta robots tag is contradictory.

Check meta robots and X-Robots-Tag headers on representative files and pages. Resolve conflicting directives conservatively. Confirm that CSS, JavaScript, and important images needed to understand the page are not blocked. Google's technical guidance recommends using robots rules for crawl control and other methods for index control: Google's technical SEO documentation.

Step 3: validate status codes and soft errors

Group crawled URLs by status and template. A handful of intentional redirects is different from thousands of redirected internal links. For every 4xx or 5xx URL, find its internal referrers, sitemap membership, organic history, and replacement if one exists.

Test nonexistent URLs. They should return a real 404 or 410, not a branded page with a 200 response. Soft 404s waste crawl attention and send ambiguous indexing signals. The custom error page should still provide useful navigation without pretending the missing content exists.

Review server errors over time rather than relying on one crawl. Logs, uptime monitoring, and Search Console can reveal intermittent problems that a clean test misses. Separate application errors, origin timeouts, CDN failures, and rate limits because their fixes belong to different systems.

Step 4: reconcile indexability signals

For every URL sample, compare five fields: HTTP status, robots directive, canonical target, sitemap inclusion, and internal links. These signals should tell one coherent story. An indexable canonical page should usually return 200, permit indexing, self-canonicalize, appear in the sitemap when important, and receive crawlable internal links.

Claude Code can join crawl and sitemap exports by normalized URL and produce these combinations. Do not automatically “fix” every mismatch. Some syndicated, filtered, or campaign pages intentionally canonicalize elsewhere. The audit must explain why the combination is harmful for this page group.

Step 5: inspect canonical implementation

Canonical tags should use absolute preferred URLs and appear once in the final rendered head. Check self-referencing canonicals on unique pages, cross-canonicals on genuine duplicates, pagination behavior, parameters, and protocol or host mismatches. Confirm that canonical targets return 200 and are themselves indexable.

Trace errors to the shared metadata function or content source. Common defects include falling back to a category URL, dropping a locale segment, using the request host from a preview deployment, and constructing URLs with double slashes. A template fix is usually better than editing individual pages, but validate every template after changing it.

Canonical is a hint, not a command. Strong internal links, redirects, sitemaps, and duplicate content patterns should reinforce the same preferred URL. When Search Console selects a different canonical, compare the full signal set instead of repeatedly changing only the tag.

Step 6: review the XML sitemap

A sitemap should be a clean inventory of canonical URLs the site wants crawled and indexed. Fetch the index and child files, validate XML, check encoding, and confirm the declared location in robots.txt. Sample URLs from every sitemap family.

Include only final, canonical, indexable, successful URLs. Exclude redirects, error pages, noindex routes, internal search, tracking variants, and duplicate filters. Use a truthful lastmod when the primary content actually changes. Generating the current timestamp for every URL on every deployment makes the field meaningless.

For a small site, a framework-generated sitemap is enough. For a large site, split files by stable page type or another operationally useful boundary. Compare database counts, sitemap counts, crawl counts, and indexed counts to find missing or inflated families.

Step 7: analyze internal architecture

Build a directed graph from crawlable internal links. Measure click depth from stable entry points, inlinks per canonical page, orphan candidates, broken targets, redirected links, and anchor-text patterns. High-value pages should be reachable through the interface, not only listed in a sitemap.

Inspect rendered navigation on desktop and mobile. JavaScript event handlers, hidden menus, or client-only widgets can sometimes produce links that crawlers or keyboard users cannot reliably follow. Prefer semantic anchors with real href values for destinations.

Internal links should help a reader continue a task. A blog cluster can link from a broad guide to focused technical, keyword, and content guides, while those focused guides link back to the core product or workflow. Avoid sitewide exact-match anchors that turn navigation into repetitive noise.

Step 8: evaluate titles, descriptions, headings, and content

Technical audits should not stop at crawl mechanics. Export titles and descriptions by template; find missing, duplicate, overly generic, and obviously truncated patterns. Check whether the rendered H1 uniquely states the page purpose and whether subsections follow a logical hierarchy.

Do not enforce simplistic character limits as pass/fail rules. Search displays vary. Focus on uniqueness, clarity, query alignment, and the value proposition near the beginning. A page can have a technically perfect title while failing to satisfy its query.

Compare near-duplicate body content and templated thin pages. Determine whether each indexable URL has a distinct user job. Consolidate pages that compete for the same intent, improve pages with genuine independent value, and remove low-value inventory only after checking traffic, links, and business use.

Step 9: validate structured data

Extract every JSON-LD block, parse it, and group types by template. Verify required and recommended properties against current documentation. More importantly, compare values with visible content: names, prices, availability, authors, dates, breadcrumbs, and images must agree with the page.

Never invent ratings, reviews, prices, credentials, or dates to satisfy a validator. Structured data helps search systems understand entities and page content; it is not a place to add claims users cannot see. Test syntax locally, then use the relevant rich-result and schema validators on deployed examples.

Good candidates include Organization and WebSite context, Product on purchasable product pages, BreadcrumbList on hierarchical pages, and BlogPosting on articles. Mark up the most specific truthful type, not every vaguely related type.

Step 10: inspect JavaScript rendering

Compare raw HTML and rendered DOM for titles, canonical, robots, main content, links, and schema. Next.js and similar frameworks can server-render these signals, but a client-only implementation or runtime error may change the result. Check console errors and blocked resources.

Step 11: diagnose performance by template

Start with field data. The Core Web Vitals reference targets are LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1 at the 75th percentile. These metrics cover loading, responsiveness, and visual stability; the official web.dev thresholds explain how they are classified.

Use lab traces to identify causes: oversized hero images, slow server response, render-blocking resources, long main-thread tasks, third-party scripts, missing dimensions, font swaps, or hydration work. Group results by template and device. One fast homepage does not clear a slow product template.

Claude Code can locate the responsible component, optimize image delivery, move noncritical work, or reduce client-side JavaScript. Retest the same route and conditions, then watch field data after deployment. A better lab score is useful evidence, not proof of a field improvement.

Step 12: check image and media SEO

Inventory image source, rendered dimensions, intrinsic dimensions, format, byte size, loading behavior, and alt text. Above-the-fold meaningful images need appropriate priority; below-the-fold media can usually load lazily. Width and height or reserved aspect ratio help prevent layout shifts.

Alt text should communicate the image's purpose in context. Decorative images need empty alt attributes, not repeated keywords. Screenshots should have nearby captions or prose explaining what the reader should notice. Ensure important image URLs are crawlable and stable.

Turn findings into an implementation backlog

Every final issue should contain evidence, affected template or URL count, impact, confidence, proposed remedy, risk, owner, and acceptance test. Separate confirmed defects from opportunities and observations.

Use severity carefully:

• Critical: production-wide block, outage, security issue, or removal of core indexable inventory.
• High: systemic issue affecting valuable crawl, indexation, rendering, or conversion paths.
• Medium: material issue limited to a template or reducing clarity and efficiency.
• Low: localized improvement with modest expected impact.

Do not inflate severity to make the report look important. A precise five-item backlog can outperform a 200-row export.

Implement in controlled batches

Create one branch or change set per coherent fix. Preserve unrelated work, review the diff, and run lint, types, tests, and a production build. Then inspect representative pages from each affected template. If the change touches redirects, canonicalization, or robots directives, add explicit regression tests.

A deployment checklist should include:

1. Confirm production environment variables and canonical host.
2. Test status and metadata on representative URLs.
3. Fetch robots.txt and sitemap.xml from production.
4. Validate structured data output.
5. Test navigation, forms, checkout, and analytics.
6. Run a focused post-release crawl.
7. Annotate the release and monitor search reports.

Rollback criteria should be defined before release for high-risk changes. Examples include unexpected growth in 404 responses, canonical changes on protected pages, broken conversion events, or a material performance regression.

A Claude Code audit prompt that produces usable evidence

Diagnose technical SEO issues without editing files.

Scope:
- canonical host https://www.example.com
- indexable templates: product, category, guide
- exclude account, checkout, internal search

Inputs:
- crawl CSV in seo-data/crawl/
- sitemap downloads in seo-data/sitemaps/
- repository in current directory

For each confirmed issue provide:
- evidence and reproduction
- affected URL count and examples
- probable source component
- impact, confidence, risk, and effort
- recommended acceptance test

Do not infer traffic, indexation, or search volume when data is absent.

After review, ask for one accepted fix at a time. This keeps diagnosis auditable and code changes small.

What “finished” means

A technical SEO audit is finished only when the important issues can be reproduced, prioritized, assigned, and verified—not when a crawler finishes. Claude Code is valuable because it shortens the distance between symptom and tested implementation. The analyst remains responsible for the page strategy, evidence quality, and business tradeoffs.

Use the process as a recurring control loop. Save the crawl configuration, baseline outputs, accepted decisions, and tests. On the next release, rerun the same checks and compare page groups. Over time the audit becomes less of a periodic emergency and more of a dependable part of shipping the website.