Strategy — Preserve Public API

When to use

• The task edits a public class, function, or interface that other modules, packages, or external consumers call.
• The task changes a library, SDK, or package whose interface is published and versioned for outside consumers.
• The task wants to remove, rename, or change the parameters of an existing public method, constant, or return type.

When NOT to use

• Do not block a breaking change the user has explicitly approved as part of a planned major-version release with a migration guide.
• Do not impose backward-compatibility ceremony on private or internal-only code that has no external consumers and is free to change.

Core guidance

• Add new parameters as optional with defaults — When a public method needs more inputs, add them as trailing optional parameters with sensible defaults rather than changing the existing parameter list.
• Search for callers before touching a public member — Before changing a public member, search the codebase and known consumers for its callers so you understand the blast radius of any change.
• Deprecate before removing anything public — Mark a public member as deprecated with a clear replacement and keep it working for at least one release cycle before removing it in a later major version.
• Keep a compatibility shim when reshaping internals — When you reshape the implementation behind a public member, keep the old signature as a thin shim that delegates to the new code.
• Preserve observable behavior, not just the signature — Keep not only the signature but also the observable behavior — return shapes, thrown exceptions, and null handling — that callers already rely on.

Never

• Never change or remove a public or exported method signature, constant, or return type that outside code depends on without a deliberate, versioned break.

Prefer

• Prefer adding new methods, optional parameters with defaults, or new overloads over changing existing ones, so current callers keep working unchanged.

Avoid

• Avoid deleting or renaming a public member outright; deprecate it first, keep it working for a transition period, and document the replacement.

Escalate to user when

• Escalate to the user when a correct fix truly requires breaking a public signature, so the break can be planned, versioned, and communicated to callers.

Quick recipe

1. Determine which members are part of the public contract, then search the codebase and known consumers to map who depends on them. (verify: You know exactly which members are public and have a list of their callers or consuming packages.)
2. Implement the change additively — new method, optional parameter, or delegating shim — and deprecate anything to be removed rather than deleting it now. (verify: Every existing caller still compiles and behaves the same, and any member slated for removal is deprecated with a documented replacement rather than deleted.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Narrowing a return type or throwing new exceptions — Narrowing a return type, returning null where a value was guaranteed, or throwing a new exception type breaks callers even with an unchanged signature. Fix: Keep the return shape and error behavior callers rely on, and introduce any new behavior through a separate method or an opt-in flag.
2. Reordering parameters silently breaks callers — Reordering existing parameters keeps the arity the same, so positional calls still compile but now pass values into the wrong slots. Fix: Leave existing parameters in place and add new ones at the end as optional, or introduce a new method rather than reordering.
3. Tightening a parameter type rejects valid callers — Making a public parameter type stricter — from a broad type to a narrow one — rejects arguments that were previously accepted. Fix: Keep the accepted input type at least as wide as before, and validate the narrower requirement inside the method instead of in the signature.

Version notes

• API-preservation discipline is version-agnostic (PHP >=7.4) — Preserving public signatures and deprecating before removing is a strategy that applies to any PHP version; it constrains how the agent evolves a contract, not which language features it uses, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-preserve-public-api.yaml.

Additional resources

• references/anti-patterns.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-legacy-safe-edits, ai-rules/strategy-minimal-diff