Legacy modernization with private AI agents

September 24, 2026 - 5 minute read

Legacy modernization with private AI begins with a behavior the engineering team can preserve and test. A model can propose a replacement API or reorganize a module, but the migration still needs evidence that the system meets its existing obligations.

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

Choose a migration with a clear end state. Replacing a deprecated library in one service is easier to review than asking an agent to modernize an entire application. The narrower task makes dependencies, validation, and rollback more concrete.

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. The migration still depends on the execution environment, model service, and development tools that the customer permits.

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.

Factory's deployment patterns describe running Droid on customer VMs, containers, and CI runners with internal model and telemetry endpoints. Use the environment that can execute the required checks within the approved boundary.

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.

A milestone should end with evidence a maintainer can inspect. For example, adapting an internal interface should include its compatibility tests and a clear account of which consumers have changed. Avoid milestones that merely count edited files.

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.

Measure accepted migration work

Track progress against the reviewed delivery plan. Count accepted changes and completed compatibility checks rather than generated patches. Record validation failures and reviewer corrections so the team can see where the workflow still needs guidance.

Measure operator intervention separately from code review. An internal package mirror failure and an incorrect API replacement create different kinds of work. Keeping those causes distinct helps the team decide whether to improve the environment, the instructions, or the migration scope.

Factory's telemetry documentation supports customer-owned activity metrics. Combine those signals with CI and source-control records to understand the complete workflow. Obtain inference cost from a source that actually provides it rather than inferring it from tool counts.

At the end of the pilot, review whether the migration process is repeatable. Preserve the approved environment, validation commands, task instructions, and acceptance evidence. Remove temporary exceptions that are no longer needed.

Expand to another service only after the team can explain what worked and what required correction. A private AI migration becomes useful when maintainers can reproduce the process, validate compatibility, and retain control over the systems being changed.