With GPT-5.5 now available in the API, OpenAI published a prompting guide for developers. Simon Willison’s post highlights the parts he considers most significant. The lead recommendation is direct: don’t treat GPT-5.5 as a drop-in replacement for earlier models. Willison quotes the guide opening: “To get the most out of GPT-5.5, treat it as a new model family to tune for, not a drop-in replacement for gpt-5.2 or gpt-5.4.”
According to Willison’s summary, the guide recommends starting with a fresh baseline rather than carrying over existing prompt stacks, and re-tuning dimensions including reasoning effort, verbosity, tool descriptions, and output format against representative examples.
Why a fresh baseline
The reasoning behind starting from scratch, as Willison describes it, is that prompts optimized for gpt-5.2 or gpt-5.4 may not translate cleanly to GPT-5.5. Accumulated instructions designed to correct earlier model behavior may be unnecessary or counterproductive with the new model, adding noise rather than signal.
This framing has practical consequences for teams that have invested in prompt engineering. Treating accumulated prompts as a starting point means inheriting behavioral constraints the new model may not require. Treating them as a baseline to replace means accepting migration cost upfront rather than debugging unexplained regressions later.
Handling long-running tasks
The guide includes a specific recommendation for applications where the model spends substantial time working before returning a visible response. Willison quotes this directly:
“Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences.”
The problem this addresses is latency perception in agentic applications. Without an acknowledgment step, users cannot distinguish between a model that is working and one that has stalled. Willison notes he has already observed this pattern in the Codex app, and says “it does make longer running tasks feel less like the model has crashed.”
Automated migration via Codex
For developers who want to migrate existing codebases to GPT-5.5 systematically, OpenAI has embedded guidance in a Codex skill. According to Willison’s post, running the following in Codex triggers an automated migration:
$openai-docs migrate this project to gpt-5.5The upgrade guide the Codex agent follows is publicly available on GitHub and includes instructions for light prompt rewriting. A separate guide — Using GPT-5.5 — is also available, and the main prompting guide for API usage is at developers.openai.com.
Implications for engineering teams
Willison describes the fresh-baseline recommendation as “interesting.” For teams with production deployments on earlier GPT versions, the conventional migration path is test-then-port: run existing evaluations on the new model, patch where things break, ship. OpenAI’s guidance here proposes a different approach: audit what the prompt is actually doing, strip it to the minimum, and rebuild for the new model’s behavior profile.
The published, version-pinned migration guide that a coding agent can follow suggests OpenAI expects migration to be a real engineering task, not a string substitution.