Mirroring Competitor Codebases

Mirroring Competitor Codebases (the Codebase Mirror)

Overview

When a competitor outranks you, the instinct is to read their copy. But a lot of what search and answer engines reward is not written by a writer at all — it is emitted by a template: the JSON-LD block, the heading shape, the internal-link footer, whether the page arrives as HTML or as an empty <div id="root">. Those are codebase decisions, and they are visible in the HTML they serve.

The Codebase Mirror reads that HTML on both sides and answers one question: what does their template do that yours doesn't?

It reports gaps in one direction only. A pattern you ship and they don't is not in the report — this list exists to be acted on, and acting on it means adding what is missing.

Where the line is with analyzing-content-gaps

They are complementary and easy to confuse:

Rule of thumb: "what should this page say?" → content gaps. "what should our template emit?" → this skill. Run both when a competitor beats you on a query you care about; the fixes land in different PRs and usually different files.

Architecture: where the pieces live

Everything the engine does is unit-tested against fixtures (test/codebase-mirror.test.js, HTML in fixtures/codebase-mirror/ours/home.html and fixtures/codebase-mirror/theirs/home.html).

The loop

1. Pick comparable page types. 3–5 per side, matched by role, not by URL: their home vs your home, their money page vs your money page, two of their guide/blog pages vs two of yours. Mirroring their blog against your pricing page produces noise, and one page per side produces anecdotes — the tool warns when a side has fewer than two.

2. Get the SERP positions (optional but this is what makes the ranking mean something). From GSC via finding-underserved-keywords: your average position for the query, and theirs from the live SERP. Write them into a small JSON file:

   { "query": "invoicing software for freelancers",
     "ours":   { "url": "https://ledgerly.example/",  "position": 14.2 },
     "theirs": { "url": "https://billfold.example/",  "position": 3.1 } }
   

3. Run the mirror:

   node scripts/codebase-mirror.js \
     --ours   https://yoursite.com/ \
     --ours   https://yoursite.com/pricing \
     --ours   https://yoursite.com/guide/setup \
     --theirs https://competitor.com/ \
     --theirs https://competitor.com/pricing \
     --theirs https://competitor.com/guide/setup \
     --serp .claude/seo/serp-positions.json \
     --json .claude/seo/codebase-mirror.json
   

   Try it with no setup at all against the shipped fixtures:

   node scripts/codebase-mirror.js \
     --ours   fixtures/codebase-mirror/ours/home.html \
     --theirs fixtures/codebase-mirror/theirs/home.html
   

4. Read the ranked list. Each row is severity × SERP multiplier = impact, with the two rates that produced it (them 100% / you 0%) and a hand-off to the skill that fixes that class of gap.

5. Act, top-down, one PR per axis. Schema gaps → adding-schema-markup. Rendering → auditing-technical-seo. Heading shape → optimizing-for-generative-engines. Internal links → planning-topic-clusters. Meta coverage → optimizing-on-page or seo-bootstrap. Then re-run the mirror; the closed rows should disappear.

What it looks at, and why each axis is there

Every threshold is a named constant at the top of scripts/codebase-mirror.js. If you disagree with one, change the constant — do not argue with the output.

Reading the ranking honestly

• With --serp: the multiplier encodes how much their pattern is worth as evidence. They beat you by 10+ positions → ×2.0. They edge you out → ×1.2. You already outrank them → ×0.75 — their pattern is weak evidence, and copying a worse-performing site is how you talk yourself into work that does not pay.
• Without --serp: every row is tagged serp: "unknown" and ranked by severity alone. The tool never invents a position, and the report says so in a warning rather than quietly looking SERP-informed.
• Correlation, not causation. "They rank above you and their template does X" is not proof X is why. It is the strongest cheap evidence available — treat the high-severity rows as hypotheses worth a PR, not as a diagnosis.

Etiquette and legality

• It reads the HTML any crawler receives, at crawler volume: robots.txt is honoured for our user-agent, and a disallowed path is skipped with a warning rather than fetched anyway. One request per origin per second by default (--delay).
• It never touches a competitor's repo, admin, or private endpoints — "codebase mirror" means the shipped implementation, not their source.
• Copy patterns, never content. Emitting FAQPage because they do is fine. Copying their FAQ answers is duplicate content that Google flags and AI systems deprioritize. The report deliberately gives you rates and structures, not their prose.

What this is NOT

• Not a crawler. It mirrors the URLs you hand it. Site-wide discovery is out of scope by design — a crawl of someone else's site is a different, heavier, ruder tool.
• Not a renderer. It sees what arrives in the HTML. Content injected client-side is invisible here — exactly as it is to an AI-search crawler, which is why rendering is an axis rather than a caveat.
• Not a content brief. No entities, no sub-question analysis, no writing guidance. That is analyzing-content-gaps.
• Not a verdict on their ranking. It explains what they ship, not why Google likes them.

Common mistakes

• Mirroring one page per side. Rates over one page are anecdotes; the tool warns, and the warning is real. Three to five comparable pages per side.
• Comparing unlike page types. Their blog against your landing page manufactures gaps that mean nothing.
• Running it without --serp, then treating the order as truth. Severity-only ordering is a reasonable default and an explicitly labelled one. Get the positions if the ranking is going to drive the sprint.
• Starting with the depth row. It is last for a reason. Close schema/rendering/heading gaps, then re-measure — depth usually shrinks on its own once the structure is right.
• Copying a pattern from a site you already outrank. Check the multiplier before you build.

Lifecycle awareness

Growth → Mature. Needs a live competitor and a live you. Pre-launch there is nothing to mirror on your side — use researching-keywords-pre-launch and seo-bootstrap first, then come back once your pages exist.

What next

• Schema rows → adding-schema-markup.
• Rendering row → auditing-technical-seo.
• Question-heading row → optimizing-for-generative-engines.
• Internal-link row → planning-topic-clusters.
• Meta rows → optimizing-on-page (per page) or seo-bootstrap (site-wide defaults).
• Depth row, last → analyzing-content-gaps for what to actually add.