Use AI across monorepo packages: contracts before cross-package edits

A worked example: where the task becomes difficult

A fictional monorepo contains a web client, an API and a shared validation package. A request adds an optional delivery note to orders. Editing only the browser form would leave the server dropping the field; editing a shared required type could break older clients. Map the data path and choose a compatible optional field before changing the three packages.

Decisions to make before implementation

Document the workspace manager, package dependency directions and code-generation steps. Decide whether a shared contract is source-owned or generated from a schema. Keep circular dependencies out of a convenient “common” package. Consider deployed-version compatibility: frontend and backend releases may not occur simultaneously. A cross-package feature needs behavior for clients that omit the new field.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Locate workspace manifests and the affected package entry points.
• Trace the current order payload through client, validation and persistence.
• Implement a compatible contract extension at its authoritative source.
• Verify relevant package checks and an old-client payload before release.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Add an optional delivery note through the existing monorepo order flow. Identify the owning schema and generated files first. Preserve the current package manager and dependency direction. Validate the note on the server and verify an older payload without it. List affected packages, commands actually run and any unverified runtime dependencies.

Failure modes that an attractive preview can hide

The agent may run a command from the wrong root, regenerate files inconsistently or install a second package manager. Preserve the repository’s established workflow. A successful build in one package does not prove callers are compatible. Inspect shared exports and generated artifacts for expected changes, and report packages whose runtime prerequisites prevented verification.

Technical references: GitHub: getting useful results from coding tasks

Acceptance checks and the evidence to retain

Provide the package map, authoritative contract change and compatibility evidence. Keep generated-file changes reproducible and avoid claiming that unstarted services were tested.

Specific answers

Common questions