From bde335e2a8d82fb5bfce6952417aedb0d7d482b9 Mon Sep 17 00:00:00 2001 From: Guillaume Nodet Date: Wed, 25 Mar 2026 12:57:00 +0100 Subject: [PATCH 1/4] Improve AI agent guidelines: git history review and doc conventions - Add "Issue Investigation" section requiring agents to check git history, related JIRA tickets, and design docs before implementing fixes - Add "Git History Review" section for PR reviews with same rigor - Add "Documentation Conventions" for adoc files: use xref instead of external URLs, and verify cross-version fragment anchors Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ddd45ed05473d..34d5ddb672670 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,58 @@ 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 ` and `git blame ` 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. + +### 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 ``` From 9b9ca3a56beca66f7dca624fe30ec7c1f79faf79 Mon Sep 17 00:00:00 2001 From: Guillaume Nodet Date: Wed, 25 Mar 2026 14:32:40 +0100 Subject: [PATCH 2/4] Add PR reviewer identification guidelines for AI agents Require agents to identify relevant committers using git log/blame on affected files and request reviews when creating PRs. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 34d5ddb672670..e58361bc52125 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,19 @@ 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 Reviewers + +When creating a PR, **always identify and request reviews** from the most relevant committers: + +- Run `git log --format='%an' --since='1 year' -- | 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**. From c993e815c55448dfe99018597b000abca87b3c07 Mon Sep 17 00:00:00 2001 From: Guillaume Nodet Date: Wed, 25 Mar 2026 14:56:13 +0100 Subject: [PATCH 3/4] Add rule to update PR description on each push Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e58361bc52125..9c5f61f896c35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,12 @@ 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: From 19ef1ca29fb41010ee0f072ed9f8ffc32114c3fe Mon Sep 17 00:00:00 2001 From: Guillaume Nodet Date: Wed, 25 Mar 2026 15:58:22 +0100 Subject: [PATCH 4/4] Add knowledge cutoff awareness guideline for AI agents Require agents to verify external project versions and state via web search rather than relying on potentially stale training data. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 9c5f61f896c35..53e3e88f31389 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,6 +99,20 @@ jump straight to implementation after reading the issue description and the curr **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: