Hi,
I'm sharing my experience of using this simple class
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD,
ElementType.PARAMETER})
@Documented
public @interface AgentInstruction {
String value();
String example() default "";
String[] constraints() default {};
String[] dependencies() default {};
String caveat() default "";
}
To annotate my libraries, directing the AI Agent on how to use them to
generate new code, meaning, new applications supported by the libraries.
By embedding this metadata in the jar files, we provide hints, rules,
warnings, etc. to the AI to generate better code and reduce hallucinations.
On Mon, May 4, 2026 at 3:24 PM Remi Forax <[email protected]> wrote:
> Hello,
> there is already a whole ecosystem for what you want to do, called
> OpenRewrite [1],
> with declarative recipe LLMs are able to generate, skills you can add to
> your harness, etc.
>
> regards,
> Rémi
>
> [1] https://docs.openrewrite.org/
>
> ----- Original Message -----
> > From: "Úber A. Calderón Alfaro" <[email protected]>
> > To: "core-libs-dev" <[email protected]>
> > Sent: Monday, May 4, 2026 10:43:48 PM
> > Subject: [External] : [PROPOSAL] Standard AI-Agent Metadata Annotation:
> @AgentInstruction
>
> > Dear OpenJDK Core Libs Development Team,
> >
> > I would like to propose the introduction of a new standard annotation,
> > java.lang.annotation.AgentInstruction, into the core library.
> >
> > MOTIVATION
> > As AI-driven development tools (LLMs, autonomous agents, and IDE
> > assistants) become primary consumers of Java APIs, there is a growing
> > "intent gap." While Javadoc provides human-readable documentation, and
> > annotations like @Deprecated provide compiler hints, we lack a
> > standardized, machine-readable way to communicate behavioral guardrails
> and
> > idiomatic intent directly to AI agents.
> > Currently, agents rely on speculative interpretations of method names or
> > broad training data. This leads to hallucinations or the use of
> > anti-patterns when project-specific or library-specific constraints are
> not
> > explicitly declared in a way the agent can prioritize.
> >
> > THE PROPOSAL
> > The @AgentInstruction annotation provides a declarative bridge within the
> > bytecode to guide AI agents in generating safe, idiomatic code.
> >
> > package java.lang.annotation;
> > @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD,
> > ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Documented
> > public @interface AgentInstruction {
> >
> > /** The primary instruction or intent for the AI agent. */
> > String value();
> >
> > /** An idiomatic code example. */
> > String example() default "";
> >
> > /** Behavioral or architectural constraints. */
> > String[] constraints() default {};
> >
> > /** Prerequisites or dependencies. */
> > String dependencies() default "";
> >
> > /** Warnings about common pitfalls or anti-patterns. */
> > String caveat() default "";
> > }
> >
> >
> > POTENTIAL APPLICATIONS IN THE JDK
> > • On java.util.Optional#get(): @AgentInstruction(value="Discouraged for
> > direct use.", caveat="Use .orElse() or .ifPresent() to avoid
> > NoSuchElementException.")
> >
> > • On java.util.concurrent.ExecutorService:
> > @AgentInstruction(constraints={"Always shut down the executor after
> use.",
> > "Prefer try-with-resources in JDK 19+."})
> >
> >
> > BENEFITS
> > 1. AI-Native Developer Experience: Standardizing this metadata allows
> Java
> > to remain the premier platform for enterprise-grade, AI-assisted
> > development.
> > 2. Architectural Guardrails: Enables developers to "negative prompt"
> agents
> > (e.g., "Do not use reflection here") directly within the code.
> > 3. Standardized Tooling: Provides a uniform specification that IDEs and
> > agents can reflectively query across all Java libraries.
> >
> > VERIFICATION OF CONCEPT
> > I have empirically tested this approach using a prototype framework. The
> > presence of structured metadata like caveats and examples reduced agent
> > implementation errors significantly, ensuring the agent followed complex
> > patterns (like Post-Redirect-Get) without human intervention.
> > I am seeking feedback on the feasibility of this proposal and would
> welcome
> > a sponsor to help navigate the JEP process.
> >
> > Best regards,
>
