Guide Software migrations and modernization 8 min read

AngularJS to Angular Migration with AI: How to Preserve Architecture

time cockpit dissolved its hybrid AngularJS and Angular app in 233 commits with Claude Code. The agent carried the conversion, while silent failures and architectural boundaries needed people, tests and separate checks. Record three kinds of decisions before the agent starts.

233 commits in 25 days

On September 3, 2026, Karin Huber, founder and CEO of software architects gmbh, which makes the time-tracking product time cockpit, published AngularJS to Angular Migration in a Month with Claude Code. Since 2018 the product had run as a hybrid app, with AngularJS and Angular side by side, joined through Angular's @angular/upgrade package. The team used Claude Code to remove the AngularJS half and that bridge.

The numbers describe a large change done quickly:

The post is candid about why it worked. The team wrote down rules for the agents before the work began, and Huber treats those written rules as the precondition for the pace. An AGENTS.md file, a file of standing instructions that coding agents read, split the work: one model explored, planned and reviewed, and a second implemented. People decided the sequencing, the scope and the policy for change detection.

Why AngularJS migrations are still running

AngularJS, the original version of the framework, is a different framework from modern Angular, not an older version of it. Support for AngularJS officially ended in January 2022. Many enterprise applications still run on it, often as hybrids like time cockpit's, because a full rewrite of a large product was never affordable.

The hybrid route uses Angular's UpgradeModule, which bootstraps one application containing both frameworks and lets components and services cross between them. It allows a team to migrate one screen or one service at a time. It also means the codebase holds two architectures at once for as long as the migration lasts, sometimes for years.

The target has moved, too. Angular is at version 22, and zoneless change detection is the default from version 21, meaning Angular no longer relies on the zone.js library to know when to update the screen. A team leaving AngularJS today is migrating toward standalone components (components that declare their own dependencies), signals (Angular's reactive values) and zoneless rendering, not toward the Angular of 2018.

What the agent sped up, and what it did not

The time cockpit account separates the two kinds of work. The agent carried the repetitive conversion and the test runs, under rules written in advance. People made the decisions about order and scope.

The risks came from changes that compiled and looked correct:

Tests caught the export and the redirect. Reading the diffs did not. Separately, the post reports that ESLint, the project's linter, had stopped running without reporting any error well before the migration began. It lists open work as well: 16 legacy NgModules (Angular's original module system, which standalone components replace), a lint backlog and zone-based change detection.

The lesson is not that the agent was careless. The migration produced a great deal of correct code fast, and the defects that got through were ones no single diff revealed.

Five architectural risks in an AngularJS migration

Behavior is only half of what a migration must preserve. Five boundaries are most at risk when an agent does the moving in a hybrid codebase:

  1. Dependency direction. Migrated Angular code should not import from AngularJS modules. An agent that finds a working helper in the legacy tree will reuse it, and the new code inherits a dependency the migration was meant to remove.
  2. Shared services. During a hybrid phase, some services are upgraded for use in both frameworks. Decide which side owns each one. Two copies of a service with diverging logic produce bugs that look like data errors.
  3. Routing. Two routers can coexist in a hybrid app. Redirects, guards and deep links are easy to lose when routes move, as time cockpit's start page showed.
  4. State ownership. State that lived in AngularJS scopes or services must have one owner in the target. An agent asked to make a screen work will often read state from wherever it currently sits.
  5. Temporary adapters. Upgraded and downgraded components (AngularJS pieces wrapped to run inside Angular, and the reverse) are scaffolding. Without a recorded exit condition, they outlive the migration, and later changes start depending on them.

Record three kinds of decisions

An agent can only respect decisions that are written somewhere it reads. A migration needs three kinds:

KindWhat it statesExample
LegacyWhat must keep working until it is retired on purposeCustomer-defined forms keep their current validation rules
TargetWhere the code is goingNew components are standalone; components never call the HTTP client directly
TransitionalWhich temporary bridges are allowed, and when each one endsThe downgraded report widget stays until the reports module is migrated, then is removed

