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,
