Skip to content

Include Aurea remarks as PR of the original blog was already merged #2672

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxandersen merged 2 commits into from
Jun 4, 2026
Merged

Include Aurea remarks as PR of the original blog was already merged #2672

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc4c6b0
Include Aurea remarks: add section concerning git branch creation, be…
cmoulliard Jun 3, 2026
0084560
Add missing report image
cmoulliard Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 56 additions & 10 deletions _posts/2026-05-26-ai-skills-migration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,13 @@ Skills bridge that gap. By giving the agent a curated set of instructions, refer

== How we designed the migration Skill

The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[migrate-spring-to-quarkus] Skill uses a *modular, domain-based approach with gate checks*. Rather than one monolithic script, the migration is broken into independent modules, each responsible for a specific technical domain:
The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[migrate-spring-to-quarkus] Skill uses a:
- *Modular, domain-based approach* with *Gate checks*
- *Critical rules*: "Never delete code you cannot migrate", "don't break the build", "Document every decision", "No silent changes" aiming to safely migrate an application and to document the decisions made.

NOTE: Such rules enforce how the migration process will take place and better express the needs than a generic prompt.

Rather than one monolithic script, the migration is broken into independent modules, each responsible for a specific technical domain:

[cols="20%,80%",options="header"]
|===
Expand Down Expand Up @@ -93,9 +99,16 @@ image::01-project-to-migrate.png[alt=Application to migrate, align=left, width=6

TIP: Don't forget to configure the agent authentication mode using the API Key and/or subscription according to the provider before to launch it !

Then ask the agent to start the migration using the following tailored prompt:
Then ask the agent to start the migration using the following tailored prompt.

[source]
The prompt message already provide to AI important information like:

- The text to be used to trigger the appropriate skill: "Migrate this Spring Boot project to Quarkus"
- The migration strategy to be used. See hereafter the section covering that part
- Migration and build instructions
- The summary report to be generated

[source,shell]
----
claude "Migrate this Spring Boot project to Quarkus using the full migration strategy.
Work entirely within this directory.
Expand All @@ -107,9 +120,14 @@ claude "Migrate this Spring Boot project to Quarkus using the full migration str
Include a summary of the migration in the end of the output."
----

NOTE: The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[migrate-spring-to-quarkus] skill supports 2 migration strategies: full - Quarkus native or https://quarkus.io/guides/#q=spring[Spring Compatibility].
[IMPORTANT]
====
The https://github.com/quarkusio/skills/tree/main/skills/migrate-spring-to-quarkus[migrate-spring-to-quarkus] skill supports 2 migration strategies: full - Quarkus native or https://quarkus.io/guides/#q=spring[Spring Compatibility].

The `full` strategy implies that we want to migrate the code of Spring Boot using the Quarkus equivalents while the Spring Compatibility allows to reuse some of the Spring core features: DI, Web, Rest, Data, etc; annotations, etc.

The agent selects the correct installed skill by matching the phrase 'Migrate this Spring Boot' from the user's prompt with the skill's description.
====

.Skill invocation
image::03-skill-invocation.png[alt="skill invocation",align=left, width=80%]
Expand All @@ -121,7 +139,9 @@ The agent first scans the application using different tools executed locally and
.AI analysis overview
image::04-analysis-overview.png[alt="analysis overview",align=left, width=80%]

NOTE: The summary includes the strategy defined part of the user's prompt to be executed. This means that AI will replace all Spring annotations with JAX-RS/CDI/Panache equivalents using the instructions of the modules: code, web, etc.
NOTE: The summary includes the strategy defined part of the user's prompt to be executed.

If your application is a git managed project, then AI will execute the instructions of this https://github.com/quarkusio/skills/blob/main/skills/migrate-spring-to-quarkus/SKILL.md[section] and will propose to create a new branch named according to the convention: `migration/run-01`, `migration/run-02`, ..., created from main. The branch will contain a single commit with all changes plus a migration report. A `draft PR` against main will be created for review — it is never merged but will serve as a permanent diff and discussion record.

=== Step 4: Module selection and execution

Expand All @@ -142,14 +162,16 @@ The agent populates a list of "check boxes" corresponding to the list of the mod
.Module Build System
image::08-module-build-executed.png[alt="Module Build system",align=left, width=85%]

Here are the messages that we got by example during the execution of the module "Code" where Spring annotations have been discovered within the java source files.
Here are some example messages produced during the execution of the "Code" module when Spring annotations were detected in Java source files.

NOTE: The messages will depend on the model selected and tokens window size !
NOTE: The messages will depend on the selected model and tokens window size !

.Module Code
image::07-module-code-executed.png[alt="Module code executed",align=left, width=95%]

NOTE: The module "web" is optional if the application to be migrated don't include, thymeleaf files, jsp and/or JavaScript assets
NOTE: The "frontend" module is optional if the application to be migrated doesn't include, thymeleaf files, jsp and/or JavaScript assets

IMPORTANT: if the compilation fails after a module, the agent pauses but will try to fix the issue, and only moves to the next module when the build is green again."

=== Step 5: Verification

Expand All @@ -159,9 +181,33 @@ The checks we are doing allow to verify if the application has been migrated, th
.Verification checks
image::09-verification-checks.png[alt="Verification checks",align=left, width=95%]

=== Step 6: Launch your Quarkus application
=== Step 6: Migration report

The summary report that we request to be created is defined part of the following https://github.com/quarkusio/skills/blob/main/skills/migrate-spring-to-quarkus/SKILL.md#migration-report[skill's section] and will provide you with important information:

- Strategy used
- Agent and model used
- Score about the migration:
- Modules completed
- Checks passed
- Token usage and estimated costs (optional and depend on the agent used)

Next, the report will detail:

- Changes by Module
- Validation Results
- Unmigrated Code (TODOs)
- Removed code
- Skill Improvement Suggestions

.Migration report example
image::10-migration-report-1.png[alt="migration report",align=left, width=95%]

TIP: Don't hesitate to compare different models, to change the strategy and use such a report to validate your migration path !

=== Nest step: Launch your Quarkus application

Your application is now a Quarkus project. Start it in dev mode:
Your migrated application is now a Quarkus project. Start it in dev mode:

[source,bash]
----
Expand Down