如何把 Claude Code Hooks 当成 SEO/GEO Quality Gates

你会建立什么

这篇教学会示范如何把 Claude Code hooks 当成实用的 SEO/GEO quality gates。目标不是笼统地让 Claude「更小心」，而是在 Claude 编辑可能伤害 search visibility 的档案时，跑 deterministic checks：metadata helpers、schema、robots rules、sitemap generation、canonical tags、analytics 和 content templates。

你会建立：

.claude/
settings.local.json
scripts/
seo-geo-hook-guard.mjs
seo-geo-launch-gate.mjs
seo-geo/
qa/
hook-test-plan.md
hook-reports/

图说：先用 warning hooks，等 checks 稳定可信后，才把高信心检查改成 blocking hooks。

步骤 1：建立小型 hook guard script

建立 folders：

mkdir -p .claude scripts seo-geo/qa/hook-reports

建立一个 hook script，检查目前 git diff，并标记 high-risk SEO/GEO files：

cat > scripts/seo-geo-hook-guard.mjs <<'EOF2'
#!/usr/bin/env node
import { execSync } from 'node:child_process';
import { mkdirSync, writeFileSync } from 'node:fs';

mkdirSync('seo-geo/qa/hook-reports', { recursive: true });

function sh(cmd) {
try { return execSync(cmd, { encoding: 'utf8' }).trim(); }
catch { return ''; }
}

const changed = sh('git diff --name-only HEAD').split('
').filter(Boolean);
const riskyPatterns = [
/robots\.txt$/,
/sitemap/i,
/canonical/i,
/noindex/i,
/schema|json-ld|structured-data/i,
/middleware\.(js|ts)$/,
/analytics|gtm|ga4/i,
/seo\.(js|ts|tsx|mjs)$/,
/metadata|meta-tags/i,
];

const risky = changed.filter(file => riskyPatterns.some(pattern => pattern.test(file)));
const report = [
'# SEO/GEO Hook Guard',
'',
`Changed files: ${changed.length}`,
'',
risky.length ? '## Risky files' : '## Risky files
None detected.',
...risky.map(file => `- ${file}`),
'',
'## Required reviewer action',
risky.length
? 'Review crawl/indexing/schema/analytics impact before continuing.'
: 'No high-risk SEO/GEO file pattern detected.',
].join('
');

writeFileSync('seo-geo/qa/hook-reports/latest-guard.md', report);

if (risky.length) {
console.error(report);
// Exit 0 for warning mode. Change to exit 2 only after the team trusts the rule.
process.exit(0);
}
EOF2
chmod +x scripts/seo-geo-hook-guard.mjs

把它接进 Claude Code 前，先手动跑一次：

node scripts/seo-geo-hook-guard.mjs
cat seo-geo/qa/hook-reports/latest-guard.md

如果你的 repo 不是 Git-based，就把 script 改成从 build system 或 PR export 读 changed files。

步骤 2：建立 launch gate script

Hooks 应该很快。比较重的 checks 放在 launch gate，让 Claude 在 final response 或 PR 前执行。

cat > scripts/seo-geo-launch-gate.mjs <<'EOF2'
#!/usr/bin/env node
import { execSync } from 'node:child_process';

const commands = [
['git status', 'git status --short'],
['changed files', 'git diff --name-only HEAD'],
];

let failed = false;
for (const [label, cmd] of commands) {
try {
const out = execSync(cmd, { encoding: 'utf8' }).trim();
console.log(`
## ${label}
${out || '(no output)'}`);
} catch (err) {
failed = true;
console.error(`
## ${label}
FAILED: ${err.message}`);
}
}

console.log('
## Manual SEO/GEO review still required');
console.log('- Check title/meta/canonical changes');
console.log('- Check schema and unsupported claims');
console.log('- Check robots, sitemap, redirects, noindex, analytics');
console.log('- Check internal links and answer extraction blocks');

process.exit(failed ? 1 : 0);
EOF2
chmod +x scripts/seo-geo-launch-gate.mjs

之后再加入真正 build command，例如 npm run build、npm run lint 或 site-specific crawler。

步骤 3：请 Claude Code 提出 hook config

不要盲贴 hook config。请 Claude Code inspect 你的 repo，产出最适合目前 Claude Code installation 的安全版本：

Inspect this repository and help me configure Claude Code hooks for SEO/GEO quality gates.

Use these scripts:
- scripts/seo-geo-hook-guard.mjs
- scripts/seo-geo-launch-gate.mjs

Requirements:
- Start in warning mode, not blocking mode.
- Run the guard after file edits that may touch SEO/GEO files.
- Do not auto-approve edits.
- Do not publish, deploy, submit URLs, or change credentials.
- Put the proposed configuration in `.claude/settings.local.json` or the current Claude Code settings location recommended by the docs.
- Explain how I can test the hook with one harmless metadata edit.

Do not edit live content until I approve the settings.

为什么要让 Claude 产生 exact config？Claude Code hook syntax 可能演进。让 Claude 依 installed version 和 current docs 产生设定；你的 scripts 和 safety policy 则保持稳定。

步骤 4：使用 starter settings pattern

如果你的 Claude Code version 支援 JSON hook settings，local settings 可能长得像：

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "node scripts/seo-geo-hook-guard.mjs"
}
]
}
]
}
}

