A reliable Claude Code SEO workflow is a controlled delivery loop, not one giant prompt asking the agent to optimize everything.
Use this order: scan the production site, classify the failure, select one dependency, package the evidence and constraints, let Claude Code inspect connected files, approve a bounded plan, implement and test, review the diff, deploy, inspect the anonymous production response, rescan, and measure later search or AI visibility signals separately.
This developer guide focuses on execution mechanics and instruction placement. It complements the existing Claude Code SEO consultant article, which explains the consultant concept, by showing exactly when to use CLAUDE.md, a skill, a hook, a one-off task, and a post-deploy evidence record.
Quick Questions
Inspect the live production URL and identify one observable failure before asking Claude Code to edit the repository.
Use a hook for deterministic lifecycle actions that must run, such as linting after edits or blocking protected operations.
Local work is complete after review and tests; the website fix is verified only after deployment, public inspection, and rescanning.
Definition of done by stage
| Stage | Completion evidence | Not yet proven |
|---|---|---|
| Local edit | Reviewed diff and passing relevant checks | Deployed behavior. |
| Deployment | Expected version active on production | Crawler refresh or indexing. |
| Public verification | Anonymous route and rescan pass | Rankings, citations, or traffic. |
| Measurement | Dated external reporting evidence | Causation from one change alone. |
Main Explanation
Stage one is production evidence. Scan the canonical host and open the affected route anonymously. Capture the final status, redirects, canonical, index directives, rendered text, links, structured data, and sitemap state. Write one sentence describing the observed failure and one sentence describing the expected behavior. This becomes the task boundary.
Stage two is dependency classification. Access and successful responses come before indexing controls; indexing controls come before discovery; discovery comes before content enhancement; content clarity comes before optional machine-readable additions. Do not ask Claude Code to add FAQ schema while the route returns a firewall challenge or points its canonical to another URL.
Stage three is instruction placement. Put permanent project architecture, protected routes, and normal test commands in CLAUDE.md. Put the repeatable audit-to-fix process in an SEO skill. Use a hook only for deterministic enforcement. Keep the specific URL, failure, and acceptance criteria in the one-off task so stale incident details do not become permanent instructions.
Stage four is repository discovery. Ask Claude Code to read applicable instructions and locate the route, content source, shared renderer, layout, metadata, sitemap logic, styles, and tests. Require a short impact map before edits. This reduces the chance of patching compiled output, duplicating shared logic, or breaking another page that uses the same template.
Stage five is the bounded plan. State exactly what may change and what must remain stable. Protect private application routes, authentication, billing, APIs, webhooks, analytics, user data, and unrelated UI. If content changes, provide verified product facts and forbid fabricated evidence. If a new public URL is considered, require a distinct visitor need and an overlap check.
Stage six is implementation and local validation. Make the smallest correct edit, then run syntax checks, tests, internal-link audits, XML parsing, and rendered-page checks proportional to the change. For content pages, inspect title, description, H1, canonical, robots meta, Markdown alternate, visible FAQ, JSON-LD, contextual links, image loading, and responsive layout.
Stage seven is diff review. Read the final patch as a reviewer. Remove unrelated formatting churn, stale references, duplicate links, copied boilerplate, unsupported claims, and generated test artifacts. Confirm that user-owned changes were preserved. A large diff is not proof of a thorough fix; it often makes the result harder to verify.
Stage eight is deployment and public verification. Release through the existing process, wait for the active version, open the canonical route without a session, inspect the real response, and rerun the same scan. CDN cache, hosting adapters, DNS, redirects, and environment configuration can make production differ from local output.
Stage nine is outcome measurement. Record the deployment date and evidence baseline. Search Console can later show discovery and search impressions; analytics can show referrals and conversions; verified logs can show crawler requests. None of these alone proves AI recommendation. Keep technical completion separate from delayed external outcomes.
Practical Steps
- Scan and document one live failure.
- Classify its dependency layer.
- Place permanent, reusable, deterministic, and one-off instructions correctly.
- Ask Claude Code to map connected files.
- Approve a bounded plan with protected areas.
- Implement and run proportional checks.
- Review the complete diff and remove artifacts.
- Deploy and inspect the anonymous public route.
- Rescan and monitor delayed external evidence separately.
FAQ
Should Claude Code fix all SEO issues in one task?
Usually no. Fix the highest dependency first, verify it, then continue. Smaller tasks are easier to review and attribute.
What should a Claude Code SEO prompt include?
Include the live URL, observed and expected behavior, scan evidence, allowed scope, protected areas, project tests, and production verification steps.
How is this different from the Claude Code SEO consultant guide?
The consultant guide explains the scan-backed advisory model. This page defines the delivery stages and where each kind of Claude Code instruction belongs.
Sources and methodology
The workflow was reviewed on 2026-08-26 against Claude Code documentation for skills, CLAUDE.md, hooks, and agent behavior, plus Google guidance for JavaScript rendering and people-first content. Every completion claim is bounded to local, deployed, or external evidence.
These references support the changeable facts and study findings discussed above. Results depend on each source's sample, date, market, query set, and measurement method.