docs: add AGENTS.md for AI-assisted contributions#1276
docs: add AGENTS.md for AI-assisted contributions#1276turanalmammadov wants to merge 1 commit intoopen-policy-agent:masterfrom
Conversation
Add AGENTS.md as requested in open-policy-agent#1234 to guide AI coding agents (Cursor, Copilot, Claude, etc.) when working in this repository. The file covers: - Project overview and links to OPA/Rego docs - Repository layout with brief description of each directory - Development environment setup (Go, Make, Bats, golangci-lint, Nix) - Build & test workflow commands - How to write unit tests and Bats acceptance tests - Code conventions - PR submission checklist Closes open-policy-agent#1234 Co-authored-by: Cursor <cursoragent@cursor.com>
| - New parsers implement the `parser.Parser` interface in `parser/` | ||
| - New output formatters implement the `output.Outputter` interface in `output/` | ||
|
|
||
| ## Submitting a PR |
There was a problem hiding this comment.
Agents should not be submitting PRs.
There was a problem hiding this comment.
but it can co-author PRs, right? That's the usual workflow with claude / cursor type of tools
If we don't agree with these, let's explicitly mention
There was a problem hiding this comment.
Personally, I expect all PRs are submitted by humans, after the human has reviewed the code and ensured tests are passing locally.
I do not have an issue with using AI tools, but I am wary of the burden that PRs being sent without care can introduce to the project.
|
|
||
| ### Prerequisites | ||
|
|
||
| - **Go** ≥ 1.22 – <https://go.dev/doc/install> |
There was a problem hiding this comment.
Please can you verify the LLM output, this version is wrong.
There was a problem hiding this comment.
It might be nice to give a ref to go.mod, where we are trying to consolidate the version across all resources like ci / nix dev env etc
| @@ -0,0 +1,124 @@ | |||
| # AGENTS.md | |||
|
|
|||
| This file guides AI coding agents (e.g. Cursor, Copilot, Claude) on how to | |||
There was a problem hiding this comment.
Claude (famously) does not read agents.md. Please see https://github.com/open-policy-agent/opa/blob/main/.claude/settings.json but we have not seen great results with this approach either.
There was a problem hiding this comment.
I am in favor of forgoing AGENTS.md. The instruction provided to the agent should include enough information for the agent to do the right thing. It should adapt to the code style, tests, etc. of the repo as a human would.
4 participants
Closes #1234
Summary
Adds
AGENTS.mdas requested in the linked issue. This file guides AIcoding agents (Cursor, GitHub Copilot, Claude, etc.) when contributing to
this repository.
What's included
go test ./...,bats acceptance.bats,make ciexamples/directory@testblockMade with Cursor