Claude Code Opus 4.7 Migration Tool: 5-Layer Compatibility Scanner

Why a Claude Code Opus 4.7 Migration Tool Has to Be Bidirectional

The brief was simple at first. Read a Claude Code project's configuration, find the patterns that broke on Opus 4.7, propose fixes. A migration tool. One direction of travel.

The brief broke when the question landed mid-test. What happens to teams that want to keep Opus 4.6 in rotation for token-heavy work? 4.7 uses 1.0x to 1.35x as many tokens for the same input per Anthropic's release notes. Anyone shipping long-context workloads will keep both models live. A migration-only tool would propose 4.7-only changes that broke the route back to 4.6.

I shut the test down and re-shaped the project. Compatibility by default. 4.7-only as opt-in. The scanner now never proposes a change that would degrade either model.

The full build story sits in the companion blog post. This case study is the deliverable summary: what shipped, what it audits, and what the scan surfaced when I ran it on my own most-curated Claude Code project.

What the Scanner Audits

The scanner reads the five configuration layers a Claude Code session loads on every turn. Anthropic's migration guide does not audit any of them in your project.

1. CLAUDE.md (root and nested). Advisory directives the model tries to follow. The layer that grows fastest as a project ages, and the layer the literal-reading change hits hardest.
2. AGENTS.md and subagent definitions under .claude/agents/. Advisory plus deterministic shape for the invocation envelope.
3. .claude/settings.json and hook scripts. Deterministic. These fire every session or 400.
4. Skill bodies (SKILL.md) under .claude/skills/. Advisory, trigger-loaded.
5. Anthropic SDK call sites in your application code. Deterministic. Runtime parameter validation lives here.

Package manifests (package.json, pyproject.toml, requirements.txt) are scanned alongside SDK call sites for SDK version floors and import-shape changes.

The catalogue covers seventy pattern IDs across those five layers. Thirty-seven cover prose: literal-following hazards, scope-ambiguous directives, and scaffolding 4.7 no longer needs (the "think step by step" preambles, the "after every N tool calls, summarize" rules). Thirty-three are config IDs (two reserved for future patterns): deprecated thinking shapes, removed sampling parameters, beta header churn, SDK version floors, and model ID strings.

Every Critical finding cites a Tier 1 source by URL. Tier 1 means Anthropic-authored documentation. Practitioner observations cap at Warning. The credibility of every finding in the report depends on this rule, and I built the catalogue around it.

Three Criticals on My Own Most-Curated Setup

Production has been running 4.7 since launch. My CLAUDE.md was tighter than average. I had published a dedicated post on the 4.6 / 4.7 split ten days before the scan, and a deep dive on 4.7's behavior changes one day after that. I expected the scanner to come back clean.

It surfaced three Critical findings and four Warnings.

The Critical that hurt most was a deprecated thinking: {type: "enabled", budget_tokens: N} shape in one of my subagent definitions. That is the 4.6 idiom. On 4.7 it returns HTTP 400. The agent had been failing silently in some sessions and the failures had been written off as token-cost variance for weeks before the scan caught the actual cause.

A second Critical caught a sampling parameter on an SDK call site that 4.7 no longer accepts. A third caught a deprecated model ID string in a configuration file. All three findings cited the exact Anthropic page where the change was documented.

The pattern was clear. The most curated projects carry the most configuration debt because they have the most surface area. My other Claude Code projects, when I scanned them next, came back with zero or one Critical and a couple of Warnings each. Curation cost is real, and it compounds across files. The mixed-fleet operations post covers the broader pattern this scanner sits inside.

Architecture Decisions That Shaped the Apply Flow

Per-finding apply over batch. A batch path would let users clear a 40-finding report in one keystroke. Per-finding makes them sit through every fix. The deciding factor was a failure mode I had watched in code reviews: in batches, things slip through. The scanner is supposed to surface findings the user has not thought about. If the apply path is also batched, the user never thinks about most of them.

LLM-judgment fallback for contradiction detection. The regex-only version flagged contradictions everywhere. A directive that said "Ask First when in doubt" and another that said "Depth Over Economy when researching" looked like a conflict to a string match, but the precedence was scope-differentiated through bullet structure. A heuristic that flagged that pair as Critical destroyed trust in the rest of the report. The fix was a stage-two LLM-judgment pass when the regex flagged a candidate and the surrounding lines had no inline scope keywords. Default verdict on uncertainty: Warning, not Critical.

Tier-1 citation requirement on Critical findings. Practitioner blog posts and community observations cap at Warning. A Critical without an Anthropic-authored citation is one a reader can argue with. An arguable Critical destroys the credibility of every other finding in the report. I built the catalogue around this rule from the start.

Self-exclusion on the scanner's own files. The pre-ship moment that hurt was v3.2.2. The first end-to-end run produced false positives on the scanner's own pattern documentation, because the catalogue files contain the directive shapes the scanner is built to flag. Of course they do. The fix was a self-exclusion path that suppresses scans against any opus-compatibility-scanner/ path during scan setup. Obvious in retrospect, embarrassing to discover at v3.2.2.

If this kind of skill engineering is what your team needs configured around your codebase, Claude Code Infrastructure Setup is the engagement. The AI Persona Profiler case study covers another build with this shape: custom skills, hook chains, and agent orchestration shipped as a working pipeline.

By the Numbers

• 5 Claude Code configuration layers audited per scan
• 70 pattern IDs in the catalogue, split 37 prose and 33 config (2 of the config IDs reserved for future patterns)
• 3 Critical findings on my own most-curated Claude Code setup
• 4 Warning findings on the same scan
• ~38K tokens loaded for a full-scope scan, under 4 percent of a 1M context window
• 0 files written without explicit user opt-in (manifest and report default to no)
• MIT licensed, free, no signup, no telemetry
• 3.2.2 current version, pattern catalog reviewed against Anthropic docs through 2026-04-26

What I Cut, and What I'm Honest About

A few honest limits, ordered from most likely to bite to least.

Pattern catalogue currency. Anthropic's release cadence on Opus is roughly 90 to 120 days, and each release has shifted at least one parameter or default in a way the scanner needs to learn. The mitigation is shipping updates against the catalogue when something material moves. Treat the manifest's data_current_through field as an expiration marker, not a watermark. Re-run the scanner after major Anthropic releases. Do not treat a clean scan from six months ago as proof your project is still clean.

Semantic-judgment non-determinism. The LLM-judgment pass that suppresses false positives on prose patterns is non-deterministic. The same CLAUDE.md scanned twice on different days might produce slightly different verdicts on the same edge-case pattern. The bias is toward Warning when uncertain, which bounds the consequences. If you treat the scanner as a deterministic linter the way you treat ESLint, you will occasionally see disagreement between runs.

Abstraction-layer projects. If your team routes Claude calls through an abstraction layer like LiteLLM or the AI SDK, the maintainer absorbs most of the API-shape changes for you. Same effect from a different angle if you pin to dated model snapshot IDs rather than the floating claude-opus-4-7 alias. The scanner's prose audit on CLAUDE.md, skills, and AGENTS.md still applies; the SDK call-site audit surfaces fewer findings. Most valuable for engineers writing directly against the Anthropic SDK and routing to floating aliases.

What is on the roadmap and not in v3.2.2: a catalogue-update channel that lets the scanner fetch new patterns without a fresh skill download, and a CI-friendly mode that returns structured output for fail-the-build checks. The MIT license means anyone can fork and ship those features ahead of me. If you do, open a discussion on GitHub.

If a 4.7 cutover is on your team's calendar and you want a configuration audit before the rollout, book a free 15-minute intro call. No pitch, no obligation.