Migrating From GPT-4 to Claude: A Practical Porting Guide

Moving an application from OpenAI's API to Claude involves two kinds of work. Changing the API calls is quick. Checking that prompts still produce the behavior you need takes longer, and it's the part teams tend to underestimate.

Part 1: API differences

Most changes are mechanical:

• System prompt: passed as a top-level system parameter, not as a message with the role system.
• max_tokens: required on every request.
• Tools: the schema goes in input_schema instead of parameters. Tool calls come back as tool_use content blocks, and you return results as tool_result blocks in a user message rather than as messages with the role tool.
• Responses: content is a list of blocks. Check each block's type before reading text from it.
• Stop reasons: named differently, for example end_turn, max_tokens, tool_use and refusal.
• JSON output: use structured outputs or strict tool definitions instead of JSON mode.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4000,
    system="You are a contracts assistant.",
    messages=[{"role": "user", "content": question}],
)
answer = "".join(b.text for b in response.content if b.type == "text")

Use the official Anthropic SDK rather than a compatibility layer, so features like prompt caching and thinking work fully.

Part 2: Prompts

• Claude follows instructions closely. Prompts full of repeated warnings, written to control a different model, can make Claude too rigid. Remove the repetition.
• XML tags work well for separating instructions from documents.
• Explain why each rule exists. Claude applies rules more sensibly when it knows their purpose.
• Few-shot examples written for another model may need to be shortened or replaced.

Part 3: Evaluations

Compare the old and new versions before switching:

1. Export a few hundred real requests along with outputs you know are correct.
2. Run them through both setups.
3. Compare task success, format compliance, refusals and cost.
4. Read the differences yourself. Some will be improvements that your metrics don't capture.

Part 4: Rollout

Release behind a feature flag and send a small share of traffic to Claude first. Watch error rates and user feedback before moving everything over, and keep the old path available until the new one has handled a busy period.

Other differences to plan for

• The tokenizers differ, so token counts, costs and context estimates will change.
• Error types and retry behavior differ. Use the SDK's typed exceptions.

Budget a day for the code changes and most of the week for prompts and evaluations.