Skip to content

docs: Add AGENTS.md and CLAUDE.md for AI coding agents - #1774

Draft
DiamondJoseph wants to merge 1 commit into
DiamondLightSource:mainfrom
DiamondJoseph:agents.md
Draft

DiamondJoseph wants to merge 1 commit into
DiamondLightSource:mainfrom
DiamondJoseph:agents.md

Conversation

@DiamondJoseph

Copy link
Copy Markdown
Contributor

Adds guidance for AI coding agents working in this repository. There is no linked issue.

What changed

  • AGENTS.md follows the agents.md convention, which most coding agents read. It holds what an agent cannot cheaply work out from the code:
    • the checks CI runs, as just recipes inside the devcontainer and as uv commands outside it
    • environment traps, such as a bare pytest collecting the system tests
    • the two-process architecture and the rules for calling into the subprocess
    • changes that must travel together, such as the OpenAPI schema with REST_API_VERSION
    • conventions, a glossary of DLS terms and a dated summary of open design issues
  • CLAUDE.md contains only @AGENTS.md, because Claude Code reads CLAUDE.md and this imports the same file.

Policy the file sets, for reviewers to agree or change

  • Agents must disclose their involvement with an Assisted-by: <model name> via <tool name> footer on every commit and pull request description, following the Assisted-by footer note.
  • Agents use the devcontainer when they are started inside it, and do not build or start it themselves.
  • Agents ask before changing a public contract, adding a dependency, touching authentication, or editing CI and release files.
  • Agents must consider variance when using generics and add tests that pin it.

Things to know

  • The file states one current behaviour that reviewers may want to look at. is_compatible_args in core/context.py compares type arguments with issubclass(actual, expected) whatever variance the protocol declares. For a Movable[int] parameter it accepts a Movable[bool] device and rejects a Movable[object] one, although Movable is contravariant. No issue has been filed.
  • The commands were checked outside the devcontainer: the unit tests except the helm-dependent ones, pyright, the docs build and schema regeneration. The developer image was built to confirm it contains just, uv and helm with the schema plugin. just lint and just unit were not run inside the devcontainer, and the system tests were not run.
  • The file points to docs/how-to/run-with-dev.md for the devcontainer. That page is rewritten in docs: Update docs to match code #1773 and is out of date until that merges.
  • "Direction of travel" is a snapshot of open issues from November 2026 and will need upkeep.
  • If docs: Update contribution guidelines #1767 merges, the label names the file mentions (decision pending, needs clarification) will need updating.

Instructions to reviewer on how to test:

  1. Read AGENTS.md and check that the workflow and policy it describes are what the team wants agents to follow.
  2. In the devcontainer, run just lint and just unit as the Commands section describes.
  3. Optionally start a coding agent in the repository and ask it which checks it would run before finishing a change.

Checks for reviewer

  • Would the PR title make sense to a user on a set of release notes

🤖 Generated with Claude Code

Assisted-by: Claude Fable 5.2 via Claude Code

AGENTS.md gives coding agents what they cannot cheaply work out from
the code: the checks CI runs, the files that must change together, the
public contracts other teams rely on and what to ask before changing.
It also asks agents to disclose their involvement with an Assisted-by
footer and to consider variance when using generics.

CLAUDE.md only imports AGENTS.md, because Claude Code reads CLAUDE.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Assisted-by: Claude Fable 5.2 via Claude Code
@DiamondJoseph
DiamondJoseph requested a review from a team as a code owner November 16, 2026 18:13
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.30%. Comparing base (1e761f9) to head (7f68f60).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1774   +/-   ##
=======================================
  Coverage   96.30%   96.30%           
=======================================
  Files          50       50           
  Lines        3821     3821           
=======================================
  Hits         3680     3680           
  Misses        141      141           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tpoliaw

tpoliaw commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Not going to block this if it something everyone wants but I would just like it on record that I hate everything about it.

@DiamondJoseph

Copy link
Copy Markdown
Contributor Author

Not going to block this if it something everyone wants but I would just like it on record that I hate everything about it.

Better to have guardrails now and denote any practices we don't want ridden roughshod over before it happens.

Join us Peter. 🤖 .

@ZohebShaikh ZohebShaikh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like the harness for your personal agent is a personal thing and you should configure it according to your own taste.

If we put this in VCS it needs to be reviewed by human. With no verification system it is very costly in terms of time for reviewers.

My suggestion if this added to VCS

Auto approved and merge is enabled just for this file.
(With a ci verification of prompt injections, etc)
A special agent:(or something else) created to make sure we can filter this out in release notes

The approach I would like.

In your dotfiles configure to ignore the agents file. And then your agent can keep using/changing it as you wills without maintenance overhead on human reviewers

@DiamondJoseph

DiamondJoseph commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

I feel like the harness for your personal agent is a personal thing and you should configure it according to your own taste.

That's against current conventions; there's 1.4M examples on github: https://github.com/search?q=path%3AAGENTS.md+NOT+is%3Afork+NOT+is%3Aarchived&type=code and you can find all manner of resources out there. It's your choice if you're working on a project with just you, but this is a shared project that needs to have shared expectations. It also enables e.g. agentic review in CI (UoC are using Gitlab Duo, don't know if Diamond will ever enable Copilot reviews?) to be a little more thorough.

If we put this in VCS it needs to be reviewed by human. With no verification system it is very costly in terms of time for reviewers.

It's not that long to read it right now and ensure it's correct, then to read any updates- there won't be updates with every change, just whenever the system or expectations or build changes, so it can also act as an early warning. It just puts guardrails up now to make sure AI don't go rogue.

My suggestion if this added to VCS [is that a]uto approved and merge is enabled just for this file. (With a ci verification of prompt injections, etc) A special agent:(or something else) created to make sure we can filter this out in release notes

The approach I would like.

In your dotfiles configure to ignore the agents file. And then your agent can keep using/changing it as you wills without maintenance overhead on human reviewers

I disagree. Treat it like the readme: make sure any changes are accurate, make sure it is read by any [AI] contributors (NB: this will happen automatically when they read the project into context) the same way you'd direct a human to the readme before they contribute.

My org are also using it as a marker that the codebase has been checked for any leaked credentials- it's probably best if no agents are used on a project until it has an agents.md, because that means somebody has at least thought about the risks.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants