Make CLAUDE.md optional in the agents-md standard

Andrew Dunnrequested to merge
standards/generic-agents-md into main

What does this MR do and why?

I want AGENTS.md to be the only required agent-instructions file, because Claude Code v2.1.277 and later reads it directly, so the one-line @AGENTS.md CLAUDE.md adds nothing there.

The agents-md check asserts AGENTS.md alone, the rule no longer names tools, and the agents-md template, the docs, lab and paper starters and this repository drop their one-line CLAUDE.md.

Claude Code reads AGENTS.md only when no CLAUDE.md exists in the working directory or above it, and a CLAUDE.md takes precedence. A project that keeps a CLAUDE.md for an older client therefore makes it the single line @AGENTS.md, and the standard now says so.

flowchart LR
  start["Claude Code session<br/>in a project"] --> q{"CLAUDE.md in the<br/>working directory or above?"}
  q -- no --> direct["reads AGENTS.md<br/>v2.1.277 and later"]
  q -- yes --> claude["reads CLAUDE.md"]
  claude --> imp{"CLAUDE.md is<br/>@AGENTS.md?"}
  imp -- yes --> via["AGENTS.md arrives<br/>through the import"]
  imp -- no --> shadow["AGENTS.md is<br/>never read"]

A project has nothing to do. A CLAUDE.md that is already the one-line import still passes and keeps working, and a project can delete it once its clients read AGENTS.md directly.

References

Standards affected

agents-md: check.sh drops check_file_exists CLAUDE.md and keeps check_file_exists AGENTS.md. The ## Verify block is regenerated by just sync-verify. The rule table, the description, the template list and a new "CLAUDE.md is optional" section describe the one-file form. The standard stays enforcing, and the check accepts every project it accepted before, with or without a CLAUDE.md.

The README row, the two site pages that list the starters' files, the .gitlab-ci.yml vale paths and the AGENTS.md and README templates in docs, lab and paper stop naming the removed files.

Exemption implications

None. An exemption a consumer holds for file-exists:CLAUDE.md reports as unused and can be deleted.

Test plan

  • just guard passes locally
  • just check passes locally (self-conformance)
  • just ship passes on the branch merged with main: TOTAL: 21 standard(s) passed, 0 exempt, 0 failed
  • just check-one STANDARD=agents-md REPO=<dir> passes on a directory with AGENTS.md and no CLAUDE.md, fails on one with neither, and passes on one with both. The AGENTS.md-only directory failed on the CLAUDE.md assertion before this change.
  • Starters lifted into a consumer repo. Each of the three changes by one deleted file and one line in its AGENTS.md and its README template, so this is left to review.

Reviewer checklist

  • Voice is GitLab Inc. neutral (no solo-developer narrative, no decorative essays)
  • No em-dashes in customer-facing prose
  • No filler words ("comprehensive", "robust", "leverage", "seamless")
  • Trailers present (Signed-off-by:, Changelog: if user-visible, AI-Assisted: if applicable)
  • CODEOWNERS section matches paths touched
  • If breaking for consumers, CHANGELOG entry calls it out and the schedule is realistic

An AI tool wrote this change and ran the checks above.

Merge request reports