luigidemasi opened a new issue, #106: URL: https://github.com/apache/camel-kit/issues/106
> Imported from [luigidemasi/camel-kit#246](https://github.com/luigidemasi/camel-kit/issues/246), opened by [Croway](https://github.com/Croway) on 2026-10-10. > Closed by commit [d6f3426](https://github.com/luigidemasi/camel-kit/commit/d6f3426ef6493a48062ad77f3c78bebe65d4ebfa). --- ## Problem The generated `AGENTS.md` (`camel-kit-core/src/main/resources/templates/shared/agents-md.md`, unchanged on `main` since 0.4.1) contains routing lines, five Laws and the CLI prefix. The only Camel-specific guidance is Law 1, "Verify ALL components/EIPs/dataformats via MCP before use". The concrete rules that would prevent the most common defects are in skill guides (for example `camel-implement/guides/yaml-structure.md`, `properties-generation.md`), and agents mostly do not load those guides. In an evaluation of coding agents (Claude Code with Haiku/Sonnet 5.5, and IBM Bob) on legacy-to-Camel migration tasks with camel-kit 0.4.1 and camel-jbang-mcp 4.22.1: - `AGENTS.md` was read in 29 of 31 camel-kit Claude sessions that were examined in detail (always through an explicit file read). No Claude session invoked a pipeline skill on its own. The measured gain of the camel-kit setup over plain Claude Code comes from `AGENTS.md` and the MCP configuration, not from the skills. - The defects that remained were the same few Camel 4.22 rules, again and again. 55 of 250 Claude sessions produced YAML that the YAML DSL schema rejects. ## Proposal Add a short "Camel 4.22 rules" block (about 15 one-line rules) to `templates/shared/agents-md.md`, and to the per-target `agents-md.md` templates for antigravity, codex, copilot and pi. Each line below is followed by the eval evidence for it. - [ ] `onException`, `onCompletion`, `intercept*` and `routeConfiguration` are top-level items, never `steps` entries. For route-scoped handling, use a `routeConfiguration` with an id and set `routeConfigurationId` on the route. `errorHandler` goes at the top level or as a route property. *(This was the most common schema failure among the 55: `property 'onException' is not defined in the schema` at `/0/route/from/steps/0`.)* - [ ] Write `handled`, `continued` and the `constant` values as expressions or strings. Write `redeliveryDelay`, `maximumRedeliveries` and `delay` as strings, not YAML ints or booleans. *(About 20 of the 55.)* - [ ] Do not copy `camel validate normalize` output back over the route: in 4.22.1 it moves a top-level `onException` into the route steps (CAMEL-25490). *(23 of the 55 came from copying the normaliser's output back.)* - [ ] Run `camel_validate_yaml_dsl` (or `camel validate yaml`) on the final file, after the last edit. *(Every session that validated its final file passed the schema check. None of the sessions that skipped it was protected.)* - [ ] Passing the schema check does not mean the route runs. Run the app with `camel run`, read the log, and exercise the endpoints, mail and broker before you declare the work done. *(Examples that passed the validator: a `doCatch` placed as a sibling of `doTry`, an `onException` naming a class that does not exist, and a mail flow that was never checked.)* - [ ] mail: since 4.21, `useHeaderSubject`, `useHeaderFrom` and `useHeaderRecipients` default to false, so `Subject`/`From`/`To` headers are ignored. Set the option or put the value on the endpoint. *(This caused every lost email subject: 3 Claude and 10 Bob sessions, plus 3 sessions that lost half their cases to the wrong To/From. The catalog description still says "Defaults to true".)* - [ ] Before every outbound http or mail producer, run `removeHeaders` (at least `CamelHttp*`, or `*` before mail). `bridgeEndpoint=true` does not stop the producer from appending `CamelHttpPath`. *(4 sessions got HTTP 404 from the inbound path appended to the outbound URL. In 8 sessions the HTTP query API key leaked into the e-mail headers.)* - [ ] With `camel run`, platform-http needs both `camel.server.enabled=true` and `camel.server.port`. Without the first property the port is ignored and the server binds to 8080. *(This made 5 of 10 Bob sessions on a SOAP/HTTP task fail at startup, each after 15 to 47 calls spent hunting for the port. Sessions that set both properties had no problem.)* - [ ] For third-party jars needed by YAML `beans:`, add a `//DEPS group:artifact:version` line in a route file or use `--dep`. `camel.jbang.dependencies` in a properties file passed on the command line is silently ignored (CAMEL-25528). *(Seen in every session of the two hardest tasks: `ClassNotFoundException` loops, up to 27 in one session.)* - [ ] xpath namespaces in YAML: `namespace: [{key: p, value: "uri"}]`. The YAML DSL can declare namespaces. *(13 of 13 Sonnet sessions on a Fuse task replaced namespaces with `local-name()` and claimed YAML cannot declare them. 10 Haiku/Bob sessions wrote `prefix`/`uri` and were rejected.)* - [ ] Use `optionsFilter` on catalog component calls. An empty filter result means no option name matched, not that the feature is unsupported (TLS for mail is `mail.smtp.*` via `additionalJavaMailProperties`). *(Filtered calls returned 0.4–3 K and were the ones whose content ended up in the routes. Unfiltered calls returned 20–40 K. 11 sessions read an empty `tls` filter as "not supported".)* - [ ] For the YAML shape of a construct, look at `camel_catalog_examples` / `camel_catalog_example_file` before writing it. *(Bob's first validation failed on route-level shape in every session of one task. The one session that started from a bundled example converged fastest.)* - [ ] EIP doc names are camelCase model names (`wireTap-eip`, `recipientList-eip`, `onException-eip`). *(Kebab-case guesses returned "not found" and agents gave up on the page.)* - [ ] Retries: put `redeliveryPolicy` on an `onException` for the specific exception, not a route-wide `defaultErrorHandler`, which also retries 4xx/5xx. *(One of the causes of the 9 of 12 Bob sessions on a JMS/HTTP task that lost cases to endless or excess retries.)* - [ ] activemq manual ack: `transacted=true`, or `acknowledgementModeName=CLIENT_ACKNOWLEDGE` together with transacted handling. *(3 sessions set `CLIENT_ACKNOWLEDGE` without `transacted`. One session spent 22 minutes tuning redelivery by trial and error.)* ## Notes - `yaml-structure.md` has a related problem. Its scope table says route-scoped error handling is "`onException:` inside the route", but `RouteDefinition` in the 4.22.1 YAML DSL schema has no `onException` property, so the only valid route-scoped form is `routeConfiguration` + `routeConfigurationId`. The guide should say so. - For Claude Code, the block only reaches the model automatically if `CLAUDE.md` imports `AGENTS.md` (`@AGENTS.md`). Today the generated `CLAUDE.md` only says "See `AGENTS.md`", which keeps `AGENTS.md` out of the automatic context, so agents read it only if they decide to. - The rules that point at a Camel bug (CAMEL-25490 normaliser, CAMEL-25528 dependencies) can be dropped once camel-kit targets a Camel version with the fix. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
