contributing: Add AGENTS.md with guidelines for AI agents

[wenzeslaus]

Adds instructions for AI coding agents in general (somewhat standardized AGENTS.md in the top dir) and Claude Code specific file linking it. This should improve the quality of the code and commits generated by agents/tools which have access to the repository code.

I developed that during test creation (for pytest), so probably more is needed for Python and C tools, GUI, grass.gunittest tests. I then tried to optimize what is in the new file versus what is already elsewhere to minimize duplication (maybe we eventually want to cover some of these items in the other documetation). It now references a lot of existing files which likely increases the computational cost.

Details

Original description:

Adds instructions for Claude Code on building for generating code for this repository. I developed that during test creation (for pytest), so probably more is needed for Python and C tools, GUI, grass.gunittest tests. The content is generated by Claude with me iterating with the content on the side as I was making the actual changes to the test, so it contains more than the generic instructions Claude was able to get from the repo itself. Claude actually followed the instructions and improved the result.

There is duplication with the doc and the contributing file. The aim is at AI not humans, so it does not need much intro, can be technical and overwhelming, so it is a different type of document. At this point. I'm more concerned about adding a file like this for every AI out there. I know @cwhite911 is preparing one for GitHub Copilot.

The file lives in .claude/CLAUDE.md (top dir is an alternative and also it can be broken down if it becomes too large). While having one (or no?) AI file would be preferable, I like it more than the top level file.

Love it? Hate it? Tell me.

Commit message:

Adds instructions for AI coding agents in general (somewhat standardized AGENTS.md in the top dir) and Claude Code specific file linking it. This should improve the quality of the code and commits generated by agents/tools which have access to the repository code.

I developed that during test creation (for pytest) and during the work on the file itself, so probably more is needed for Python and C tools, GUI, grass.gunittest tests. I then tried to optimize what is in the new file versus what is already elsewhere to minimize duplication (maybe we eventually want to cover some of these items in the other documentation). It now references a lot of existing files which likely increases the computational cost.

Comments on use of AI and references CONTRIBUTING.md AI use policy.

For (local) linting, only pre-commit is used. Also pytest run of all test is left for the CI.

[echoix]

Isn't there a standard now, something like AGENTS.md?

[wenzeslaus]

Well, it seems there is AGENTS.md which needs to be at top level and I did not test that file with Claude. I had to leave my computer before I answered that question.

[wenzeslaus]

Hm, it seems you need both to get it working, from Claude Code doc:

Document requirements: Clearly specify dependencies and commands in your CLAUDE.md file. If you have an AGENTS.md file, you can source it in your CLAUDE.md using @AGENTS.md to maintain a single source of truth.

This seems to partially validate my original impression that a Claude-specific file is need, but at least this solution would have the single source of truth part.

[wenzeslaus]

I shifted towards more general file and less duplication. Description updated accordingly.

[wenzeslaus]

I made comments which I made as pending review by mistake. Here they are.

[echoix]

I hadn't published some comments

[cwhite911]

I know @cwhite911 is preparing one for GitHub Copilot.

I've not gotten a chance to look at this yet to check for potential overlap between the clauda and copilot configuration. The copilot instructions live in .github/instructions/*.md and you can also include a .github/copilot-instructions.md. I'll put what I have in a draft PR just so you can more easily reference it.

Another thought I have is how to best sync these between OSGeo/grass and OSGeo/grass-addons?

[wenzeslaus]

@cwhite911 From what I found, there should be a separate file, and it should just reference AGENTS.md. It can then include additional info if there is something specific, let's say env setup or how commands should be offered in agent's user interface (just making it up examples here).

For addons repo, I think it should reference the main one. There will be the cost of retrieving an URL, but our cost of syncing and getting out of sync is also real and scales poorly. There, I see that we want to add some additional instructions. The code structure is different, handling of libraries...