Transitional decisions are the ones that go missing. They are true for a few months and then false, so nobody writes them into permanent documentation. They are also the ones an agent breaks most easily, by reintroducing a bridge the team already removed.

Put the decisions where both the agents and the people read them: in an AGENTS.md file, as time cockpit did, and in a decision record the team keeps in the repository.

Verify behavior and architecture separately

Time cockpit's tests caught two silent failures that diff review missed. That is behavioral verification doing its job, and a migration needs a lot of it: the test count more than doubled during the work.

Tests answer whether the application still does what it did. They do not answer whether the new code respects the target architecture. A component that injects the HTTP client directly passes every test that checks what the screen shows. A migrated feature that imports a legacy helper runs perfectly. Those are architectural questions, and they need checks of their own, as we argue in Behavioral Equivalence Is Not Architectural Compliance.

Many of the five boundaries above can be checked mechanically. A forbidden import is a line of text in a file. A rule that says migrated directories may not import from the legacy tree is a lint or CI check, not a matter of reviewer attention.

A migration governance checklist

  1. Inventory the hybrid. List the upgraded services, downgraded components and shared state, and who owns each.
  2. Write the three kinds of decisions down before the agent's first commit, with an exit condition for every transitional one.
  3. Split the work into reviewable streams. Time cockpit used 95. Keep each stream small enough that one person can understand its intent.
  4. Separate the version bump from the modernization. Pin old behavior first, as time cockpit did with change detection, and remove the pins in batches.
  5. Add tests ahead of the change, especially for exports, redirects and anything else users notice only when it is gone.
  6. Turn checkable boundaries into CI checks: forbidden imports from the legacy tree, direct HTTP client use in components, reintroduced adapters.
  7. Check that your tools still run. A linter that fails silently looks the same as a clean codebase, as time cockpit found.
  8. Close transitional decisions on purpose. When a bridge is removed, retire its decision and add a check that keeps it removed.

Where Mneme fits

Mneme, an open-source decision and control layer for agentic software development, covers the literal-text checks in the CI step of the checklist, and keeps a record of the decisions you write down. It does not migrate code, run tests or compare behavior.

Mneme enforces decisions that carry an active typed rule: a rule a machine can check, such as an exact piece of text that must not appear in code, optionally limited to certain paths. A rule that forbids the legacy module's import path as literal text in the migrated directories returns a FAIL when an agent's change adds that import, and the violation names the decision it broke. The same works for a removed adapter's name. Direct HTTP client use in components is checkable only if your component files can be told apart by path. A decision without an active typed rule is not enforced, and a boundary a literal rule cannot express needs its own test.

The checks run in continuous integration (CI) and in coding agents including Claude Code, where each agent's native write tools are checked before the write lands. Decisions live in the Decision Index, Mneme's persisted, versioned record of a repository's decisions, with each decision's lifecycle status. Write a transitional decision's exit condition into its text, since there is no separate field for it. When you retire that decision, its rule stops being checked, so keep the removed bridge out with a second decision that stays active.

Frequently asked questions

Can AI coding agents migrate an AngularJS application to Angular?+
They can carry much of the work. time cockpit dissolved a hybrid AngularJS and Angular application in 233 commits across 25 days of work, weekends included, with 218 commits co-authored by Claude Code. People set the sequencing, scope and change-detection policy, and the team wrote rules for the agents before starting.
What breaks most often in an AI-assisted AngularJS migration?+
Changes that compile and look correct. In time cockpit's migration, an Excel export was silently disconnected and a start-page redirect disappeared; tests caught both, and diff review did not. Architecturally, the boundaries most at risk are dependency direction, shared services, routing, state ownership and temporary adapters that outlive the migration.
How do you keep architectural decisions intact during an Angular migration?+
Write down three kinds of decisions before the agent starts: legacy behavior that must keep working, the target architecture, and transitional bridges with an exit condition. Verify behavior with tests and architecture with separate checks, such as a CI rule that forbids migrated code from importing the legacy tree.