agentleFS
quarkiversequarkiverse/quarkus-langchain4j/AGENTS.md

quarkus-langchain4j

AGENTS.md325 starsChanged 8 days agoApache-2.0View on GitHub

Guidance for AI agents and human contributors working on Quarkus LangChain4j. Read AI_POLICY.md first. It applies to every contribution, including the ones prepared with an agent. This repository follows the conventions of Quarkus core. Read the Quarkus core AGENTS.md and, before the matching kind of work, the skills in .agents/skills: coding-style, writing-tests, working-with-config, pull-requests and writing-build-steps. This file only adds what is specific to Quarkus LangChain4j or stricter than core. The skills are verbatim copies from Quarkus core, see UPSTREAM.md…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,219 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read AI_POLICY.md first. It applies to every contribution, including the ones prepared with an agent.

    line 5
  2. Distinctive:

    Avoid lambdas and method references everywhere: runtime code, deployment code and tests.

    line 13
  3. Very specific:

    Create DotName constants from class literals when the class is on the deployment classpath, and keep them as static final fields.

    line 19
  4. Very specific:

    When the default is owned by upstream LangChain4j, do not copy it with @WithDefault.

    line 26
  5. Distinctive:

    When you change a default of a model provider, check that proxy support, authentication and retries still work, and report anything that …

    line 27

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Guidance for AI agents and human contributors working on Quarkus LangChain4j.

Read AI_POLICY.md first. It applies to every contribution, including the ones prepared with an agent.

This repository follows the conventions of Quarkus core. Read the Quarkus core AGENTS.md and, before the matching kind of work, the skills in .agents/skills: coding-style, writing-tests, working-with-config, pull-requests and writing-build-steps. This file only adds what is specific to Quarkus LangChain4j or stricter than core.

The skills are verbatim copies from Quarkus core, see UPSTREAM.md for the commit and .agents/sync-core-skills.sh to refresh them. Do not edit them here. Their paths and commands (extensions/<name>/, integration-tests/<name>/) refer to the core layout, so map them to the modules of this repository. Where a skill and this file disagree, this file wins. Other core skills, such as manage-deprecations, are not copied: read them in core when a task needs them.

Lambdas and method references

  • Avoid lambdas and method references everywhere: runtime code, deployment code and tests. Core asks to minimize them in runtime code, here the rule is stricter.
  • In runtime modules it is a hard requirement. Use anonymous classes, loops and if statements, and avoid streams.
  • The only accepted exception is a case where every alternative is clearly worse. Explain it in the PR.

Deployment modules

  • Create DotName constants from class literals when the class is on the deployment classpath, and keep them as static final fields. Use a String only when the class is not available to the deployment module.
  • Reuse the existing DotName holders (DotNames, LangChain4jDotNames and the per-module *DotNames classes) before declaring a new constant.
  • Resolve and validate at build time whatever the build already knows, and pass the result to the recorder.

Configuration

  • Endpoints and API keys are runtime configuration.
  • When the default is owned by upstream LangChain4j, do not copy it with @WithDefault. Declare the property as Optional and document the default with @ConfigDocDefault. Core's rule against Optional defaults applies to defaults that Quarkus owns.
  • When you change a default of a model provider, check that proxy support, authentication and retries still work, and report anything that stops working as a breaking change.

Tests

  • The writing-tests skill prefers QuarkusExtensionTest. This repository still has many QuarkusUnitTest tests, so follow the style of the neighbouring tests in the module you are changing.
  • Mock the wire, not the classes. Use WireMock or a stub chat model, and Vert.x if a test needs a fake HTTP server. Avoid Mockito mocks of internal classes.
  • Assert outcomes, such as what the client actually sends or what the AI service returns. Do not assert internal state of a class.

Pull requests

  • Backports to maintenance branches are cherry-picks of the original commits, not squashes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.