This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 6e5b4784e875 Improve AI agent guidelines: investigation, review, and
doc conventions
6e5b4784e875 is described below
commit 6e5b4784e875ff328356f87044411062dd998e1e
Author: Guillaume Nodet <[email protected]>
AuthorDate: Fri Mar 27 08:59:34 2026 +0100
Improve AI agent guidelines: investigation, review, and doc conventions
- Add "Issue Investigation" section requiring agents to validate JIRA
issues,
check git history/blame, search related tickets, look for design docs in
proposals/, and understand module replacement context before implementing
- Add "Knowledge Cutoff Awareness" rule: verify external project versions
via
web search rather than relying on potentially stale training data
- Add "Git History Review" section for PR reviews: check git log/blame on
modified files, verify fixes don't revert prior intentional behavior,
check
for related design proposals
- Add "Documentation Conventions": use xref: for internal links (not
external
URLs), verify cross-version xref fragment anchors resolve against released
versions
- Add "PR Description Maintenance" rule: update PR description/title after
each push to reflect current changeset
- Add "PR Reviewers" section: identify relevant committers via git log/blame
on affected files and request reviews from at least 2 committers
---
AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 85 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 44fa8026ad56..2930b447503c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,6 +43,25 @@ These rules apply to ALL AI agents working on this codebase.
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](https://camel.apache.org/community/team/#committers)
+ 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, API), include committers with broader
project knowledge.
+- Request review from **at least 2 relevant committers** using `gh pr edit
--add-reviewer`.
+
### Merge Requirements
- An agent MUST NOT merge a PR if there are any **unresolved review
conversations**.
@@ -56,6 +75,72 @@ These rules apply to ALL AI agents working on this codebase.
- All code must pass formatting checks (`mvn formatter:format impsort:sort`)
before pushing.
- All generated files must be regenerated and committed (CI checks for
uncommitted changes).
+### 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. **Look for design documents**: Check the `proposals/` directory for design
docs (`.adoc` files)
+ that may explain architectural decisions in the affected area.
+5. **Understand the broader context**: If the issue involves a module that
replaced or deprecated
+ another (e.g., `camel-opentelemetry2` replacing `camel-opentelemetry`),
understand *why* the
+ replacement was made and what was intentionally changed vs. accidentally
omitted.
+6. **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.
+- Check for design proposals (`proposals/*.adoc`) related to the affected area.
+- Search for related JIRA tickets that provide context on why the code was
written that way.
+
+### Documentation Conventions
+
+When writing or modifying `.adoc` documentation:
+
+- **Use `xref:` for internal links**, never external
`https://camel.apache.org/...` URLs.
+ Example: `xref:manual::camel-jbang.adoc[Camel JBang]` instead of
+ `https://camel.apache.org/manual/camel-jbang.html[Camel JBang]`.
+- **Cross-version xref fragments**: When linking to a section anchor (e.g.,
`#_my_section`) using
+ the `components::` prefix, verify that the target section exists in the
**current released version**,
+ not just on `main`. The `components::` prefix resolves to the latest
released version, so anchors
+ that only exist on `main` will produce broken links. Either omit the
fragment or use a
+ version-aware reference.
+- **When reviewing doc PRs**, check that all `xref:` links and anchors resolve
correctly, especially
+ cross-component references that may span versions.
+
## Structure
```
