Improve AI development guidance

[wborn]

Description

This PR improves and expands the repository guidance for AI coding agents.

The existing AGENTS.md has been reworked to provide clearer, more actionable instructions while avoiding duplication of information that is already maintained in the repository documentation. It now focuses more strongly on openHAB-specific development practices and on preventing issues that are commonly caught during code review.

The guidance is based on:

• existing openHAB contribution, development, coding, and review documentation;
• established patterns and conventions in the openHAB codebase;
• recurring issues identified while reviewing openHAB pull requests, particularly around lifecycle handling, concurrency, external APIs and protocols, compatibility, configuration, testing, comments, and unnecessary abstractions;
• lessons from well-maintained AGENTS.md files in other projects, while keeping the instructions specific to openHAB.

Notable improvements include guidance for:

• determining the intended behavior before implementing a change and keeping changes narrowly scoped;
• reusing existing openHAB APIs and avoiding unnecessary abstractions or dependencies;
• verifying assumptions about external APIs, protocols, libraries, and file formats against authoritative sources;
• lifecycle, concurrency, asynchronous work, reconnection, cleanup, and runtime configuration changes;
• OSGi Declarative Services and HTTP Whiteboard usage;
• external data validation, protocol compatibility, caching, and error handling;
• security and handling of sensitive data;
• useful source-code comments and accurate documentation;
• Maven dependency changes, including features.xml and *.bndrun implications;
• generated files, formatting, Markdown linting, and commit conventions;
• deterministic tests, integration tests, static analysis, and appropriate build validation;
• Thing, Channel, and configuration metadata;
• creating new bindings and preparing pull requests.

The document also points agents to the relevant README.md, CONTRIBUTING.md, openHAB developer documentation, coding guidelines, and review checklist instead of duplicating those sources.

Small CLAUDE.md and GEMINI.md compatibility files are added so Claude Code and Gemini Code Assist follow the same AGENTS.md guidance rather than maintaining separate copies of the instructions.

There are no runtime or add-on behavior changes in this PR.

[Copilot]

Pull request overview

Expands repository-wide guidance for AI coding agents without changing runtime behavior.

Changes:

• Reworks AGENTS.md with detailed development and review practices.
• Adds Claude Code and Gemini Code Assist compatibility files.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
AGENTS.md	Defines comprehensive repository guidance.
CLAUDE.md	Imports the shared agent guidance.
GEMINI.md	Directs Gemini to shared and scoped guidance.

Suppressed comments (3)

AGENTS.md:209

• This bare URL violates the enabled MD034 Markdown lint rule. Use an autolink so this changed file passes the configuration referenced at line 182.

- Reference documentation: https://bnd.bndtools.org/chapters/825-instructions-ref.html

AGENTS.md:227

• This bare URL violates the enabled MD034 Markdown lint rule. Use an autolink so this changed file passes the configuration referenced at line 182.

- Reference documentation: https://www.openhab.org/docs/developer/utils/i18n.html#managing-translations

AGENTS.md:296

• This bare URL violates the enabled MD034 Markdown lint rule. Use an autolink so this changed file passes the configuration referenced at line 182.

- Read the binding development guide before creating a new binding: https://www.openhab.org/docs/developer/#develop-a-new-binding

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

AGENTS.md:299

• The skeleton scripts resolve archetype-settings.xml and ../src/etc/NOTICE relative to the current working directory, so invoking them from the repository root fails. Specify that they must be run from bundles/ to make this instruction reliably actionable.

- Use the provided `create_openhab_binding_skeleton` script rather than creating the binding structure manually.

[lsiepel]

Thanks for taking the time to adjust this.
Let's see how this improves the reviews and contributions. A first test seemed to improve the results. 👍

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[wborn]

Yes it would be nice to see how quickly the AIs pick up on this!
Retriggering Copilot on a few PRs might already show if it has learned some new tricks. 😉

[wborn]

These improvements helped with guiding my AI:
#21357 (review)