Claude Code helps developers build websites, components, and entire web applications quickly. However, working code does not guarantee that pages will be properly indexed by Google, attract organic traffic, or meet technical SEO requirements. Problems often become apparent only after publication: search engines cannot access some of the content, internal links do not work as expected, meta tags are duplicated, or page speed is poor.
This guide covers 10 common SEO mistakes that can occur when developing websites with Claude Code. Each section explains how to identify the problem, why it matters, and how to use a ready-made prompt to investigate and fix it. These instructions are suitable for auditing an existing project, improving individual pages, and establishing permanent development rules in the CLAUDE.md file.
If you use Claude Code to build an SEO-friendly website, do not limit your checks to appearance and functionality. Review the source HTML, page indexing, heading structure, metadata, internal linking, images, and actual performance metrics.
1. Excessive DOM Size and Unnecessary HTML Wrappers
One issue that can appear in AI-generated code is excessive element nesting. Instead of a few meaningful containers, a page may contain long chains of <div> elements, empty blocks, and components that add their own wrappers even when those wrappers serve no purpose in the layout or functionality.
A large number of DOM nodes does not automatically mean that a website will rank poorly. However, an unnecessarily complex structure can increase HTML size, complicate style calculations, and put additional strain on the browser. Depending on the implementation, this can affect performance, page processing time, and Core Web Vitals.
How to check: Open DevTools, go to the Elements tab, and inspect the DOM structure. You can also use Lighthouse and PageSpeed Insights. If a page contains deeply nested containers, determine which ones are actually necessary instead of removing elements solely to reduce their number.
Prompt for Claude Code:
Audit the project's DOM structure and identify excessive HTML nesting.
1. Find unnecessary div wrappers, empty containers, and components that serve no independent purpose.
2. Remove elements only after checking their impact on CSS, JavaScript, accessibility, and interface behavior.
3. Simplify the structure wherever possible without losing functionality.
4. Do not change the visual appearance of the page unnecessarily.
5. Do not impose an arbitrary nesting limit on all elements. Evaluate each component according to its purpose.
6. Check whether the changes introduce additional issues with CLS, INP, or LCP.
7. Compare the number of DOM nodes before and after the changes, along with available performance test results.
8. Report the changes and identify which improvements are supported by measurements.2. JavaScript, Rendering, and Google Indexing
A website can work perfectly in a browser while still creating problems for search engines. For example, headings, product descriptions, or the main body text may appear only after client-side JavaScript runs. Data may be loaded through separate requests, while the server returns almost empty HTML.
Google can process JavaScript, so client-side rendering is not inherently an SEO mistake. Problems arise when Googlebot cannot retrieve the necessary content, script execution fails, or important links and data are generated in an unreliable way.
Websites built with React, Vue, and other JavaScript frameworks deserve particular attention. For informational pages, category pages, product listings, and landing pages, server-side rendering (SSR) or static site generation (SSG) can simplify indexing and make content available sooner. However, the choice should depend on the project’s architecture rather than a blanket assumption that every website needs server-side rendering.
How to check: Compare the original HTML with the rendered page using Google’s URL Inspection tool in Search Console. Check whether important text, headings, and links are present in the HTML and whether JavaScript errors prevent content from loading.
Prompt for Claude Code:
Perform a technical SEO audit of JavaScript rendering in this project.
1. Determine how important pages are rendered: on the server, through static generation, or in the browser.
2. Identify main content, headings, metadata, and internal links that may be missing from the initial HTML or fail to appear after rendering.
3. Check JavaScript errors, failed network requests, and dependencies that prevent search engines from accessing content.
4. Ensure important text is accessible without requiring a click, hover, or other user interaction.
5. Verify that links use valid anchor elements with href attributes.
6. If content loads dynamically, evaluate whether it can be retrieved and indexed reliably.
7. Consider SSR or SSG where they solve identified problems.
8. Do not rewrite the project using a different framework without a clear justification.
9. Inspect the HTML and rendered page using available tools.
10. Report the problems found, changes made, and checks that should be completed in Google Search Console.3. Duplicate Meta Tags, Unnecessary Code, and Unused Resources
AI-assisted development can leave behind duplicate <meta> tags, unnecessary script imports, unused styles, and fragments of old templates. Sometimes several components attempt to generate the page title, description, or canonical URL at the same time, resulting in conflicting output.
For SEO, the contents of <head> deserve particular attention. Duplicate metadata can complicate snippet management and canonicalization. Unnecessary scripts and styles can also increase the amount of data that must be downloaded and make the website harder to maintain.
Not every additional tag or code comment harms Google rankings. The goal of an audit is to eliminate genuine duplication, conflicts, and unnecessary overhead rather than mechanically reducing the number of lines in the codebase.
How to check: Inspect the source HTML of several page types, examine the <head> section, and run a crawler such as Screaming Frog SEO Spider. Use Lighthouse and browser developer tools to identify unused CSS and JavaScript.
Prompt for Claude Code:
Audit the project's HTML markup and loaded resources.
1. Find duplicate title, meta description, canonical, and other conflicting metadata tags.
2. Check which component generates metadata for each page type.
3. Identify empty HTML elements, leftover template fragments, and unused CSS or JavaScript imports.
4. Check whether the same libraries are loaded multiple times.
5. Remove code only after confirming that components, plugins, and third-party integrations do not depend on it.
6. Do not remove necessary tags or attributes merely to simplify the markup.
7. Preserve the existing design and functionality.
8. After making changes, inspect the final HTML for several page types.
9. Provide a list of fixes, explain why they were necessary, and describe potential consequences.4. Incorrect HTML Semantics
AI-generated interfaces sometimes use <div> elements for almost everything. Navigation, main content, lists, and interactive elements may lack appropriate HTML semantics.
Semantic markup helps browsers, assistive technologies, and search engines interpret document structure. However, replacing every <div> with a semantic element without analyzing its purpose will not solve the problem. Each element must match the role of its content.
For example, primary navigation belongs in <nav>, the main page content in <main>, a standalone article in <article>, and lists in <ul> or <ol>. Use <button> for an action and <a href="..."> to navigate to another page.
How to check: Inspect the element tree in DevTools and test the accessibility of interactive components. Pay attention to buttons, menus, lists, tables, headings, and the main content area.
Prompt for Claude Code:
Audit HTML5 semantics throughout the project.
1. Check the use of header, nav, main, article, section, aside, and footer.
2. Use semantic elements only where they match the purpose of the content.
3. Use button for actions and a with a valid href for navigation.
4. Mark up actual lists with ul or ol and li, and tables with table, tr, th, and td.
5. Check accessible names for buttons, input fields, and navigation elements.
6. Verify the main content structure on each page.
7. Do not replace elements mechanically or create multiple main elements on a page.
8. Preserve CSS, responsive behavior, event handlers, and visual design.
9. Test accessibility and interactive functionality after the changes.
10. List the issues found and the fixes applied.5. Problems with H1, H2, and H3 Heading Structure
Headings do more than format text. They help readers understand a page’s content at a glance and help search engines interpret its structure and main topics. A chaotic heading hierarchy makes content harder to navigate.
Common mistakes in Claude Code projects include multiple main headings generated by different parts of a template, skipped heading levels, empty headings, and the use of H2 or H3 elements purely to control font size. Another issue occurs when a website template adds its own H1 on top of the article title.
A single clear H1 is a useful practical recommendation, but multiple H1 elements do not automatically trigger a Google penalty. What matters more is that headings accurately describe the content, avoid unnecessary duplication, and create a logical hierarchy.
How to check: Crawl the website or use a browser extension such as HeadingsMap. Check the homepage, category pages, articles, product pages, and other templates separately.
Prompt for Claude Code:
Audit H1–H6 headings across all page types and templates.
1. Find empty, duplicated, and misleading headings.
2. Check whether a shared template adds an unnecessary H1 to an article or product title.
3. Ensure headings create a clear hierarchy of sections.
4. Use H1 to identify the page's main topic, H2 for major sections, and H3 for nested subsections.
5. Do not use heading elements solely to change font size.
6. Do not insert keywords into headings unless they accurately reflect the content.
7. Preserve the visual design, moving styles into CSS classes where necessary.
8. Generate heading trees before and after the changes for each page type.
9. Identify issues that require editorial decisions.6. Internal Links Without href and Broken Internal Linking
Internal linking helps search engines discover website pages and understand the relationships between sections. If Claude Code implements navigation entirely through JavaScript event handlers, some links may be inaccessible to conventional crawling methods.
For example, an element such as <div onClick="..."> or a handler that calls router.push() may be used instead of an anchor with a URL. The element might work for visitors, but it is not a conventional HTML link. For page navigation, prefer <a href="..."> or routing components that generate valid anchor elements.
Pagination, breadcrumbs, category links, navigation menus, and footer links deserve particular attention. If an important page can only be reached through a complicated sequence of interactions, search engines may have difficulty discovering it.
How to check: Run a crawler and compare the number of discovered URLs with the number you expect. Inspect links in the source HTML, check the HTTP status codes of destination pages, review redirects, and identify pages with no internal incoming links.
Prompt for Claude Code:
Audit internal linking and website navigation.
1. Check menus, breadcrumbs, pagination, cards, contextual links, and footer navigation.
2. Use a elements with real href attributes, or routing components that generate valid links.
3. Find navigation elements that rely exclusively on onClick and determine whether semantic links are appropriate.
4. Identify href="#", javascript:void(0), and hash-based routes used instead of normal page URLs.
5. Do not modify anchor links that legitimately navigate to sections of the current page.
6. Check destination URLs, redirects, and server responses.
7. Find important pages without internal incoming links.
8. Do not add links automatically without considering the website structure and context.
9. Report internal linking issues and fix confirmed problems.7. Duplicate Titles, Meta Descriptions, and Canonical Errors
Meta tags remain an important part of technical SEO. If every page uses the same title, descriptions do not reflect the actual content, or canonical tags point to the homepage instead of the relevant page, search engines may misinterpret the website’s structure.
However, there is no need to impose identical character limits on every page’s metadata. Title and description lengths are practical guidelines for how text may appear in search results, not strict ranking rules. Relevance, clarity, and alignment with the page content matter more.
Canonical tags require separate attention. In most cases, a canonical should identify the preferred version of a page. But for filters, sorting options, URL parameters, pagination, and pages with similar content, the correct approach depends on the website’s architecture. Automatically removing all URL parameters from canonical tags can incorrectly consolidate independent pages.
How to check: Review the Pages report in Google Search Console and use a crawler that reports titles, descriptions, canonical URLs, and indexing status. Compare the declared canonical with the URL Google has selected.
Prompt for Claude Code:
Audit metadata and canonical tags across all website templates.
1. Find missing, duplicated, and irrelevant title and meta description tags.
2. Ensure metadata reflects the content of each page.
3. Suggest titles and descriptions based on search intent and actual content, without mechanically inserting keywords.
4. Check canonical tags on the homepage, articles, categories, product pages, paginated pages, and URLs with parameters.
5. Do not automatically remove URL parameters from canonical tags. First determine the purpose of each URL and the indexing rules.
6. Find independent pages that incorrectly point to the homepage or another irrelevant URL.
7. Do not add meta keywords. Google does not use this tag for web ranking.
8. Generate a table containing URL, title, description, canonical, and identified issues.
9. Verify the final HTML after changes and preserve the existing website architecture.8. Schema.org Structured Data Errors
Structured data helps search engines interpret information about articles, products, organizations, breadcrumbs, and other entities. When generating code with AI, it is important to check not only whether the JSON-LD syntax is valid but also whether every value is accurate.
Claude Code may add ratings, prices, review counts, or other details that are not actually displayed on the page. Another common problem is choosing an unsuitable Schema.org type or implementing markup that exists in the vocabulary but does not meet Google’s requirements for rich results.
Valid JSON-LD does not guarantee that a rich snippet will appear. Google applies specific requirements to each supported result type and considers page content and site quality. You must therefore verify both the data and the page’s eligibility for a particular search appearance.
How to check: Use Google’s Rich Results Test for structured data types supported by rich results and the Schema Markup Validator to validate the Schema.org vocabulary. Compare every value in the markup with the information available to visitors.
Prompt for Claude Code:
Audit Schema.org structured data throughout the project.
1. Find existing JSON-LD markup and validate its structure.
2. Compare types and properties with the actual content of each page.
3. Never invent ratings, reviews, prices, addresses, publication dates, or other values.
4. Use suitable types such as Organization, Article, Product, and BreadcrumbList only when they match the page content.
5. Check Google's requirements separately for each rich result type.
6. Do not add FAQPage or other markup solely in the hope of expanding search snippets.
7. Avoid conflicting or duplicated JSON-LD blocks.
8. Validate the syntax and the implementation available in the project.
9. Prepare a list of pages, their Schema.org types, detected errors, and required fixes.
10. Identify which results need further testing with Rich Results Test and manual review.9. Images, Page Speed, and Core Web Vitals
Images often account for a substantial share of a webpage’s total size. If Claude Code inserts full-resolution files without responsive alternatives, omits image dimensions, or loads every resource immediately, the website may become slower, particularly on mobile devices.
Image SEO can also suffer. The alt attribute describes an image’s content, while explicit dimensions allow the browser to reserve space and reduce layout shifts. WebP and AVIF can reduce file sizes when appropriate quality settings are used and compatibility with target browsers is considered.
Lazy loading requires particular care. The main above-the-fold image, if it contributes to LCP, should generally not use loading="lazy". The fetchpriority="high" attribute may help prioritize that image, but it should not be applied indiscriminately to every image. Other images should be loaded according to their position and actual performance impact.
How to check: Run PageSpeed Insights or Lighthouse for mobile and desktop. Review LCP, INP, and CLS, image sizes, render-blocking resources, and loading recommendations. For real-world performance, also consider field data when available.
Prompt for Claude Code:
Audit images, resource loading, and Core Web Vitals.
1. Find images without alt attributes. Use alt="" for decorative images.
2. Check for width and height attributes or another reliable method of reserving layout space.
3. Identify images that can be optimized in terms of file size and quality.
4. Consider WebP, AVIF, and responsive srcset where appropriate.
5. Identify the main image affecting LCP and check how it is loaded.
6. Do not use loading="lazy" on an image that needs priority loading above the fold.
7. Configure loading for other images according to their position and requirements.
8. Find unnecessary libraries, oversized resources, and scripts that affect loading performance.
9. Do not remove functionality simply to reduce code size.
10. Run available tests before and after the changes and report measured LCP, INP, and CLS results. If field data is unavailable, state that explicitly.10. Skipping the Final SEO Check Before Launch
Even when individual development tasks are completed correctly, problems can emerge during release that prevent the entire website or important sections from being indexed. For example, a noindex directive from the staging environment may remain on the production site, robots.txt may block necessary pages, or sitemap.xml may contain URLs that redirect or return errors.
Another risk is trusting Claude Code’s report without verifying the actual result. The model may modify source files without accounting for build settings, server configuration, HTTP headers, or CMS behavior. After making changes, you need to inspect not only the code but also what the published website actually returns.
However, a Disallow directive in robots.txt is not always a mistake, and noindex may be appropriate for certain pages. The important thing is to verify that the configuration matches the intended indexing strategy.
How to check: Open robots.txt and sitemap.xml on the production domain, inspect important URLs in Google Search Console, and review the final HTML. Also check response codes, redirects, canonical tags, and the X-Robots-Tag HTTP header.
Prompt for Claude Code:
Perform a final technical SEO audit before releasing the project.
1. Check robots.txt and determine whether it blocks important pages or resources that need to be indexed.
2. Check sitemap.xml for valid URLs, response codes, redirects, duplicates, and consistency with the indexing strategy.
3. Find noindex, nofollow, and X-Robots-Tag directives in the configuration, source code, and available server responses.
4. Do not remove these directives automatically. First determine which pages they are intended to affect.
5. Check HTTP status codes for important pages, redirect chains, and handling of nonexistent URLs.
6. Retrieve the final HTML using available tools and check title, description, canonical, H1, main content, and internal links.
7. Verify sitemap and canonical settings for pages that should be indexed.
8. Run available technical SEO and performance tests.
9. Do not claim to have checked Google Search Console unless you actually have access to the relevant data.
10. Prepare a report covering detected errors, changes made, test results, and items requiring manual review before release.General SEO Prompt for Claude Code
If you regularly use Claude Code to develop and maintain a website, you can combine these instructions into a permanent set of project rules. The CLAUDE.md file in the repository root is a convenient place to store them. This helps establish consistent requirements for HTML, metadata, indexing, and result verification without repeating the same instructions for every task.
The following prompt provides a foundation for technical SEO audits. Save it in your project and use it when checking new pages, modifying templates, or preparing a release.
You are working on a web project where Google indexing, technical SEO, performance, and accessibility are important.
Follow these rules when developing or modifying code.
INDEXING AND RENDERING
- Check whether search engines can access the main content after rendering.
- Prevent JavaScript errors from blocking text, links, or important data.
- Use SSR or SSG when they suit the project architecture and solve specific problems.
- Do not make important content accessible only through user interactions when that prevents reliable discovery.
- Provide accessible links for paginated navigation.
- Inspect the actual HTML, not just the source components.
HTML AND SEMANTICS
- Use semantic HTML5 elements according to their purpose.
- Avoid unnecessary div wrappers and empty elements.
- Use button for actions and a href for navigation.
- Check the structure of headings, lists, tables, and main content.
- Do not change the appearance or functionality unnecessarily.
- Consider interface accessibility.
INTERNAL LINKS
- Use valid URLs and links with real href attributes.
- Check menus, breadcrumbs, pagination, cards, and contextual links.
- Find important pages without internal incoming links.
- Do not change page URLs or routing without evaluating the consequences.
- Preserve existing redirect rules.
METADATA
- Check that title and meta description are unique and relevant to page content.
- Do not insert keywords mechanically.
- Validate canonical tags according to page type, URL parameters, and the indexing strategy.
- Do not use meta keywords as a Google ranking technique.
- Follow appropriate indexing rules for filters, pagination, and technical pages.
STRUCTURED DATA
- Use Schema.org only when the markup matches the actual content.
- Never invent ratings, reviews, prices, addresses, or other details.
- Validate JSON-LD syntax and current Google requirements for rich results.
- Do not promise rich snippets simply because the markup is valid.
IMAGES AND PERFORMANCE
- Check alt attributes, image dimensions, and responsive loading.
- Use modern image formats where they provide measurable benefits.
- Do not lazy-load the main image if this harms LCP.
- Optimize resources without sacrificing quality or functionality.
- Test LCP, INP, and CLS using available tools.
- Distinguish laboratory results from real-user data.
FINAL VERIFICATION
- After making changes, inspect the final HTML rather than relying only on source code.
- Check robots.txt, sitemap.xml, canonical tags, metadata, and HTTP status codes for important pages.
- Look for accidental noindex directives and other indexing restrictions.
- Run available tests for affected pages.
- Do not claim to have performed checks that were not actually completed.
- Do not automatically change settings whose consequences have not been evaluated.
- Before making changes, assess their impact on the existing architecture, URLs, and functionality.
At the end of every task, provide a concise report:
1. What was checked.
2. Which problems were found.
3. What was changed.
4. Which tests were performed and their results.
5. What requires manual review or access to external tools.
If a requirement cannot be implemented in the current architecture, explain why and propose a justified alternative.What to Keep in Mind When Using Claude Code for SEO
Claude Code can speed up development, identify source-code issues, and help with technical optimization. However, the quality of the result depends on the project, the constraints you provide, and how carefully the final implementation is tested.
Do not assume that every generated implementation is an SEO mistake simply because it differs from a familiar template. Client-side JavaScript is not prohibited, multiple H1 elements do not automatically trigger a penalty, and reducing the number of DOM nodes does not guarantee higher rankings. Focus on confirmed problems and measure the results of your changes.
If you are building a website from scratch, start with URL architecture, indexing rules, semantic markup, and content rendering. If the website is already live, begin with a technical SEO audit, prioritize the most serious issues, and only then modify the code.
The principle is straightforward: use Claude Code as a development and analysis tool, but do not replace website testing with its conclusions. Combine clear instructions, source HTML inspection, performance testing, crawling, and Google Search Console data. This approach helps identify technical problems that can genuinely interfere with search visibility.
