openxava / documentation / AI coding assistants

Why OpenXava works well with AI coding assistants

OpenXava works remarkably well with AI coding assistants and agents such as GitHub Copilot, Windsurf, Cursor, JetBrains Junie, Claude Code, and others. There are several reasons for this:

• Built on Java standards: OpenXava is based on well-known Java standards like JPA, Bean Validation, and standard annotations. AI models have been extensively trained on these technologies and understand them deeply.
• Over 20 years of open source history: OpenXava has been an open source project since 2004. This means there are two decades of source code, documentation, forum discussions, tutorials, and example applications publicly available on the internet—all of which has been ingested by AI training datasets.
• Convention over configuration: OpenXava's approach of generating the entire user interface from annotated Java classes is straightforward for AI to understand. The AI only needs to produce a JPA entity with a few annotations, and OpenXava takes care of the rest.
• Minimal boilerplate: Thanks to Lombok integration and OpenXava's declarative style, the code that AI needs to generate is concise and pattern-based—exactly the kind of code AI excels at producing.

You can see this in action in the Course with AI, where a complete business application is built using an AI agent with minimal manual intervention.

Optimizations for AI agents (7.7+)

Starting with version 7.7, OpenXava includes specific optimizations to make AI coding assistants even more effective. These optimizations provide AI agents with project-specific context and real code examples, so they produce correct OpenXava code from the very first attempt.

AGENTS.md

Every new OpenXava project includes an AGENTS.md file in the project root. This is a special Markdown file that AI coding assistants automatically read to understand the conventions and rules of your project. Most modern AI-powered IDEs (Windsurf, Cursor, GitHub Copilot, etc.) recognize this file and use it as context when generating code.

The AGENTS.md file included with OpenXava projects contains:

• JPA entity conventions: How to use Lombok, field visibility rules, and correct annotation patterns.
• Master-detail patterns: Instructions to use @ElementCollection and @Embeddable instead of @OneToMany for detail collections.
• Actions conventions (new in 7.7.2): Rules on how to define actions in controllers.xml and create action classes without modifying the entity.
• Test conventions: How to write JUnit tests using ModuleTestBase, including the requirement to call login() as the first line.
• Dashboards conventions (new in 7.7.2): Instructions to review the documentation and where to place the dashboard classes.
• References to the .xava folder: Directing the AI to look at real code examples for guidance.

This means that when you ask an AI agent to "create a Customer entity" or "write a test for the Invoice module," it will follow OpenXava conventions automatically.

The .xava folder

In addition to AGENTS.md, OpenXava projects use a .xava folder that contains real code examples for AI agents to reference. This folder is generated automatically and includes:

• agents/test/bymodule/: Real JUnit test examples from the OpenXava test suite, showing how to test different types of modules.
• agents/test/default-controllers.xml: The complete list of available actions in OpenXava controllers, so the AI knows which actions it can use in tests.

The .xava folder is generated from the openxava-agents-examples Maven artifact. It is not meant to be edited manually—it is regenerated automatically when the OpenXava version changes.

How it works together

When an AI coding assistant opens your project, it reads AGENTS.md to learn the project rules. When it needs to generate a test or understand how OpenXava works, it looks at the examples in the .xava folder. This combination of rules and examples results in much more accurate code generation.

New projects (7.7 or later)

Projects created with OpenXava 7.7 or later already include everything needed. Both the AGENTS.md file and the pom.xml configuration for the .xava folder are set up automatically.

The only step you need to take is to run a Maven build to generate the .xava folder:

mvn package

After this, the .xava folder will be created in your project root with all the example files. The .xava folder is not included in .gitignore and you should not add it, because most AI coding assistants only search files that are inside the project and not ignored by Git. The content of the .xava folder is regenerated automatically when the OpenXava version changes.

Adding AI support to existing projects

If your project was created with a version prior to 7.7 and you have upgraded to 7.7 or later, you can add AI coding assistant support manually by following these steps:

Step 1: Add AGENTS.md

Download the AGENTS.md file from the OpenXava GitHub repository and place it in your project root:

https://github.com/openxava/openxava/blob/master/openxava-archetype/AGENTS.md

After downloading, edit the file to replace the archetype placeholders with your actual project values:

• Replace ${package} with your base package (e.g. com.yourcompany)
• Replace ${artifactId} with your project name (e.g. yourapp)

For example, if your package is com.mycompany and your artifact is invoicing, change:

package ${package}.${artifactId}.model;

to:

package com.mycompany.invoicing.model;

Step 2: Modify pom.xml

Add the following execution inside the maven-dependency-plugin in your pom.xml. If you already have a maven-dependency-plugin configuration (most OpenXava projects do), just add this new <execution> block alongside the existing ones:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <!-- ... your existing executions ... -->
        <execution>
            <id>unpack-agents-examples</id>
            <phase>initialize</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>org.openxava</groupId>
                        <artifactId>openxava-agents-examples</artifactId>
                        <version>${openxava.version}</version>
                        <outputDirectory>.xava</outputDirectory>
                        <includes>agents/**</includes>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>

This configuration unpacks the openxava-agents-examples artifact into the .xava folder during the Maven initialize phase, which runs before compilation.

Step 3: Generate the .xava folder

Run Maven to generate the .xava folder:

mvn package

You should now see a .xava/agents/ folder in your project root containing the test examples and controller definitions.

Do not add .xava to your .gitignore file, because most AI coding assistants only search files that are inside the project and not ignored by Git. If .xava is in .gitignore, the agents will not be able to find the examples.

Customizing AGENTS.md

The AGENTS.md file is fully customizable. You can and should edit it to include conventions specific to your project. For example:

• Add naming conventions for your entities and packages.
• Document specific business rules that the AI should follow.
• Include patterns for custom actions or validators used in your project.
• Add references to your own example code.

The more specific and detailed your AGENTS.md is, the better the AI coding assistant will understand your project and generate code that fits your standards. Think of it as onboarding documentation—not for a new developer, but for an AI agent.