I maintain a small Python library used by several internal teams. I want Claude to help simplify its internals, but “keep the public API unchanged” feels too vague as a refactoring instruction.

A function can keep the same name and parameters while changing something callers rely on: the exception it raises, whether it accepts an iterator, or whether results arrive in a stable order. Our tests cover common usage, not every behavior that has become an unofficial contract.

For people using Claude for public API compatibility reviews, what context has actually helped?

• Examples from real downstream callers?
• A written list of guaranteed behavior and known quirks?
• Tests that must remain unchanged during the refactor?
• A separate review of observable behavior before any edits?

I’m particularly unsure about backward compatibility testing for undocumented behavior. Should I ask Claude to flag every possible change for review, or first define which behaviors we explicitly do not promise to preserve?