OpenAI Codex with Spring Boot: Setup, Tasks, and Verification

OpenAI Codex can work on a Spring Boot repository, but a useful result requires more than a prompt saying “make the tests green.” The task needs a working Java environment, the project’s actual rules, and an acceptance check that survives a misleading agent summary.

This is a repository workflow guide. Earlier versions described personal work incidents and product rankings without retained evidence. The examples here are proposed instructions; they do not report measured model performance.

Establish the environment first

For a local CLI workflow, follow the official installation guide, then record the installed version and inspect its help:

codex --version
codex --help
java -version
./mvnw -version
./mvnw -B verify

Run the last command only in a repository using Maven. For Gradle, use the checked-in wrapper and its documented verification task instead. Record the baseline result before requesting a change. A pre-existing failure is important context, not a reason to weaken a test.

A hosted task runs in a different environment from your laptop. Verify dependency resolution, JDK availability, required credentials, and test services there. A database reachable on your laptop’s localhost is not automatically reachable from a hosted task. Testcontainers requires a compatible container runtime; an embedded database can have different behavior from production.

Give Codex a narrow project contract

OpenAI documents discovery and scoping of AGENTS.md instructions. Put the commands and decisions relevant to this repository in that file. The following is a template, with versions to be filled from the build rather than copied from an article:

## Project
- Read the build file and wrapper before editing. Preserve the declared JDK.
- Controllers delegate to services; services enforce ownership and business rules.
- Reuse existing DTOs, mappers, exception handling, and dependency management.

## Task boundaries
- Preserve unrelated working-tree changes.
- Propose dependency, security, and migration changes explicitly.
- Do not change a business rule just to agree with a failing test.

## Verification
- Run the repository's documented verification command.
- Report the command, exit status, executed test counts, and skipped tests.
- State any check blocked by the environment.
- Review the final diff for weakened assertions, disabled tests, or altered rules.

Instructions guide an agent; they do not enforce a filesystem boundary. Put mandatory controls in permissions, CI, and review rules. For a longer example, see AGENTS.md for Spring Boot.

Keep permissions and instructions separate

Use the current approvals and security documentation together with your installed CLI’s help. Earlier versions of this article recommended retired suggest and auto-edit modes and treated sandboxing and approvals as one setting. Those recommendations have been removed.

Choose the filesystem and network access required by the task. A Maven dependency-download failure needs diagnosis of network and repository configuration. It does not establish that the agent needs unrestricted machine access. Start with the Maven sandbox diagnostic sequence if the build works outside the agent but fails inside it.

Example task: default order sorting

Use a concrete acceptance contract instead of “fix pagination”:

Inspect the existing orders endpoint and repository query. When the caller omits sorting, return newest orders first, with an ID tie-breaker. Preserve explicitly requested sorting. Keep ownership filtering and page-size limits. Add tests for equal timestamps, the next page, and a different authenticated user. Do not change the public response shape.

Before accepting the patch, insert records with different timestamps and equal-timestamp ties. Request two pages and check ordering, overlap, and ownership. Review the generated SQL or query method. Sorting a single returned page in memory is not equivalent to ordering the database query before pagination.

This example is a task design, not a claim that a particular model completed it. It gives reviewers something observable to check.

Verify what completed

After the agent stops, inspect the diff and rerun the appropriate checks in the intended environment:

git diff --stat
git diff --check
git diff -- pom.xml build.gradle build.gradle.kts src
./mvnw -B verify

A successful agent process is not proof of a successful build. Likewise, a successful build does not prove tests were discovered or business rules preserved. Use the CI verification guide for that distinction.

Check dependencies for actual activation, not just resolution. On Boot 4, a third-party library alone may not bring the Boot integration required by the feature; the dependency diagnostic guide explains how to investigate it.

Choose a model available in your own installation and record its exact identifier for comparisons. codex --version reports the CLI version, not the model used in a run. Historical model labels and anecdotal speed comparisons are poor substitutes for a task whose result can be checked.

For other working surfaces, compare the Claude Code workflow and Cursor workflow. The Java guide organizes the related verification topics.