Change a Multi-Package Codebase Without Breaking What Already Works
Use when an AI edits a repository with many packages. It finds which package owns the change and its rules, keeps old behavior and public names working, adds tests and docs, asks before adding dependencies, and reports what was checked and what risk remains.
To use this AI rule
## Before Editing, Find Which Package Owns the Change and Its Rules
Before editing, identify the repository root, the package or subsystem that owns the behavior, and the nearest applicable contributor instructions.
- Route work to the lowest correct scope.
- Read the local architecture, conventions, build, and testing references needed for that scope.
- Use targeted search for a single symbol and an available dependency graph for cross-file callers, imports, rename impact, or broad change radius.
- Confirm runtime versions, package-manager versions, workspace definitions, and build prerequisites from checked-in configuration.
- Treat linked or generated instruction files as views of their declared source; edit the source file only.
If instructions conflict or ownership is unclear, stop before writing and surface the exact conflict. Do not modify unrelated packages while investigating.
## Keep Old Behavior and Public Names Working and Follow the Architecture
Avoid breaking existing users. Do not change a default value or remove a public name unless the approved change explicitly requires it. Keep legacy names working, and pair deprecation with a documented transition and tests for the old behavior.
Respect the architecture already established by the repository:
- keep behavior inside its owning layer or extension boundary;
- maintain parity across official adapters when the core contract changes;
- preserve cascading configuration and public customization contracts;
- sanitize user-controlled content and avoid global namespace pollution;
- support declared internationalization and accessibility requirements; and
- prefer existing utilities and minimal dependencies over parallel mechanisms.
If a breaking change is unavoidable, state it prominently, explain the affected contract, and provide a migration path.
## Make the Smallest Change, with Tests and Docs
Make the smallest coherent change that satisfies the requirement. Follow the package's established code, comment, and documentation style.
For changed behavior:
1. Add or update focused unit coverage.
2. Add the appropriate integration, browser, or end-to-end coverage when the behavior crosses a boundary.
3. Run required prerequisite builds before dependent package tests.
4. Run the narrow lint, type, style, and test commands for the affected scope.
5. Update public guides, API references, examples, migration notes, or changelog entries when users can observe the change.
6. Update scoped contributor guidance only when the change creates a durable convention, location, constraint, or recurring pitfall.
Do not claim completion when required coverage or user-facing documentation is missing. Record any test that could not run and the concrete reason.
## Get Approval Before Adding Dependencies and Check Before Release
Obtain maintainer approval before adding a third-party dependency. Check direct and transitive licenses, maintenance status, security implications, bundle or runtime cost, and whether the repository already provides the capability.
Follow the repository's branch, pull-request, review, and changelog conventions. Keep the change history reviewable, avoid rewriting shared history, and separate unrelated work. For work spanning multiple days, preserve a visible checkpoint using the repository's approved collaboration method.
Before release, confirm that compatibility tests cover old and new behavior, required documentation is present, generated artifacts are current, and the intended package variants or adapters have been exercised.
## Report the Tests Run and the Risk That Remains
Return a concise verification report that lists:
- the behavior changed and its scope;
- files or components affected;
- tests, builds, lint, and type checks run with their outcomes;
- compatibility and security considerations;
- documentation or changelog updates; and
- anything not run, remaining risk, and the next required action.
Separate verified results from assumptions. Highlight any breaking change or incomplete required check before secondary details.