Treat every keyword as a proposed change to the website
A keyword is not useful because it looks attractive in a spreadsheet. It is useful when it points to a searcher need your business can answer on the right URL without creating a second page that competes with the first.
Claude Code is well suited to this decision when the website lives in a repository. It can inspect page routes, content files, templates, navigation, and project guidance next to the research evidence you provide. The goal is not to let a coding agent choose a phrase and start editing. The goal is to produce a keyword change request that explains which page should own the topic, what evidence supports the choice, and what a reviewer must approve.
Use this workflow if: your marketing site, documentation, or content collection is version-controlled.
You will finish with: one primary query, a small supporting set, an owner URL, a proposed file list, and a no-edit decision memo.
You need: a clean working tree or a known baseline, authorized keyword data, a current URL inventory, business facts, and a live SERP review completed by a human or an approved browser tool.
Done means: a content owner can accept or reject the opportunity before Claude Code changes a source file.
Build a repository map before discussing candidates
Start in read-only mode. Ask Claude Code to locate the files that define public pages and the rules that govern edits. Do not begin with a request such as "find the best keywords for this site." That invites a broad answer without a reliable owner-page check.
Use a narrow reconnaissance prompt:
Inspect this repository without editing files.
Find:
1. project guidance that applies to content or SEO work;
2. the page, route, or content directories that produce public URLs;
3. any sitemap, navigation, redirect, or canonical configuration;
4. files that contain page titles, descriptions, headings, and body copy;
5. existing pages related to [customer problem].
Return a repository map with file paths and uncertainties. Do not propose edits yet.The expected output is a short map, not a site audit. It should distinguish source content from generated output and identify any area Claude Code cannot interpret safely.
Quality check: every claimed page relationship includes a path. If the response talks about "the website" without naming files, it is not ready.
Recovery: provide the build command, framework, or content-directory location. If the repository does not contain the published content, switch to an export-first workflow rather than pretending the repo is complete.
Store research as evidence, not instructions
Keep supplied metrics and observations separate from executable project guidance. A small research directory makes provenance easier to review:
seo-research/
inputs/
candidate-keywords.csv
url-inventory.csv
business-facts.md
serp-notes.md
decisions/
keyword-change-request.mdIf these files contain private data, put them in an approved location and confirm whether they should be ignored by Git. Do not paste API tokens, account cookies, or customer records into the repository.
The candidate file should preserve the original provider fields. If search volume, difficulty, CPC, trend, or intent is missing, use UNKNOWN. Claude Code can normalize supplied data; it should not estimate absent values.
Evidence field | What it answers | What it cannot prove |
|---|---|---|
Query and market | Which wording and audience are under review | Whether the business should target it |
Provider metrics and date | What the approved source reported | Future traffic or ranking probability |
SERP page types | What Google currently appears to reward | That copying those pages will rank |
Existing URL and file path | Whether the site already addresses the need | Whether that page is performing well |
Business facts | What the page can support honestly | Search demand |
Ask Claude Code to route queries to URLs
The useful comparison is not keyword versus keyword. It is candidate query versus existing content surface.
Read the repository map and files in seo-research/inputs/.
For each candidate query:
- state the searcher job in one sentence;
- cite the supplied metric fields and observation date;
- identify the closest existing URL and source file;
- choose one route: refresh, expand, consolidate, create, or reject;
- explain the main overlap or cannibalization risk;
- list the business evidence the page would need.
Do not score UNKNOWN fields. Do not edit the website.Claude Code should be especially good at spotting structural collisions: two Markdown files that answer the same question, a product route with a thin title, a template that already generates the proposed page type, or a redirect that makes a suggested URL invalid.
Caption: Route the query through the website you already have before proposing a new page.
Use the live SERP as a feasibility test
Repository context answers "where would this live?" The live SERP answers "what kind of result is the searcher being offered now?" They are different questions.
Review the result page outside the model or through an explicitly authorized browser tool. Record only what you can observe:
- dominant page types, such as category, tool, guide, product, or forum;
- result features, including video, local, shopping, images, or AI answers;
- whether the query changes meaning across markets;
- the brands or institutions that recur;
- gaps the business can fill with first-hand evidence.
Then ask Claude Code to compare those notes with the proposed route. A documentation page should not win simply because it is easy to edit when the SERP clearly calls for an interactive tool. A new guide should not be approved if an existing product page already satisfies the same job.
Write a no-edit change request
The decision document is the control point between research and implementation. Require this shape:
# Keyword change request
Decision: [refresh / expand / consolidate / create / reject]
Primary query: [...]
Supporting queries: [...]
Target market: [...]
Owner URL: [...]
Source file or proposed route: [...]
Evidence:
- supplied metrics and dates
- SERP observations
- existing-page findings
- approved business facts
Proposed change surface:
- files that may change
- files that must not change
- title/H1/content intent
- internal-link implications
Open questions:
- UNKNOWN data
- claims requiring an owner
- technical review needed
Approval required from: [...]This is deliberately more specific than a content brief. It tells a reviewer what the keyword decision would change in the repository.
Approve the decision before requesting a diff
Use four gates:
- Intent gate: the proposed page type matches the observed searcher job.
- Ownership gate: one URL, not several, is responsible for the topic.
- Evidence gate: the business can support the important claims.
- Change gate: the proposed file scope is narrow enough to review and test.
If any gate fails, reject or defer the candidate. Do not average the failure away with a weighted score.
After approval, start a separate implementation request. Tell Claude Code exactly which change request was approved, which files it may edit, and which checks must pass. Keyword selection and content implementation should not be one unbroken agent turn.
Caption: The keyword decision ends at approval; implementation begins as a separate, bounded task.
Verify the handoff
Before calling the task complete, confirm:
- the owner URL appears only once in the decision;
- every metric retains its source date and market;
UNKNOWNfields remain visible;- the proposed file list matches the repository map;
- no content or configuration file changed during research;
- a named human owns the approve, reject, or defer decision.
Run git status --short or the repository's equivalent baseline check. If research artifacts appear unexpectedly, decide whether they belong in version control before continuing.
Common failure modes
Failure | Why it happens | Better response |
|---|---|---|
Claude Code picks the largest volume | Business fit was never defined | Add conversion, evidence, and audience constraints |
A new article is proposed for every query | The URL inventory was missing | Route each query to an existing page first |
The agent edits while researching | The prompt combined decision and implementation | Require a no-edit change request |
A difficulty score becomes a forecast | The metric is treated as certainty | Preserve the provider label and use it comparatively |
A generated directory is analyzed as source | Build structure was not mapped | Identify source-of-truth directories first |
FAQ
Can Claude Code get keyword volumes from the repository?
Only if approved research data is already present or an authorized provider connection supplies it. A repository does not contain search demand by default.
Should the research files be committed?
That depends on your data policy. A sanitized decision memo may belong in version control, while raw exports or account-derived data may need an ignored or external location.
Can Claude Code publish the selected page?
It may be technically capable in some environments, but this workflow does not grant that authority. Publishing remains a separate reviewed action.
Is a new file always required for a new primary keyword?
No. Refreshing, consolidating, or expanding an existing owner page is often the better decision.
Author: Julian Mercer, 14-Year Technical SEO Practitioner at Auspia. Julian writes about repository-aware SEO, crawlability, structured data, and safe implementation workflows.
