Chapter 2: Building a legacy modernization framework powered by Vibe Engineering
The chapter introduces LLM-assisted legacy migration as a way to recover knowledge from unfamiliar code and make understandable, incremental changes.
After this chapter you will be able to
- LLM-assisted incremental migration. Describe how the introduction proposes using LLMs to analyze code, extract implicit knowledge, and gain enough insight to migrate in small steps while checking the direction.
- Change size versus comprehension. Explain the trade-off between the size of an LLM-proposed code increment and a human's ability to understand and reason about the change.
- Full-stack migration scope. Describe the kitchensink application as an end-to-end JBoss-backed system whose database, REST controller, business logic, and UI must be migrated to a modern Java stack. Explain why the example chooses Spring Boot.
- MongoDB migration rationale. Explain why the example replaces its SQL-accessed relational database with MongoDB and how that choice fits the Spring-based replacement.
- Chat and Agent modes. Distinguish Chat mode from Agent mode and explain why the chapter uses Agent mode for multi-step migrations.
- AI-first application overview. Explain why the pre-analysis starts with an LLM-generated overview rather than reading README files first, and when a README becomes useful.
- Product purpose before technology. Explain why the analysis starts with the product’s use case and business value rather than its code, and describe the member-management example at that level.
- Architecture and migration baseline. Describe what the high-level architecture prompt reveals and how that overview informs the planned migration.
- Mermaid architecture visualization. Describe how to ask an AI agent for a Mermaid chart of the application's high-level architecture, then use its text output to create a visual diagram. Explain why this is useful when planning the migration.
- Deployment options and focus. Describe the deployment options the AI identifies and explain why the chapter focuses on JBoss deployment rather than migrating the Helm chart.
- Whole Application Replacement. Explain why the migration can replace the old application all at once and what compatibility the new version must retain.
- Migration Repository Trade-offs. Explain the advantages and drawbacks of creating a new repository versus migrating the Kitchensink code in place, including the practical difficulty of keeping the original code available for reference.
- Copied-source modernization workspace. Explain why the chosen hybrid approach copies the complete legacy codebase into a new repository: AI tools can see and refactor the application as a whole without moving code layer by layer.
- Repository isolation trade-offs. Justify using a separate repository instead of a branch in the legacy repository, and describe what is deliberately left out of the source copy.
- Legacy baseline and migration branch. Describe how to initialize a repository for the copied application, push the intact legacy version to master, and make migration changes on a separate branch so the two versions can be compared.
- Logical migration commits and pull requests. Explain how commits should represent clear, stable migration increments rather than necessarily matching each numbered book step, and contrast the example's single final pull request with smaller pull requests in a larger migration.
- Testing Before Code Migration. Explain why the application should be thoroughly tested before existing code is modified or migrated, and how LLM-generated missing tests can support more assured iteration.
- Missing test generation. Describe how to use an AI coding tool to identify important logic missing unit or integration tests before migration, and explain why this chapter leaves UI tests out.
- Test verification and early failures. Explain why the generated tests should be run and reviewed, and how a failing test during migration can be useful.
- Legacy integration test coupling. Explain why integration tests need attention during the migration: they can depend on the framework and persistence technology under test, so migrated tests must no longer target legacy JBoss.
- AI-assisted test migration decisions. Describe what the AI was asked to identify and what its commit changed: tests coupled to JBoss or JPA/Hibernate/SQL, migration to Spring and JUnit 5, and removal of a redundant Arquillian-bound test. Explain why adding the JUnit Jupiter engine was a logical, though unrequested, consequence.
- Incomplete test migration consequences. Explain how a test can appear migrated while still importing a legacy library, and why discovering that dependency during cleanup disrupts the staged migration and other teams' work.
- Gap-directed prompt and verification. Distinguish a loosely rephrased retry from a prompt that diagnoses the specific omission, and describe the check required before starting production-code migration.
- Migration Change-Set Size Trade-Off. Explain why AI-assisted migration should use substantial but reviewable change-sets rather than tiny edits or a single codebase-wide change.
- Minimal migration prompt. Explain why the migration prompt asks Cursor to apply a minimal set of changes while replacing Jakarta EE/CDI/EJB patterns with Spring equivalents.
- Connected application layer changes. Trace why introducing the Spring Boot entry point also led to persistence, REST, and event-service changes in this increment.
- First-stage JBoss cleanup. Describe why cleanup can begin before every layer is migrated and what the AI was asked to remove.
- UI verification gap. Explain why the UI migration needs extra verification: UI test coverage is weak, so a production migration should add controller/UI tests, while this example uses manual human testing.
- Selective context reset. Explain why the author clears chat context before a new migration step, and distinguish disposable conversation history from project constraints that should persist in the repository.
- Migrated UI parity check. Describe what the UI migration changed and what a comparison with the legacy application revealed.
- Correcting unwanted UI changes. Explain why the AI tool's UI change needed correction and how a more specific prompt addressed it.
- Preserving the legacy URL. Explain the backward-compatible URL behavior the migration retained and why it matters to existing customers.
- Inference and context trade-off. Explain how an LLM that anticipates unstated needs can save prompting effort but may add unnecessary code, while one that guesses less is usually more precise but requires more context. Describe the desired middle ground: limited prompting without sacrificing engineering basics such as backward compatibility and edge-case handling.
- QA-Guided AI Bug Fix. Trace how a user-perspective test exposed the empty member list after a page refresh, how the team supplied the problem and logs to Cursor, and how tests and QA retesting helped confirm the fix.
- Residual JBoss reference check. Describe how to check for remaining JBoss references and distinguish obsolete names from actual library usage.
- Static refactoring tool choice. Explain why the section favors IDE refactoring over an AI tool for the package rename, using the attempted removal of “jboss” as the example.
- Code as documentation source. Explain why an AI tool can help document an application even when its knowledge is already in the code.
- Practical migrated application README. Describe what the example prompt asks the AI to put in the README and how the author suggests expanding it.
- Persistence migration scope. Distinguish changing the application’s persistence code from migrating existing customer data, and explain why this chapter addresses only the code.
- MongoDB migration changeset. Describe the changes the AI tool made to replace the relational database with MongoDB, including repository access, configuration, data initialization, documentation, dependencies, and the repository test.
- Reasons for migration success. Explain the section’s two proposed reasons the AI tool handled this migration well, and contrast the consistent Spring codebase with the earlier mixed-framework stage.
- Self-starting MongoDB integration tests. Explain why RemoteMemberRegistrationIT needed changing and how the revised test avoids a manual MongoDB startup step.
- Migration pull request granularity. Explain how the migration steps were packaged as separate commits on a dedicated branch and unified in a final pull request. Describe why a larger project might instead open a pull request for each step or layer.
- Combined human and AI review. Explain why engineers familiar with the legacy codebase should review the migration pull request and how an AI tool can complement that review.
Section by section
Introduction
The chapter introduces LLM-assisted legacy migration as a way to recover knowledge from unfamiliar code and make understandable, incremental changes.
- Legacy migration knowledge gap: Explain why migrating an unfamiliar legacy codebase is difficult when knowledge of the old technology, target technology, and application domain is needed but may no longer be available.
Why it matters: This explains why understanding the existing application is a migration challenge, not just a coding task. - LLM-assisted incremental migration: Describe how the introduction proposes using LLMs to analyze code, extract implicit knowledge, and gain enough insight to migrate in small steps while checking the direction.
Why it matters: The proposed migration approach starts with understanding the code rather than generating a wholesale replacement. - Change size versus comprehension: Explain the trade-off between the size of an LLM-proposed code increment and a human's ability to understand and reason about the change.
Why it matters: Fast code generation is less useful if the resulting change is too large for a person to assess properly.
Key terms: legacy applications, knowledge, LLMs, implicit knowledge, small incremental steps, size of the increment, human ability to understand and reason
2.1 Context and application
The section sets up an end-to-end legacy application migration, explains the chosen replacement technologies and AI tool modes, and recommends commits as checkpoints.
- Full-stack migration scope: Describe the kitchensink application as an end-to-end JBoss-backed system whose database, REST controller, business logic, and UI must be migrated to a modern Java stack. Explain why the example chooses Spring Boot.
Why it matters: The migration steps make more sense when you keep the whole application in view. - MongoDB migration rationale: Explain why the example replaces its SQL-accessed relational database with MongoDB and how that choice fits the Spring-based replacement.
Why it matters: The database change is driven by stated requirements, not just a preference for a newer product. - Chat and Agent modes: Distinguish Chat mode from Agent mode and explain why the chapter uses Agent mode for multi-step migrations.
Why it matters: Choosing the right mode determines whether the assistant merely advises you or makes the requested migration edits. - Migration commit checkpoints: Explain the recommendation to commit after each completed migration step and what that provides.
Why it matters: Frequent checkpoints make a multi-step migration easier to inspect and undo.
Key terms: kitchensink, JBoss, Spring (Boot), end-to-end (e2e), relational database, MongoDB, horizontal scaling, document-oriented data model, Spring Data MongoDB, Chat mode
2.2 Pre-analysis of the application
This section recommends starting legacy-application pre-analysis with an LLM-generated overview, then consulting documentation for specific details.
- AI-first application overview: Explain why the pre-analysis starts with an LLM-generated overview rather than reading README files first, and when a README becomes useful.
Why it matters: An overview first helps you decide which parts of a large codebase deserve closer inspection. - Variability of prompt results: State what to expect when running the book’s prompts with a generative AI tool.
Why it matters: A different-looking response need not mean your prompt failed if it conveys a similar result.
Key terms: README files, LLM, bigger picture, huge codebases, not entirely deterministic, prompt, similar
2.2.1 Extracting the bigger picture
This section uses an indexed project and broad LLM prompts to establish the application’s purpose before mapping its architecture and features for migration.
- Product purpose before technology: Explain why the analysis starts with the product’s use case and business value rather than its code, and describe the member-management example at that level.
Why it matters: Starting with user needs gives the migration a purpose beyond replacing technologies. - Architecture and migration baseline: Describe what the high-level architecture prompt reveals and how that overview informs the planned migration.
Why it matters: A layer-and-feature overview helps distinguish replacing a framework from preserving what the application does. - Indexed black-box exploration: State the preparation and prompting approach used when starting with no knowledge of an imported application.
Why it matters: This gives the broad initial questions a project-aware starting point without pretending the team already knows what to ask in detail.
Key terms: use case, business value, quickstart, member registration and management system, technology stack, architecture components, key features, JBoss, Jakarta, Spring
2.2.2 Visualizing with Mermaid
The section shows how an AI-generated Mermaid diagram can make an application's high-level architecture visible and useful for migration planning.
- Mermaid architecture visualization: Describe how to ask an AI agent for a Mermaid chart of the application's high-level architecture, then use its text output to create a visual diagram. Explain why this is useful when planning the migration.
Why it matters: A shareable architecture diagram helps turn an initial picture of the application into something the migration work can use.
Key terms: Mermaid, high-level architecture, version control, migration framework
2.2.3 Deployment models
The section identifies the application's deployment options, chooses JBoss as the migration focus, and points to existing instructions for running the application.
- Deployment options and focus: Describe the deployment options the AI identifies and explain why the chapter focuses on JBoss deployment rather than migrating the Helm chart.
Why it matters: The deployment choice sets a practical boundary for the migration. - Existing deployment instructions: Explain how the application's README can be used to run and understand the app locally, and what alternative the section offers.
Why it matters: Existing documentation gives a concrete starting point for running the legacy application before migrating it.
Key terms: non-functional aspects, JBoss EAP, OpenShift, Helm charts, Maven profiles, README, deployment steps, LLM
2.2.4 Decisions and assumptions
This section sets the assumptions that define what the legacy application migration must preserve and what it can leave out.
- Whole Application Replacement: Explain why the migration can replace the old application all at once and what compatibility the new version must retain.
Why it matters: This assumption sets the boundary for migration choices without dropping existing functionality. - UI Functionality Versus Appearance: Distinguish the required UI functionality from the permitted changes in visual style, and describe who would judge the result in a real migration.
Why it matters: It keeps the migration focused on what the UI lets users do without treating every visual difference as a failure. - Containerized Deployment Boundary: Describe the deployment model assumed for this chapter and distinguish it from the deployment tooling excluded from scope.
Why it matters: It clarifies which deployment concerns the migration example does—and does not—address.
Key terms: gradually, swapped, backward compatibility, same functionalities, UI style, same functionality, QA/UX, containerized deployment model, specific port, Kubernetes
2.3 Trade-offs: copying the code in place vs a new repo
The section compares starting a new repository with migrating in place and identifies the trade-offs that motivate a hybrid approach.
- Migration Repository Trade-offs: Explain the advantages and drawbacks of creating a new repository versus migrating the Kitchensink code in place, including the practical difficulty of keeping the original code available for reference.
Why it matters: These trade-offs explain why neither migration approach is an obvious choice on its own.
Key terms: new repository, in-place migration, git history, legacy configuration
2.3.1 A hybrid approach
The section explains why the modernization uses a separate repository containing a copy of the legacy source code, then gives the initial setup steps for that workspace.
- Copied-source modernization workspace: Explain why the chosen hybrid approach copies the complete legacy codebase into a new repository: AI tools can see and refactor the application as a whole without moving code layer by layer.
Why it matters: Keeping the whole application visible lets AI assist with broad changes while the modernization remains separate from the original project. - Repository isolation trade-offs: Justify using a separate repository instead of a branch in the legacy repository, and describe what is deliberately left out of the source copy.
Why it matters: The isolation makes restructuring and experimentation possible without imposing the original repository’s constraints or affecting it. - Initial repository copy: Describe the initial setup: create a new repository, recursively copy the legacy project into it, and remove the copied legacy .git folder.
Why it matters: Removing the copied Git metadata lets the copied source live under the new repository’s own history.
Key terms: hybrid approach, new repository, sandbox, AI-assisted refactoring, legacy repository infrastructure, Git metadata, CI/CD workflows, new branch, separate repository, cp -R
2.3.2 Procedure for code increments
The section establishes a Git workflow for preserving the legacy application, reviewing AI-generated changes, and recording migration work as logical increments.
- Legacy baseline and migration branch: Describe how to initialize a repository for the copied application, push the intact legacy version to master, and make migration changes on a separate branch so the two versions can be compared.
Why it matters: A preserved baseline makes the migration changes visible rather than mixing them into the legacy version. - Review before accepting AI changes: Explain how Cursor's Plan Mode or Composer can help plan a migration and show a unified diff for review before AI-generated changes are accepted, and when the agent may be asked to commit.
Why it matters: Review keeps the developer responsible for the changes even when AI handles planning or Git commands. - Logical migration commits and pull requests: Explain how commits should represent clear, stable migration increments rather than necessarily matching each numbered book step, and contrast the example's single final pull request with smaller pull requests in a larger migration.
Why it matters: Logical increments make the migration history reflect stable changes rather than an arbitrary chapter outline.
Key terms: git origin, master, migration branch, JBoss legacy version, Cursor, Plan Mode, Composer, unified diff, conventional commit message, migration step
2.4 Testing
The section establishes testing as a safeguard before legacy-code migration and notes that LLM tools can help fill gaps in the test suite.
- Testing Before Code Migration: Explain why the application should be thoroughly tested before existing code is modified or migrated, and how LLM-generated missing tests can support more assured iteration.
Why it matters: Tests give you a way to check that the application still behaves as expected while you change it.
Key terms: unit tests, integration tests, e2e tests, performance tests, LLM tools
2.4.1 Generate missing tests
This section shows how to fill test gaps before migrating legacy code, verify the AI-generated tests, and retain a REST-based integration test when changing backends.
- Missing test generation: Describe how to use an AI coding tool to identify important logic missing unit or integration tests before migration, and explain why this chapter leaves UI tests out.
Why it matters: Filling test gaps first gives the migration more ways to reveal broken behavior. - Test verification and early failures: Explain why the generated tests should be run and reviewed, and how a failing test during migration can be useful.
Why it matters: A trustworthy test suite can expose migration errors before reviewers or users have to find them. - REST integration test portability: Explain why the existing RemoteMemberRegistrationIT can be retained when moving from JBoss to a Spring backend.
Why it matters: Not every legacy test has to be replaced when the application changes frameworks.
Key terms: unit/integration tests, UI tests, REST and data layers, AI-generated, false positives, fail-fast, RemoteMemberRegistrationIT, JBoss agnostic, REST, Spring backend
2.4.2 Migrate tightly coupled tests from the old framework
This section shows how to identify and migrate integration tests tied to a legacy framework while removing redundant tests and adopting Spring Boot-compatible test infrastructure.
- Legacy integration test coupling: Explain why integration tests need attention during the migration: they can depend on the framework and persistence technology under test, so migrated tests must no longer target legacy JBoss.
Why it matters: A migrated application still needs tests that exercise its new framework rather than its old one. - AI-assisted test migration decisions: Describe what the AI was asked to identify and what its commit changed: tests coupled to JBoss or JPA/Hibernate/SQL, migration to Spring and JUnit 5, and removal of a redundant Arquillian-bound test. Explain why adding the JUnit Jupiter engine was a logical, though unrequested, consequence.
Why it matters: The example shows that test migration involves judging which tests to adapt, which to remove, and which supporting dependencies must change.
Key terms: integration tests, tight coupling, legacy JBoss, ITs, JPA/Hibernate/SQL, Spring Boot, MongoDB, JUnit 5, junit-jupiter-engine
2.4.3 Mistake of missing steps in the process
An overlooked legacy import in a migrated test shows why each migration step needs review, a targeted correction, and test verification before production-code migration.
- Incomplete test migration consequences: Explain how a test can appear migrated while still importing a legacy library, and why discovering that dependency during cleanup disrupts the staged migration and other teams' work.
Why it matters: A missed test dependency can surface only when a later cleanup step tries to remove the legacy library. - Gap-directed prompt and verification: Distinguish a loosely rephrased retry from a prompt that diagnoses the specific omission, and describe the check required before starting production-code migration.
Why it matters: A specific prompt addresses the omission, while passing tests provides a check before the next migration stage.
Key terms: legacy library, legacy dependencies, isolated step, JBoss-related libraries, package imports, Jupiter (Junit 5), more context
2.5 Production code migration trade-offs
The section explains how to size AI-assisted production-code migration increments to balance automation payoff against human review risk.
- Migration Change-Set Size Trade-Off: Explain why AI-assisted migration should use substantial but reviewable change-sets rather than tiny edits or a single codebase-wide change.
Why it matters: The size of each migration step affects both the value gained from AI and the team's ability to verify its work.
Key terms: change-set size, AI payoff, human review, balanced range
2.5.1 Applying a minimal set of changes
This section applies a minimal Spring Boot and Java 21 migration, shows why related application layers must change together, and checks that the resulting application starts and passes its tests.
- Minimal migration prompt: Explain why the migration prompt asks Cursor to apply a minimal set of changes while replacing Jakarta EE/CDI/EJB patterns with Spring equivalents.
Why it matters: A narrow prompt helps keep the migration focused without sacrificing a functioning result. - Connected application layer changes: Trace why introducing the Spring Boot entry point also led to persistence, REST, and event-service changes in this increment.
Why it matters: Following dependencies prevents a seemingly small framework change from leaving connected parts inconsistent. - Increment validation and limits: Describe how this migration increment is checked and what remains unfinished after its tests pass.
Why it matters: A passing increment provides a checkpoint without hiding the legacy cleanup still to do.
Key terms: minimal set of changes, over-engineering, Spring Boot, Java 21, KitchensinkApplication, spring-boot-starter-data-jpa, MemberResourceRESTService, ApplicationEventPublisher, event service, mvn spring-boot:run
2.6 Cleanup stage
The section shows how to clean up obsolete JBoss artifacts during an incomplete migration and explains the test-based judgment used to move on.
- First-stage JBoss cleanup: Describe why cleanup can begin before every layer is migrated and what the AI was asked to remove.
Why it matters: Cleanup can be incremental rather than waiting for the entire migration to finish. - Test-backed cleanup review: Explain the author's condition for moving past review of the removed legacy code and proceeding to UI migration.
Why it matters: The decision to move on rests on passing tests and strong coverage, not simply on the AI reporting that cleanup is done.
Key terms: JBoss, cleanup stage, dependencies, configuration files, test coverage, tests, UI layer
2.7 UI layer migration
The section starts the UI and controller migration, explains how to reset AI chat context between steps, and shows why the resulting UI still needs human comparison with the legacy application.
- UI verification gap: Explain why the UI migration needs extra verification: UI test coverage is weak, so a production migration should add controller/UI tests, while this example uses manual human testing.
Why it matters: A migrated page can appear to work while losing behavior that tests do not cover. - Selective context reset: Explain why the author clears chat context before a new migration step, and distinguish disposable conversation history from project constraints that should persist in the repository.
Why it matters: The AI can leave behind stale suggestions without losing the rules that govern the project. - Migrated UI parity check: Describe what the UI migration changed and what a comparison with the legacy application revealed.
Why it matters: Comparing the running UI with the original catches changes that a broad migration prompt did not intend.
Key terms: UI migration, controller/UI part, manual testing, let’s clean the context, New Chat, conversational chat history, persistent file, core guardrails, MemberController, template engine
2.7.1 Taking a step back when AI tools did too much
The section shows how to correct an AI tool that changed too much during UI migration while retaining a useful compatibility change it anticipated.
- Correcting unwanted UI changes: Explain why the AI tool's UI change needed correction and how a more specific prompt addressed it.
Why it matters: A precise correction can bring an AI-assisted migration back in line with the intended UI. - Preserving the legacy URL: Explain the backward-compatible URL behavior the migration retained and why it matters to existing customers.
Why it matters: Keeping the old address working helps existing customers reach the migrated application.
Key terms: UI, registered members, CSS changes, prompt, backward compatible, web URL, index.jsf
2.7.2 Trade-off between LLM inferring too much vs too little
Explains the trade-off between an LLM that requires detailed instructions and one that infers too much, and how prompts can help set the desired balance.
- Inference and context trade-off: Explain how an LLM that anticipates unstated needs can save prompting effort but may add unnecessary code, while one that guesses less is usually more precise but requires more context. Describe the desired middle ground: limited prompting without sacrificing engineering basics such as backward compatibility and edge-case handling.
Why it matters: The amount an LLM infers affects both the work it saves and the unwanted changes you may have to undo. - Prompting for controlled inference: Describe why users may want different amounts of LLM inference, and how an explicit prompt can limit guessing or over-engineering when precision matters.
Why it matters: Stating the boundaries of a request helps you retain control when the LLM's helpful guesses go too far.
Key terms: context, over-engineering, backward compatibility, edge cases, precise prompts, explicit guidance, over-assume
2.7.3 Fixing bugs with AI tools
The section shows how QA findings and application logs can guide an AI tool to fix a post-migration UI bug, with tests and QA retesting confirming the result.
- QA-Guided AI Bug Fix: Trace how a user-perspective test exposed the empty member list after a page refresh, how the team supplied the problem and logs to Cursor, and how tests and QA retesting helped confirm the fix.
Why it matters: A reported symptom and its logs give the AI tool a concrete bug to investigate, while updated tests and QA retesting check the result.
Key terms: Q/A, e2e testing, logs, Cursor IDE, unit tests, re-testing
2.8 Cleanup - the 2nd stage
This section uses a codebase search to check what remains of JBoss after an initial, high-level cleanup.
- Residual JBoss reference check: Describe how to check for remaining JBoss references and distinguish obsolete names from actual library usage.
Why it matters: A search helps identify what still needs cleanup without mistaking old names for a remaining library dependency.
Key terms: grep, JBoss library, package names, static files
2.8.1 Mistake of overusing LLMs over static code refactoring tools
A failed AI-assisted package rename shows why language-aware IDE refactoring is preferable for changes that static analysis can fully determine.
- Static refactoring tool choice: Explain why the section favors IDE refactoring over an AI tool for the package rename, using the attempted removal of “jboss” as the example.
Why it matters: Choosing the tool suited to a predictable change avoids introducing errors during cleanup. - Accuracy and cost trade-off: Justify why the section warns against using LLMs for every task, even if an AI tool could eventually perform the refactoring accurately.
Why it matters: An AI-first workflow still benefits from checking whether an established tool is more reliable and less costly.
Key terms: static analysis, IDE refactoring, package name, references, LLMs, static code analysis, refactoring tools, tokens
2.9 Adding documentation
The section shows how to use an AI tool to turn knowledge in a migrated application's code into a useful README.
- Code as documentation source: Explain why an AI tool can help document an application even when its knowledge is already in the code.
Why it matters: Existing code can provide the raw material for documentation that developers can read more quickly. - Practical migrated application README: Describe what the example prompt asks the AI to put in the README and how the author suggests expanding it.
Why it matters: A useful README helps another developer build, run, and understand the migrated application.
Key terms: code, LLMs, documentation, README, build, run, endpoints, features, iterate
2.10 Migrating the persistence layer
This section separates production-code changes for a database migration from the runtime work of moving existing customer data.
- Persistence migration scope: Distinguish changing the application’s persistence code from migrating existing customer data, and explain why this chapter addresses only the code.
Why it matters: It keeps the upcoming code changes from being mistaken for a complete database migration.
Key terms: persistence layer, runtime, production code, migrating the data
2.10.1 Adding Mongo support
A prompt-driven MongoDB migration changes the application’s persistence layer, and the section explains why the AI tool handled this step well.
- MongoDB migration changeset: Describe the changes the AI tool made to replace the relational database with MongoDB, including repository access, configuration, data initialization, documentation, dependencies, and the repository test.
Why it matters: A database migration affects setup, initialization, and tests as well as repository code. - Reasons for migration success: Explain the section’s two proposed reasons the AI tool handled this migration well, and contrast the consistent Spring codebase with the earlier mixed-framework stage.
Why it matters: Familiar examples and a consistent codebase can make an AI-assisted change easier to carry out.
Key terms: MemberRepository, MongoDB, DataInitializer, repository test, open-source resources, Spring, code patterns, JBoss
2.10.2 Improving tests not to require a manual step
The section removes a manual MongoDB startup step from integration testing and documents the Docker requirement for running the revised tests.
- Self-starting MongoDB integration tests: Explain why RemoteMemberRegistrationIT needed changing and how the revised test avoids a manual MongoDB startup step.
Why it matters: Removing manual setup makes the test process suitable for a fully automatic continuous delivery pipeline. - Docker requirement in test documentation: Describe what the README needed to tell developers about running the revised integration tests.
Why it matters: Automating MongoDB startup does not eliminate the need to make the tests’ Docker prerequisite clear.
Key terms: RemoteMemberRegistrationIT, MongoDBContainer, testcontainers framework, continuous delivery pipeline, README, Docker, integration tests, mvn
2.11 Conclude with merge pull requests
The section explains how to package a completed legacy migration for review, adjusting pull-request size to the project and combining human and AI review.
- Migration pull request granularity: Explain how the migration steps were packaged as separate commits on a dedicated branch and unified in a final pull request. Describe why a larger project might instead open a pull request for each step or layer.
Why it matters: Reviewable increments make it easier to examine a migration without losing sight of individual changes. - Combined human and AI review: Explain why engineers familiar with the legacy codebase should review the migration pull request and how an AI tool can complement that review.
Why it matters: AI review can add useful findings, but it does not replace the judgment of engineers who understand the old system.
Key terms: migration branch, commit, pull request, migration step, human engineers, AI tool, review, legacy codebase
2.12 Summary
Where this is used later
- (chapter intro) (chapter 7) · The earlier discussion of narrowing code increments, which the introduction explicitly cross-references.
- Context rot: is too much context a bad thing? (chapter 3) · Develops the problem of excessive context introduced here.
- From .cursorrules to AGENTS.md (chapter 5) · Addresses repository files for persistent agent guidance.
- Context vacuum: first potential mistake (chapter 3) · The need to supply context when an LLM cannot infer the request becomes a focus.
- Mistakes of LLMs over-engineering performance improvements (chapter 7) · The risk of AI over-engineering becomes a focus in performance work.
- AI code review: rules, checklists, and heuristics (chapter 8) · Develops AI code review as part of evaluating code changes.
Concepts explained in this chapter
- migrationSoftware migration is the process of moving an application or its code to a different platform, framework, architecture, dependency, or implementation while preserving required behavior.
- CursorCursor is an AI-powered code editor and development environment that assists users with generating, modifying, and understanding source code.
- integration testAn integration test evaluates interactions between multiple software components or with external infrastructure rather than isolating a single unit.
- commitA Git commit is an immutable recorded snapshot of repository changes with associated metadata and parent history.
- Spring BootSpring Boot is a framework for building and configuring Spring-based applications with convention-over-configuration support.
- language modelA language model is a machine-learning model that processes and generates text by predicting sequences of tokens.
- hybrid migration approachA migration approach that combines in-place repository modification with work in a separate repository, retaining the legacy repository as a reference.
- pull requestA proposed set of repository changes submitted for review and integration into a codebase.
- MongoDBA document-oriented database system that stores and queries data using BSON documents and provides distributed data-management capabilities.
- Spring Data MongoDBSpring Data MongoDB is a Spring Data module that provides repository and data-access abstractions for MongoDB.
- code coverageCode coverage is a metric reporting the proportion of source-code lines, branches, or paths executed during testing.
- code incrementA code increment is a coherent set of changes that produces a stable intermediate version of a codebase.
- JUnitJUnit is a Java testing framework for defining and executing automated tests.
- deploymentDeployment is the process of installing and configuring software so that it runs in a target environment.
- software testingAn executable procedure that evaluates software behavior against expected results or conditions.
- Agent ModeAgent mode is an AI-assistance mode that can directly edit files and execute instructed changes within a codebase.
- backward compatibilityBackward compatibility is the ability of a newer software version to preserve the behavior and interfaces expected by an older version's users or integrations.
- prompt engineeringPrompting is the practice of formulating and supplying instructions or context to an AI model to guide its output.
- code reviewThe manual examination of proposed source-code changes to identify defects, risks, and conformance or maintainability problems before integration.
- context windowThe finite amount of input information a language model can consider during a single inference or conversation state.
- overengineeringOver-engineering is the addition of unnecessary complexity, abstractions, or functionality beyond the actual requirements of a software system.
- promptA prompt is an input instruction or request supplied to an AI model to elicit a response or action.
- IDEAn integrated development environment is a software application that combines source editing, building, debugging, and related programming tools.
- conversational aiAn AI assistant is a software system that uses artificial intelligence to help a user perform tasks or generate information.
- static analysisThe automated examination of source code without executing it to identify defects, suspicious constructs, policy violations, or program properties.
- unit testA unit test evaluates an isolated software unit, such as a function or class, against expected behavior.
- documentationSoftware documentation is written reference material describing a software product's installation, interfaces, behavior, design, or usage.
- model architectureA neural network architecture is the organization of computational layers and connections that transform inputs into outputs through learned parameters.
- sandboxingThe isolation of software execution within constrained resources and permissions to limit its impact on the surrounding system.
- indexingProject indexing is the process of analyzing and cataloging project files to support efficient code search and contextual retrieval.
- AI-generated pull requestSource code produced in whole or in part by an artificial-intelligence system.
- plan modePlan mode is an AI-assistance mode that outlines intended development steps before modifying code.
- false positiveA false positive is a classification that incorrectly reports a positive or high-risk condition when it is absent.
- refactoringRefactoring is the restructuring of existing code to improve its design or understandability without intentionally changing its externally observable behavior.
- manual testingManual testing is the evaluation of software behavior by a human executing and inspecting test procedures rather than automated test code.
- performance testingA performance test measures whether a system meets responsiveness, throughput, or resource-efficiency requirements under workload.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
