AI assistants: move CLAUDE.md to AGENTS.md, with CLAUDE.md importing it #939

New issue

Closed

opened 2026-10-16 13:51:52 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-16 13:51:52 +00:00

Owner

The instructions for AI assistants live in CLAUDE.md, which only Claude Code reads. Move them to AGENTS.md, the shared convention that Codex, GitHub Copilot, Cursor and others read, and keep CLAUDE.md as a one-line import of it. Then every assistant a contributor uses gets the same rules.

What exists today

One file, for one tool. CLAUDE.md at the repository root is 99 lines: Working on Postulo, What this project promises, How the code is shaped, Before saying a change is done and Working with AI. It describes itself as "the short version for an AI assistant", and it defers to docs/PLAN.md and CONTRIBUTING.md.
Two references to it. README.md:131 links it, and CONTRIBUTING.md:335 says "CLAUDE.md in the repository root tells an assistant how this project works; keep it current when the rules change."
No AGENTS.md anywhere, in core or in any plugin or extension repository.

How Claude Code reads AGENTS.md

From How Claude remembers your project, v2.1.277 and later:

By default, AGENTS.md is read only when there is no CLAUDE.md in the working directory or above it. A CLAUDE.md takes precedence.
Both can be read together if Project instructions is set to claude-md-and-agents-md in /config. That is a per-person setting, so the project can't rely on it.
@path imports work everywhere, on every version and setting. The documentation recommends a CLAUDE.md that contains @AGENTS.md plus any Claude-only notes.
Not a symlink. The documentation advises against making CLAUDE.md a symlink to AGENTS.md: it needs Developer Mode or admin rights on Windows, a clone without core.symlinks turns it into a one-line text file, and Claude's Edit and Write tools refuse to write through it.

What would change

Move the content to AGENTS.md. Rename CLAUDE.md to AGENTS.md, keeping its history (git mv). Reword it so that no sentence assumes one particular tool: "an AI assistant", not "Claude".
A new CLAUDE.md is one import:
```
@AGENTS.md
```
Add a short Claude Code section only if something genuinely applies to Claude Code alone. Nothing does today.
Update the references.
- README.md:131 links AGENTS.md.
- CONTRIBUTING.md:335 names AGENTS.md as the file to keep current, and says that CLAUDE.md only imports it.
A check. A small test asserts that CLAUDE.md still imports AGENTS.md. Otherwise somebody may later add rules to CLAUDE.md by mistake, and only Claude would see them.
The other repositories. No plugin or extension repository has either file today. If any gains assistant instructions (see #938's caution about tool-specific files), it should start with AGENTS.md and the same one-line CLAUDE.md.

Done when

Codex, Copilot and Claude Code opened in the repository all load the same instructions. For Claude Code, /memory lists CLAUDE.md with AGENTS.md imported.
The README and CONTRIBUTING point to AGENTS.md.
The test is in place.

The instructions for AI assistants live in `CLAUDE.md`, which only Claude Code reads. Move them to `AGENTS.md`, the shared convention that Codex, GitHub Copilot, Cursor and others read, and keep `CLAUDE.md` as a one-line import of it. Then every assistant a contributor uses gets the same rules. ## What exists today - **One file, for one tool.** `CLAUDE.md` at the repository root is 99 lines: *Working on Postulo*, *What this project promises*, *How the code is shaped*, *Before saying a change is done* and *Working with AI*. It describes itself as "the short version for an AI assistant", and it defers to `docs/PLAN.md` and `CONTRIBUTING.md`. - **Two references to it.** `README.md:131` links it, and `CONTRIBUTING.md:335` says "`CLAUDE.md` in the repository root tells an assistant how this project works; keep it current when the rules change." - **No `AGENTS.md` anywhere,** in core or in any plugin or extension repository. ## How Claude Code reads AGENTS.md From [*How Claude remembers your project*](https://code.claude.com/docs/en/memory.md), v2.1.277 and later: - **By default, `AGENTS.md` is read only when there is no `CLAUDE.md`** in the working directory or above it. A `CLAUDE.md` takes precedence. - **Both can be read together** if *Project instructions* is set to `claude-md-and-agents-md` in `/config`. That is a per-person setting, so the project can't rely on it. - **`@path` imports work everywhere,** on every version and setting. The documentation recommends a `CLAUDE.md` that contains `@AGENTS.md` plus any Claude-only notes. - **Not a symlink.** The documentation advises against making `CLAUDE.md` a symlink to `AGENTS.md`: it needs Developer Mode or admin rights on Windows, a clone without `core.symlinks` turns it into a one-line text file, and Claude's Edit and Write tools refuse to write through it. ## What would change 1. **Move the content to `AGENTS.md`.** Rename `CLAUDE.md` to `AGENTS.md`, keeping its history (`git mv`). Reword it so that no sentence assumes one particular tool: "an AI assistant", not "Claude". 2. **A new `CLAUDE.md` is one import**: ```markdown @AGENTS.md ``` Add a short *Claude Code* section only if something genuinely applies to Claude Code alone. Nothing does today. 3. **Update the references.** - `README.md:131` links `AGENTS.md`. - `CONTRIBUTING.md:335` names `AGENTS.md` as the file to keep current, and says that `CLAUDE.md` only imports it. 4. **A check.** A small test asserts that `CLAUDE.md` still imports `AGENTS.md`. Otherwise somebody may later add rules to `CLAUDE.md` by mistake, and only Claude would see them. 5. **The other repositories.** No plugin or extension repository has either file today. If any gains assistant instructions (see #938's caution about tool-specific files), it should start with `AGENTS.md` and the same one-line `CLAUDE.md`. ## Done when - Codex, Copilot and Claude Code opened in the repository all load the same instructions. For Claude Code, `/memory` lists `CLAUDE.md` with `AGENTS.md` imported. - The README and CONTRIBUTING point to `AGENTS.md`. - The test is in place.

tiagoagueda added the

documentation

label

2026-10-16 13:51:58 +00:00

tiagoagueda referenced this issue

2026-10-16 13:54:45 +00:00

Contributing: every change reaches main through a pull request, with main protected #940

tiagoagueda referenced this issue from a commit

2026-10-18 21:39:29 +00:00

docs: AGENTS.md for every assistant, a code of conduct, an accessibility statement

tiagoagueda referenced this issue from a pull request that will close it,

2026-10-18 21:39:33 +00:00