Using Codex to Automate Full Java Spring Boot Tasks, Not Just Generate Code

1. Stop Treating Codex as a Simple Code Generator

Many first‑time users ask Codex to "write a user login interface" or "write an order query interface". While it can produce code, the real pain points in Java projects are not writing a single controller method but understanding existing project structure, keeping response formats consistent, handling exceptions, permission checks, transaction boundaries, database migrations, tests, and running mvn verify. Codex is designed as a software‑engineering agent that can write features, answer repository questions, fix bugs, and propose pull requests.

Key insight: Codex is better at completing a relatively complete development task rather than generating a single code snippet.

2. Choose Small, Well‑Bounded Tasks for Java Projects

Large‑scale refactorings such as rewriting the entire user system, changing the permission architecture, converting a monolith to micro‑services, or upgrading to the latest Spring Boot are risky for AI. Instead start with tasks that have clear boundaries and existing code to reference, e.g. adding a standard REST endpoint, adding tests to an existing service, fixing a specific bug, locating a problem from an error log, adding parameter validation, adding pagination, writing a module README, etc.

3. First Step: Provide Codex with Project Rules (AGENTS.md)

Codex often fails because it does not know the implicit conventions of a Java project (controller style, DTO naming, exception handling, logging, transaction layer, test execution, protected configurations). Create an AGENTS.md file at the project root that acts as a README for the agent. Example content:

# AGENTS.md
## Project Tech Stack
- Java 21
- Spring Boot 3.x
- Maven
- MySQL
- MyBatis Plus
- JUnit 5

## Layer Rules
- Controllers only handle request parameters, return results, and permission entry.
- Controllers must not access Mapper or Repository directly.
- Business logic resides in Service layer.
- Database access must go through Mapper or Repository.
- Entities must not be returned directly to the front end.
- New APIs must define Request and Response DTO.

## Exception Rules
- Do not return null directly.
- Business exceptions use BusinessException.
- Parameter errors use unified validation.
- Controllers must not swallow exceptions.

## Config Rules
- Do not modify application‑prod.yml.
- Do not change production DB connection info.
- Do not log tokens, passwords, or keys.

## Test Rules
After code changes, run:
```
./mvnw test
./mvnw verify
```

If tests fail, read the logs and fix the issues.

4. Second Step: Isolate Codex Work in a Separate Git Worktree

Never let Codex modify the main project directory directly. Create an independent worktree for each AI task:

id="uvtc5n"
git switch main
git pull
git worktree add ../order-cancel-codex -b feat/order-cancel-codex
cd ../order-cancel-codex

This isolation prevents accidental changes to configuration files, shared components, or database scripts, allows parallel tasks, and makes it easy to review the diff before merging.

5. Third Step: Give Codex Detailed Acceptance Criteria, Not a One‑Liner

A bad prompt is "Help me implement a cancel‑order interface." A good prompt includes business goals, functional requirements, and execution constraints, e.g.:

Please implement a cancel‑order endpoint in the current Spring Boot project.

Business goals:
1. Add POST /api/orders/{orderId}/cancel.
2. Only the order owner may cancel.
3. Only orders in PENDING_PAY or PAID states may be cancelled.
4. Disallow cancellation if the order has shipped.
5. On success, set order status to CANCELLED.
6. If the order is paid, create a refund request record (do not call the real refund API).
7. Ensure the operation is idempotent.

Execution requirements:
1. Read AGENTS.md first.
2. Review existing Controller, Service, Mapper, DTO for the order module.
3. Output an implementation plan before modifying any code.
4. Follow existing code style.
5. Add Service unit tests and Controller integration tests.
6. Run ./mvnw test.
7. If tests fail, read logs and fix.
8. Finally output modified file list, test results, and potential risks.

Forbidden actions:
- Do not modify application‑prod.yml.
- Do not call the real payment refund API.
- Do not delete existing fields.
- Do not execute git push.

The prompt tells Codex what to do, what not to do, how to verify completion, and how to handle failures.

6. Split Each Task into Four Phases

Phase 1 – Analysis only (no code changes). Example prompt asks Codex to list where order status is defined, which classes need changes, existing refund code, required DTOs, needed tests, and risky points.

Phase 2 – Planning. Codex outputs a detailed implementation plan with file modifications, transaction boundaries, idempotency handling, permission checks, and test coverage.

Phase 3 – Implementation. Codex writes code according to the plan, preserving style, not introducing new frameworks, and limiting changes to relevant modules.

Phase 4 – Test and Fix. Run ./mvnw test, read any error logs, fix only task‑related issues, and re‑run tests.

7. Six Key Areas Java Developers Must Manually Review

Permission checks – ensure the endpoint validates the current user.

Transaction placement – verify all related updates are within the same transaction.

Idempotency – confirm repeated calls do not create duplicate refund records.

Status flow – avoid illegal state transitions (e.g., SHIPPED → CANCELLED).

Database changes – check new columns/tables for defaults, indexes, constraints, and backward compatibility.

Test coverage – include failure scenarios such as missing order, unauthorized user, shipped order, already cancelled order, existing refund request.

8. Let Codex Perform an Initial Diff Review

Before a human review, ask Codex to examine the Git diff against main and report only problems, e.g. unrelated file changes, permission bypasses, transaction risks, duplicate refunds, missing failure‑scenario tests, production config modifications, or log leakage.

9. What Codex Actually Saves for Java Developers

From a real‑world perspective, Codex excels at reducing time spent on repetitive engineering tasks: reading duplicated code, adding DTOs, writing controller tests, locating small bugs from logs, writing mapper conversions, updating READMEs, summarizing Git diffs, and generating boundary‑condition tests.

10. A Replicable Codex + Java Workflow

1. Keep main branch clean.
2. Create an isolated worktree for each AI task.
3. Maintain AGENTS.md at project root.
4. Let Codex analyze first; do not modify code yet.
5. Confirm the plan, then implement.
6. Run all tests after implementation.
7. Ask Codex to review the diff.
8. Developer manually checks high‑risk areas.
9. Submit PR.
10. After merge, clean up the worktree.

This workflow aligns with typical Java team practices of layering, testing, code review, transaction management, and permission handling.

11. Why This Article Focuses Solely on Codex

Including many AI tools dilutes actionable guidance. By concentrating on a single agent and a concrete workflow, readers can immediately try the process on their own Spring Boot project.

Conclusion

Codex’s greatest value for Java programmers is not generating a pretty controller but executing an entire, well‑scoped development flow: read the project, produce a plan, modify code, add tests, run Maven, inspect logs, fix bugs, summarize the diff, and await human review. Managing AI‑generated code safely and efficiently will become a highly valuable skill.