Skip to content

AGENTS.md

Latest commit

 

History

History
294 lines (218 loc) · 13.2 KB

AGENTS.md

File metadata and controls

294 lines (218 loc) · 13.2 KB

Apache Camel Spring Boot - AI Agent Guidelines

Guidelines for AI agents working on this codebase.

Project Info

Apache Camel Spring Boot provides Spring Boot auto-configuration and starter modules for Apache Camel components.

AI Agent Rules of Engagement

These rules apply to ALL AI agents working on this codebase.

Attribution

  • All AI-generated content (GitHub PR descriptions, review comments, JIRA comments) MUST clearly identify itself as AI-generated and mention the human operator. Example: "Claude Code on behalf of [Human Name]"

PR Volume

  • An agent MUST NOT open more than 10 PRs per day per operator to ensure human reviewers can keep up.
  • Prioritize quality over quantity — fewer well-tested PRs are better than many shallow ones.

Git branch

  • An agent MUST NEVER push commits to a branch it did not create.
  • If a contributor's PR needs changes, the agent may suggest changes via review comments, but must not push to their branch without explicit permission.
  • An agent should prefer to use his own fork to push branches instead of the main apache/camel-spring-boot repository. It avoids filling the main repository with a long list of uncleaned branches.
  • An agent must provide a useful name for the git branch. It should contain the global topic and issue number if possible.
  • After a Pull Request is merged or rejected, the branch should be deleted.

JIRA Ticket Ownership

  • An agent MUST ONLY pick up Unassigned JIRA tickets.
  • If a ticket is already assigned to a human, the agent must not reassign it or work on it.
  • Before starting work, the agent must assign the ticket to its operator and transition it to "In Progress".
  • Before closing a ticket, always set the correct fixVersions field. Note: fixVersions cannot be set on an already-closed issue — set it before closing, or reopen/set/close if needed.

PR Description Maintenance

When pushing new commits to a PR, always update the PR description (and title if needed) to reflect the current state of the changeset. PRs evolve across commits — the description must stay accurate and complete. Use gh pr edit --title "..." --body "..." after each push.

PR Reviewers

When creating a PR, always identify and request reviews from the most relevant committers:

  • Run git log --format='%an' --since='1 year' -- <affected-files> | sort | uniq -c | sort -rn | head -10 to find who has been most active on the affected files.
  • Use git blame on key modified files to identify who wrote the code being changed.
  • Cross-reference with the committer list to ensure you request reviews from active committers (not just contributors).
  • For component-specific changes, prefer reviewers who have recently worked on that component.
  • For cross-cutting changes (core, auto-configuration), include committers with broader project knowledge.
  • Request review from at least 2 relevant committers using gh pr edit --add-reviewer.
  • When all comments on the Pull Request are addressed (by providing a fix or providing more explanation) and the PR checks are green, re-request review on existing reviewers so that they are aware that the new changeset is ready to be reviewed.

Merge Requirements

  • An agent MUST NOT merge a PR if there are any unresolved review conversations.
  • An agent MUST NOT merge a PR without at least one human approval.
  • An agent MUST NOT approve its own PRs — human review is always required.

Code Quality

  • Every PR must include tests for new functionality or bug fixes.
  • Every PR must include documentation updates where applicable.
  • All generated files must be regenerated and committed (CI checks for uncommitted changes).

Asynchronous Testing: Use Awaitility Instead of Thread.sleep

Do NOT use Thread.sleep() in test code. It leads to flaky, slow, and non-deterministic tests. Use the Awaitility library instead, which is already available as a test dependency in the project.

Example — waiting for a route to be registered:

import static org.awaitility.Awaitility.await;

await().atMost(20, TimeUnit.SECONDS)
       .untilAsserted(() -> assertEquals(1, context.getRoutes().size()));

Rules:

  • New test code MUST NOT introduce Thread.sleep() calls.
  • When modifying existing test code that contains Thread.sleep(), migrate it to Awaitility.
  • Always set an explicit atMost timeout to avoid hanging builds.
  • Use untilAsserted or until with a clear predicate — do not replace a sleep with a busy-wait loop.

Issue Investigation (Before Implementation)

Before implementing a fix for a JIRA issue, thoroughly investigate the issue's validity and context. Camel is a large, long-lived project — code often looks "wrong" but exists for good reasons. Do NOT jump straight to implementation after reading the issue description and the current code.

Required investigation steps:

  1. Validate the issue: Confirm the reported problem is real and reproducible. Question assumptions in the issue description — they may be incomplete or based on misunderstanding.
  2. Check git history: Run git log --oneline <file> and git blame <file> on the affected code. Read the commit messages and linked JIRA tickets for prior changes to understand why the code is written the way it is.
  3. Search for related issues: Search JIRA for related tickets (same component, similar keywords) to find prior discussions, rejected approaches, or intentional design decisions.
  4. Understand the broader context: If the issue involves a module that replaced or deprecated another, understand why the replacement was made and what was intentionally changed vs. accidentally omitted. Check the apache/camel repository for design documents in proposals/ if the affected area touches core Camel behaviour.
  5. Check if the "fix" reverts prior work: If your proposed change effectively reverts a prior intentional commit, stop and reconsider. If the revert is still justified, explicitly acknowledge it in the PR description and explain why despite the original rationale.

Present your findings to the operator before implementing. Flag any risks, ambiguities, or cases where the issue may be invalid or the proposed approach may conflict with prior decisions.

