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,