把它当 starter pattern，不是 universal copy-paste guarantee。加入后，如果环境需要，restart Claude Code 或 reload session。

步骤 5：安全测试 hook

建立 harmless branch：

git checkout -b test/seo-geo-hooks

请 Claude Code：

Make a harmless test change to a temporary markdown file under seo-geo/qa/. Then confirm whether the SEO/GEO hook ran and show me seo-geo/qa/hook-reports/latest-guard.md.

接著用不改 production logic 的 risky filename 测试：

mkdir -p seo-geo/qa/fake-risk
cat > seo-geo/qa/fake-risk/test-sitemap-note.md <<'EOF2'
This is a test note. It is not the real sitemap.
EOF2

问 Claude：

Run the hook guard and explain whether it warns on this fake-risk file. Do not edit production sitemap, robots, canonical, schema, or analytics files.

步骤 6：决定哪些 warn、哪些 block

在把任何 hook 变成 blocking 前，先用这张表：

初学者安全 hook 会 warn、写 report、强制 review。成熟 hook 只应在 failure 机械、低模糊时 block。

步骤 7：把 rule 加到 CLAUDE.md

Hooks 跑 commands；CLAUDE.md 解释背后 policy。加入短 section：

## SEO/GEO quality gates

Before final response on SEO/GEO tasks:
- summarize changed files
- run the available validation command
- read `seo-geo/qa/hook-reports/latest-guard.md` if it exists
- flag any robots, sitemap, canonical, noindex, schema, metadata, analytics, or routing change
- do not publish, deploy, or submit URLs without explicit approval

这让 Claude 的 reasoning 和 hook output 对齐。

好的 hook output 长什么样

有用 warning 是 specific 的：

Risky files:
- src/lib/seo.ts
- src/components/JsonLd.tsx

Required reviewer action:
Review canonical generation and JSON-LD output before continuing. Run build and inspect one rendered page.

弱 warning 是：

SEO issue found. Be careful.

如果 warning 没有命名 files 和 review steps，先改善 script，再依赖它。

FAQ

Hooks 可以取代 human review 吗？

不行。Hooks 抓 repeatable mechanical risks。Claims、positioning、legal language、competitor comparisons、redirects、analytics interpretation 和 release timing 仍要人 review。

第一天就该把 hooks 设成 blocking 吗？

不要。先用 warning mode。跑过几次安全流程后，只 block false-positive risk 低的 checks。

Hook scripts 应该放哪里？

Shared scripts 放在 repo 的 scripts/。Personal hook settings 放在 local Claude Code settings，除非整个 team 已同意同一行为。

Claude Code SEO/GEO 学习路径

这篇属于 Claude Code SEO/GEO operator series。如果你从零建立 workflow，请照这个顺序：

1. 如何用 Claude Code 做 SEO Automation
2. 如何建立 Claude Code SEO/GEO Workflow Cockpit
3. 如何把 CLAUDE.md 和 Memory 用在 SEO/GEO Workflows
4. 如何用 Claude Code VS Code Extension 更新 SEO Pages
5. 2026 年最佳 GEO Claude Code Skills
6. 如何用 Claude Code Subagents 做 GEO Research
7. 如何把 Claude Code Hooks 当成 SEO/GEO Quality Gates
8. 如何用 MCP 将 Claude Code 接上 SEO 资料
9. 如何用 Claude Code GitHub Actions 做 SEO/GEO Reviews
10. 如何在 Claude Code 里跑每日 SEO/GEO Monitoring

Sources and notes

• Anthropic Claude Code docs: Hooks guide and Claude Code overview 。

Author: Julian Mercer, Auspia 14-Year Technical SEO Practitioner。Julian 撰写 crawlability、schema、rendering 与 AI-readable content 的 technical foundations。