What this covers
A reusable Claude Code prompt and workflow that turns “I should audit the site” into a concrete two-hour session ending in three shipped fixes. The pain: traditional SEO audits dump 300 findings on you, most apply to two pages, and you ship nothing. Using Claude Code on your own repo, you can score findings by how many pages they touch, fix the top three with reviewed diffs, and rebuild — all without leaving the editor.
Key tools and concepts:
- Claude Code: Anthropic’s command-line AI coding agent; here it acts as a read-only auditor for the first half and a careful editor for the second.
- Content data registry: Files like
src/data/categories.tsandsrc/data/hubs.tsthat describe your site structure; pointing the agent at these is the single biggest quality lever. - Audit script: Your existing content validator (e.g.
npm run audit:content) used as ground truth after each fix.
Who this is for
Indie content site owners on Astro / Next.js / Hugo who already have Claude Code installed and a CLAUDE.md in their repo. Especially valuable for bilingual sites (EN + ZH) where hreflang and translation parity multiply the surface area.
When to reach for it
Before launch — to catch the bulk of issues while the cost of fixes is low. Then every 90 days post-launch, because models, content, and Google’s preferences drift. Also after any large content migration or template change.
Before you start
- Commit your working tree. The agent’s diffs are easier to review against a clean baseline.
- Confirm your audit script runs cleanly today. If it fails, fix that first; otherwise you cannot tell whether the agent broke something or it was already broken.
- Decide your scope: which categories, languages, and page templates to audit. “Everything” is not a scope.
- Have a sample of typical articles ready — the agent will read these as patterns, not the whole library.
Step by step
- Open Claude Code in your site repo. Confirm CLAUDE.md mentions the site’s directory layout and the audit script command.
- Run the audit prompt:
Run an SEO audit. Read src/data/categories.ts, src/data/hubs.ts, and 5 sample articles per category. Output: metadata issues, thin content candidates, internal-link gaps, hreflang issues. Do not fix anything yet. - Review the findings. Sort by how many pages each issue affects; focus on issues that affect 10+ pages. Single-page issues are not worth an agent session.
- Pick top 3 issues. For each, ask:
Fix issue 1 in the listed files. Show the diff before applying. Do not touch any other files.Approve only after reading the diff. - After each fix, run
npm run audit:contentplusnpm run build. Both must pass before moving to the next fix. - Commit after each issue. One issue per commit makes rollback surgical if you find a regression later.
- End the session by asking the agent to summarize: what was fixed, what was deferred, what new patterns it noticed. Paste that into your audit log.
First-run exercise
- Choose one category with about 30-50 articles. Smaller than your whole site, big enough to be representative.
- Run only step 2’s audit prompt against that category. Save the findings to a Markdown file.
- Fix only one finding end-to-end (steps 4-6). Note any place the agent was unclear or asked twice.
- Update CLAUDE.md with anything you learned about how to phrase the audit prompt — terms it understood, files it kept missing.
Quality check
- Did the agent read your data registry, or guess? Skim the response — references to
categories.tsfield names show it actually read. - Are findings concrete (file paths + line numbers + reproducible issue), or generic (“some articles have thin content”)? Push back on generic findings until they cite specific files.
- After each fix, did
audit:contentcount of issues actually drop? If not, the fix was cosmetic. - Are the diffs in scope? An agent fixing “metadata” should not edit article body content. If it did, your prompt was too loose.
How to reuse this workflow
- Save the audit prompt as a slash command in
.claude/commands/seo-audit.md. Run quarterly without retyping. - Track findings count over time in a simple table — quarter, total findings, top categories. The trend is more useful than any single audit.
- Build a per-finding template for the fix prompt: file path, exact change, test command. Reusable across categories.
- Re-test the workflow itself every six months — Astro’s defaults, Google’s SEO guidance, and Claude’s behavior shift.
Recommended workflow
Open repo -> audit prompt -> review findings -> fix top 3 -> validate -> commit -> log results. Two hours, three commits, measurable issue-count reduction.
FAQ
- Will Claude understand my site structure?: Better if you point it at your data registry (categories.ts, hubs.ts) first. Add a CLAUDE.md describing site conventions.
- What if the agent suggests fixes that hurt SEO?: It can; review every diff. The most common failure mode is over-aggressive keyword stuffing in titles.
- Can I skip the human review on small fixes?: On the first audit, no. After three clean audits, you can batch-review trivial fixes (single-line metadata).
- Does this work without CLAUDE.md?: Yes, but quality drops. Even a 10-line CLAUDE.md naming the data files improves agent grounding.
- How long should the audit take?: Two hours including fixes. If you exceed four hours, the scope was too broad; narrow to one category.
- What about hreflang specifically?: The audit catches obvious mismatches; deeper coverage in AI hreflang check tutorial.
Common mistakes
- Asking Claude Code to fix everything in one prompt — too broad, you get a giant diff you cannot review.
- Skipping the human review of findings — even good audits include 10-20% noise.
- Not validating with
audit:contentplus build after each fix — silent regressions slip through. - Letting the agent invent new conventions instead of following the registry — pin it to
categories.tsandhubs.ts. - Auditing the whole site at once — pick one category, learn the patterns, then scale.
- Treating the audit output as final — it is a triage list, not a fix log.