[GRASS-git] [OSGeo/grass] 9a634e: contributing: Add AGENTS.md with guidelines for AI...

Tue Jul 14 00:31:09 PDT 2026

  Branch: refs/heads/releasebranch_8_5
  Home:   https://github.com/OSGeo/grass
  Commit: 9a634e77ea7061241629c7f99f6d5b6a9b7330c2
      https://github.com/OSGeo/grass/commit/9a634e77ea7061241629c7f99f6d5b6a9b7330c2
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    A .claude/CLAUDE.md
    A AGENTS.md

  Log Message:
  -----------
  contributing: Add AGENTS.md with guidelines for AI agents (#7110)

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.

  Commit: 154d3b314e8b1cd8bbcfa815ec2eb102ccc9b843
      https://github.com/OSGeo/grass/commit/154d3b314e8b1cd8bbcfa815ec2eb102ccc9b843
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md

  Log Message:
  -----------
  contributing: Add AI agent instructions for writing tests (#7121)

This adds a series of instructions about writing tests which I collected during writing a comprehensive test for r.sim.water covering tiny data and testing theoretical conditions (not a regression test with specific numbers). It covers the different edge cases and troubles the agent (Claude Code with Opus 4.6) hit. It also provides instructions for adding reasoning behind the new tests. While some of this should be documented elsewhere (or also elsewhere), adding it here now may help creating better tests more quickly.

  Commit: b91a473fffa877275da5b4e1e3da97b0f1534a55
      https://github.com/OSGeo/grass/commit/b91a473fffa877275da5b4e1e3da97b0f1534a55
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md

  Log Message:
  -----------
  contributing: Add StringIO pattern and comment banner to AI agent instructions  (#7179)

  Commit: 959fc40dc5c1b3ce31337bcda6d5f0afa842a617
      https://github.com/OSGeo/grass/commit/959fc40dc5c1b3ce31337bcda6d5f0afa842a617
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md
    M CONTRIBUTING.md

  Log Message:
  -----------
  contributing: Add more human responsibility in AI use (#7120)

This modifies the agent and contributing instructions to back the code in the change and also pre-review the code before submitting it. While the contributing file already has instructions for taking responsibility, this add explicit ask for reviewing your own code before submitting.

For the agent instructions, this pushes the agent more to do a review by including explicit instructions. The policy section and these instructions are moved to the top to increase the chances that the agent will pick them up and consider them, and are also formulated more as instructions in imperative (rather than policy). I'm doing the move because Claude was not picking up the instructions anymore even when asked after the file became longer.

The no-AI-co-author instructions is now more connected with the acknowledge instruction hopefully providing more clarity to the intention.

The language is trying to be direct, imperative-like. The text avoids words like justify and prefers words like evaluate to battle unprompted AI inventing justifications for bad lines.

  Commit: 14a0c3db3b633ad43d808f902dd880130575b04f
      https://github.com/OSGeo/grass/commit/14a0c3db3b633ad43d808f902dd880130575b04f
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md

  Log Message:
  -----------
  contributing: Point AI agents to --md-description for Python type info (#7195)

  Commit: b641b3f38b6c88ffb6d5ede7888eac64586673fc
      https://github.com/OSGeo/grass/commit/b641b3f38b6c88ffb6d5ede7888eac64586673fc
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md

  Log Message:
  -----------
  contributing: Improve build instructions for agents (#7603)

  Commit: a28eb797078ec837f655d27db8d7815a162ace9b
      https://github.com/OSGeo/grass/commit/a28eb797078ec837f655d27db8d7815a162ace9b
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M AGENTS.md

  Log Message:
  -----------
  contributing: Add notes on sandbox and addon builds to AGENTS.md (#7609)

* contributing: Add notes on sandbox and addon builds to AGENTS.md

Using a use case of a standalone addon tool repo (specifically, r.pops.spread is published in addons, but the developed in a standalone repo), this expands instructions in AGENTS.md on how to compile and run with CMake in a sandbox (developed with Claude Code sandbox) and how to compile an addon tool. While grass-addon and cookie cutter repo instructions would be helpful as well, the addons instruction part covers the case when you use the source code of GRASS, but don't deal with the grass-addon repo.

I'm also slighltly changing how the grass.gunittest is presented, focusing on a single file, rather than a directory run. This simplifies the project-related instructions, replacing the currently confusing version.

* Wrap lines correctly

  Commit: 28f710df8f21ff19bb9557f5cc7c5ac2fc252a5f
      https://github.com/OSGeo/grass/commit/28f710df8f21ff19bb9557f5cc7c5ac2fc252a5f
  Author: Markus Neteler <neteler at gmail.com>
  Date:   2026-07-14 (Tue, 14 Jul 2026)

  Changed paths:
    M .claude/CLAUDE.md

  Log Message:
  -----------
  fix path

Compare: https://github.com/OSGeo/grass/compare/b0d1e84b79e8...28f710df8f21

To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications