Legacy modernization with private AI agents

Consider a legacy service that must replace a deprecated dependency without changing its public API or error responses. Private AI modernization has to preserve those behaviors while keeping source, inference, and validation inside the approved environment. An agent-generated replacement is useful only if maintainers can demonstrate compatibility.

Factory's sovereign software development whitepaper identifies Migration & Modernization as a starting workstream. It recommends dependency analysis, a reviewable delivery plan, phased implementation, and measurable validation gates. Those are useful constraints for a first migration inside a private environment.

Legacy modernization with private AI needs a bounded target

For the dependency replacement, define which calls must move to the new library and which public responses must remain unchanged. Keep unrelated refactoring outside the patch. The target is a service that runs without the deprecated dependency and still satisfies its callers.

Record what must stay the same. That may include an API response, a file format, transaction behavior, error handling, or the sequence of messages sent to another system. Separate those invariants from intentional changes that require approval.

Use representative examples already permitted in the development environment. If production data cannot enter the workspace or model context, prepare synthetic fixtures that exercise the relevant behavior. Avoid making the migration depend on an exception to the data boundary.

Identify the maintainers who can resolve ambiguity. Legacy behavior may be undocumented, and a failing test may reflect either an important contract or a stale assumption. Decide who makes that judgment before an automated change reaches review.

Write the acceptance criteria as observable results. A successful build is useful but may not prove compatibility. Require the task-specific checks that establish the behavior being preserved, and record any area where the team lacks enough evidence to proceed.

Prepare the private build environment

Factory Private places the control plane in customer-owned infrastructure. For this migration, the replacement library, its transitive dependencies, and the compatibility tests must also be available through approved internal sources.

Reproduce the existing build before asking Droid to change it. Inventory runtime versions, compilers, package sources, generated-code tools, test fixtures, and external services. A migration cannot distinguish an incorrect patch from a broken baseline if the original system never passed validation.

For an isolated deployment, import the required tools and dependencies through the organization's artifact process. Include the target versions, not only the versions used by the existing application. Otherwise, the first attempted upgrade may reach for an unavailable public registry.

Keep the baseline reproducible. Record the environment definition and a known-good revision. If a later test fails, reviewers should be able to determine whether the failure came from the migration, a model-generated edit, or an unrelated change to the build infrastructure.

Legacy modernization with private AI benefits from milestones

Factory Missions provide upfront planning, features, milestones, and orchestrated execution for bounded multi-part work. The documentation specifically includes brownfield migrations that preserve existing behavior.

Use a Mission when the migration genuinely benefits from that structure. A straightforward local replacement can remain a normal task. A migration spanning interfaces, tests, and several implementation areas needs an explicit plan and checkpoints.

Have the initial plan identify dependencies and the order in which changes can be reviewed. Keep architecture decisions separate from mechanical edits. Review the proposed compatibility strategy before generating a broad diff.

For the example service, the first milestone could capture existing API responses and errors in contract tests. The next could replace the library behind an adapter. A final milestone could remove the old dependency after those tests and affected consumer checks pass. A changed exception type should stop the migration until the adapter restores the public error contract or maintainers approve the difference.

Preserve a stopping point between meaningful changes. If validation exposes an unsupported assumption, pause and revise the plan before expanding the patch. The value of orchestration comes from keeping work aligned with reviewed intent, not from running through the original plan regardless of new evidence.

Give the agent enough context without broadening access

Migration work can require source code, architecture notes, and examples from neighboring components. Provide the context necessary to understand the change while keeping unrelated credentials and sensitive datasets outside the workspace.

Factory's data-flow documentation explains that Droid reads files locally and sends selected context to the configured model endpoint. Confirm that the inference path is approved for the code and documentation used in the migration.

Use repository instructions to explain build commands, compatibility requirements, and areas the task must not modify. Keep those instructions aligned with actual tests. A statement that behavior must remain unchanged is difficult to enforce when no one can demonstrate the existing behavior.

Apply Factory's agent controls to the execution environment. Bound filesystem access, restrict network destinations, and preserve approval requirements for consequential actions. A migration task does not need authority to apply production database changes merely because it can draft the migration code.

For airgapped work, confirm the local workflow against the airgap feature contract. Missions and local tools remain available, but cloud-dependent collaboration and public lookup features do not. Supply approved references and internal dependencies before execution.

Validate compatibility before judging progress

Inspect the original and changed behavior with the same inputs wherever possible. For a data transformation, compare the resulting records. For an API change, exercise representative requests and error conditions. For a dependency upgrade, include the paths most exposed to changed semantics.

Add a regression test when the migration reveals behavior the existing suite did not cover. Keep the test focused on the contract that matters rather than the incidental structure of the previous implementation.

Review generated changes in manageable units. A large diff can make an apparently routine replacement hide an unrelated behavior change. Keep formatting-only work separate where the repository's conventions allow it, and explain intentional changes in the review description.

Validation should include the environment in which the application will run. Passing on a developer machine may miss a runtime, packaging, or permissions difference in the target environment. Use an approved staging or test setup rather than production access.

Preserve rollback assumptions. A code revert may be sufficient for one change but inadequate after a data-format transition. Have the system owner review the recovery plan before the migration reaches a deployment decision.

For the dependency replacement, the review should show that the deprecated package is absent from the resolved dependency graph, the public API and error checks still pass, and the target runtime can build and start the service. Keep any deliberately changed behavior visible in the release notes. Those results establish whether this migration is ready for a deployment decision.

Further reading

• Factory Private architecture
• Private AI model gateways
• Mission planning and validation