TL;DR
Most SEO audits hand you 300 findings, 250 of which touch two pages, so you ship nothing. This workflow uses Claude Code on your own repo: run it in plan mode (read-only) to score findings by how many pages they touch, fix only the top three with reviewed diffs, validate with your own audit script and a build, and commit one fix per commit. Budget two hours. You end with three shipped fixes and a measurable drop in issue count, never having left the terminal.
What you need
This is a tutorial, so here is the exact setup it assumes (as of June 2026):
- Claude Code installed and signed in. It runs Anthropic models only — Opus 4.7 (deep reasoning) and Sonnet 4.6 (fast workhorse). It ships inside the Claude Pro plan at $20/month ($17/month billed annually), so you do not need a separate API key for this workflow. See Claude pricing.
- A content site on Astro, Next.js, or Hugo with a
CLAUDE.mdat the repo root. - An existing content validator you can run, e.g.
npm run audit:content, plusnpm run build. - A clean git working tree before you start.
Why Claude Code rather than pasting pages into a chat window: the agent reads your actual files, cites real paths and line numbers, and applies fixes as diffs you approve. A chat window only sees what you paste, so it invents structure it cannot verify.
Plan mode is the safety rail
The single most important setting here is plan mode. Plan mode is a read-only permission state: Claude Code can read files and run shell commands to explore, but it cannot edit a single source file until you leave the mode. That is exactly what you want for the audit half of the session.
Three ways to enter it:
- Start the session read-only:
claude --permission-mode plan - Mid-session, press Shift+Tab to cycle
default → acceptEdits → plan - Type
/planin your prompt
Run the entire audit in plan mode. Only after you have picked your top three fixes do you leave plan mode to apply them, one at a time.
Point the agent at your data registry first
The biggest quality lever is grounding. Before any audit prompt, make sure the agent reads the files that describe your site structure — the content data registry. On this kind of Astro site those are files like src/data/categories.ts and src/data/hubs.ts. If the agent reads those, its findings reference real category and hub fields instead of guessing.
Keep CLAUDE.md under 200 lines (Anthropic’s own guidance: longer files consume more context and reduce how reliably Claude follows them). A high-signal CLAUDE.md for this workflow needs only three things: the directory layout, the exact audit command, and a one-line “always run in plan mode for audits” rule. Run /init once to generate a starting file from your codebase, then trim it.
The audit prompt
Run this in plan mode. It is read-only by construction, but plan mode makes that guarantee enforceable rather than a polite request:
Run an SEO audit in plan mode. Read src/data/categories.ts, src/data/hubs.ts,
and 5 sample articles per category. Report four buckets:
1. Metadata issues (missing/short title, short or duplicate description)
2. Thin-content candidates (body under your word floor)
3. Internal-link gaps (orphans and pages with under 2 inlinks)
4. hreflang issues (missing return tags, en vs en-us mismatches)
For each finding: file path, exact problem, and how many pages it affects.
Do not edit anything.The “how many pages it affects” clause is the whole game. It turns a flat list into a triage queue.
Score and triage
Sort every finding by page count and bucket it. Single-page issues are not worth an agent session — fix those by hand later. Use this rough cutoff:
| Pages affected | Action | Why |
|---|---|---|
| 50+ | Fix this session | Template- or registry-level bug; one fix moves many pages |
| 10–49 | Fix if it lands in your top 3 | Worth an agent diff |
| 2–9 | Batch for a later by-hand pass | Too small to justify review overhead |
| 1 | Edit manually | Not an agent task |
Pick the top three by page count. Everything else goes in the audit log for next quarter.
Apply fixes one at a time
Now leave plan mode (Shift+Tab back to default, or /accept-edits if you trust the scope). For each of your three issues:
Fix issue 1 in the listed files only. Show the diff before applying. Do not touch any other file.- Read the diff. A fix scoped to “metadata” must not rewrite article body content — if it does, your prompt was too loose.
- Approve, then run
npm run audit:contentandnpm run build. Both must pass. - Confirm the issue count from
audit:contentactually dropped. If it did not, the fix was cosmetic — revert it. - Commit. One issue per commit makes rollback surgical if you find a regression later.
End the session by asking the agent to summarize what it fixed, what it deferred, and any new pattern it noticed. Paste that into your audit log.
Worked example: the hreflang return-tag fix
The most common bilingual finding is hreflang “no return tags” — Google’s most frequent hreflang error. It means page A links to its alternate B, but B does not link back, so Google may serve the wrong language version or ignore your hreflang entirely. On a bilingual EN/ZH site this typically traces to one root cause: a translationKey mismatch or an en vs en-us value mismatch in the alternates list. Because it is registry-level, a single corrected helper can fix hundreds of pages at once — exactly the 50+ row above. Ask the agent to find the generator that emits the alternates and fix the value there, not page by page.
First-run exercise
Do not point this at your whole site on day one.
- Choose one category with 30–50 articles — smaller than your library, big enough to be representative.
- Run the audit prompt against only that category. Save the findings to a Markdown file.
- Fix exactly one finding end to end. Note any place the agent was unclear or asked twice.
- Update
CLAUDE.mdwith what you learned: terms the agent understood, files it kept missing.
Make it reusable
- Save the audit prompt as a project slash command at
.claude/commands/seo-audit.md. After that, typing/seo-auditruns the whole prompt without retyping. (.claude/commands/is the per-project location;~/.claude/commands/makes it available across all your repos.) - Track findings count over time in a small table — quarter, total findings, top categories. The trend matters more than any single audit.
- Re-test the workflow itself every six months. Astro defaults, Google’s SEO guidance, and Claude Code’s own behavior all shift.
FAQ
- Do I need a separate API key?: No. Claude Code is included in the Claude Pro plan at $20/month ($17/month annual) and draws from your normal subscription token budget. A standalone API key is only needed for unattended automation.
- Will Claude understand my site structure?: Much better if you point it at your data registry (
categories.ts,hubs.ts) and keep aCLAUDE.mdunder 200 lines naming those files. Without grounding, findings turn generic. - What if a fix hurts SEO?: It can. The most common failure mode is over-aggressive keyword stuffing in titles. Plan mode plus per-fix diff review catches this before anything ships.
- Can I skip human review on small fixes?: On the first audit, no. After three clean audits you can batch-review trivial single-line metadata changes.
- How long should this take?: Two hours including fixes. Past four hours, the scope was too broad — narrow to one category.
- What about deeper hreflang coverage?: This audit catches the obvious return-tag and value mismatches; for a focused pass see AI hreflang check tutorial.
Common mistakes
- Asking Claude Code to fix everything in one prompt — you get a giant diff you cannot review.
- Running the audit without plan mode, so a stray “and fix it” turns the audit into uncontrolled edits.
- Skipping human review of findings — even good audits include 10–20% noise.
- Not validating with
audit:contentplus a build after each fix — silent regressions slip through. - Letting the agent invent conventions instead of following the registry — pin it to
categories.tsandhubs.ts. - Treating the audit output as final — it is a triage list, not a fix log.