Knowledge Cutoff Awareness

AI agents have a training data cutoff and may not know about recent releases, API changes, or deprecations in external projects. Never make authoritative claims about external project state based solely on training knowledge.

  • When a JIRA issue, PR, or code references a specific version of an external dependency (e.g., Spring Boot 4.0, JUnit 6, Jakarta EE 11), verify it exists by checking official sources (web search, Maven Central, release notes) before questioning or relying on it.
  • When implementing or reviewing changes that depend on external project behavior, verify the current state rather than assuming training data is up to date.
  • If uncertain about whether something exists or has changed, say so and verify — do not confidently assert something is wrong based on potentially stale knowledge.

Git History Review (When Reviewing PRs)

When reviewing PRs, apply the same investigative rigor:

  • Check git log and git blame on modified files to see if the change conflicts with prior intentional decisions.
  • Verify that "fixes" don't revert deliberate behavior without justification.
  • Search for related JIRA tickets that provide context on why the code was written that way.

Security Model

This project shares the same security model as Apache Camel core. The canonical security model document is maintained in the apache/camel repository at docs/user-manual/modules/ROOT/pages/security-model.adoc.

camel-spring-boot is an auto-configuration layer — it wraps Camel components with @ConfigurationProperties and Spring Boot lifecycle integration but does not define its own trust boundaries, consumers, producers, header filtering, or deserialization paths. The Camel core security model's trust assumptions, in-scope vulnerability classes, and out-of-scope categories apply directly.

When triaging security reports or reviewing security-sensitive PRs in this repository, refer to the Camel core security model for:

  • Trust assumptions: Route authors and deployment operators are fully trusted; external message senders are untrusted.
  • In-scope classes: Unsafe deserialization, XXE, expression injection, path traversal, SSRF, header/bean-dispatch abuse, auth bypass, information disclosure, insecure defaults, query injection.
  • Out-of-scope: Route-author code, explicit opt-ins, DoS via unthrottled routes, deployer misconfiguration of management surfaces, unreachable transitive CVEs, scanner reports without PoC.

For reporting vulnerabilities, see SECURITY.md.

Structure

camel-spring-boot/
├── core/                # Core auto-configuration (CamelAutoConfiguration, actuator, vault)
│   ├── camel-spring-boot/     # Main auto-configuration module
│   └── camel-spring-boot-xml/ # XML (JAXB) route loading variant
├── components-starter/  # ~425 generated starter modules, one per Camel component
├── core-starter/        # Starters for core Camel modules
├── dsl-starter/         # Starters for Camel DSL modules (YAML, Groovy, Kotlin, etc.)
├── tooling/             # Maven plugins for code generation (starters, BOMs, catalog)
├── catalog/             # Spring Boot runtime provider for Camel catalog
├── tests/               # Integration tests and fat-jar tests
└── archetypes/          # Maven archetype for new Camel Spring Boot projects

Build

# Build a specific starter (preferred — always build in the module directory)
cd components-starter/camel-aws2-s3-starter && mvn verify

# Build core module
cd core/camel-spring-boot && mvn verify

# Fast install (skip tests)
mvn install -Dfastinstall

# Run a single test
cd components-starter/camel-aws2-s3-starter && mvn verify -Dtest=S3ComponentTest

# Format/install without tests
cd <module> && mvn -DskipTests install

Do NOT parallelize Maven jobs — builds are resource-intensive.

Code Generation

Most code in components-starter/ is generated by the Maven plugins in tooling/. For each Camel component, the generator produces:

  • *ComponentAutoConfiguration.java — Spring Boot @AutoConfiguration that registers the component bean
  • *ComponentConfiguration.java — @ConfigurationProperties class exposing component options as camel.component.<name>.*
  • *ComponentConverter.java — Type converter for complex property types
  • META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports — Registers auto-configuration classes

Generated code blocks are delimited by <!--START OF GENERATED CODE--> / <!--END OF GENERATED CODE--> in POM files. Do not manually edit generated sections.

Auto-Configuration Pattern

Each starter's auto-configuration class follows a consistent pattern:

  1. @AutoConfiguration(after = CamelAutoConfiguration.class) — ensures CamelContext is available
  2. @ConditionalOnHierarchicalProperties — enables/disables via camel.component.<name>.enabled
  3. ComponentCustomizer bean copies Spring Boot properties onto the Camel component

The core CamelAutoConfiguration in core/camel-spring-boot is the central configuration that all starters depend on.

Creating/Deleting Starters

./starter-create <component-name>    # Create a new starter
./starter-delete <component-name>    # Delete a starter

These invoke the camel-spring-boot-generator-maven-plugin under tooling/.

Relationship with Camel Core

This project depends on apache/camel for component implementations. The camel-version property must match the target Camel release. When Camel core adds/removes/changes a component, the starters here must be regenerated.

Conventions

Code style:

  • Do NOT use Records or Lombok (unless already present in the file)
  • Do NOT change public API signatures without justification
  • Do NOT add new dependencies without justification
  • Maintain backwards compatibility for public APIs

Import style:

  • Do NOT use fully qualified class names (FQCNs) in Java code. Always add an import statement and use the simple class name.
  • Exception: when two classes share the same simple name, import the most-used one and qualify the other.

Tests: *Test.java (JUnit 5)

Commits

CAMEL-XXXX: Brief description

Reference JIRA when applicable.

Links