agentleFS
quarkiversequarkiverse/quarkus-langchain4j/.agents/skills/working-with-config/SKILL.md

working-with-config

Skill325 starsChanged 7 days agoApache-2.0View on GitHub

Quarkus configuration conventions: @ConfigMapping interfaces, config phases, and migration from legacy @ConfigRoot classes.

1 other project uses a version of this; 1 new project in the last 4 weeks, against 0 the 4 before.

Adopted by

Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 1 new project
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 1 in all, so this is a hint, not a trend.

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. quarkusio/quarkus★ 16k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

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

    Never use Optional and provide a default via .orElse(...) in application code.

    line 34
  2. Distinctive:

    Use this when mapping a sub-tree of configuration that does not represent an extension's top-level config root.

    line 52
  3. Very specific:

    Use for settings that affect code generation.

    line 83
  4. Distinctive:

    Before you add a key, read the keys next to it and use the same form.

    line 97
  5. Very specific:

    Use a -mode suffix only when the key copies a term of an external system, such as the OIDC response_mode.

    line 101
  6. Distinctive:

    When the key maps to a term of a tool that users know, such as Docker or Hibernate ORM, use that term and that default value.

    line 103
  7. Very specific:

    Always specify phase explicitly on @ConfigRoot — the default is BUILD_TIME, which is not injectable via CDI at runtime

    line 143
  8. Very specific:

    Use RUN_TIME phase unless the config genuinely affects build-time behavior

    line 146
  9. Very specific:

    Do NOT access RUN_TIME config during build steps — it is not available yet

    line 147
  10. Distinctive:

    When the code cannot apply a configured value, fail at startup with a message that names the property, or log one warning.

    line 149
  11. Very specific:

    When adding new quarkus.* properties, always register them in a @ConfigMapping interface.

    line 153

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
SKILL.md

Working with Configuration

Use @ConfigMapping Interfaces (Not Legacy Classes)

Quarkus configuration must use @ConfigMapping interfaces. The legacy @ConfigRoot-annotated classes with @ConfigItem have been fully removed (see adr/0008-phasing-out-config-classes.adoc).

Correct (current approach)

@ConfigMapping(prefix = "quarkus.my-extension")
@ConfigRoot(phase = ConfigPhase.RUN_TIME)
public interface MyExtensionRuntimeConfig {

    /** Description of the property. */
    @WithDefault("default-value")
    String myProperty();

    /** Optional property (absent means not set by the user). */
    Optional<String> optionalProperty();
}

Do NOT Use Optional to Define Default Values

Never use Optional and provide a default via .orElse(...) in application code. The default must be declared in the config mapping itself via @WithDefault:

// BAD — do not do this
String name = config.optName().orElse("theDefaultName");

// GOOD — declare the default in the config mapping
@WithDefault("theDefaultName")
String name();

Non-root @ConfigMapping (without @ConfigRoot)

@ConfigMapping can also be used without @ConfigRoot for non-root mappings. These are not auto-discovered — you must register them explicitly (e.g., via @Inject in a CDI bean or programmatically with SmallRye Config). Use this when mapping a sub-tree of configuration that does not represent an extension's top-level config root.

@ConfigMapping(prefix = "some.custom.prefix")
public interface MyCustomConfig {

    /** A non-root config property. */
    String someValue();
}

Wrong (legacy approach, do not use)

// DO NOT use this pattern
@ConfigRoot(name = "my-extension", phase = ConfigPhase.RUN_TIME)
public class MyExtensionConfig {
    @ConfigItem(defaultValue = "default-value")
    String myProperty;
}

Config Phases

@ConfigRoot defaults to BUILD_TIME when no phase is specified. Always set the phase explicitly — omitting it for a config injected at runtime will cause UnsatisfiedResolutionException because BUILD_TIME configs are not registered as CDI beans.

  • BUILD_TIME — Baked into the binary at build time, immutable at runtime. Use for settings that affect code generation. Only available in @BuildStep methods — not injectable via @Inject in runtime CDI beans.
  • BUILD_AND_RUN_TIME_FIXED — Read at build time, also available at runtime. Cannot change without rebuilding. Available in both @BuildStep methods and runtime CDI beans.
  • RUN_TIME — Read at application startup. Can change between runs. Available in runtime CDI beans via @Inject. Not available in @BuildStep methods.

Naming

  • Config interfaces: <Feature>Config.java, or split as <Feature>BuildTimeConfig.java / <Feature>RuntimeConfig.java
  • Config prefix: quarkus.<extension-name>
  • Before you add a key, read the keys next to it and use the same form.
  • Name the thing that the key configures, in full words: index-directories, not dir-mode. An enum value carries the action: quarkus.http.insecure-requests=enabled|redirect|disabled.
  • Use a -mode suffix only when the key copies a term of an external system, such as the OIDC response_mode.
  • When the key maps to a term of a tool that users know, such as Docker or Hibernate ORM, use that term and that default value.
  • The method name gives the key: indexDirectories() becomes index-directories. A rename changes the method, the docs and the tests.

Annotation Processor (quarkus-extension-processor)

The quarkus-extension-processor annotation processor is required for all extension modules, not just those with @ConfigRoot. It generates metadata files (including META-INF/quarkus-config-roots.list for config discovery) that Quarkus needs to wire extensions correctly. Without it, most extension functionality will silently fail.

Both runtime/ and deployment/ POMs must include:

<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <executions>
        <execution>
            <id>default-compile</id>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.quarkus</groupId>
                        <artifactId>quarkus-extension-processor</artifactId>
                        <version>${project.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </execution>
    </executions>
</plugin>

Most modules already have this. If you create a new module or notice missing metadata, verify the annotation processor is present in its pom.xml.

Key Rules

  • Always specify phase explicitly on @ConfigRoot — the default is BUILD_TIME, which is not injectable via CDI at runtime
  • Configuration is immutable — never mutate config objects
  • Use RUN_TIME phase unless the config genuinely affects build-time behavior
  • Do NOT access RUN_TIME config during build steps — it is not available yet
  • BUILD_TIME config changes require a rebuild
  • When the code cannot apply a configured value, fail at startup with a message that names the property, or log one warning. Never ignore the value without a message. Examples: a TLS option that the client does not support, a runtime value that a reload does not apply.
  • When adding new quarkus.* properties, always register them in a @ConfigMapping interface. Reading them programmatically via Config.get().getOptionalValue(...) is fine, but the corresponding key must still be defined in a @ConfigMapping — otherwise SmallRye Config will emit "unknown property" warnings at startup.

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.