Tags
Share
Enterprise AEM migrations are multi-month ordeals. We built a self-improving agent on Adobe's migration skills — it deployed, analyzed Cloud Manager output, rewrote its own instructions, and redeployed until a complex AEM 6.5 codebase landed clean on AEMaaCS in weeks. Here's the architecture, the failures, and the structural decisions worth reusing.
The Migration That Used to Take Months
Enterprise AEM 6.5 to AEMaaCS migrations have a reputation. They consume months, absorb budgets, and surface technical debt nobody bothered to document. We recently completed one for a large client — a project with non-standard module structure, third-party integrations, and legacy Java 8 dependencies. The code migration took weeks. The difference was an agentic approach built on self-improving AI skills.
Everything we outlined in our practical migration guide and the companion piece on 10 mistakes to avoid still holds. The checklists, the BPA analysis, the architectural preparation — all valid. But now an agent provides structured guidance for both executing that checklist and making informed migration decisions along the way.
Adobe's Foundation — and Where Projects Diverge
In early 2026 Adobe released an AI-assisted code migration solution. With the agent-level AI (Claude 4+, OpenAI 5+) it is posed to be a major game-changer in how migration to AEMaaCS is done. Adobe's skillset has a layered architecture. The Migration Skill handles orchestration — processing BPA findings in batches, one migration pattern per session. It delegates pattern-specific transformations to a library of Best Practices modules covering schedulers, replication, event handling, SCR-to-OSGi-DS conversions, and HTL linting.
Solid foundation — but generalized. Our client's project had custom module hierarchies, bespoke service integrations, and a Java 8 codebase that needed to land on Java 21. Adobe's skill doesn't account for any of that.
Customizing the Skillset
Skills are an architecture built for extension — and the agent can refine its own instructions. We started by asking GitHub Copilot to analyze the client's codebase against Adobe's base migration skills and produce a project-specific skillset. Account for the non-standard module structure. Map the third-party dependencies. Plan the Java 8-to-21 upgrade path.
The tailored skill migrated the codebase and completed a test deployment to AEMaaCS. It worked. Partially.
The Self-Improving Loop
Cloud Manager returned a substantial vulnerability report. We fed those findings back into the skillset — not as one-off patches, but as generalized heuristics the agent could apply across projects. Deploy, analyze, refine, redeploy.
Each cycle sharpened the skill's accuracy. We compressed context to keep the agent focused, eliminated ambiguities and duplicate instructions, tightened the overall structure. Multiple iterations. The skillset learned from real deployment output and improved its own instructions with each pass — patterns extracted from actual Cloud Manager findings, not hypothetical best practices.
Decompose, Then Delegate
One practical lesson emerged early: don't let the agent rewrite the entire codebase in a single pass. Instead, we had it generate a migration task list. Each task lives in its own Markdown file, grouped by type and priority — blocking fixes first, dependent tasks next, cosmetic changes last.
Each task is sized for roughly 60–90 minutes of human developer effort, which means an agent handles it in minutes. Because the tasks are granular and stored in an agent-friendly format, you choose per task: assign it to a developer or hand it to the agent for autonomous execution. The human keeps the steering wheel.
Where the Agent Couldn't Quite Finish
The modified skillset didn't solve everything. Several project dependencies had known vulnerabilities — Guava and Log4j among them. Copilot attempted replacements and couldn't get them right. Library substitution where API surfaces shift and transitive dependencies cascade still requires an experienced engineer making judgment calls.
And accelerating code migration shifts the bottleneck. Content migration from legacy AEM instances, cloud environment stabilization, regression testing on new infrastructure — these remain significant work.
Two preparation steps measurably improve your odds. First, audit your AEM instances before migration and strip out dead weight — pages built on deprecated components, orphaned assets and their accumulated renditions, stale workflows nobody triggers. Every piece of dead content still travels through the migration pipeline; pruning it costs less than migrating and deleting later. Second, get your test coverage to at least 50–60% before the first migration task runs. Tests written against the legacy codebase become your regression safety net on AEMaaCS. Without them, every deployment cycle is a manual verification pass.
The code migrates in weeks. The full project demands realistic planning beyond the codebase.
What We Took Away
Large skills grow unwieldy. As our skillset evolved, its logic became harder to audit for contradictions and blind spots. Two structural decisions helped:
- Decompose monolithic skills into focused sub-skills with sub-agent delegation. Smaller skills are simpler to edit, test, and reason about individually.
- Generate task lists, not bulk transformations. When the agent decomposes work into discrete tasks, a human reviews each one before execution starts.
One broader pattern stood out: invest more time designing prompts than issuing them. A well-structured instruction yields disproportionate returns. Think of the agent as a thorough but literal executor — fast, capable, and entirely dependent on the quality of what you give it. Responsibility stays with you.
What We Shipped
We migrated a complex AEM 6.5 project to AEMaaCS — Java 8 to 21 included — using an agent-driven methodology built on Adobe's migration skills and refined through multiple deployment cycles. The resulting skillset is battle-tested, reusable, and self-improving: it processes BPA reports and Cloud Manager output, decomposes migration work into human-reviewable tasks, and feeds lessons from each deployment back into its own instructions. With this tooling, even a large-scale AEMaaCS migration becomes a structured, supervised engagement — measured in weeks, shaped by your project's specifics, and grounded in evidence from ours.
