# AGENTS.md vs CLAUDE.md: which file should hold your design rules?

Updated 2026-11-21 · https://briefatto.com/guides/agents-md-vs-claude-md/

Put a short pointer in both files and keep the design itself in DESIGN.md. `npx briefatto-board install` writes the same marked block to AGENTS.md and CLAUDE.md, so Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf and the other agents that read either file get the same instruction.

## Which agent reads which file

| Agent | What its documentation says |
| --- | --- |
| Claude Code | [Persistent instructions](https://code.claude.com/docs/en/memory) through CLAUDE.md or AGENTS.md files. |
| Codex | [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md). |
| Cursor | [AGENTS.md](https://cursor.com/docs/context/rules) as a plain-markdown alternative to `.cursor/rules`. |
| GitHub Copilot | [AGENTS.md files](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) anywhere in the repository; the nearest one takes precedence. |
| OpenCode | [AGENTS.md](https://opencode.ai/docs/rules/), and CLAUDE.md in any directory without one. |
| Lovable | [AGENTS.md or CLAUDE.md](https://docs.lovable.dev/features/knowledge) at the top level, read with every message. |

## One block, both files, one guide

The Briefatto Board block sits between `<!-- briefatto-board:start -->` and `<!-- briefatto-board:end -->` in each file. After a freeze it tells the agent to read `DESIGN.md` before any visual work, to route brand changes through `board freeze` and to run `board check` on every piece.

Running the installer again replaces that one block instead of adding a second, so the files never disagree.

## Questions and answers

### Will it overwrite my CLAUDE.md?

No. It adds one marked block and leaves the rest of the file as it is.

### Why not put the whole design system in AGENTS.md?

The instruction files load in every session. A short pointer keeps them small, and the guide in DESIGN.md is frozen, versioned and checked against a render.

### Is Briefatto Board free?

Yes. It is open source under the Apache-2.0 licence and installs with `npx briefatto-board install`.

## Try it

```
npx briefatto-board install
```

Briefatto Board is free and open source under Apache-2.0: https://github.com/Briefatto/briefatto-board

## Related guides

- [DESIGN.md vs AGENTS.md: what goes in each file](https://briefatto.com/guides/design-md-vs-agents-md/)
- [CLAUDE.md vs DESIGN.md: what to put in each for Claude Code](https://briefatto.com/guides/claude-md-vs-design-md/)
- [Claude Code ignores AGENTS.md or CLAUDE.md: what to do](https://briefatto.com/guides/claude-code-ignores-agents-md/)
- [How do you keep design context across different AI coding tools?](https://briefatto.com/guides/one-design-guide-across-ai-coding-tools/)

## Sources

- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/board.mjs
- https://code.claude.com/docs/en/memory (checked 2026-11-21)
- https://agents.md (checked 2026-11-21)
- https://developers.openai.com/codex/guides/agents-md (checked 2026-11-21)
- https://cursor.com/docs/context/rules (checked 2026-11-21)
- https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions (checked 2026-11-21)
- https://opencode.ai/docs/rules/ (checked 2026-11-21)
- https://docs.lovable.dev/features/knowledge (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
