Claude Code 中的 Opus 4.5 迁移指南：从 Sonnet 4.x / Opus 4.1 平滑升级模型字符串与提示词

Claude Code 中的 Opus 4.5 迁移指南从 Sonnet 4.x / Opus 4.1 平滑升级模型字符串与提示词【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code导读本文以 Claude Code 仓库中的claude-opus-4-5-migration官方 Skill技能包为核心系统讲解如何将代码库、提示词与 API 调用从 Claude Sonnet 4.0、Sonnet 4.5 或 Opus 4.1 一次性迁移到 Opus 4.5覆盖模型字符串替换、不受支持的 Beta Header 清理、effort参数配置以及针对 Opus 4.5 已知行为差异工具过度触发、过度工程化、代码探索不足、前端设计平庸、对 think 措辞敏感等的提示词调整方案。读完本文你将掌握一套可直接落地的迁移工作流与可复制的提示词片段。迁移 Skill 是什么claude-opus-4-5-migration是 Claude Code 官方插件目录 plugins/claude-opus-4-5-migration 中提供的一个自动化迁移技能。它在 SKILL.md 的 YAML frontmatter 中声明了触发条件当用户要求更新代码库、提示词或 API 调用以使用 Opus 4.5时自动激活负责处理模型字符串更新以及针对已知 Opus 4.5 行为差异的提示词调整。需要特别留意其边界该技能明确不迁移 Haiku 4.5例如claude-haiku-4-5-20251001因为它属于轻量级模型不在本次升级路径之内。此外Opus 4.5 迁移技能的文件结构也遵循了 Claude Code 插件中 Skills 的标准组织方式SKILL.md主文件 references/引用资料这种渐进式披露设计参考 plugin-structure 与 skill-development 的最佳实践保证了主文件精炼、细节按需加载。一次性迁移工作流SKILL.md 定义了一套 6 步的 One-shot 迁移流程从 Sonnet 4.0、Sonnet 4.5 或 Opus 4.1 升级到 Opus 4.5搜索代码库中的模型字符串与 API 调用更新模型字符串为 Opus 4.5平台专属字符串见下文对照表移除不受支持的 Beta Header添加effort参数并设置为high详见 references/effort.md汇总所有改动并告知用户提示用户If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts.如果遇到 Opus 4.5 的问题告诉我我可以帮你调整提示词。这套流程的核心思想是先机械替换、后按需优化默认情况下只做模型字符串替换即可完成迁移提示词调整仅在用户明确请求或报告具体问题时才应用。移除不受支持的 Beta Header迁移时如果请求中带有context-1m-2025-08-07这个 1M 上下文 Beta Header必须将其移除——Opus 4.5 目前尚不支持该 Beta。移除后应保留一行注释方便后续追溯# Note: 1M context beta (context-1m-2025-08-07) not yet supported with Opus 4.5从源码结构看这一步针对的是 Anthropic API 的anthropic-beta请求头字段Beta 功能通过该请求头按版本号启用模型与 Beta 能力之间存在兼容矩阵迁移模型时需同步核对 Beta 名单。平台模型字符串对照表迁移的第一步是确认代码库运行在哪个平台上再按平台替换模型字符串。SKILL.md 给出了 Opus 4.5 在四大平台上的目标字符串平台Opus 4.5 模型字符串Anthropic API (1P)claude-opus-4-5-20251101AWS Bedrockanthropic.claude-opus-4-5-20251101-v1:0Google Vertex AIclaude-opus-4-520251101Azure AI Foundryclaude-opus-4-5-20251101注意各平台命名规则差异AWS Bedrock 使用anthropic.前缀并带-v1:0版本后缀Vertex AI 使用加日期版本号而 Anthropic API 与 Azure AI Foundry 使用裸模型 ID 加日期后缀。源模型字符串需要替换的对象源模型Anthropic API (1P)AWS BedrockGoogle Vertex AISonnet 4.0claude-sonnet-4-20250514anthropic.claude-sonnet-4-20250514-v1:0claude-sonnet-420250514Sonnet 4.5claude-sonnet-4-5-20250929anthropic.claude-sonnet-4-5-20250929-v1:0claude-sonnet-4-520250929Opus 4.1claude-opus-4-1-20250422anthropic.claude-opus-4-1-20250422-v1:0claude-opus-4-120250422在代码库中搜索这些字符串时建议同时覆盖三种形态环境变量如ANTHROPIC_MODEL、配置文件YAML/JSON/Terraform以及代码中的硬编码字符串。仓库的 AWS/GCP 网关示例examples/gateway/aws/gateway.yaml.example、examples/gateway/gcp/gateway.yaml.example与 Terraform 配置examples/gateway/aws/terraform/main.tf展示了模型字符串在多基础设施层中的分布形态可作为排查参考。不要迁移任何 Haiku 模型例如claude-haiku-4-5-20251001。effort 参数迁移的默认配置在迁移的第 4 步中需要为 API 调用添加effort参数并设为high这是 Opus 4.5 最佳性能的默认配置。详见 references/effort.md。effort 是什么effortBeta控制 Claude 花费 token 的积极程度影响所有 token 类型思考thinking、文本回复和函数调用。它分为三档effort适用场景high最佳性能、深度推理默认medium成本/延迟与性能的平衡low简单、高吞吐查询显著节省 token三种 SDK/API 实现方式使用effort参数需要携带 Beta 标志effort-2025-11-24并将配置放在output_config对象中。Python SDKresponse client.messages.create( modelclaude-opus-4-5-20251101, max_tokens1024, betas[effort-2025-11-24], output_config{ effort: high # or medium or low }, messages[...] )TypeScript SDKconst response await client.messages.create({ model: claude-opus-4-5-20251101, max_tokens: 1024, betas: [effort-2025-11-24], output_config: { effort: high // or medium or low }, messages: [...] });Raw API直接 HTTP 请求{ model: claude-opus-4-5-20251101, max_tokens: 1024, anthropic-beta: effort-2025-11-24, output_config: { effort: high }, messages: [...] }effort 与思考预算Thinking Budget的关系effort与思考预算相互独立可以自由组合High effort 无 thinking 消耗更多 token但没有 thinking tokenHigh effort 32k thinking 消耗更多 token但思考被限制在 32k 以内。推荐配置顺序先确定 effort 档位再设定思考预算最佳性能high effort 高思考预算成本/延迟优化medium effort简单高吞吐查询low effort。提示词调整针对 Opus 4.5 的已知行为差异SKILL.md 强调了一个重要原则默认情况下迁移只更新模型字符串。以下提示词调整仅在用户明确请求或报告了具体问题时才应用。当需要添加提示词片段时必须遵循整合式插入而非简单追加使用 XML 标签如code_guidelines、tool_usage组织新增内容匹配现有提示词的风格与结构将片段放在逻辑合理的位置如编码规范放在其他编码指令附近如果提示词已使用 XML 标签在合适的现有标签内添加新内容或创建风格一致的新标签不得删除现有功能性内容迁移结束后汇总列出所有模型字符串更新与提示词修改。所有片段的完整原文见 references/prompt-snippets.md。1. 工具过度触发Tool Overtriggering问题Opus 4.5 对系统提示词更敏感。在旧模型上为防止工具调用不足而使用的激进措辞现在可能导致工具调用过频。应用条件用户报告工具被调用得过于频繁或不必要。查找并软化以下激进表达CRITICAL:→ 删除或软化You MUST...→You should...ALWAYS do X→Do XNEVER skip...→Dont skip...REQUIRED→ 删除或软化。只对触发工具的指令应用此调整其他位置的重点强调保持不变。参考替换示例之前之后CRITICAL: You MUST use this tool when...Use this tool when...ALWAYS call the search function before...Call the search function before...You are REQUIRED to...You should...NEVER skip this stepDont skip this step2. 过度工程化预防Over-Engineering Prevention问题Opus 4.5 倾向于创建多余文件、添加不必要的抽象层、构建未被要求的功能。应用条件用户报告出现不想要的文件、过度抽象或未请求的功能。从 prompt-snippets.md 添加以下系统提示词片段- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused. - Dont add features, refactor code, or make improvements beyond what was asked. A bug fix doesnt need surrounding code cleaned up. A simple feature doesnt need extra configurability. - Dont add error handling, fallbacks, or validation for scenarios that cant happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Dont use backwards-compatibility shims when you can just change the code. - Dont create helpers, utilities, or abstractions for one-time operations. Dont design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.3. 代码探索Code Exploration问题Opus 4.5 在代码探索上可能过于保守不读取文件就提出解决方案或对未读取的文件做假设。应用条件用户报告模型未检查相关代码就提出修复方案。添加以下系统提示词片段ALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.4. 前端设计质量Frontend Design应用条件用户要求提升前端设计质量或报告输出千篇一律AI slop 审美。添加以下前端美学片段建议用 XML 标签包裹后插入系统提示词frontend_aesthetics You tend to converge toward generic, on distribution outputs. In frontend design, this creates what users call the AI slop aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight. Focus on: - Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontends aesthetics. - Color Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration. - Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. - Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic. Avoid generic AI-generated aesthetics: - Overused font families (Inter, Roboto, Arial, system fonts) - Clichéd color schemes (particularly purple gradients on white backgrounds) - Predictable layouts and component patterns - Cookie-cutter design that lacks context-specific character Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box! /frontend_aesthetics该片段在仓库中与 frontend-design 插件所倡导的做出独特、有区分度的前端理念一致两者可配合使用。5. 思考敏感性Thinking Sensitivity问题当扩展思考extended thinking未启用时默认情况Opus 4.5 对 think 及其变体词汇特别敏感。扩展思考仅在 API 请求包含thinking参数时才会启用thinking: { type: enabled, budget_tokens: 10000 }应用条件用户报告在未启用扩展思考请求中没有thinking参数时出现与 thinking 相关的问题。解决方案将 think 替换为替代措辞之前之后think aboutconsiderthink throughevaluateI thinkI believethink carefullyconsider carefullythinkingreasoning/considering片段使用指南来自 prompt-snippets.md 的六条整合准则整合式插入——不要只做追加要把片段编织进现有提示词结构使用 XML 标签——用描述性标签如coding_guidelines、tool_behavior包裹新增内容与现有结构匹配或互补匹配提示词风格——提示词简洁则精简片段冗长则保留完整细节逻辑放置——编码片段放在其他编码指令附近工具指导放在工具定义附近保留现有内容——插入片段时不得删除功能性内容汇总改动——迁移结束后列出所有模型字符串更新和提示词修改。使用该迁移技能在 Claude Code 中你只需用自然语言发出请求即可触发该技能例如Migrate my codebase to Opus 4.5技能被激活后会按照前面介绍的 6 步工作流自动执行搜索模型字符串 → 替换为 Opus 4.5 → 清理context-1m-2025-08-07Beta Header → 添加effort: high→ 汇总改动 → 告知后续可继续协助调整提示词。如果迁移后遇到问题可以继续通过该技能进行提示词微调。迁移检查清单与注意事项必须执行全库搜索源模型字符串三个平台形态都要覆盖按平台替换为对应的 Opus 4.5 字符串AWS Bedrock 带v1:0、Vertex 用版本号移除context-1m-2025-08-07Beta 并留注释添加betas: [effort-2025-11-24]与output_config: {effort: high}确认不迁移任何 Haiku 模型。按需执行仅当用户报告问题工具过度触发 → 软化激进措辞过度工程化 → 添加防过度工程片段代码探索不足 → 添加强制读码片段前端设计平庸 → 添加前端美学片段think 措辞敏感 → 替换为 consider/evaluate/believe 等。迁移后的提示词调整路径迁移完成后如果 Opus 4.5 出现任何问题可以再次触发该技能进行迭代调整。SKILL.md 给出的标准话术是If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts. 结合 references/effort.md 中的建议调整顺序通常是先确定 effort 档位high/medium/low再按需设置思考预算最后根据实际表现选择性地应用上述五类提示词片段形成迁移 → 观察 → 按需微调的闭环。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考